Установка PanDev Metrics on-prem
Кратко. Гайд проводит администратора через установку PanDev Metrics on-prem на Docker Compose примерно за 60 минут. К концу процедуры запущен backend на порту 8080, frontend за reverse proxy, PostgreSQL 17 на отдельном хосте и проверенный health-check. Аудитория: администратор.
Что понадобится
- Два Linux-хоста, удовлетворяющие системным требованиям: один для backend + frontend, второй для PostgreSQL (Redis опционален — нужен только для горизонтального шарирования сессий)
- На application-хосте — Docker Engine ≥ 20.10 и Docker Compose ≥ v2.0 (рекомендуется v2.20+)
- PostgreSQL 17 — установленный на database-хосте или доступный как managed-инстанс с application-хоста
- Доступный hostname и TLS-сертификат для публичного endpoint (PanDev Metrics также работает с самоподписанным сертификатом, если отключить SSL-валидацию на клиенте)
- Исходящий HTTPS-доступ к вашему Git-провайдеру и таск-трекеру — egress минимальный, но отключить нельзя
- Архив дистрибутива PanDev Metrics от вашего менеджера
PanDev Metrics on-prem — установка на одну организацию. Не закладывайтесь на multi-tenant разделение: это возможно только в Cloud. Air-gapped развёртывания не поддерживаются.
Шаг 1 — Подготовьте database-хост
Установите PostgreSQL 17 на выделенный database-хост. Создайте базу, роль и выдайте права владельца:
CREATE ROLE pandev WITH LOGIN PASSWORD '<STRONG_DB_PASSWORD>';
CREATE DATABASE pandev_metrics OWNER pandev;
GRANT ALL PRIVILEGES ON DATABASE pandev_metrics TO pandev;
Разрешите подключения с application-хоста в pg_hba.conf и перезагрузите PostgreSQL. PanDev Metrics применяет схему и миграции Flyway автоматически при первом старте — таблицы вручную создавать не нужно.
Шаг 2 — Подготовьте application-хост
Создайте рабочую директорию и положите туда архив дистрибутива:
sudo mkdir -p /opt/pandev
sudo chown "$USER":"$USER" /opt/pandev
cd /opt/pandev
unzip /tmp/pandev_metrics_latest.zip -d .
В архиве — docker-compose.yml, файл .env.example и сопутствующие конфиги. Скопируйте пример в реальный .env, который будете редактировать на следующем шаге:
cp .env.example .env
Шаг 3 — Настройте переменные окружения
Откройте .env и подставьте значения под вашу среду. Минимальный набор для свежей установки:
| Переменная | Назначение | Пример |
|---|---|---|
DB_URL | JDBC URL вашей PostgreSQL 17 | jdbc:postgresql://db.internal:5432/pandev_metrics |
DB_USERNAME | Пользователь БД из шага 1 | pandev |
DB_PASSWORD | Пароль пользователя БД | <STRONG_DB_PASSWORD> |
DB_SCHEMA | Схема для таблиц PanDev | public |
SPRING_DATA_REDIS_HOST | Hostname Redis (опционально — задавайте, только если развернули Redis) | redis |
SPRING_DATA_REDIS_PORT | Порт Redis (опционально) | 6379 |
SERVER_PORT | HTTP-порт backend | 8080 |
AI_AGENT_DB_PASSWORD | Пароль read-only AI-роли в БД (зарезервирован под будущий функционал; всё равно задайте надёжный) | <STRONG_AI_DB_PASSWORD> |
APPLICATION_IS_CLOUD | Маркер on-prem | false |
GOOGLE_AUTH_ENABLE | Google sign-in — только Cloud, оставьте отключённым | false |
LOG_LEVEL | Уровень логирования | INFO |
Относитесь к .env как к секрету. Поставьте chmod 600 и не коммитьте в репозиторий. Не переиспользуйте один пароль для DB_PASSWORD и AI_AGENT_DB_PASSWORD.
Переменные LDAP не обязательны для первого запуска — настроить LDAP можно из UI после первого входа. Полный список переменных и поведение описаны в LDAP-интеграции.
Шаг 4 — Скачайте образы и поднимите стек
Скачайте образы из реестра, указанного в docker-compose.yml, и запустите стек:
docker compose pull
docker compose up -d
При первом запуске backend прогоняет Flyway-миграции против пустой базы. Подождите 1–3 минуты до готовности. Логи смотрите так:
docker compose logs -f pandev-metrics
Вы должны увидеть строки org.flywaydb.core.internal.command.DbMigrate, а затем сообщения Spring о старте, заканчивающиеся Started PandevApplication.
Шаг 5 — Проверьте установку
С application-хоста выполните health-check actuator. Ожидаемый ответ — 200 OK с "status":"UP":
curl -fsS http://localhost:9090/actuator/health | jq '.status'
# → "UP"
Проверьте, что frontend доступен через reverse proxy на публичном hostname. Должен появиться экран входа PanDev Metrics. Первого администратора создаёте в процессе первого входа.
Шаг 6 — Настройте reverse proxy и TLS
Терминируйте TLS на reverse proxy. Минимальный server-блок Nginx выглядит так:
server {
listen 443 ssl http2;
server_name metrics.example.com;
ssl_certificate /etc/ssl/certs/pandev.crt;
ssl_certificate_key /etc/ssl/private/pandev.key;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
PanDev Metrics также умеет работать с самоподписанным сертификатом — если отключить SSL-валидацию на клиенте. Подробнее: Сеть и порты.
Решение проблем
Backend падает с `FATAL: password authentication failed for user "pandev"`
DB_PASSWORD в .env не совпадает с паролем роли из шага 1. Пересоздайте роль с правильным паролем или обновите .env и выполните docker compose up -d --force-recreate pandev-metrics.
Flyway падает с `ERROR: permission denied for schema public`
Роль из шага 1 не является владельцем базы. Из суперюзер-сессии выполните ALTER DATABASE pandev_metrics OWNER TO pandev; и перезапустите backend.
`/actuator/health` возвращает `DOWN`, и причиной указан `redis`
Backend не может достучаться до Redis. Проверьте, что контейнер запущен (docker compose ps redis), и что SPRING_DATA_REDIS_HOST совпадает с именем сервиса в docker-compose.yml.
Экран входа загружается, но API-запросы ломаются с mixed-content или CORS-ошибками
Reverse proxy не пробрасывает X-Forwarded-Proto. Убедитесь, что Nginx-блок из шага 6 содержит proxy_set_header X-Forwarded-Proto $scheme;, и перезапустите Nginx.
Контейнер крутится в рестарт-цикле с `OutOfMemoryError`
На application-хосте меньше RAM, чем рекомендовано. Увеличьте хост до минимум 16 GB RAM согласно системным требованиям или ограничьте память Docker и Java heap через JAVA_OPTS=-Xmx12g.
FAQ
Можно ли поставить БД на тот же хост, что и backend?
Для маленькой evaluation-инсталляции — можно, но для прода рекомендуем выделенный database-хост с sizing-ом из системных требований. Application и database выигрывают от независимого профиля CPU, памяти и диска, а обновления проще, когда они разнесены.
Нужно ли создавать таблицы вручную?
Нет. Backend сам прогоняет Flyway-миграции при первом запуске и при каждом обновлении. От вас — пустая база и роль-владелец из шага 1.
Как обновиться до новой версии?
Замените теги образов в docker-compose.yml (или в Helm-чарте) и выполните docker compose pull && docker compose up -d. Flyway применит все pending-миграции на старте. Перед обновлением снимите pg_dump — см. раздел Бэкапы и DR ниже.
Можно ли отключить исходящий сетевой доступ?
Нет. PanDev Metrics нужен минимальный исходящий HTTPS до Git-провайдера, таск-трекера и других подключённых интеграций. Egress минимальный, но отключить нельзя. Air-gapped развёртывания не поддерживаются.
Какие версии Kubernetes поддерживаются?
PanDev Metrics работает на Kubernetes >= 1.28. Helm-чарт поставляется в комплекте с Docker Compose дистрибутивом. Форма конфига идентична — те же env-переменные из шага 3.
Бэкапы и disaster recovery
Для бэкапов достаточно регулярного pg_dump базы PanDev Metrics — continuous archiving не обязательно. Запланируйте дамп с database-хоста и отправляйте вывод в вашу систему хранения:
pg_dump -Fc -U pandev pandev_metrics > pandev_metrics_$(date +%F).dump
Параметры disaster recovery (RPO/RTO) клиент задаёт сам. PanDev Metrics не навязывает целевых значений: восстановите базу через pg_restore, поднимите стек docker compose up -d, и миграции автоматически выровняются.
Дальнейшие шаги
- Первый вход — создание начального администратора
- LDAP-интеграция — подключение корпоративного каталога для SSO
- Сеть и порты — финализация reverse proxy и firewall
Связанные материалы
- Reference: Системные требования
- Концепция: Архитектура on-prem