Переменные окружения¶

Панель конфигурируется через окружение. Единственная обязательная переменная — DATABASE_URL; для реального деплоя добавьте VPNHUB_MASTER_KEY. Все остальные имеют префикс VPNHUB_ и разумные значения по умолчанию.

Как передавать

В Compose — через .env (см. Docker Compose); в Kubernetes — через ConfigMap (несекретные) и Secret (секретные, см. Kubernetes); в docker run — флагами -e / --env-file.

Безопасность¶

Переменная	По умолчанию	Назначение
`VPNHUB_MASTER_KEY`	—	Ключ восстановления. HKDF-выводит ключи шифрования секретов и бэкапов — единственный источник ключа шифрования. Обязателен на `https` (иначе панель не стартует). См. Требования → Мастер-ключ.
`VPNHUB_BACKUP_KEY`	—	Явный ключ шифрования бэкапов. Если задан — приоритетнее ключа из БД, но не мастер-производного. Обычно не нужен.

База данных¶

Переменная	По умолчанию	Назначение
`DATABASE_URL`	— (обязательна: без неё приложение не стартует)	DSN PostgreSQL. Драйвер `asyncpg` обязателен. Для managed-БД добавьте `?ssl=require`.

Псевдоним DATABASE_URL / VPNHUB_DATABASE_URL

Принимаются оба имени, но DATABASE_URL имеет приоритет. Спецсимволы в пароле URL-кодируйте (@→%40, :→%3A, /→%2F) или используйте пароль из hex (openssl rand -hex 32).

Сеть и адрес¶

Переменная	По умолчанию	Назначение
`VPNHUB_BASE_URL`	`http://localhost:8000`	Публичный адрес панели. На `https` включается HSTS и требуется валидный мастер-ключ. Должен совпадать с доменом в reverse-proxy / Ingress.
`VPNHUB_TRUSTED_PROXY`	`false`	Приложение за обратным прокси. `true` → доверять `X-Forwarded-Proto` (флаг `Secure` у cookie на https) и `X-Forwarded-For` (реальный IP клиента для rate-limit/аудита — берётся правый элемент, добавленный прокси). Оверлей Caddy и k8s-ConfigMap включают это сами.
`PORT`	`8000`	Порт внутри контейнера.

Порт: используйте PORT, а не VPNHUB_PORT

В официальном образе процесс поднимает entrypoint.sh, который читает только PORT. Переменная VPNHUB_PORT на контейнер не влияет. Кроме того, встроенный HEALTHCHECK образа жёстко ходит на :8000/healthz — при смене порта healthcheck образа перестанет работать. В большинстве деплоев порт менять не нужно: маппьте его снаружи (-p 9000:8000 / VPNHUB_HTTP_ADDR), а внутри оставьте 8000.

Первичный администратор¶

Переменная	По умолчанию	Назначение
`VPNHUB_ADMIN_PHONE`	—	Телефон первичного админа.
`VPNHUB_ADMIN_PASSWORD`	—	Пароль первичного админа.

Админ создаётся при старте только если заданы обе переменные. Если не заданы — при первом входе откроется setup-экран.

Тонкость setup-экрана

Setup-экран показывается, пока в БД нет ни одного админа и не задан VPNHUB_ADMIN_PHONE. Если задать только VPNHUB_ADMIN_PHONE без пароля — setup-экран скроется, но админ не создастся. Задавайте либо обе переменные, либо ни одной.

Хранилище и бэкапы¶

Переменная	По умолчанию	Назначение
`VPNHUB_BACKUP_DIR`	`./backups`	Каталог `.vhb`-бэкапов БД. Смонтируйте на том, иначе локальные копии теряются при пересоздании контейнера. В образе — `/var/lib/vpnhub/backups`.
`VPNHUB_PROVIDERS_FILE`	`./data/providers.yaml`	Каталог провайдеров; правится из админки → пишется на диск. Смонтируйте на том, чтобы правки не терялись.

Бэкапы логические (дамп строк через SQLAlchemy), не зависят от версии PostgreSQL — восстановление переносится между версиями БД.

Планировщик: мониторинг и синхронизация¶

Фоновые задачи внутри процесса панели. Работают в каждой реплике (лидер-элекшена нет).

Переменная	По умолчанию	Назначение
`VPNHUB_MONITOR_ENABLED`	`true`	Фоновая проверка доступности серверов (TCP-зонд SSH-порта).
`VPNHUB_MONITOR_INTERVAL`	`120`	Период проверки, сек.
`VPNHUB_MONITOR_TIMEOUT`	`5.0`	Таймаут одного зонда, сек.
`VPNHUB_MONITOR_CONCURRENCY`	`16`	Одновременных зондов за тик.
`VPNHUB_SYNC_ENABLED`	`true`	Синхронизация состояния Amnezia по SSH (тяжелее монитора).
`VPNHUB_SYNC_INTERVAL`	`300`	Период синхронизации, сек.

