Jak hostować Qdrant samodzielnie w 2026 roku: storage, klucze API i backupy

Samodzielne hostowanie Qdrant staje się interesujące przy pierwszym redeploymencie, a nie przy pierwszym docker run. Jeśli wystąpią problemy z uprawnieniami do storage albo klient korzysta z portu 6334, podczas gdy routowany jest tylko port 6333, Docker nadal może raportować całkowicie poprawnie działający proces. Poniższe wdrożenie opiera się na obserwowalnym zachowaniu: utworzeniu kolekcji z docelowym rozmiarem wektora, wstawieniu punktów z payloadem, wykonaniu filtrowanego zapytania nearest-neighbor oraz odtworzeniu snapshotu kolekcji.

Rola Qdrant jest jasno określona: to vector database dla embeddingów i systemów retrieval. Taki opis wskazuje, co musi pozostać publiczne, co powinno być prywatne i co backup musi odtworzyć.

Poznaj Qdrant, zanim dotkniesz Dockera

Nie pozwól, aby obraz Qdrant przypadkowo narzucił architekturę produkcyjną. Obraz dostarcza proces na porcie 6333, ale storage, routing i wymagania zewnętrzne nadal wymagają świadomego zarządzania cyklem życia. Lokalne wymagania runtime to wystarczająca ilość RAM-u i miejsca na dysku na wymiary wektorów, payloady i indeksy. Udokumentuj oczekiwaną pojemność, właściciela i scenariusz awarii, zamiast pozostawiać te ustawienia jako domyślne wartości obrazu.

Wdrożenie jest gotowe do dokładniejszych testów, gdy potrafi utworzyć kolekcję z docelowym rozmiarem wektora, wstawić punkty z payloadem, wykonać filtrowane zapytanie nearest-neighbor i odtworzyć snapshot kolekcji. Śledź transakcję w logach i obserwuj wymiary wektorów, budowanie HNSW, indeksy payloadów, repliki kolekcji oraz różnicę między danymi memory-mapped a dostępnym RAM-em. Te obserwacje pokazują, czy obecna topologia izoluje właściwy komponent.

Skonfiguruj routing Qdrant bez udawania HTTPS

Wybierz docelowy hostname Qdrant, zanim użytkownicy zapiszą callbacki lub ustawienia klienta. REST udostępniaj publicznie tylko wtedy, gdy klienci rzeczywiście tego wymagają, a gRPC pozostaw prywatne. Route na platformie powinien kończyć TLS raz i kierować ruch na prywatny port 6333.

Wykonaj transakcję akceptacyjną z zewnątrz. Jeśli klient nigdy nie dociera do Qdrant, użyj checklisty walidacji SSL, aby sprawdzić DNS i certyfikat. Jeśli żądanie dociera do Qdrant, ale występują problemy z uprawnieniami do storage albo klient korzysta z portu 6334, podczas gdy routowany jest tylko port 6333, przestań zmieniać redirecty proxy i sprawdź granicę właściwą dla aplikacji.

Zmień lokalne polecenie w usługę, którą można sprawdzać

Użyj polecenia, które pokazuje wszystkie istotne decyzje. Ta konfiguracja bazowa wiąże Qdrant z loopbackiem hosta, dodaje znane mounty danych i dostarcza pierwsze wymagane ustawienie. Przed udostępnieniem usługi potwierdź lokalne wymagania: wystarczającą ilość RAM-u i miejsca na dysku na wymiary wektorów, payloady i indeksy.

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

Zastąp pływające tagi przetestowaną wersją lub digestem. Po uruchomieniu sprawdź docker logs --tail 200 qdrant i potwierdź, że proces nasłuchuje na porcie 6333. Następnie wykonaj działanie akceptacyjne Qdrant; odpowiedź strony głównej nie dowodzi, że cały scenariusz zakończy się powodzeniem: utwórz kolekcję z docelowym rozmiarem wektora, wstaw punkty z payloadem, wykonaj filtrowane zapytanie nearest-neighbor i odtwórz snapshot kolekcji.

Aktualizuj Qdrant bez zgadywania

