Обновление#

Важно

Перед обновлением рекомендуется выполнить резервное копирование БД.
Принудительное удаление предыдущей версии не требуется. Необходимо перегенерировать ключи Secman.

Обновление/установка Platform V Vector DB (далее - Vector DB) выполняется с помощью архива. Архив распаковывается в один каталог. Каталог содержит бинарные файлы и конфигурационные файлы, которые расположены в подкаталогах. Особенностью установки из архива является отсутствие необходимости получения прав корневого администратора (root) и возможность установки на любом дистрибутиве ОС.

В зависимости от выбранного способа установки, предусмотрено несколько сценариев обновления:

Базовый сценарий обновления
Сценарий обновления кластера

Изменения в системных требованиях#

Для версии 2.0.0 программного продукта отсутствуют изменения в ПО.

Изменения в параметрах настройки#

Параметр	Значение по умолчанию	Пример заполнения	Описание
`tls.supported_versions`	`['tls1.2', 'tls1.3']`	`['tls1.2', 'tls1.3']`	Параметр , позволяющий задать список поддерживаемых версий протокола TLS Может быть `null`, пустой список `[ ]` или отсутствовать — в этом случае применяются значения по умолчанию
`cluster.mode.arbiter`	`false`	`false`	Параметр, определяющий, будет ли узел запущен в режиме арбитра. Режим применяется при первоначальном подключении к кластеру (bootstrap). Если bootstrap сервер не указан и `arbiter=true`, узел не стартует. При включенном режиме арбитра узел не сохраняет данные локально, а перенаправляет пользовательские запросы на другие узлы кластера
`ephemeral_api_key.enable`	`false`	`false`	Флаг функций, активирующий механизм ротации временных ключей. Если установлен в значение `true`, ключ автоматически обновляется согласно настройкам
`ephemeral_api_key.rotation_interval`	`24h`	`48h`	Интервал времени, определяющий частоту обновления ключ
`ephemeral_api_key.storage_path`		`"/home/<username>/qdrant_consensus/master"`	Путь к каталогу на файловой системе, используемый для долговременного хранения зашифрованного значения API-ключа. Данный параметр является необязательным. Если он отсутствует, API-ключ сохраняется в основной директории хранилища компонентов (`storage.storage_path`). Файл для долговременного хранения APIKEY должен сохранять с правами `600`, независимо от выбранного местоположения
`cluster.consensus.leader_lost_lock_enabled`	`false`	`false`	Активация механизма защиты от split brain (защита от неконсистентности данных при split brain в распределенном кластере за счет блокировки операций записи и модификации на узлах, потерявших связь с кворумом, предотвращая тем самым расхождение реплик в условиях сетевого разделения). При активации механизма защиты от spit brain и по истечении таймаута блокируются мутирующие операции над данными
`cluster.consensus.leader_lost_lock_timeout_sec`	`10`	`10`	Время в секундах, в течение которого узел, потерявший кворум, продолжает полноценную работу с данными
`auth.storage_path`		`"/home/<username>/qdrant_consensus/master"`	Место, где хранится состояние Role-Based Access Control (Ролевой модели доступа). Является обязательным для заполнения, если `enable_rbac` имеет значение `true`
`auth.subject_regex`		`"CN=([^,]+)"`	Regex для поля `Subject` сертификата
`auth.bootstrap`		`principals_to_roles:` `bob: ["some-role"]` `roles:` `some-role:` `- read_role` `- write_role` `- read_principal` `- write_principal`	Перечисление принципалов и ролей с привилегиями для первоначальной настройки ролевой модели
`auth_flow`	`LocalStorage`, `Bootstrap`, `Ldap`	`LocalStorage`, `Bootstrap`, `Ldap`	Упорядоченный список методов аутентификации. Методы проверяются последовательно до первого успешного результата

Если для параметра tls.supported_versions указана недопустимая версия (например, 'tls1.1') - Qdrant не запускается и выводит понятную ошибку валидации.
При отсутствии в конфигурации секции ephemeral_api_key или параметр ephemeral_api_key.enable имеет значение false, доступ к компоненту осуществляется посредством постоянного ключа, указанного в параметре service.api_key.

Базовый сценарий обновления#

Этот сценарий подходит для случаев, когда Vector DB был установлен вручную на сервере — например, через распаковку официального архива в домашнюю директорию или /opt.

Шаг 1. Подготовка#

Остановите Vector DB, если он запущен.
- Если запускали вручную: нажмите Ctrl + C в терминале.
- Если настроили как сервис через systemd:
```
sudo systemctl stop qdrant
```
Создайте резервную копию данных. Данные находятся в директориях storage и snapshots, которые лежат рядом со старым бинарным файлом.
```
cp -r ./storage /backup/storage-$(date +%Y%m%d)
cp -r ./snapshots /backup/snapshots-$(date +%Y%m%d)
```
Либо скопируйте всю директорию Vector DB целиком.

