Все ключи показаны со значениями по умолчанию. Если параметр не помечен как задаваемый только через окружение, его можно указать в config.yaml или через указанную переменную окружения, которая имеет приоритет. Недопустимые значения (неположительные таймауты, нулевая конкурентность, TTL вне допустимого диапазона) прерывают запуск с ошибкой config: validate:, в которой указан проблемный ключ.
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
env | VISION_ENV | development | Окружение развёртывания: development | staging | production. Определяет строгость проверок |
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
http.addr | VISION_HTTP_ADDR | :3303 | Адрес и порт прослушивания |
http.read_timeout | VISION_HTTP_READ_TIMEOUT | 15s | Максимальное время чтения полного запроса |
http.write_timeout | VISION_HTTP_WRITE_TIMEOUT | 30s | Максимальное время записи ответа |
http.idle_timeout | VISION_HTTP_IDLE_TIMEOUT | 60s | Таймаут простоя keep-alive |
http.shutdown_grace | VISION_HTTP_SHUTDOWN_GRACE | 10s | Время на завершение выполняющихся запросов при остановке |
http.pre_drain_delay | VISION_HTTP_PREDRAIN_DELAY | 5s | Задержка между началом сбоев /readyz и остановкой (для балансировщиков нагрузки) |
http.secure_cookies | VISION_HTTP_SECURE_COOKIES | true | Помечать cookie сессии/авторизации как Secure (только HTTPS). vision install записывает false (обычный http://); установите true, когда перед сервером будет HTTPS |
http.allowed_origins | VISION_ALLOWED_ORIGINS | ["http://localhost:3303"] | Список разрешённых источников CORS. Staging и production отклоняют * и пустой список при запуске |
http.internal_addr | VISION_HTTP_INTERNAL_ADDR | (пусто) | Отдельный адрес прослушивания для /healthz, /readyz, /metrics |
Источники сопоставляются в виде scheme://host[:port], без учёта регистра, с заголовком Origin запроса. Кросс-доменные запросы могут использовать только заголовки Authorization, Content-Type, X-Request-ID, Idempotency-Key и Last-Event-ID — список разрешённых заголовков фиксирован, и любой другой не проходит preflight-проверку. Итоговый список источников записывается в журнал при запуске как CORS allow-list. Production автоматически включает HSTS. Каждый ответ также содержит X-Frame-Options: DENY; интерфейс нельзя встроить в iframe, и переключателя для этого нет.
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
db.path | VISION_DB_PATH | ./data/vision.db | Путь к файлу SQLite (родительский каталог должен существовать) |
db.connect_timeout | VISION_DB_CONNECT_TIMEOUT | 5s | Таймаут открытия соединения |
db.query_timeout | VISION_DB_QUERY_TIMEOUT | 30s | Таймаут одного запроса |
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
log.level | VISION_LOG_LEVEL | info | debug | info | warn | error |
log.format | VISION_LOG_FORMAT | json | json (production) | text (development) |
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
auth.jwt_secret | VISION_AUTH_JWT_SECRET | (пусто) | Секрет подписи JWT. Обязателен в staging/production |
auth.access_ttl | VISION_AUTH_ACCESS_TTL | 15m | Время жизни короткоживущего токена доступа (> 0, ≤ 1h) |
auth.refresh_ttl | VISION_AUTH_REFRESH_TTL | 168h | Время жизни ротируемой сессии обновления (> 0, ≤ 720h). Неактивная сессия браузера истекает по истечении этого срока |
auth.oauth2_secret | VISION_OAUTH2_SECRET | (пусто) | Секрет Base64 длиной 32 байта для входящих токенов OAuth2 client-credentials. Если не задан, POST /api/v1/events не подключается |
crypto.encryption_keys | VISION_ENCRYPTION_KEY, _V2, _V3, … | [] | Только через окружение. Ключи AES-256-GCM в Base64 для зашифрованных полей БД. Первый ключ активный; более старые ключи расшифровывают данные во время ротации. Обязательны в staging/production |
Сгенерируйте ключ командой openssl rand -base64 32. Значение YAML для crypto.encryption_keys игнорируется; храните все ключи в /etc/vision/vision.env. Нумеруйте ротируемые ключи без пропусков (_V2, _V3, …), потому что загрузка останавливается на первом отсутствующем номере. Секрет JWT принимает стандартный или URL-safe Base64, с дополнением (padding) или без, и должен декодироваться ровно в 32 байта.
Эти значения создают первого пользователя-администратора, только пока таблица пользователей пуста, а затем игнорируются — их изменение после появления администратора не имеет эффекта. В режиме разработки отсутствующие значения заменяются на admin@localhost / admin (с предупреждением при запуске). В staging и production запуск прерывается, если в базе данных нет пользователей и отсутствует любое из значений. Установщик генерирует оба значения в /etc/vision/vision.env.
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
bootstrap.admin_email | ADMIN_EMAIL | (пусто) | Email начального администратора. Значение для разработки: admin@localhost |
bootstrap.admin_password | ADMIN_PASSWORD | (пусто) | Пароль начального администратора. Значение для разработки: admin |
Сведения о подключении к серверу Alta (базовый URL, учётные данные и callback base URL каждого сервера) хранятся в базе данных и управляются в интерфейсе. Эти ключи настраивают только общий клиент.
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
alta.default_timeout | VISION_ALTA_DEFAULT_TIMEOUT | 10s | Таймаут одной попытки для CRUD-вызовов |
alta.long_timeout | VISION_ALTA_LONG_TIMEOUT | 30s | Таймаут одной попытки для вызовов Preview/VOD |
alta.breaker_threshold | VISION_ALTA_BREAKER_THRESHOLD | 5 | Число последовательных сбоев до размыкания circuit breaker |
alta.breaker_open_for | VISION_ALTA_BREAKER_OPEN_FOR | 30s | Как долго breaker остаётся разомкнутым |
alta.bulkhead_capacity | VISION_ALTA_BULKHEAD_CAPACITY | 64 | Максимальное число одновременных вызовов Alta в обработке |
alta.stream.hls_token_ttl | VISION_ALTA_STREAM_HLS_TOKEN_TTL | 5m | TTL токенов плейлиста HLS (≤ 1h) |
alta.stream.webrtc_token_ttl | VISION_ALTA_STREAM_WEBRTC_TOKEN_TTL | 2m | TTL bearer-токенов WHEP (≤ 1h) |
alta.stream.archive_token_ttl | VISION_ALTA_STREAM_ARCHIVE_TOKEN_TTL | 5m | TTL токенов воспроизведения архива (VOD) (≤ 1h) |
alta.stream.preview_list_max_window | VISION_ALTA_STREAM_PREVIEW_LIST_MAX_WINDOW | 2h | Максимальный интервал времени, который может охватывать один запрос списка превью (≤ 24h) |
alta.stream.auth_mode | VISION_ALTA_STREAM_AUTH_MODE | jwt | jwt (production) | none (только для разработки, пишет предупреждение в журнал) |
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
workers.enabled | VISION_WORKERS_ENABLED | стандартные worker | Список разрешённых значений через запятую из {clips, cleanup, health_server, health_camera, health, alta_prober, alerts, notifications, io, reconcile}. true включает стандартный набор (кроме выведенного из эксплуатации io); false не включает ни одного. motion и screenshots недопустимы и прерывают запуск |
workers.health_probe_concurrency | VISION_WORKERS_HEALTH_PROBE_CONCURRENCY | 8 | Максимальное число одновременных проверок работоспособности Alta за один тик (≥ 1) |
workers.clips_output_path | CLIPS_OUTPUT_PATH | /var/lib/vision/clips | Устаревший путь, сохранённый для существующих записей; новым экспортам требуется хранилище для вывода |
workers.clips_ffmpeg_binary | CLIPS_FFMPEG_BINARY | ffmpeg | Путь к исполняемому файлу ffmpeg |
workers.clips_ffprobe_binary | CLIPS_FFPROBE_BINARY | ffprobe | Путь к ffprobe, используется при добавлении камер RTSP и измерении экспортированных клипов |
workers.clips_worker_timeout | CLIPS_WORKER_TIMEOUT | 5m | Предельное время ffmpeg на один клип |
workers.clips_worker_concurrency | CLIPS_WORKER_CONCURRENCY | 2 | Максимальное число одновременных подпроцессов ffmpeg |
workers.screenshots_output_path | SCREENSHOTS_OUTPUT_PATH | /var/lib/vision/screenshots | Устаревший путь, сохранённый для существующих записей; новым снимкам требуется хранилище для вывода |
workers.notifications_dispatch_concurrency | VISION_NOTIFICATIONS_DISPATCH_CONCURRENCY | 8 | Максимальное число одновременных goroutine, рассылающих email, push и webhook |
workers.drain_timeout | VISION_WORKERS_DRAIN_TIMEOUT | 10s | Общее время на остановку worker при завершении работы |
Worker io остаётся доступным только для совместимости и пишет предупреждение в журнал при явном включении; его интерфейс выведен из эксплуатации. Worker alta_prober примерно раз в секунду опрашивает каждый сервер Alta, чтобы быстро обнаруживать сбои и перезапуски; его периодичность задаётся системным параметром Server ping interval ниже.
Worker reconcile запускается каждый час и удаляет осиротевшие ресурсы на стороне Alta — но только те, создание которых эта установка может доказать (долговременная запись о владении, а не догадка по шаблону имени), поэтому одна установка никогда не удалит ресурсы другой на общем сервере Alta. О том, что это означает в повседневной работе, см. Подключение сервера Alta, а параметры, ограничивающие объём удаления за один проход, — в строках Reconcile ниже.
Worker cleanup применяет политики хранения. Политика хранения журнала аудита ниже записывается при первой установке; после записи источником истины во время работы становится параметр в приложении в разделе Settings → Storages.
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
retention.audit_days | VISION_RETENTION_AUDIT_DAYS | 365 | Начальное значение срока хранения журнала аудита при первой установке, в днях |
Опрос работоспособности и настройка reconcile хранятся в базе данных, а не в config.yaml. Каждый ключ ниже можно записать через PUT /api/v1/settings/{key}; в столбце UI указано, у каких из них уже есть элемент управления в Settings → Connections — остальные пока доступны только через API параметров/CLI.
| Ключ | UI | По умолчанию | Диапазон | Описание |
|---|
connection.camera_health_interval | Camera health interval | 3 | 1–30 | Интервал опроса работоспособности камер, в секундах |
connection.server_ping_interval | Server ping interval | 1 | 1–10 | Интервал проверки доступности Alta, в секундах. Определяет, как быстро обнаруживаются сбои и перезапуски |
connection.server_health_interval | Server status | 15 | 10–300 | Опрос телеметрии хоста/хранилища, а также подтверждение доступности и debounce чистых опросов, снимающие статус «флаппинга» сервера. Не определяет скорость обнаружения сбоев — это интервал ping выше |
connection.server_config_interval | Server config | 300 | 60–3600 | Периодичность проверки дрейфа конфигурации — как часто загружается полная конфигурация Alta для обнаружения ручных правок. Самый тяжёлый вызов Alta; редкие запуски безопасны и не влияют на обнаружение сбоев |
connection.reconcile_grace_seconds | (нет) | 600 | 60–86400 | Как долго ресурс Alta без соответствующей записи Vision должен оставаться без ссылок и невостребованным, прежде чем worker reconcile удалит его. Это не выключатель очистки — тот же ключ ограничивает путь аварийного восстановления worker health; чтобы отключить очистку, уберите reconcile из workers.enabled |
connection.reconcile_max_deletes_per_tick | (нет) | 20 | 1–1000 | Ограничение на сервер за тик на число ресурсов, удаляемых очисткой reconcile; остальные ждут следующего тика |
connection.reconcile_candidate_ratio_guard | (нет) | 1 | 0–100 | Отклоняет весь проход reconcile для сервера, когда кандидатов на удаление больше, чем references × this ratio — защита от очистки сервера из-за ошибочного чтения ссылок. 0 отключает защиту для намеренной массовой очистки |
connection.server_health_interval и connection.server_config_interval были выделены из одного параметра (ADR-0045): опрос доступности/статуса/телеметрии и более тяжёлое сканирование дрейфа конфигурации теперь выполняются с независимой периодичностью, поэтому проверку дрейфа можно делать редкой, не замедляя обнаружение сбоев. Два ограничителя reconcile добавлены вместе с журналом заявок на владение — что очистка делает с ними, см. в разделе Подключение сервера Alta.
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
maps_background_path | MAPS_BACKGROUND_PATH | (пусто) | Корень файловой системы для изображений планов этажей. Если пусто, используется каталог maps рядом с db.path; установщик записывает /var/lib/vision/maps |
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
metrics.enabled | VISION_METRICS_ENABLED | true | Публиковать метрики Prometheus на /metrics |
readiness.timeout | VISION_READINESS_TIMEOUT | 5s | Общий предельный срок для /readyz |
readiness.check_workers | VISION_READINESS_CHECK_WORKERS | true | Учитывать работоспособность worker в проверке готовности |
readiness.check_schema | VISION_READINESS_CHECK_SCHEMA | true | Включать проверку версии схемы |
readiness.worker_stale_multiplier | VISION_READINESS_WORKER_STALE_MULTIPLIER | 2.0 | Worker считается устаревшим, когда его последний heartbeat старше multiplier × tick |
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
security.csp_strict_mode | VISION_SECURITY_CSP_STRICT | false | Включить строгий CSP в режиме разработки (в production всегда строгий) |
startup.check_schema | VISION_STARTUP_CHECK_SCHEMA | true | Проверять схему БД при загрузке |
startup.check_environment | VISION_STARTUP_CHECK_ENVIRONMENT | true | Проверять окружение при загрузке |
startup.check_keyring | VISION_STARTUP_CHECK_KEYRING | true | Проверять связку ключей шифрования при загрузке |
startup.check_alta | VISION_STARTUP_CHECK_ALTA | true | Проверять доступность Alta при загрузке. Проходит, если сервер ещё не добавлен |
startup.timeout | VISION_STARTUP_TIMEOUT | 10s | Общее время на проверки при запуске |
Алгоритм token bucket для каждого пользователя, ключ — ID пользователя. Публичные эндпоинты (/healthz, /readyz, /metrics, /auth/verify) исключены.
Видео в реальном времени (запуск и остановка потоков) и PTZ используют отдельный бюджет реального времени — 300 запросов в минуту, поэтому листание видеостены никогда не расходует бюджет на изменения. Ответ 429 сообщает, сколько нужно подождать.
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
rate_limit.enabled | VISION_RATE_LIMIT_ENABLED | true | Включить ограничитель |
rate_limit.read_per_min | VISION_RATE_LIMIT_READ_PER_MIN | 60 | Запросов на чтение в минуту |
rate_limit.write_per_min | VISION_RATE_LIMIT_WRITE_PER_MIN | 60 | Запросов на запись в минуту |
rate_limit.burst | VISION_RATE_LIMIT_BURST | 0 | Допустимый всплеск (0 = использовать бюджет в минуту) |
Независимо от ограничителя на пользователя выше, этот механизм защищает неаутентифицированные запросы входа, обновления сессии и сброса пароля. Вход должен пройти оба лимита: настроенный бюджет на email и фиксированный бюджет 60 в минуту на IP-адрес источника. Блокировка по email фиксирована и длится 60 секунд. Обновление сессии привязано к IP-адресу источника и только ограничивается по частоте, но никогда не блокируется — серия перезагрузок страницы ждёт несколько секунд, а не выходит из системы. Сброс пароля привязан к IP-адресу источника и использует параметры прогрессивной блокировки ниже. Счётчики хранятся в памяти процесса и сбрасываются при перезапуске.
| Ключ | Переменная окружения | По умолчанию | Описание |
|---|
auth_rate_limit.enabled | VISION_AUTH_RATE_LIMIT_ENABLED | true | Включить ограничение/блокировку аутентификации |
auth_rate_limit.per_min | VISION_AUTH_RATE_LIMIT_PER_MIN | 5 | Устойчивое число попыток в минуту на ключ |
auth_rate_limit.burst | VISION_AUTH_RATE_LIMIT_BURST | 5 | Ёмкость корзины токенов (0 = использовать per_min) |
auth_rate_limit.max_failures | VISION_AUTH_RATE_LIMIT_MAX_FAILURES | 5 | Число последовательных неудач до блокировки |
auth_rate_limit.lockout_base | VISION_AUTH_RATE_LIMIT_LOCKOUT_BASE | 1m | Первая блокировка; удваивается при каждой следующей неудаче |
auth_rate_limit.lockout_max | VISION_AUTH_RATE_LIMIT_LOCKOUT_MAX | 15m | Предел прогрессивного увеличения задержки |
auth_rate_limit.ttl | VISION_AUTH_RATE_LIMIT_TTL | 15m | Окно простоя, после которого ключ вытесняется |
auth_rate_limit.max_keys | VISION_AUTH_RATE_LIMIT_MAX_KEYS | 4096 | Жёсткий предел числа отслеживаемых ключей (ограничивает память) |