Testy pojemności powinny obejmować wymiary wektorów, budowanie HNSW, indeksy payloadów, repliki kolekcji oraz różnicę między danymi memory-mapped a dostępnym RAM-em, a nie powtarzające się żądanie do /. Uruchom scenariusz „utwórz kolekcję z docelowym rozmiarem wektora, wstaw punkty z payloadem, wykonaj filtrowane zapytanie nearest-neighbor i odtwórz snapshot kolekcji” przy realistycznym poziomie współbieżności, a następnie zapisz opóźnienie, współczynnik błędów i przyrost storage.

Planowanie aktualizacji musi uwzględniać następujące ryzyko: snapshoty kolekcji, kompatybilność formatu storage i zachowanie client library wymagają testów przed przeskokiem na nową wersję serwera. Przetestuj nowe wydanie na reprezentatywnych danych, a następnie powtórz transakcję akceptacyjną i porównaj jej wynik. Jeśli występują problemy z uprawnieniami do storage albo klient korzysta z portu 6334, podczas gdy routowany jest tylko port 6333, zarejestruj nieudaną transakcję i sprawdź pierwszą zaangażowaną granicę, zamiast zakładać, że odpowiada za to ingress.

Zmień smoke test Qdrant w kontrolę wydania

Kandydat do wydania Qdrant zasługuje na obsługę ruchu dopiero po ukończeniu stałego scenariusza: utwórz kolekcję z docelowym rozmiarem wektora, wstaw punkty z payloadem, wykonaj filtrowane zapytanie nearest-neighbor i odtwórz snapshot kolekcji. Zapisz digest obrazu, efektywną konfigurację niezawierającą sekretów, publiczny origin i znaczniki czasu dla tego scenariusza. Dane testowe powinny być nietrwałe, ale wystarczająco realistyczne, aby przejść tą samą ścieżką co użytkownicy.

Uruchom test po wymianie runtime, a następnie odtwórz usługę z snapshotów Qdrant i persistent storage directory. Odzyskiwanie kończy się powodzeniem, gdy snapshot odtwarza kolekcję z tą samą liczbą punktów, konfiguracją wektorów i reprezentatywnymi wynikami zapytań. Porównaj pomiary zasobów dotyczące wymiarów wektorów, budowania HNSW, indeksów payloadów, replik kolekcji oraz różnicy między danymi memory-mapped a dostępnym RAM-em z poprzednim wydaniem i zbadaj istotne odchylenia przed wdrożeniem.

Na koniec wykonaj kontrolowaną awarię: prześlij nieszkodliwy input blisko limitu zasobów lub formatu związanego z tą granicą: występują problemy z uprawnieniami do storage albo klient korzysta z portu 6334, podczas gdy routowany jest tylko port 6333. Sprawdź, czy Qdrant wyjaśnia przyczynę awarii, nie uszkadza istniejącego stanu i wznawia działanie po przywróceniu poprawnych warunków. Zapisz zredagowany fragment logu i czas odzyskiwania. Łącznie te testy obejmują zachowanie, trwałość i operacyjność, a nie tylko uptime procesu.

Sprawdź, czy Qdrant przetrwa wymianę

W przypadku Qdrant bezpieczeństwo redeploymentu zaczyna się od snapshotów Qdrant i persistent storage directory. Zamontuj /qdrant/storage przed bootstrapem, zapisz nieszkodliwe przykładowe dane i wymień kontener, aby potwierdzić, że ta ścieżka rzeczywiście jest persistent. Przetestuj ścieżkę, wymieniając kontener, gdy istnieją nieszkodliwe przykładowe dane; ujawni to mounty wskazujące katalog o jeden poziom za wysoko lub za nisko.

Następnie przetestuj disaster recovery na pustym hoście. W razie potrzeby użyj eksportu bazy danych spójnego z aplikacją i sprawdź, czy snapshot odtwarza kolekcję z tą samą liczbą punktów, konfiguracją wektorów i reprezentatywnymi wynikami zapytań. Przewodnik po backupach baz danych, które zostały odtworzone wyznacza lepszy cel niż samo sprawdzenie, czy utworzono plik archiwum.

Dane uwierzytelniające, role i udostępnione powierzchnie

