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

Selvhosting af Qdrant bliver interessant ved den første redeploy – ikke ved den første docker run. Hvis storage-tilladelserne fejler, eller klienten bruger 6334, mens kun 6333 er routet, kan Docker stadig rapportere en helt sund proces. Deploymentet nedenfor er struktureret omkring observerbar adfærd: Opret en collection med den tilsigtede vektorstørrelse, indsæt punkter med payload, kør en filtreret nearest-neighbor-forespørgsel, og gendan et collection-snapshot.

Qdrants tilsigtede rolle er klar: en vector database til embeddings og retrieval-systemer. Den beskrivelse fortæller os, hvad der skal være offentligt, hvad der bør forblive privat, og hvad en backup skal kunne genskabe.

Kortlæg Qdrant, før du rører ved Docker

Lad ikke Qdrant-imaget ved et uheld bestemme produktionsarkitekturen. Imaget leverer en proces på 6333; storage, routing og eksterne krav kræver stadig bevidste lifecycles. Kravet til det lokale runtime-miljø er tilstrækkeligt RAM og diskplads til vektordimensioner, payloads og indexes. Dokumentér den forventede kapacitet, ejerskab og fejltilstand i stedet for at lade det være en image-default.

Deploymentet er klar til dybere test, når det kan oprette en collection med den tilsigtede vektorstørrelse, indsætte punkter med payload, køre en filtreret nearest-neighbor-forespørgsel og gendanne et collection-snapshot. Følg transaktionen i logs, og hold øje med vektordimensioner, HNSW-konstruktion, payload-indexes, collection-replikaer samt forskellen mellem memory-mapped data og tilgængeligt RAM. Disse observationer viser, om den aktuelle topologi isolerer den rigtige komponent.

Rout Qdrant uden at give et forkert indtryk af HTTPS

Vælg det endelige Qdrant-hostnavn, før brugerne gemmer callbacks eller client settings, og hold derefter kun REST offentligt, når klienterne reelt kræver det, mens gRPC forbliver privat. Platformens route bør terminere TLS én gang og pege på den private port 6333.

Kør acceptance-transaktionen eksternt. Hvis klienten aldrig når frem til Qdrant, kan du bruge SSL-valideringstjeklisten til DNS- og certifikattjek. Hvis requesten når frem til Qdrant, men storage-tilladelserne fejler, eller klienten bruger 6334, mens kun 6333 er routet, skal du stoppe med at ændre proxy-redirects og i stedet undersøge den applikationsspecifikke grænse.

Gør den lokale kommando til en service, der kan inspiceres

Brug en kommando, der synliggør alle vigtige valg. Denne baseline binder Qdrant til hostens loopback, tilføjer de kendte data mounts og angiver den første nødvendige indstilling. Bekræft det lokale krav før eksponering: tilstrækkeligt RAM og diskplads til vektordimensioner, payloads og indexes.

docker run -d \
  --name qdrant \
  --restart unless-stopped \
  -p 127.0.0.1:6333:6333 \
  -v qdrant-data:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY=replace-with-a-long-random-value \
  qdrant/qdrant:latest

Erstat floating tags med en testet version eller digest. Efter opstart skal du inspicere docker logs --tail 200 qdrant og bekræfte, at processen lytter på 6333. Udfør derefter Qdrants acceptance-handling; et svar fra root-siden kan ikke bevise, at hele scenariet lykkes: Opret en collection med den tilsigtede vektorstørrelse, indsæt punkter med payload, kør en filtreret nearest-neighbor-forespørgsel, og gendan et collection-snapshot.

Opgrader Qdrant uden at gætte

Kapacitetstests bør afprøve vektordimensioner, HNSW-konstruktion, payload-indexes, collection-replikaer samt forskellen mellem memory-mapped data og tilgængeligt RAM – ikke en gentagen request til /. Kør scenariet “opret en collection med den tilsigtede vektorstørrelse, indsæt punkter med payload, kør en filtreret nearest-neighbor-forespørgsel, og gendan et collection-snapshot” med realistisk concurrency, og registrér latency, fejlrate og vækst i storage.

Upgrade-planlægningen skal tage højde for denne risiko: Collection-snapshots, kompatibilitet mellem storage-formater og client-library-adfærd skal testes, før serverversionen opgraderes. Test den nye release med repræsentativt input, gentag derefter acceptance-transaktionen, og sammenlign resultatet. Hvis storage-tilladelserne fejler, eller klienten bruger 6334, mens kun 6333 er routet, skal du opsamle den fejlslagne transaktion og undersøge den første involverede grænse i stedet for at antage, at ingress er ansvarlig.

Gør Qdrants smoke test til et release-tjek

En release candidate til Qdrant får trafik ved at gennemføre et fast scenarie: Opret en collection med den tilsigtede vektorstørrelse, indsæt punkter med payload, kør en filtreret nearest-neighbor-forespørgsel, og gendan et collection-snapshot. Registrér image-digestet, den effektive ikke-hemmelige konfiguration, den offentlige origin og tidsstemplerne for scenariet. Testdataene bør kunne bortskaffes, men samtidig være realistiske nok til at afprøve den samme sti som brugerne.

