Slik selvhoster du Typesense i 2026: API-nøkler, collections og sikkerhetskopier

Den korteste Typesense-demoen viser at en prosess lytter på port 8108. Produksjon krever sterkere bevis. Den må bestå dette scenariet selv etter at containeren er erstattet: definer et collection-skjema, importer eksempeldata, kjør stavefeilsøk, facets og filtre, og test deretter health-endepunktet.

Typesense distribueres med et tydelig formål: en søkemotor for umiddelbare resultater med et enkelt HTTP-API. Den vanligste feilen ved distribusjon er at kommandoen utelater --data-dir, eller at health checks treffer feil path. Derfor må håndtering av offentlig URL og persistent state få like mye oppmerksomhet som oppstart av imaget.

Begrens hvilke rettigheter Typesense har

Den applikasjonsspesifikke sikkerhetsrisikoen er å bygge inn bootstrap-admin API-nøkkelen i nettleserkode. Den operasjonelle løsningen er å aldri sende bootstrap-administratornøkkelen til nettleseren. Generer i stedet scoped search keys for offentlige klienter. Fullfør bootstrap gjennom en begrenset route, og fjern midlertidig oppsettstilgang umiddelbart etterpå.

Behandle TYPESENSE_API_KEY i tråd med Typesense-rollen: hold sensitive verdier ute av Git, dokumenter konsekvensene av rotasjon, og bruk aldri et offentlig eksempel i produksjon. Gi Typesense-prosessen bare de dokumenterte mountene og dependency-routene. Unngå tilgang til hostens root og Docker-socketen. Logg mislykket autentisering og konfigurasjonsfeil, men rediger bort tokens, connection strings og brukerinnhold.

Typesenses produksjonsoppsett

Typesense HTTP-prosessen lytter på 8108. Behold denne porten på applikasjonsnettverket, og eksponer bare platform-routen. Det lokale runtime-kravet er diskplass for collections og nok minne til det aktive datasettet. Dokumenter forventet kapasitet, eierskap og feilmåte i stedet for å la dette være et image-default.

Skriv ned grensen som en kort kontrakt: hvem som eier kravet, hvilken credential som brukes, hvilken timeout som er akseptabel, og hvordan feil vises. Kjør deretter denne transaksjonen: definer et collection-skjema, importer eksempeldata, kjør stavefeilsøk, facets og filtre, og test deretter health-endepunktet. Observer RAM-behovet for aktive indekser, størrelsen på bulk-importen, diskpersistens og trafikken for cluster-replikering under kjøringen. Denne arbeidsbelastningen gir et mer nyttig utgangspunkt for dimensjonering enn en inaktiv container.

Containerinnstillinger som bør gjennomgås

Den første containeren bør være enkel å slette og opprette på nytt. Hold data borte fra det skrivbare laget, bind port 8108 bare der proxien kan nå den, og send konfigurasjon ved runtime.

docker run -d \
  --name typesense \
  --restart unless-stopped \
  -p 127.0.0.1:8108:8108 \
  -v typesense-data:/data \
  -e TYPESENSE_API_KEY=replace-with-a-long-random-value \
  -e TYPESENSE_DATA_DIR=/data \
  typesense/typesense:latest

Lås imaget etter den første testen. Les den tidligste oppstartsfeilen i stedet for den siste restart-meldingen, verifiser hver mount med docker inspect, og følg loggene mens du definerer et collection-skjema, importerer eksempeldata, kjører stavefeilsøk, facets og filtre, og deretter tester health-endepunktet. Denne sekvensen skiller en feil i image-kommandoen fra et dependency- eller rettighetsproblem.

Typesenses release-gate

En release candidate for Typesense fortjener trafikk ved å fullføre et fast scenario: definer et collection-skjema, importer eksempeldata, kjør stavefeilsøk, facets og filtre, og test deretter health-endepunktet. Ta vare på image digest, effektiv konfigurasjon uten secrets, offentlig origin og tidsstempler for scenariet. Testdataene bør kunne kastes, men samtidig være realistiske nok til å utøve den samme pathen som brukerne.

Kjør testen etter at runtime er erstattet, og bygg deretter tjenesten på nytt fra datakatalogen og, for clusters, konsistente snapshots av hver node. Gjenoppretting er godkjent når collections, aliases, overrides og synonyms kommer tilbake, og det samme søket gir et tilsvarende rangert resultat. Sammenlign ressursmålinger for RAM-behovet til aktive indekser, størrelsen på bulk-importen, diskpersistens og trafikken for cluster-replikering med forrige release. Undersøk betydelige avvik før promotion.

Test til slutt denne kontrollerte feilen: send ufarlig input nær ressurs- eller formatgrensen som gjelder for denne grensen: kommandoen utelater --data-dir, eller health checks treffer feil path. Kontroller at Typesense forklarer feilen, ikke skader eksisterende state, og fortsetter når den gyldige tilstanden kommer tilbake. Lagre et redigert loggutdrag og tiden det tok å gjenopprette. Til sammen dekker disse kontrollene oppførsel, persistens og drift – ikke bare at prosessen er oppe.