W przypadku Qdrant wartościową powierzchnią niekoniecznie jest strona docelowa. Głównym błędem jest udostępnienie nieuwierzytelnionego API w internecie. Przeciwdziałaj temu świadomie: przyznaj usługom ingest scoped API access i pozostaw pełne administracyjne API na prywatnej trasie.

Traktuj QDRANT__SERVICE__API_KEY zgodnie z jego rolą w Qdrant: przechowuj wrażliwe wartości poza Gitem, udokumentuj skutki rotacji i nigdy nie zastępuj produkcyjnej wartości publicznym przykładem. Używaj nieuprzywilejowanego użytkownika kontenera, gdy obraz to obsługuje, i nie montuj niezwiązanych z usługą danych uwierzytelniających. Stosuj limity rate lub size na ingressie, gdy niezaufane operacje mogą zużywać wymiary wektorów, budowanie HNSW, indeksy payloadów, repliki kolekcji oraz różnicę między danymi memory-mapped a dostępnym RAM-em.

Przenieś powtarzalną pracę infrastrukturalną do Dockup

Dockup może zarządzać wymiennymi elementami platformy: kierować ruch na port 6333, wystawiać domenę i certyfikat, wstrzykiwać sekrety, podłączać persistent storage oraz łączyć Qdrant z usługami zarządzanymi lub prywatnie podłączonymi. Może robić to na infrastrukturze Dockup albo na podłączonym przez Ciebie serwerze.

Praca akceptacyjna dla Qdrant pozostaje jawnie określona. Po wdrożeniu one-click udostępniaj REST publicznie tylko wtedy, gdy klienci rzeczywiście tego wymagają, pozostaw gRPC prywatne, potwierdź lokalne wymaganie — wystarczającą ilość RAM-u i miejsca na dysku na wymiary wektorów, payloady i indeksy — oraz uruchom ten scenariusz: utwórz kolekcję z docelowym rozmiarem wektora, wstaw punkty z payloadem, wykonaj filtrowane zapytanie nearest-neighbor i odtwórz snapshot kolekcji. Ten podział jest celowy: Dockup usuwa powtarzalną konfigurację infrastruktury, nie udając, że role aplikacji, dane uwierzytelniające dostawców lub polityka odtwarzania wybiorą się same.

Najczęściej zadawane pytania

Czego Qdrant potrzebuje do wdrożenia produkcyjnego?

Skieruj kontener Qdrant na porcie 6333 przez jeden origin HTTPS. Lokalne wymagania runtime to wystarczająca ilość RAM-u i miejsca na dysku na wymiary wektorów, payloady i indeksy. Nie uznawaj Qdrant za gotowy, dopóki nie potrafisz utworzyć kolekcji z docelowym rozmiarem wektora, wstawić punktów z payloadem, wykonać filtrowanego zapytania nearest-neighbor i odtworzyć snapshotu kolekcji.

Które dane Qdrant powinny znaleźć się w backupie?

Utrwal /qdrant/storage i uwzględnij snapshoty Qdrant oraz persistent storage directory w tym samym recovery manifest. Poprawne odtworzenie Qdrant ma miejsce tylko wtedy, gdy snapshot odtwarza kolekcję z tą samą liczbą punktów, konfiguracją wektorów i reprezentatywnymi wynikami zapytań.

Czy Qdrant wymaga HTTPS za reverse proxy?

Używaj HTTPS dla publicznego originu Qdrant i pozostaw port 6333 na trasie wewnętrznej. Zastosuj ustawienie Qdrant poprawnie: udostępniaj REST publicznie tylko wtedy, gdy klienci rzeczywiście tego wymagają, a gRPC pozostaw prywatne. W przypadku Qdrant HTTPS chroni dane uwierzytelniające lub treści użytkowników podczas transmisji i zapewnia spójne zachowanie klienta zależne od originu.

Jak testować aktualizację Qdrant?

Odtwórz bieżący stan Qdrant w izolowanym wdrożeniu, zastosuj wersję kandydującą i powtórz transakcję akceptacyjną. Zwróć szczególną uwagę na to, że snapshoty kolekcji, kompatybilność formatu storage i zachowanie client library wymagają testów przed przeskokiem na nową wersję serwera. Zachowaj poprzedni obraz Qdrant, dopóki nie poznasz granic migracji danych i rollbacku.