Планировщик и несколько реплик

При replicas > 1 планировщик запускается в каждом поде: бэкапы, мониторинг и синхронизация начнут дублироваться (лишняя SSH-нагрузка на серверы, конкуренция за том бэкапов). Держите панель на одной реплике, пока планировщик не вынесен отдельно. Миграции при нескольких репликах безопасны (сериализованы advisory-lock), а планировщик — нет.

Миграции¶

Переменная	По умолчанию	Назначение
`VPNHUB_RUN_MIGRATIONS`	`true`	Накат `alembic upgrade head` при старте. При `false` миграции пропускаются (например, если катите их отдельным шагом).

Миграции на старте сериализованы транзакционным advisory-lock — одновременный запуск нескольких инстансов безопасен: второй ждёт первого и видит уже накатанную схему.

Обновления¶

Переменная	По умолчанию	Назначение
`VPNHUB_UPDATE_CHANNEL`	`stable`	Метка канала обновлений.
`VPNHUB_UPDATE_FEED_URL`	GitHub Releases продукта	Источник проверки обновлений. По умолчанию — официальные GitHub Releases (работает из коробки). Поддерживает формат GitHub API и простой JSON-фид `{"latest", "releases"}`. `off` (или пусто) → офлайн-режим (last-known из кэша).

Кнопка «Обновить сейчас» в разделе «Система» применяет обновление доступным драйвером. Приоритет: command → webhook → k8s → ручной путь. Ни один не задан → кнопка честно предлагает обновить образ вручную (см. Обновление).

Переменная	По умолчанию	Назначение
`VPNHUB_UPDATE_COMMAND`	`""`	Драйвер command. Shell-команда применения апдейта; `{version}` подставляется в целевую версию. Пусто → следующий драйвер.
`VPNHUB_UPDATE_WEBHOOK_URL`	`""`	Драйвер webhook. HTTP-триггер внешнего апдейтера (Watchtower из `selfupdate.compose.yaml` — `http://watchtower:8080/v1/update`).
`VPNHUB_UPDATE_WEBHOOK_TOKEN`	`""`	Bearer-токен апдейтера (в compose-оверлее задаётся через `VPNHUB_UPDATE_TOKEN`).
`VPNHUB_UPDATE_K8S`	`true`	Драйвер k8s. В кластере патчит образ собственного Deployment через API (нужен RBAC из `deploy/k8s/base/rbac.yaml`). Активен только внутри пода; `false` → выключить.
`VPNHUB_UPDATE_K8S_DEPLOYMENT`	`vpnhub`	Имя Deployment и контейнера для патча (меняйте, если переименовали манифесты).

VPNHUB_UPDATE_COMMAND выполняет shell

Значение исполняется как shell-команда. Задавайте только доверенное значение и не позволяйте задавать его недоверенным пользователям — это фактически удалённое выполнение кода.

Наблюдаемость и API-документация¶

Переменная	По умолчанию	Назначение
`VPNHUB_METRICS_TOKEN`	`""`	Токен для `/metrics` (Prometheus). Задан → нужен `Authorization: Bearer <токен>` или `?token=`. Пусто → эндпоинт открыт (закрывайте на reverse-proxy/сетевой политикой; при пустом токене в лог пишется предупреждение при старте). Скрипт установки генерирует токен автоматически — найдёте его в `.env`.
`VPNHUB_DOCS_ENABLED`	`false`	Swagger (`/docs`), ReDoc (`/redoc`) и `/openapi.json`. По умолчанию выключены (в проде не нужны и раскрывают API-поверхность). Включайте для разработки.

Отображение и прочее¶

Переменная	По умолчанию	Назначение
`VPNHUB_VERSION`	`0.1.0`	Версия в интерфейсе (в образе проставляется при сборке из тега релиза).
`VPNHUB_BUILT`	`""`	Дата сборки (проставляется в образе; пусто → mtime кода).
`VPNHUB_IMAGE`	`ghcr.io/alexeyshalaev/vpn-hub`	Имя образа в инструкции ручного обновления.
`VPNHUB_EDITION`	`Community`	Метка редакции.
`VPNHUB_LOG_LEVEL`	`INFO`	Уровень логирования.
`VPNHUB_SESSION_TTL_DAYS`	`30`	Срок жизни сессии, дней.
`VPNHUB_DEFAULT_REGION`	`RU`	Регион разбора телефонных номеров.

См. также: Требования · Docker Compose · Kubernetes