Справочник по конфигурации
Бэкенд-сервисы Planeon (api, worker, gateway) полностью настраиваются
через переменные окружения, все они читаются в единую структуру Config
при запуске. Руководства по установке —
Docker Compose,
VM/systemd и
Kubernetes/Helm —
показывают, как они собираются в рабочий planeon.env / values.yaml —
начните оттуда для первой установки. Используйте эту страницу, когда вам
нужна полная картина того, что делает каждая переменная.
Эта страница исчерпывающая: она описывает каждую переменную, которую читают сервисы api, worker, gateway и web, а также переменные встроенных контейнеров PostgreSQL и guacd, используемых в руководстве по Docker Compose. Ваш кластер Proxmox VE здесь не настраивается — вы подключаете его из веб-консоли после первого входа.
Общие
| Переменная | По умолчанию | Обязательна | Секрет | Описание |
|---|
APP_ENV | development | Нет | Нет | Метка окружения; только информационная. |
LOG_LEVEL | info | Нет | Нет | Подробность логов: debug / info / warn / error. |
API
| Переменная | По умолчанию | Обязательна | Секрет | Описание |
|---|
API_ADDR | 127.0.0.1:8080 | Нет | Нет | Адрес, на котором слушает API; в контейнере укажите 0.0.0.0:8080. |
API_SHUTDOWN_TIMEOUT | 10s | Нет | Нет | Дедлайн graceful-остановки для выполняющихся HTTP-запросов. |
OPENAPI_PATH | api/openapi/openapi.yaml | Нет | Нет | Путь к файлу OpenAPI, который отдаётся по GET /openapi.yaml. Поставляемые контейнерные образы переопределяют это значение зашитым в образ путём (руководство по Compose задаёт /usr/local/share/proxmox-vdi-admin/openapi.yaml) — оставьте как есть. |
API_CORS_ALLOWED_ORIGINS | (пусто) | Да, если веб-консоль обслуживается с другого origin | Нет | Список источников браузера через запятую, которым разрешено вызывать API. |
METRICS_ADDR | 0.0.0.0:9090 | Нет | Нет | Служебный листенер для GET /metrics, /healthz, /readyz; явно пустое значение отключает его. Общая форма настройки для процессов api и worker — см. Наблюдаемость. |
OIDC / аутентификация
| Переменная | По умолчанию | Обязательна | Секрет | Описание |
|---|
AUTH_OIDC_ISSUER_URL | (пусто) | Да | Нет | URL issuer вашего провайдера идентификации; защищённые маршруты API возвращают 503, пока не заданы и это значение, и audience. |
AUTH_OIDC_AUDIENCE | (пусто) | Да | Нет | Client ID / audience OIDC, по которому Planeon проверяет токены. |
AUTH_OIDC_GROUPS_CLAIM | groups | Нет | Нет | Claim токена, читаемый для членства в группах; поддерживает dot-path для вложенных claim'ов (например, realm_access.roles). |
AUTH_OIDC_ROLES_CLAIM | roles | Нет | Нет | Claim токена, читаемый для членства в ролях. |
AUTH_BOOTSTRAP_ADMIN_EMAILS | (пусто) | Рекомендуется для первого входа | Нет | Адрес(а) электронной почты, которым автоматически выдаётся роль platform_admin при первом входе. |
AUTH_BOOTSTRAP_ADMIN_SUBJECTS | (пусто) | Нет | Нет | Тот же bootstrap-механизм, что и выше, но по OIDC subject вместо email. |
AUTH_BOOTSTRAP_OIDC_GROUP_BINDINGS | (пусто) | Нет | Нет | Список bootstrap OIDC-привязок групп через запятую в формате <значение claim>=<ключ локальной группы>. |
Веб-консоль (браузер)
Эти значения NEXT_PUBLIC_* настраивают браузерный OIDC-клиент веб-консоли и
её endpoint API. Их читает сервис web; в поставляемом образе planeon/web
они передаются при старте контейнера (если консоль игнорирует изменение,
сверьтесь с release notes образа).
| Переменная | По умолчанию | Обязательна | Секрет | Описание |
|---|
NEXT_PUBLIC_API_BASE_URL | http://localhost:8080 | Да для продакшена | Нет | Публичный базовый URL API, к которому обращается браузер; укажите внешний origin вашего API. |
NEXT_PUBLIC_OIDC_AUTHORITY | (пусто) | Да | Нет | URL issuer/authority OIDC для браузера; вместе с client ID определяет, настроен ли вход в консоль. Должен совпадать с AUTH_OIDC_ISSUER_URL у api. |
NEXT_PUBLIC_OIDC_CLIENT_ID | (пусто) | Да | Нет | OIDC client ID приложения веб-консоли. |
NEXT_PUBLIC_OIDC_SCOPE | openid profile email groups | Нет | Нет | Scope'ы, запрашиваемые при входе; добавьте offline_access, если полагаетесь на тихое обновление токена. |
NEXT_PUBLIC_OIDC_LOGOUT_URL | (пусто) | Нет | Нет | Явный URL завершения сессии. Оставьте пустым, чтобы использовать стандартный end_session_endpoint провайдера из OIDC discovery. |
База данных
| Переменная | По умолчанию | Обязательна | Секрет | Описание |
|---|
DATABASE_URL | postgres://proxmox:proxmox@127.0.0.1:5432/proxmox_vdi_admin?sslmode=disable | Да | Да | Строка подключения к PostgreSQL; любой процесс не запускается, если это не задано. |
DATABASE_MAX_CONNS | 10 | Нет | Нет | Максимальный размер пула соединений pgx на процесс. |
Встроенный контейнер PostgreSQL
Если вы запускаете встроенный контейнер postgres (как в руководстве по Docker
Compose), эти переменные задают его начальную базу и суперпользователя. Их читает
образ postgres, а не Planeon — держите их в синхронизации с учётными данными в
DATABASE_URL. С внешним управляемым PostgreSQL эти переменные не задаются.
| Переменная | По умолчанию | Обязательна | Секрет | Описание |
|---|
POSTGRES_DB | planeon | Да, для встроенного контейнера | Нет | Имя базы, создаваемой при первом старте; должно совпадать с базой в DATABASE_URL. |
POSTGRES_USER | planeon | Да, для встроенного контейнера | Нет | Роль-суперпользователь, создаваемая при первом старте; должна совпадать с пользователем в DATABASE_URL. |
POSTGRES_PASSWORD | (пусто) | Да, для встроенного контейнера | Да | Пароль для POSTGRES_USER; должен совпадать с паролем в DATABASE_URL. |
Redis
| Переменная | По умолчанию | Обязательна | Секрет | Описание |
|---|
REDIS_ADDR | 127.0.0.1:6379 | Да | Нет | host:port Redis; любой процесс не запускается, если это не задано. |
REDIS_PASSWORD | (пусто) | Нет | Да | Пароль аутентификации Redis, если ваш инстанс Redis его требует. |
REDIS_DB | 0 | Нет | Нет | Номер логической базы данных Redis. |
Секреты в состоянии покоя
| Переменная | По умолчанию | Обязательна | Секрет | Описание |
|---|
SECRETS_MASTER_KEY | (пусто) | Да для продакшена | Да | Мастер-ключ AES-конверта, шифрующий хранимые учётные данные (токены Proxmox, учётные данные domain join, токены подключения Guacamole); gateway отказывается запускаться без него, а api/worker отказываются запускаться, как только появляются какие-либо зашифрованные данные. |
SECRETS_MASTER_KEY_PREVIOUS | (пусто) | Нет | Да | Уходящий мастер-ключ, задаётся только на время окна ротации ключа. |
Gateway и guacd
| Переменная | По умолчанию | Обязательна | Секрет | Описание |
|---|
GATEWAY_ADDR | 0.0.0.0:8081 | Нет | Нет | Собственный адрес прослушивания gateway. |
GUACD_ADDRESS | guacd:4822 | Нет | Нет | host:port guacd. |
GATEWAY_PUBLIC_WS_URL | (пусто) | Да для доступа к рабочим столам в браузере | Нет | Публичный wss:// URL туннеля gateway, возвращаемый браузеру в ответе с токеном подключения. |
GUACD_LOG_LEVEL | info | Нет | Нет | Уровень логирования встроенного контейнера guacd: trace, debug, info, warning или error. Это собственная настройка демона guacd, отличная от backend-переменной LOG_LEVEL. В Docker Compose это переменная интерполяции Compose — задавайте её в окружении shell или файле .env рядом с compose.yaml, а не в planeon.env. |
Worker и reconciliation
| Переменная | По умолчанию | Обязательна | Секрет | Описание |
|---|
WORKER_POLL_INTERVAL | 1m | Нет | Нет | Интервал опроса очереди заданий. |
POOL_RECONCILE_INTERVAL | 30s | Нет | Нет | Как часто выполняется reconciliation пулов. |
POOL_RECONCILE_BATCH_SIZE | 50 | Нет | Нет | Максимум пулов, обрабатываемых за один цикл. |
GUEST_AGENT_WAIT_TIMEOUT | 10m | Нет | Нет | Как долго провижининг ждёт ответа guest-агента, прежде чем провалить этот шаг. |
WINDOWS_READY_WAIT_TIMEOUT | 30m | Нет | Нет | Как долго провижининг ждёт завершения Sysprep/OOBE в Windows, прежде чем провалить этот шаг. |
WORKER_LEASE_DURATION | 5m | Нет | Нет | Как долго арендованное задание может выполняться без heartbeat, прежде чем другой worker заберёт его себе. |
WORKER_SHUTDOWN_TIMEOUT | 30s | Нет | Нет | Дедлайн graceful-завершения выполняющегося задания при остановке; превышайте это значение в собственном таймауте остановки вашего супервизора процессов (stop_grace_period в Compose, TimeoutStopSec в systemd). |
AUDIT_RETENTION_MONTHS | 0 | Нет | Нет | Сколько последних месяцев событий аудита хранится; 0 хранит всё. |
AUDIT_MAINTENANCE_INTERVAL | 24h | Нет | Нет | Как часто worker создаёт будущие партиции аудита и удаляет истёкшие. |
Лицензирование
| Переменная | По умолчанию | Обязательна | Секрет | Описание |
|---|
LICENSE_REPORT_URL | (пусто) | Нет | Нет | Эндпоинт отчётов активации у поставщика; пустое значение полностью отключает отчёты активации (редакция Free в любом случае никогда не отправляет отчётов). |
LICENSE_REPORT_INTERVAL | 24h | Нет | Нет | Периодичность отчётов активации (с джиттером). |
LICENSE_WATERMARK_INTERVAL | 1h | Нет | Нет | Как часто worker сохраняет монотонную водяную метку истечения лицензии. |
LICENSE_MANIFEST_PATH | (пусто → <исполняемый файл>.manifest) | Нет | Нет | Путь к подписанному манифесту сборки, используемому для обнаружения вмешательства. |
О том, что регулируют эти переменные, см. Лицензирование.