Rout Typesense uten å villede om HTTPS

Den offentlige grensen for Typesense bør være ett canonical hostname, automatisk TLS og ett internt mål på 8108. Rout HTTP-API-et, men hold peering-portene private, slik at klientene går tilbake til en adresse tjenesten kjenner igjen.

Hvis akseptansetransaksjonen feiler, klassifiser den første feilen. DNS-, sertifikat- og 502-problemer hører hjemme i sjekklisten for TLS-validering. Tilstanden «kommandoen utelater --data-dir, eller health checks treffer feil path» hører hjemme på applikasjonssiden etter at en request har nådd Typesense.

Øv på den risikable Typesense-endringen

Bruk definer et collection-skjema, importer eksempeldata, kjør stavefeilsøk, facets og filtre, og test deretter health-endepunktet som Typesense-smoketesten etter hver deployment. De tilhørende metrikkene er RAM-behovet til aktive indekser, størrelsen på bulk-importen, diskpersistens og trafikken for cluster-replikering. Sett varsler når disse ressursene nærmer seg et nivå som forringer brukerhandlingen.

Den største endringsrisikoen er at endringer i collection-skjemaet og snapshots bør øves på, fordi en image-rollback ikke kan reversere en endring i dataformatet. En trygg release starter med et gjenopprettbart snapshot og validerer alle irreversible state-endringer før trafikken flyttes. Når kommandoen utelater --data-dir, eller health checks treffer feil path, bør du beholde den feilede containeren lenge nok til å lese konfigurasjonen og den første feilen.

Bevis at Typesense overlever en erstatning

List opp state før den første virkelige posten opprettes: datakatalogen og, for clusters, konsistente snapshots av hver node. Mount /data før bootstrap, skriv ufarlige eksempeldata, og erstatt containeren for å bevise at pathen faktisk er persistent. Bekreft mounten ved å skrive ufarlige data, erstatte Typesense og lese dataene tilbake.

Snapshots er nyttige for rask rollback, men en uavhengig sikkerhetskopi er nødvendig når hosten eller volumet forsvinner. Gjenopprett til et tomt miljø med det låste imaget, og verifiser at collections, aliases, overrides og synonyms kommer tilbake, og at det samme søket gir et tilsvarende rangert resultat. Bruk persistente volumer og snapshots for å holde disse to gjenopprettingsmekanismene adskilt.

En Dockup-deployment trenger fortsatt en Typesense-akseptansetest

Routing, sertifikater, service-erstatning og tilknyttet lagring er fornuftige mål for automatisering. Dockup håndterer dette for Typesense og kan provisjonere den tilhørende managed databasen eller koble til tjenester på kundens egen server.

Det Dockup ikke bør finne på, er Typesenses trust policy. Etter deployment skal du route HTTP-API-et mens peering-portene holdes private, håndheve denne grensen – bootstrap-administratornøkkelen skal aldri sendes til nettleseren; generer scoped search keys for offentlige klienter – og verifisere resultatet av dette scenariet: definer et collection-skjema, importer eksempeldata, kjør stavefeilsøk, facets og filtre, og test deretter health-endepunktet. Resultatet er infrastruktur med ett klikk og en applikasjonsspesifikk akseptansetest.

Vanlige spørsmål

Hva trenger Typesense for en produksjonsdeployment?

Route Typesense-containeren på port 8108 gjennom én HTTPS-origin. Det lokale runtime-kravet er diskplass for collections og nok minne til det aktive datasettet. Ikke erklær Typesense som klar før du kan definere et collection-skjema, importere eksempeldata, kjøre stavefeilsøk, facets og filtre, og deretter teste health-endepunktet.

Hvilke Typesense-data hører hjemme i en sikkerhetskopi?

Persistér /data, og inkluder datakatalogen samt, for clusters, konsistente snapshots av hver node i det samme recovery-manifestet. En ren Typesense-gjenoppretting er bare godkjent når collections, aliases, overrides og synonyms kommer tilbake, og det samme søket gir et tilsvarende rangert resultat.

Krever Typesense HTTPS bak en reverse proxy?

Bruk HTTPS for den offentlige Typesense-originen, og behold port 8108 på den interne routen. Bruk Typesense-innstillingen riktig: route HTTP-API-et mens peering-portene holdes private. For Typesense beskytter HTTPS credentials eller brukerinnhold under overføring og sørger for konsistent klientadferd som avhenger av origin.

Hvordan bør en Typesense-oppgradering testes?

Gjenopprett gjeldende Typesense-state i en isolert deployment, ta i bruk kandidatversjonen og gjenta akseptansetransaksjonen. Vær spesielt oppmerksom på dette, fordi endringer i collection-skjemaet og snapshots bør øves på, siden en image-rollback ikke kan reversere en endring i dataformatet. Behold det forrige Typesense-imaget til grensen for datamigrering og rollback er forstått.