Як розгорнути Qdrant на власній інфраструктурі у 2026 році: сховище, API-ключі та резервні копії

Розгортання Qdrant на власній інфраструктурі стає по-справжньому важливим під час першого повторного розгортання, а не після першого docker run. Якщо виникають проблеми з дозволами на сховище або клієнт використовує порт 6334, тоді як маршрутизується лише 6333, Docker усе одно може повідомляти про повністю працездатний процес. Наведене нижче розгортання побудоване навколо спостережуваної поведінки: створити колекцію з потрібним розміром векторів, додати точки з payload, виконати фільтрований пошук найближчих сусідів і відновити snapshot колекції.

Призначення Qdrant визначене однозначно: vector database для embedding і retrieval-систем. Цей опис показує, що має залишатися публічним, що слід тримати приватним і що саме повинна відновлювати резервна копія.

Вивчіть Qdrant перед роботою з Docker

Не дозволяйте образу Qdrant випадково визначити production-архітектуру. Образ надає процес на порту 6333, але для сховища, маршрутизації та зовнішніх вимог усе одно потрібні продумані життєві цикли. Локальна вимога до середовища виконання — достатній обсяг RAM і дискового простору для розмірностей векторів, payload та індексів. Задокументуйте очікувану місткість, власника та сценарій відмови, а не залишайте їх як налаштування образу за замовчуванням.

Розгортання готове до глибшого тестування, коли воно може створити колекцію з потрібним розміром векторів, додати точки з payload, виконати фільтрований пошук найближчих сусідів і відновити snapshot колекції. Відстежуйте транзакцію в логах і контролюйте розмірності векторів, побудову HNSW, індекси payload, репліки колекцій та різницю між memory-mapped даними й доступним обсягом RAM. Ці спостереження показують, чи ізолює поточна топологія потрібний компонент.

Маршрутизуйте Qdrant, не створюючи хибного враження щодо HTTPS

Виберіть остаточне ім’я хоста Qdrant до того, як користувачі збережуть callback-адреси або налаштування клієнта. Залишайте REST публічним лише тоді, коли клієнтам це справді потрібно, а gRPC тримайте приватним. Маршрут платформи має завершувати TLS один раз і спрямовувати трафік на приватний порт 6333.

Запускайте acceptance-транзакцію ззовні. Якщо клієнт не досягає Qdrant, скористайтеся контрольним списком перевірки SSL для перевірки DNS і сертифіката. Якщо запит доходить до Qdrant, але виникають проблеми з дозволами на сховище або клієнт використовує порт 6334, тоді як маршрутизується лише 6333, припиніть змінювати proxy-redirect і перевірте межу, специфічну для застосунку.

Перетворіть локальну команду на сервіс, який можна перевірити

Використовуйте команду, яка явно задає всі важливі параметри. Ця базова конфігурація прив’язує Qdrant до loopback-інтерфейсу хоста, додає відомі монтування даних і передає перше обов’язкове налаштування. Перед відкриттям доступу перевірте локальну вимогу: достатній обсяг RAM і дискового простору для розмірностей векторів, payload та індексів.

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

Замініть плаваючі теги на протестовану версію або digest. Після запуску перегляньте docker logs --tail 200 qdrant і переконайтеся, що процес слухає порт 6333. Потім виконайте acceptance-дію Qdrant: відповідь кореневої сторінки не доводить успішність усього сценарію — потрібно створити колекцію з потрібним розміром векторів, додати точки з payload, виконати фільтрований пошук найближчих сусідів і відновити snapshot колекції.

Оновлюйте Qdrant без припущень

Тести місткості мають перевіряти розмірності векторів, побудову HNSW, індекси payload, репліки колекцій та різницю між memory-mapped даними й доступним обсягом RAM, а не повторний запит до /. Запускайте сценарій «створити колекцію з потрібним розміром векторів, додати точки з payload, виконати фільтрований пошук найближчих сусідів і відновити snapshot колекції» за реалістичної concurrency та фіксуйте latency, error rate і зростання обсягу сховища.

Планування оновлення має враховувати такі ризики: snapshot колекцій, сумісність форматів сховища та поведінку client library потрібно тестувати до переходу на нову версію сервера. Протестуйте новий реліз на репрезентативних вхідних даних, потім повторіть acceptance-транзакцію та порівняйте результат. Якщо виникають проблеми з дозволами на сховище або клієнт використовує порт 6334, тоді як маршрутизується лише 6333, зафіксуйте транзакцію, що завершується помилкою, і перевірте першу залучену межу, замість того щоб автоматично вважати причиною ingress.

Перетворіть smoke test Qdrant на перевірку релізу

Release candidate для Qdrant отримує право обслуговувати трафік після виконання фіксованого сценарію: створити колекцію з потрібним розміром векторів, додати точки з payload, виконати фільтрований пошук найближчих сусідів і відновити snapshot колекції. Зафіксуйте digest образу, фактичну конфігурацію без секретів, публічний origin і часові мітки цього сценарію. Тестові дані мають бути одноразовими, але достатньо реалістичними, щоб проходити той самий шлях, що й користувацькі дані.

Запустіть цей тест після заміни середовища виконання, а потім відновіть сервіс із snapshot Qdrant і каталогу постійного сховища. Відновлення вважається успішним, якщо snapshot відтворює колекцію з тією самою кількістю точок, конфігурацією векторів і репрезентативними результатами запитів. Порівняйте з попереднім релізом вимірювання ресурсів для розмірностей векторів, побудови HNSW, індексів payload, реплік колекцій та різниці між memory-mapped даними й доступним обсягом RAM. Перед promotion дослідіть будь-які суттєві відхилення.