Kør testen efter udskiftning af runtime-miljøet, og genopbyg derefter servicen fra Qdrant-snapshots og det persistente storage-directory. Recovery er godkendt, når et snapshot genskaber collectionen med det samme antal punkter, den samme vektorkonfiguration og repræsentative query-resultater. Sammenlign ressource-målinger for vektordimensioner, HNSW-konstruktion, payload-indexes, collection-replikaer samt forskellen mellem memory-mapped data og tilgængeligt RAM med den tidligere release, og undersøg væsentlige 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 grænse: storage-tilladelserne fejler, eller klienten bruger 6334, mens kun 6333 er routet. Kontrollér, at Qdrant forklarer fejlen, ikke beskadiger den eksisterende state og genoptager driften, når den gyldige tilstand vender tilbage. Gem et redigeret logudsnit og recovery-tiden. Tilsammen dækker disse tjek adfærd, durability og operability – ikke kun om processen er oppe.

Bevis, at Qdrant overlever en udskiftning

For Qdrant starter redeploy-sikkerhed med Qdrant-snapshots og det persistente storage-directory. Mount /qdrant/storage før bootstrap, skriv ufarlige sample-data, og udskift containeren for at bevise, at stien faktisk er persistent. Test stien ved at udskifte containeren, mens de ufarlige sample-data stadig findes; det afslører mounts, der peger en directory for højt eller lavt.

Test derefter disaster recovery på en tom host. Brug en application-consistent database-eksport, hvor det er nødvendigt, og kontrollér, at et snapshot genskaber collectionen med det samme antal punkter, den samme vektorkonfiguration og repræsentative query-resultater. Guiden til database-backups, der er blevet gendannet giver et stærkere mål end blot at kontrollere, at der blev oprettet en archive-fil.

Credentials, roller og eksponerede overflader

For Qdrant er den værdifulde overflade ikke nødvendigvis landing page. Den største fejl er at publicere et API uden authentication på internettet. Modvirk det bevidst: Giv ingestion-services scoped API-adgang, og hold hele det administrative API på en privat route.

Behandl QDRANT__SERVICE__API_KEY i overensstemmelse med dets Qdrant-formål: Hold følsomme værdier ude af Git, dokumentér effekten af rotation, og brug aldrig et offentligt eksempel i produktion. Brug en unprivileged container-bruger, når imaget understøtter det, og mount ingen uvedkommende credentials. Anvend rate- eller størrelsesbegrænsninger ved ingress, hvor untrusted arbejde kan forbruge vektordimensioner, HNSW-konstruktion, payload-indexes, collection-replikaer samt forskellen mellem memory-mapped data og tilgængeligt RAM.

Flyt det gentagelige infrastrukturarbejde til Dockup

Dockup kan håndtere de udskiftelige platformdele: route trafik til port 6333, udstede domain og certifikat, injicere secrets, tilknytte persistent storage og forbinde Qdrant med managed eller private tilknyttede services. Det kan ske på Dockup-infrastruktur eller på en server, du tilknytter.

Acceptance-arbejdet for Qdrant forbliver eksplicit. Efter one-click-deploymentet skal du kun holde REST offentligt, når klienterne reelt kræver det, mens gRPC forbliver privat. Bekræft det lokale krav – tilstrækkeligt RAM og diskplads til vektordimensioner, payloads og indexes – og kør dette scenarie: Opret en collection med den tilsigtede vektorstørrelse, indsæt punkter med payload, kør en filtreret nearest-neighbor-forespørgsel, og gendan et collection-snapshot. Denne opdeling er bevidst: Dockup fjerner gentagende infrastruktur-opsætning uden at lade som om, at applikationsroller, provider-credentials eller restore-politik vælger sig selv.

Ofte stillede spørgsmål

Hvad kræver Qdrant til et produktionsdeployment?

Rout Qdrant-containeren på port 6333 gennem én HTTPS-origin. Kravet til det lokale runtime-miljø er tilstrækkeligt RAM og diskplads til vektordimensioner, payloads og indexes. Kald ikke Qdrant klar, før du kan oprette en collection med den tilsigtede vektorstørrelse, indsætte punkter med payload, køre en filtreret nearest-neighbor-forespørgsel og gendanne et collection-snapshot.

Hvilke Qdrant-data hører til i en backup?

Persistér /qdrant/storage, og inkludér Qdrant-snapshots og det persistente storage-directory i det samme recovery-manifest. En ren Qdrant-restore er kun godkendt, når et snapshot genskaber collectionen med det samme antal punkter, den samme vektorkonfiguration og repræsentative query-resultater.

Kræver Qdrant HTTPS bag en reverse proxy?

Brug HTTPS til den offentlige Qdrant-origin, og hold port 6333 på den interne route. Anvend Qdrant-indstillingen korrekt: Hold kun REST offentligt, når klienterne reelt kræver det, og hold gRPC privat. For Qdrant beskytter HTTPS credentials eller brugerindhold under transmission og sikrer ensartet origin-følsom klientadfærd.

Hvordan bør en Qdrant-opgradering testes?

Gendan den aktuelle Qdrant-state i et isoleret deployment, anvend candidate-versionen, og gentag acceptance-transaktionen. Vær særligt opmærksom, fordi collection-snapshots, kompatibilitet mellem storage-formater og client-library-adfærd skal testes, før serverversionen opgraderes. Behold det tidligere Qdrant-image, indtil grænsen for data-migrering og rollback er forstået.