Эксплуатация

Установка описана в Быстром старте. Здесь — что делать с сервером после неё.

Состояние сервера

Что	Где
Служба	systemctl status forgevis
Журнал службы	journalctl -u forgevis
Файлы журнала	/var/log/forgevis/
Конфигурация	/etc/forgevis/config.yaml, /etc/forgevis/conf.d/
Рабочий каталог	/var/lib/forgevis
Состояние узла кластера	/var/lib/forgevis/data (cluster.dataDir)

Сервер готов к работе, когда отвечает 200:

curl http://localhost:9997/api/health/ready

Ответ 503 перечисляет, какая проверка не прошла: хранилище, каталог записи, лицензия, состояние кластера. Метрики и дашборд — в разделе Мониторинг.

Обновление версии

Пакет обновляется поверх установленного. Изменённый config.yaml при этом остаётся вашим. Если в новой версии поменялся и конфиг из пакета, dpkg спросит, какой оставить: ответ по умолчанию сохраняет ваш, а rpm кладёт пакетный рядом как config.yaml.rpmnew.

Debian / Ubuntu

sudo dpkg -i forgevis_*.deb
sudo systemctl restart forgevis

RHEL / Rocky / AlmaLinux

sudo rpm -U forgevis-*.rpm
sudo systemctl restart forgevis

Пакет не перезапускает службу сам: пока её не перезапустили, работает прежняя версия. На время перезапуска запись прерывается: служба останавливается штатно и закрывает открытые файлы записи.

После перезапуска проверьте /api/health/ready и что версия новая:

curl http://localhost:9997/api/health/ready

Кластер

Обновляйте узлы по одному. Следующий — только когда предыдущий снова готов (/api/health/ready отвечает 200) и числится в сети в GET /cluster/metrics.

Что происходит с камерами, пока узел перезапускается:

• узел, который не отвечает дольше 15 секунд, считается недоступным, и примерно через 15–20 секунд его камеры переезжают на другие узлы;
• если узел был лидером, кластер за несколько секунд выбирает нового.

Резервная копия

Сохраняйте каталог /etc/forgevis целиком:

• config.yaml и conf.d/ — настройки и камеры;
• forgevis.lic — файл лицензии;
• сертификаты TLS, если они лежат там.

Состояние узла кластера (cluster.dataDir) из копии не восстанавливают: узел с устаревшим журналом Raft нарушает работу кластера. Узел заводят в кластер заново — см. ниже.

Архив записей в эту копию не входит: его объём и срок хранения — отдельное решение, см. Очистка архива.

Восстановление

Сервер с нуля

1. Установите пакет той же версии.
2. Верните /etc/forgevis из копии.
3. Если диск с архивом уцелел, подключите его по тому же пути, что в record_path: записи находятся по шаблону пути и имени файла.
4. Запустите службу: sudo systemctl enable --now forgevis.

Узел кластера

Записи в базе привязаны к имени узла (nodeName), а файлы лежат на его дисках. Поэтому узел по возможности возвращают в кластер тем же сервером или хотя бы под тем же именем — тогда его архив остаётся доступен.

Сервер жив, но узел не работает в кластере — не догоняет журнал, числится офлайн при живом процессе, не может вернуться после сбоя. Узел выводят из кластера со сбросом состояния и заводят обратно: чистое состояние догонит кластер с нуля.

1. На самом узле:

   curl -X POST http://<узел>:9997/cluster/leave \
        -H 'Content-Type: application/json' -d '{}'

   Узел сам уходит из состава, останавливает свои камеры и стирает своё состояние Raft. Перезапуск не нужен. Если кластер не может принять изменение состава (например, нет лидера), добавьте "force": true — тогда уберите узел из состава отдельно, POST /cluster/remove-node на лидере.
2. Добавьте узел обратно, как при сборке кластера: add-learner, затем change-membership. Узел получает состояние от лидера и снова берёт камеры.

Ключ и сертификат при этом сохраняются. Если узел не отвечает на API и состояние пришлось удалить вручную (остановить службу, удалить <dataDir>/node_<node_id>, запустить), ключ и сертификат удаляются вместе с ним — выдайте сертификат заново, см. Сертификаты.

Сервер вышел из строя целиком. Такой узел заменяют другим сервером: с дисками или дисковыми полками прежнего и под тем же именем.

1. Уберите узел из состава: POST /cluster/remove-node на лидере. Его камеры к этому времени уже переехали, но голос недоступного узла по-прежнему учитывается: в кластере из трёх узлов с одним мёртвым ещё один отказ оставит кластер без большинства.
2. Переключите диски или дисковые полки с архивом на новый сервер. Задайте тот же nodeName и тот же record_path. Пока этого не сделано, записи узла недоступны.
3. Выдайте узлу сертификат — см. Сертификаты — и заведите его в кластер, как при сборке кластера.

Другие ситуации

Служба не запускается. Конфигурация проверяется при запуске. Причина — в journalctl -u forgevis -b: сообщение называет ключ, который нужно исправить.

Узел кластера недоступен. Его камеры переезжают на другие узлы примерно через 15–20 секунд. Когда узел вернётся, проверьте /api/health/ready на нём и его статус в GET /cluster/metrics.

Узел отрезан от кластера. Кластеру нужно большинство голосующих узлов: из трёх он переживает потерю одного, из двух — ни одного. Узел, потерявший связь с большинством, продолжает писать свои камеры, а остальные через 15–20 секунд назначают эти же камеры другим узлам. Пока связь не восстановлена, камеру держат два узла: два подключения к камере и две записи. Если связь пропала надолго, остановите службу на отрезанном узле:

sudo systemctl stop forgevis

Когда связь восстановится, запустите её снова.

Кластер без большинства. Если недоступно больше половины голосующих узлов, кластер не выбирает лидера и не переназначает камеры. Оставшиеся узлы продолжают писать то, что было назначено им до сбоя.