Насамкінець перевірте контрольовану відмову: передайте безпечні вхідні дані поблизу ресурсного або форматного обмеження, пов’язаного з цією межею: виникають проблеми з дозволами на сховище або клієнт використовує порт 6334, тоді як маршрутизується лише 6333. Переконайтеся, що Qdrant пояснює причину помилки, не пошкоджує наявний стан і відновлює роботу після повернення коректної умови. Збережіть редагований фрагмент логу та час відновлення. Разом ці перевірки охоплюють поведінку, довговічність даних і зручність експлуатації, а не лише доступність процесу.

Доведіть, що Qdrant переживає заміну

Для Qdrant безпечне повторне розгортання починається зі snapshot Qdrant і каталогу постійного сховища. Монтуйте /qdrant/storage до bootstrap, записуйте безпечні тестові дані та замінюйте контейнер, щоб довести фактичну постійність цього шляху. Перевірте шлях, замінивши контейнер, поки безпечні тестові дані ще існують: це виявляє монтування, спрямовані на каталог на один рівень вище або нижче.

Потім перевірте disaster recovery на чистому хості. За потреби використовуйте export бази даних, узгоджений із застосунком, і переконайтеся, що snapshot відтворює колекцію з тією самою кількістю точок, конфігурацією векторів і репрезентативними результатами запитів. Посібник із резервного копіювання бази даних із перевіреним відновленням задає надійнішу ціль, ніж проста перевірка факту створення архіву.

Облікові дані, ролі та відкриті поверхні

Для Qdrant цінною поверхнею не обов’язково є landing page. Головна помилка — опублікувати API без автентифікації в інтернеті. Цілеспрямовано запобігайте цьому: надавайте ingestion-сервісам API-доступ із потрібними обмеженнями, а повний адміністративний API залишайте на приватному маршруті.

Ставтеся до QDRANT__SERVICE__API_KEY відповідно до його ролі в Qdrant: не зберігайте чутливі значення в Git, документуйте наслідки ротації та ніколи не використовуйте публічний приклад у production. Використовуйте непривілейованого користувача контейнера, якщо образ це підтримує, і не монтуйте сторонні облікові дані. Застосовуйте обмеження rate або size на ingress там, де ненадійні операції можуть споживати ресурси на розмірності векторів, побудову HNSW, індекси payload, репліки колекцій та різницю між memory-mapped даними й доступним обсягом RAM.

Перенесіть повторювану інфраструктурну роботу до Dockup

Dockup може відповідати за замінні компоненти платформи: спрямовувати трафік на порт 6333, випускати домен і сертифікат, передавати секрети, підключати постійне сховище та з’єднувати Qdrant із керованими або приватно підключеними сервісами. Це можна робити на інфраструктурі Dockup або на підключеному вами сервері.

Acceptance-робота для Qdrant залишається явною. Після one-click deployment залишайте REST публічним лише тоді, коли клієнтам це справді потрібно, а gRPC тримайте приватним; переконайтеся в локальній вимозі — достатньому обсязі RAM і дискового простору для розмірностей векторів, payload та індексів — і запустіть цей сценарій: створіть колекцію з потрібним розміром векторів, додайте точки з payload, виконайте фільтрований пошук найближчих сусідів і відновіть snapshot колекції. Такий поділ навмисний: Dockup усуває повторюване налаштування інфраструктури, не вдаючи, що ролі застосунку, облікові дані провайдера або політика відновлення визначаються самі собою.

Поширені запитання

Що потрібно Qdrant для production-розгортання?

Маршрутизуйте контейнер Qdrant через один HTTPS origin на порт 6333. Локальна вимога до середовища виконання — достатній обсяг RAM і дискового простору для розмірностей векторів, payload та індексів. Не вважайте Qdrant готовим, доки не зможете створити колекцію з потрібним розміром векторів, додати точки з payload, виконати фільтрований пошук найближчих сусідів і відновити snapshot колекції.

Які дані Qdrant потрібно включати до резервної копії?

Зберігайте /qdrant/storage і включайте snapshot Qdrant та каталог постійного сховища до одного recovery manifest. Чисте відновлення Qdrant вважається успішним лише тоді, коли snapshot відтворює колекцію з тією самою кількістю точок, конфігурацією векторів і репрезентативними результатами запитів.

Чи потрібен Qdrant HTTPS за reverse proxy?

Використовуйте HTTPS для публічного origin Qdrant, а порт 6333 залишайте на внутрішньому маршруті. Коректно застосовуйте налаштування Qdrant: залишайте REST публічним лише тоді, коли клієнтам це справді потрібно, а gRPC тримайте приватним. Для Qdrant HTTPS захищає облікові дані або користувацький контент під час передавання та забезпечує узгоджену поведінку клієнта, чутливу до origin.

Як тестувати оновлення Qdrant?

Відновіть поточний стан Qdrant в ізольованому розгортанні, застосуйте candidate-версію та повторіть acceptance-транзакцію. Це особливо важливо, оскільки snapshot колекцій, сумісність форматів сховища та поведінку client library потрібно тестувати до переходу на нову версію сервера. Зберігайте попередній образ Qdrant, доки не буде зрозуміло межі міграції даних і rollback.