Руководство по развёртыванию

1. Предварительные требования

Серверы и ПО

Чек-лист перед началом

• Docker и Docker Compose установлены и работают
• Git установлен, есть доступ к репозиторию (SSH-ключ настроен)
• Достаточно ОЗУ и дискового пространства

2. Инициализация баз данных

Кастомный образ PostgreSQL

Образ собирается из database/postgres/Dockerfile на базе TimescaleDB HA (PG 17.9, TS 2.25.2) и включает расширения, необходимые для работы сервисов:

Порядок выполнения init-скриптов

При первом запуске контейнера PostgreSQL скрипты из database/postgres/init/ выполняются в лексикографическом порядке:

Что создаётся автоматически

Flyway-миграции БД refts (выполняются автоматически сервисом ts-loader)

Помимо init-скриптов, сервис ts-loader при первом запуске выполняет Flyway-миграции в БД refts:

Тестирование инициализации изолированно

Для проверки корректности init-скриптов без влияния на рабочее окружение используйте скрипт:

# Linux / macOS bash database/postgres/scripts/run-init-isolated.sh # Windows (PowerShell) .\database\postgres\scripts\run-init-isolated.ps1

Опциональные политики (после запуска)

-- Подключиться к БД refts
psql -U adv -h localhost -d refts

-- Политика удержания данных (~18 месяцев)
SELECT add_retention_policy('monraw.traffic', drop_after => 47304000);
SELECT add_retention_policy('monraw.tfc_sensor', drop_after => 47304000);
SELECT add_retention_policy('monraw.tfc_sensor_str', drop_after => 47304000);

-- Политика сжатия (через 1 день) -- Настроить compression и add_compression_policy для каждой гипертаблицы

3. Apache Kafka

Kafka входит в состав Docker Compose и запускается как контейнер kafka (образ apache/kafka:3.9.0) в режиме KRaft (без Zookeeper). Дополнительная настройка не требуется.

Справочник топиков

4. Клонирование репозитория

# Клонирование с субмодулями (обязательно!) git clone --recurse-submodules git@gitlab.advantum.ru:vibecoding/ref-vc.git
cd ref-vc

# Если уже склонировано без субмодулей
git submodule update --init --recursive

Структура субмодулей (17 штук)

5. Конфигурация

Шаг 5.1. Файл .env

# Скопировать шаблон cp .env.example .env # Отредактировать параметры
nano .env

Шаг 5.2. Конфигурация хаба (hub-config.xml)

Файл находится в settings/backend/hub-wialon-combine-v2/hub-config.xml. Он монтируется в контейнер hub-wialon-combine-v2 и содержит маппинг протокольных сенсоров.

6. Сборка Docker-образов

# Сборка всех 18 образов (первый раз — 15-40 минут) docker compose build # Или сборка конкретного сервиса
docker compose build config-service

Что происходит при сборке

7. Запуск системы

# Запуск всей системы в фоне docker compose up -d # Просмотр логов запуска
docker compose logs -f

# Просмотр логов конкретного сервиса
docker compose logs -f config-service

Порядок запуска (автоматический через depends_on)

1. postgres — запускается первым, выполняет init-скрипты (создание БД, схем, таблиц, справочников). Healthcheck ждёт полного завершения инициализации
2. kafka — запускается после postgres (KRaft-режим, готов за ~10 секунд)
3. admin-service — зависит от postgres (healthcheck)
4. config-service, hub-config-service-v2, restauth, ts-loader, ref-jofl-service — зависят от postgres (healthcheck) + admin-service
5. raw-rest-service, alarm-service, recent-values-* — зависят от config-service
6. hub-wialon-combine-v2 — зависит от hub-config-service-v2 и kafka
7. aggr-rest-service — зависит от raw-rest-service
8. aggr-builder-service, custom-online-info — зависят от aggr-rest-service
9. online-info-v2 — зависит от alarm-service и recent-values-v2
10. xls-pdf-report-service, db-report-service — зависят от aggr-builder-service
11. jsofl2 — зависит от ref-jofl-service