Шаг 2. Загрузка нового архива#

Скачайте новый архив с дистрибутивом.

Шаг 3. Замена бинарного файла#

Распакуйте скачанный архив во временную папку:
```
mkdir -p /tmp/qdrant-new
tar -xzf Vector-DB-XYZ.tar.gz -C /tmp/qdrant-new/
```
Замените старый исполняемый файл новым.
- Если запускаете Vector DB из /opt/qdrant:
```
# Перейдите в рабочую директорию со старым {{prod_name}}
cd /opt/qdrant

# Замените бинарный файл
cp /tmp/qdrant-new/qdrant ./qdrant
```
Важно

Папки storage, snapshots и конфигурационные файлы не трогайте и не удаляйте.

Шаг 4. Права доступа (обязательно)#

После замены файла нужно убедиться, что у него есть права на исполнение:

chmod +x /opt/qdrant/qdrant

Шаг 5. Запуск и проверка#

Запустите Qdrant:
- Если используете systemd:
```
sudo systemctl start qdrant
```
- Если вручную:
```
./qdrant
```
Проверьте, что Qdrant отвечает на запросы (например, через HTTP API):
```
curl http://localhost:6333/collections
```
Успешным результатом считается JSON-ответ с информацией о коллекциях или успешным статусом 200 OK

Сценарий обновления кластера#

Кластер обновляется по одному узлу за раз. Не останавливайте весь кластер целиком, а последовательно заменяйте бинарные файлы на каждом узле, давая кластеру время восстановить репликацию.

Условия для Zero-Downtime обновления

Чтобы обновление прошло без остановки сервиса, должны соблюдаться оба условия:

Конфигурация кластера: 2 и более узлов.
Настройки коллекций: Для каждой коллекции установлен replication factor ≥ 2 (то есть данные имеют минимум одну резервную копию на другом узле) .

Если коллекции с replication factor = 1, при выключении узла данные на нем станут недоступны. В этом случае потребуется окно простоя (maintenance window).

Шаги обновления#

Шаг 1: Подготовка (обязательно!)
Шаг 2: Обновление узлов (по очереди)
Шаг 3: Проверка

Шаг 1: Подготовка (обязательно!)#

Проверьте путь обновления: Убедитесь, что не прыгаете через минорные версии (например, 1.12.x → 1.13.x, но не 1.11.x → 1.13.x).
Сделайте полный бэкап:
- Создайте снепшоты (snapshots) всех коллекций через API.
- Сохраните конфигурационные файлы с каждого узла (они могут немного отличаться, если настраивались параметры конкретного узла).
Проверьте совместимость клиентов: Убедитесь, что приложение (SDK) готово к новой версии.

Шаг 2: Обновление узлов (по очереди)#

Для каждого узла кластера повторяйте следующие шаги, переходя к следующему узлу только после полного восстановления предыдущего.

На целевом узле:

Переведите узел в режим «Drain» (Рекомендуется): Это заставит кластер переместить лидеров шардов (shard leaders) с этого узла на другие, чтобы он не участвовал в записи во время перезагрузки.
```
curl -X POST "http://<IP-узла>:6333/cluster/peer/<ID-узла>/drain?type=all"
```
Остановите Qdrant на узле:
```
sudo systemctl stop qdrant
```
Замените бинарный файл:
- Скачайте новый архив с дистрибутивом.
- Распакуйте и замените Qdrant в рабочей директории (например, /opt/qdrant/).
Выдайте права на исполнение:
```
chmod +x /opt/qdrant/qdrant
```
Запустите Qdrant на узле:
```
sudo systemctl start qdrant
```
Проверьте состояние узла и кластера:
```
# Статус узла
curl "http://<IP-узла>:6333/readyz"
# Должен вернуть "OK"

# Состояние кластера (здоровье, статус пиров)
curl "http://<IP-узла>:6333/cluster"
```
Убедитесь, что узел вернулся в кластер как Active и состояние Green. Подождите, пока синхронизируются данные (если они были).
Включите узел обратно (если использовали drain): Если переводили узел в режим drain, теперь нужно активировать его для записи:
```
curl -X POST "http://<IP-узла>:6333/cluster/peer/<ID-узла>/resume"
```

Шаг 3: Проверка#

После обновления всех узлов выполните глобальную проверку:

# Проверьте версию всех узлов (они должны быть одинаковыми)
curl "http://<любой-узел>:6333/cluster" | grep version

# Запустите тестовые запросы поиска
curl -X POST "http://<любой-узел>:6333/collections/<test_collection>/points/search" ...

Проверка обновления#

Выполните проверку выполнения каждого из перечисленных действий в выбранном сценарии обновления настоящего Руководства.
Выполните проверку работоспособности продукта, следуя инструкции в подразделе «Проверка корректности работы продукта» раздела Чек-лист проверки корректности работы настоящего Руководства.