Sådan selvhoster du Typesense i 2026: API-nøgler, collections og backups

Den korteste Typesense-demo beviser, at en proces lytter på port 8108. Production kræver stærkere dokumentation. Den skal kunne gennemføre dette scenarie, selv efter containeren er blevet udskiftet: definér et collection-schema, importér eksempeldokumenter, kør typo search, facets og filters, og test derefter health-endpointet.

Typesense deployes med et klart formål: en søgemaskine til lynhurtig søgning med en enkel HTTP API. Den mest almindelige deployment-fælde er, at kommandoen udelader --data-dir, eller at health checks rammer den forkerte sti, så håndtering af den offentlige URL og persistent state får samme opmærksomhed som opstart af imaget.

Begræns de rettigheder, Typesense har

Den applikationsspecifikke sikkerhedsrisiko er at indlejre bootstrap-admin-API-nøglen i browserkode. Den operationelle løsning er aldrig at sende bootstrap administrator-nøglen til browseren; generér i stedet scoped search keys til offentlige clients. Afslut bootstrap via en begrænset route, og fjern midlertidig setup-adgang med det samme bagefter.

Behandl TYPESENSE_API_KEY i overensstemmelse med dens rolle i Typesense: Hold følsomme værdier ude af Git, dokumentér konsekvenserne af rotation, og brug aldrig et offentligt eksempel i production. Giv Typesense-processen kun de dokumenterede mounts og dependency-routes; undgå adgang til hostens root og Docker-socketen. Log mislykket authentication og konfigurationsfejl, men redigér tokens, connection strings og brugerindhold.

Typesenses production-struktur

Typesenses HTTP-proces lytter på 8108; behold den port på application networket, og publicér kun platform-routen. Det lokale runtime-krav er diskplads til collections og tilstrækkelig memory til det aktive dataset. Dokumentér den forventede kapacitet, ejerskab og failure mode i stedet for at lade det være en image-default.

Skriv grænsen ned som en kort kontrakt: Hvem ejer kravet, hvilken credential bruges, hvilken timeout er acceptabel, og hvordan viser en fejl sig? Kør derefter denne transaktion: definér et collection-schema, importér eksempeldokumenter, kør typo search, facets og filters, og test derefter health-endpointet. Observér RAM-forbruget til aktive indexes, størrelsen på bulk-importen, disk persistence og traffic til cluster replication under kørslen, fordi denne workload giver et mere nyttigt udgangspunkt for dimensionering end en idle container.

Containerindstillinger, der er værd at gennemgå

Den første container skal være nem at slette og genskabe. Hold data væk fra det writable layer, bind kun port 8108 dér, hvor proxyen kan nå den, og send konfigurationen ind 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

Pin imaget efter den indledende test. Læs den tidligste startup-fejl i stedet for den sidste restart-meddelelse, verificér hvert mount med docker inspect, og følg logs, mens du definerer et collection-schema, importerer eksempeldokumenter, kører typo search, facets og filters og derefter tester health-endpointet. Den sekvens skelner mellem en forkert image-kommando og et problem med en dependency eller permissions.

Typesenses release gate

En release candidate til Typesense fortjener traffic ved at gennemføre et fast scenarie: definér et collection-schema, importér eksempeldokumenter, kør typo search, facets og filters, og test derefter health-endpointet. Gem image digest, den effektive konfiguration uden secrets, public origin og timestamps for scenariet. Testdataene skal kunne kasseres, men være realistiske nok til at udøve den samme path som brugerne.

Kør testen efter udskiftning af runtime, og genopbyg derefter servicen fra data directoryet og — for clusters — konsistente snapshots af hver node. Recovery er godkendt, når collections, aliases, overrides og synonyms er tilbage, og den samme query giver et tilsvarende ranked result. Sammenlign målinger for RAM-forbruget til aktive indexes, størrelsen på bulk-importen, disk persistence og traffic til cluster replication med den forrige release, og undersøg markante afvigelser før promotion.

Afprøv til sidst denne kontrollerede fejl: Indsend ufarligt input tæt på den ressource- eller formatgrænse, der er forbundet med denne boundary: kommandoen udelader --data-dir, eller health checks rammer den forkerte path. Kontrollér, at Typesense forklarer fejlen, ikke beskadiger eksisterende state og genoptager driften, når den gyldige tilstand vender tilbage. Gem et redigeret logudsnit og recovery-tiden. Tilsammen dækker disse checks behavior, durability og operability — ikke kun at processen er oppe.

Route Typesense uden at give et forkert billede af HTTPS