8. Верификация и проверка здоровья

# Статус всех контейнеров docker compose ps # Проверка healthcheck
docker inspect --format='{{.State.Health.Status}}' admin-service
docker inspect --format='{{.State.Health.Status}}' config-service

# Массовая проверка здоровья for s in postgres kafka admin-service config-service \
  hub-config-service-v2 hub-wialon-combine-v2 ts-loader \
  raw-rest-service aggr-rest-service aggr-builder-service \
  alarm-service restauth online-info-v2 custom-online-info \
  recent-values-service recent-values-v2-service \
  xls-pdf-report-service db-report-service \
  ref-jofl-service jsofl2; do
  echo "$s: $(docker inspect --format='{{.State.Health.Status}}' $s 2>/dev/null || echo 'NOT FOUND')"
done

Что проверить после запуска

9. Карта портов

10. Логирование

Логи каждого сервиса записываются в файлы внутри контейнера и маунтятся в ./logs/:

# Структура директорий логов (создаётся Docker автоматически при маунте)
logs/
├── backend/
│   ├── admin-service/
│   ├── config-service/
│   ├── hub-config-service-v2/
│   ├── hub-wialon-combine-v2/
│   ├── ts-loader/
│   ├── raw-rest-service/
│   ├── aggr-rest-service/
│   ├── aggr-builder-service/
│   ├── alarm-service/
│   ├── restauth/
│   ├── xls-pdf-report-service/
│   ├── db-report-service/
│   ├── online-info-v2/
│   ├── custom-online-info/
│   ├── recent-values-service/
│   ├── recent-values-v2-service/
│   └── ref-jofl-service/
└── frontend/
    └── jsofl2/           # Nginx access/error logs

Ротация: большинство сервисов настроены на LOGGING_FILE_MAX-HISTORY: 3 (хранить 3 файла истории).

11. Обслуживание и обновление

Обновление кода

# Остановить систему
docker compose down

# Обновить код и субмодули git pull --recurse-submodules
git submodule update --recursive

# Пересобрать и запустить docker compose build && docker compose up -d

Перезапуск отдельного сервиса

docker compose restart config-service # Или с пересборкой
docker compose up -d --build config-service

Очистка

# Удалить остановленные контейнеры и неиспользуемые образы
docker system prune -f

# Удалить все образы проекта для полной пересборки
docker compose down --rmi local

Резервное копирование БД

# Дамп справочной БД (через контейнер postgres) docker compose exec postgres pg_dump -U adv -d ref -F c -f /tmp/ref_backup.dump docker compose cp postgres:/tmp/ref_backup.dump ./ref_backup_$(date +%Y%m%d).dump # Дамп телеметрической БД docker compose exec postgres pg_dump -U adv -d refts -F c -f /tmp/refts_backup.dump docker compose cp postgres:/tmp/refts_backup.dump ./refts_backup_$(date +%Y%m%d).dump # Или через pg_dump с хоста (если установлен клиент PostgreSQL)
pg_dump -U adv -h localhost -p 5432 -d ref -F c -f ref_backup_$(date +%Y%m%d).dump

12. Устранение неполадок

Контейнер не запускается / перезапускается

# Посмотреть логи контейнера
docker compose logs --tail=100 имя_сервиса

# Проверить статус healthcheck
docker inspect имя_сервиса | grep -A 10 Health

Частые проблемы

Полезные команды диагностики

# Все контейнеры и их статусы
docker compose ps -a

# Использование ресурсов
docker stats --no-stream

# Зайти внутрь контейнера
docker compose exec config-service sh

# Проверить подключение к Kafka изнутри контейнера
docker compose exec ts-loader sh -c "nc -zv kafka 9092"

# Проверить подключение к БД изнутри контейнера
docker compose exec config-service sh -c "nc -zv postgres 5432"

# Подключиться к БД напрямую через контейнер postgres
docker compose exec postgres psql -U adv -d ref

# Проверить, что init-скрипты отработали корректно
docker compose exec postgres psql -U adv -d ref -c "SELECT count(*) FROM refr.account"