Den offentlige boundary for Typesense bør være ét canonical hostname, automatisk TLS og ét internt target på 8108. Route HTTP API’en, mens peering-porte holdes private, så clients vender tilbage til en adresse, som servicen genkender.

Hvis acceptance-transaktionen fejler, skal du klassificere den første fejl. DNS-, certificate- og 502-problemer hører hjemme i TLS-validationstjeklisten. Betingelsen “kommandoen udelader --data-dir, eller health checks rammer den forkerte path” hører til på applikationssiden, efter at en request er nået frem til Typesense.

Øv den risikable Typesense-ændring

Brug definér et collection-schema, importér eksempeldokumenter, kør typo search, facets og filters, og test derefter health-endpointet som Typesenses smoke test efter hver deployment. De understøttende metrics er RAM-forbruget til aktive indexes, størrelsen på bulk-importen, disk persistence og traffic til cluster replication; opret alerts dér, hvor disse ressourcer nærmer sig et niveau, som forringer brugerhandlingen.

Den største ændringsrisiko er, at ændringer i collection-schemaer og snapshots kræver en rehearsal, fordi en image rollback ikke kan omgøre en ændring af dataformatet. En sikker release starter med et restorebart snapshot og validerer alle irreversible state changes, før traffic flyttes. Når kommandoen udelader --data-dir, eller health checks rammer den forkerte path, skal du beholde den fejlslagne container længe nok til at læse dens konfiguration og første fejl.

Bevis, at Typesense overlever en udskiftning

Oplist state, før den første rigtige record oprettes: data directoryet og — for clusters — konsistente snapshots af hver node. Mount /data før bootstrap, skriv ufarlige eksempeldata, og udskift containeren for at bevise, at pathen faktisk er persistent. Bekræft mountet ved at skrive ufarlige data, udskifte Typesense og læse dem tilbage.

Snapshots er værdifulde til hurtig rollback, men der er behov for en uafhængig backup, hvis hosten eller volumen forsvinder. Gendan til et tomt environment med det pinnede image, og verificér, at collections, aliases, overrides og synonyms kommer tilbage, og at den samme query giver et tilsvarende ranked result. Brug persistent volumes og snapshots til at holde de to recovery-mekanismer adskilt.

En Dockup-deployment kræver stadig en Typesense-acceptancetest

Routing, certificates, service replacement og attached storage er fornuftige mål for automation. Dockup håndterer dette for Typesense og kan provisionere den tilknyttede managed database eller forbinde til services på kundens egen server.

Det, den ikke bør opfinde, er Typesenses trust policy. Efter deployment skal du route HTTP API’en, mens peering-porte holdes private, håndhæve denne boundary — send aldrig bootstrap administrator-nøglen til browseren; generér scoped search keys til offentlige clients — og verificér resultatet af dette scenarie: definér et collection-schema, importér eksempeldokumenter, kør typo search, facets og filters, og test derefter health-endpointet. Resultatet er infrastruktur med ét klik og en applikationsspecifik acceptancetest.

Ofte stillede spørgsmål

Hvad har Typesense brug for i en production-deployment?

Route Typesense-containeren på port 8108 gennem én HTTPS-origin. Det lokale runtime-krav er diskplads til collections og tilstrækkelig memory til det aktive dataset. Erklær ikke Typesense for klar, før du kan definere et collection-schema, importere eksempeldokumenter, køre typo search, facets og filters og derefter teste health-endpointet.

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

Persistér /data, og inkludér data directoryet samt — for clusters — konsistente snapshots af hver node i det samme recovery-manifest. Et rent Typesense-restore er kun godkendt, når collections, aliases, overrides og synonyms kommer tilbage, og den samme query giver et tilsvarende ranked result.

Kræver Typesense HTTPS bag en reverse proxy?

Brug HTTPS til den offentlige Typesense-origin, og behold port 8108 på den interne route. Anvend Typesense-indstillingen korrekt: Route HTTP API’en, mens peering-porte holdes private. For Typesense beskytter HTTPS credentials eller brugerindhold under transport og sikrer ensartet client behavior, der afhænger af origin.

Hvordan bør en Typesense-upgrade testes?

Gendan den aktuelle Typesense-state i en isoleret deployment, anvend candidate-versionen, og gentag dens acceptancetransaktion. Vær særligt opmærksom, fordi ændringer i collection-schemaer og snapshots kræver en rehearsal, da en image rollback ikke kan omgøre en ændring af dataformatet. Behold det tidligere Typesense-image, indtil dets data-migration og rollback boundary er forstået.