Referência de configuração

Todas as chaves são mostradas com seus valores padrão. A menos que sejam marcadas como somente de ambiente, cada opção pode ser definida no config.yaml ou pela variável de ambiente listada, que tem precedência. Valores inválidos (timeouts não positivos, concorrência igual a zero, TTLs fora do intervalo) abortam a inicialização com um erro config: validate: que nomeia a chave com problema.

Geral

Chave	Variável de ambiente	Padrão	Descrição
`env`	`VISION_ENV`	`development`	Ambiente de implantação: `development` \| `staging` \| `production`. Controla o rigor da validação

HTTP

Chave	Variável de ambiente	Padrão	Descrição
`http.addr`	`VISION_HTTP_ADDR`	`:3303`	Endereço e porta de escuta
`http.read_timeout`	`VISION_HTTP_READ_TIMEOUT`	`15s`	Tempo máximo para ler uma requisição completa
`http.write_timeout`	`VISION_HTTP_WRITE_TIMEOUT`	`30s`	Tempo máximo para escrever uma resposta
`http.idle_timeout`	`VISION_HTTP_IDLE_TIMEOUT`	`60s`	Timeout de inatividade do keep-alive
`http.shutdown_grace`	`VISION_HTTP_SHUTDOWN_GRACE`	`10s`	Período de tolerância para requisições em andamento no desligamento
`http.pre_drain_delay`	`VISION_HTTP_PREDRAIN_DELAY`	`5s`	Atraso após o `/readyz` começar a falhar antes do desligamento (para balanceadores de carga)
`http.secure_cookies`	`VISION_HTTP_SECURE_COOKIES`	`true`	Marca os cookies de sessão/autenticação como `Secure` (somente HTTPS). O `vision install` grava `false` (`http://` simples); defina `true` assim que houver HTTPS na frente
`http.allowed_origins`	`VISION_ALLOWED_ORIGINS`	`["http://localhost:3303"]`	Lista de origens permitidas do CORS. Staging e production rejeitam `*` e uma lista vazia na inicialização
`http.internal_addr`	`VISION_HTTP_INTERNAL_ADDR`	(vazio)	Listener separado para `/healthz`, `/readyz`, `/metrics`

As origens são comparadas como scheme://host[:port], sem diferenciar maiúsculas de minúsculas, com o cabeçalho Origin da requisição. Requisições cross-origin podem usar apenas os cabeçalhos Authorization, Content-Type, X-Request-ID, Idempotency-Key e Last-Event-ID — a lista de cabeçalhos permitidos é fixa, e qualquer outro falha no preflight. A lista efetiva de origens é registrada na inicialização como CORS allow-list. A produção habilita o HSTS automaticamente. Toda resposta também carrega X-Frame-Options: DENY; a interface não pode ser incorporada em um iframe, e não há opção para alterar isso.

Banco de dados

Chave	Variável de ambiente	Padrão	Descrição
`db.path`	`VISION_DB_PATH`	`./data/vision.db`	Caminho do arquivo SQLite (o diretório pai deve existir)
`db.connect_timeout`	`VISION_DB_CONNECT_TIMEOUT`	`5s`	Timeout de abertura de conexão
`db.query_timeout`	`VISION_DB_QUERY_TIMEOUT`	`30s`	Timeout de uma única consulta

Logs

Chave	Variável de ambiente	Padrão	Descrição
`log.level`	`VISION_LOG_LEVEL`	`info`	`debug` \| `info` \| `warn` \| `error`
`log.format`	`VISION_LOG_FORMAT`	`json`	`json` (produção) \| `text` (desenvolvimento)

Autenticação e criptografia

Chave	Variável de ambiente	Padrão	Descrição
`auth.jwt_secret`	`VISION_AUTH_JWT_SECRET`	(vazio)	Segredo de assinatura do JWT. Obrigatório em staging/production
`auth.access_ttl`	`VISION_AUTH_ACCESS_TTL`	`15m`	Tempo de vida do token de acesso de curta duração (> 0, ≤ 1h)
`auth.refresh_ttl`	`VISION_AUTH_REFRESH_TTL`	`168h`	Tempo de vida da sessão de refresh rotativa (> 0, ≤ 720h). Uma sessão de navegador inativa expira após esse período
`auth.oauth2_secret`	`VISION_OAUTH2_SECRET`	(vazio)	Segredo base64 de 32 bytes para tokens de entrada OAuth2 client-credentials. Quando não definido, `POST /api/v1/events` não é montado
`crypto.encryption_keys`	`VISION_ENCRYPTION_KEY`, `_V2`, `_V3`, …	`[]`	Somente de ambiente. Chaves AES-256-GCM em base64 para campos criptografados do banco. A primeira chave é a ativa; as chaves mais antigas descriptografam durante a rotação. Obrigatórias em staging/production

Gere uma chave com openssl rand -base64 32. Um valor YAML para crypto.encryption_keys é ignorado; mantenha todas as chaves em /etc/vision/vision.env. Numere as chaves rotacionadas sem lacunas (_V2, _V3, …), pois o carregamento para no primeiro número ausente. O segredo JWT aceita base64 padrão ou URL-safe, com ou sem preenchimento, e deve ser decodificado para exatamente 32 bytes.

Bootstrap do administrador

Estes valores criam o primeiro usuário administrador somente enquanto a tabela de usuários está vazia e são ignorados depois disso — editá-los quando já existe um administrador não tem efeito. Em desenvolvimento, valores ausentes recorrem a admin@localhost / admin (com um aviso na inicialização). Em staging e produção, a criação inicial aborta a inicialização quando o banco de dados não tem usuários e um dos valores está ausente. O instalador gera ambos em /etc/vision/vision.env.

Chave	Variável de ambiente	Padrão	Descrição
`bootstrap.admin_email`	`ADMIN_EMAIL`	(vazio)	E-mail inicial do administrador. Padrão de desenvolvimento: `admin@localhost`
`bootstrap.admin_password`	`ADMIN_PASSWORD`	(vazio)	Senha inicial do administrador. Padrão de desenvolvimento: `admin`

Cliente Alta

Os detalhes de conexão do servidor Alta (URL base, credenciais e a callback base URL de cada servidor) ficam no banco de dados e são gerenciados na interface. Estas chaves ajustam apenas o cliente compartilhado.

Chave	Variável de ambiente	Padrão	Descrição
`alta.default_timeout`	`VISION_ALTA_DEFAULT_TIMEOUT`	`10s`	Timeout por tentativa para chamadas CRUD
`alta.long_timeout`	`VISION_ALTA_LONG_TIMEOUT`	`30s`	Timeout por tentativa para chamadas de Preview/VOD
`alta.breaker_threshold`	`VISION_ALTA_BREAKER_THRESHOLD`	`5`	Falhas consecutivas antes de o circuit breaker abrir
`alta.breaker_open_for`	`VISION_ALTA_BREAKER_OPEN_FOR`	`30s`	Por quanto tempo o breaker permanece aberto
`alta.bulkhead_capacity`	`VISION_ALTA_BULKHEAD_CAPACITY`	`64`	Máximo de chamadas simultâneas em andamento ao Alta
`alta.stream.hls_token_ttl`	`VISION_ALTA_STREAM_HLS_TOKEN_TTL`	`5m`	TTL dos tokens de playlist HLS (≤ 1h)
`alta.stream.webrtc_token_ttl`	`VISION_ALTA_STREAM_WEBRTC_TOKEN_TTL`	`2m`	TTL dos tokens bearer WHEP (≤ 1h)
`alta.stream.archive_token_ttl`	`VISION_ALTA_STREAM_ARCHIVE_TOKEN_TTL`	`5m`	TTL dos tokens de reprodução de arquivo (VOD) (≤ 1h)
`alta.stream.preview_list_max_window`	`VISION_ALTA_STREAM_PREVIEW_LIST_MAX_WINDOW`	`2h`	Intervalo de tempo máximo que uma única requisição de lista de previews pode cobrir (≤ 24h)
`alta.stream.auth_mode`	`VISION_ALTA_STREAM_AUTH_MODE`	`jwt`	`jwt` (produção) \| `none` (somente desenvolvimento, registra um aviso)

Workers

Chave	Variável de ambiente	Padrão	Descrição
`workers.enabled`	`VISION_WORKERS_ENABLED`	workers padrão	Lista de permissões separada por vírgulas, a partir de `{clips, cleanup, health_server, health_camera, health, alta_prober, alerts, notifications, io, reconcile}`. `true` habilita o conjunto padrão (excluindo o `io`, descontinuado); `false` não habilita nenhum. `motion` e `screenshots` são inválidos e abortam a inicialização
`workers.health_probe_concurrency`	`VISION_WORKERS_HEALTH_PROBE_CONCURRENCY`	`8`	Máximo de sondagens de saúde do Alta simultâneas por tick (≥ 1)
`workers.clips_output_path`	`CLIPS_OUTPUT_PATH`	`/var/lib/vision/clips`	Caminho legado mantido para registros existentes; novas exportações exigem um armazenamento de saída
`workers.clips_ffmpeg_binary`	`CLIPS_FFMPEG_BINARY`	`ffmpeg`	Caminho do executável do ffmpeg
`workers.clips_ffprobe_binary`	`CLIPS_FFPROBE_BINARY`	`ffprobe`	Caminho do ffprobe, usado ao adicionar câmeras RTSP e ao medir clipes exportados
`workers.clips_worker_timeout`	`CLIPS_WORKER_TIMEOUT`	`5m`	Prazo do ffmpeg por clipe
`workers.clips_worker_concurrency`	`CLIPS_WORKER_CONCURRENCY`	`2`	Máximo de subprocessos ffmpeg simultâneos
`workers.screenshots_output_path`	`SCREENSHOTS_OUTPUT_PATH`	`/var/lib/vision/screenshots`	Caminho legado mantido para registros existentes; novas capturas exigem um armazenamento de saída
`workers.notifications_dispatch_concurrency`	`VISION_NOTIFICATIONS_DISPATCH_CONCURRENCY`	`8`	Máximo de goroutines simultâneas despachando e-mails, push e webhooks
`workers.drain_timeout`	`VISION_WORKERS_DRAIN_TIMEOUT`	`10s`	Orçamento total para drenar os workers no desligamento

O worker io permanece disponível apenas por compatibilidade e registra um aviso quando habilitado explicitamente; sua interface foi descontinuada. O worker alta_prober faz ping em cada servidor Alta cerca de uma vez por segundo para detectar quedas e reinicializações rapidamente; sua cadência é a configuração de sistema Server ping interval abaixo.

O worker reconcile é executado a cada hora e exclui recursos órfãos do lado do Alta — mas apenas aqueles que esta instalação consegue provar que criou (um registro de propriedade durável, não um palpite por padrão de nome), de modo que uma instalação nunca pode excluir os recursos de outra em um servidor Alta compartilhado. Consulte Conectar um servidor Alta para saber o que isso significa no dia a dia, e as linhas Reconcile abaixo para as configurações que limitam quanto ele exclui por passagem.

Retenção

O worker cleanup aplica a retenção. A política do log de auditoria abaixo é criada na primeira instalação; depois de gravada, a fonte de verdade em tempo de execução é a configuração no aplicativo em Settings → Storages.

Chave	Variável de ambiente	Padrão	Descrição
`retention.audit_days`	`VISION_RETENTION_AUDIT_DAYS`	`365`	Valor inicial da primeira instalação para a retenção do log de auditoria, em dias

Configurações do sistema

A sondagem de saúde e o ajuste do reconcile ficam no banco de dados, não no config.yaml. Toda chave abaixo pode ser gravada via PUT /api/v1/settings/{key}; a coluna UI mostra quais delas também têm um controle em Settings → Connections hoje — as demais são, por enquanto, apenas da API de configurações/CLI.

Chave	UI	Padrão	Intervalo	Descrição
`connection.camera_health_interval`	Camera health interval	`3`	`1`–`30`	Intervalo de sondagem de saúde da câmera, em segundos
`connection.server_ping_interval`	Server ping interval	`1`	`1`–`10`	Intervalo da sondagem de disponibilidade do Alta, em segundos. Define a rapidez com que quedas e reinicializações são detectadas
`connection.server_health_interval`	Server status	`15`	`10`–`300`	Sondagem de telemetria do host/armazenamento, além da corroboração de alcance e do debounce de sondagens limpas que remove um servidor instável. Não define a velocidade de detecção de quedas — quem define isso é o intervalo de ping acima
`connection.server_config_interval`	Server config	`300`	`60`–`3600`	Cadência da inspeção de desvio de configuração — com que frequência a configuração completa do Alta é obtida para detectar edições manuais. É a chamada mais pesada ao Alta; mantê-la pouco frequente é seguro e não afeta a detecção de quedas
`connection.reconcile_grace_seconds`	(nenhuma)	`600`	`60`–`86400`	Por quanto tempo um recurso do Alta sem registro correspondente no Vision deve permanecer sem referência e não reivindicado antes de o worker reconcile excluí-lo. Isto não é um interruptor de desligamento da varredura — a mesma chave limita o caminho de recuperação de falhas do worker health; remova `reconcile` de `workers.enabled` para desabilitar a varredura
`connection.reconcile_max_deletes_per_tick`	(nenhuma)	`20`	`1`–`1000`	Limite por servidor e por tick de quantos recursos a varredura de reconcile exclui; o restante espera o próximo tick
`connection.reconcile_candidate_ratio_guard`	(nenhuma)	`1`	`0`–`100`	Recusa a passagem de reconcile inteira de um servidor quando os candidatos à exclusão excedem `references × this ratio` — um freio contra uma leitura incorreta de referências apagar um servidor. `0` desabilita a proteção, para uma limpeza em massa intencional

connection.server_health_interval e connection.server_config_interval foram separados de uma única configuração (ADR-0045): a sondagem de alcance/status/telemetria e a varredura mais pesada de desvio de configuração agora são executadas em cadências independentes, de modo que a inspeção de desvio pode permanecer lenta sem também atrasar a detecção de quedas. As duas proteções de reconcile foram adicionadas junto com o registro de reivindicação de propriedade — consulte Conectar um servidor Alta para saber o que a varredura faz com elas.

Mapas

Chave	Variável de ambiente	Padrão	Descrição
`maps_background_path`	`MAPS_BACKGROUND_PATH`	(vazio)	Raiz do sistema de arquivos para imagens de planta baixa. Vazio usa um diretório `maps` ao lado de `db.path`; o instalador grava `/var/lib/vision/maps`

Observabilidade

Chave	Variável de ambiente	Padrão	Descrição
`metrics.enabled`	`VISION_METRICS_ENABLED`	`true`	Expõe as métricas do Prometheus em `/metrics`
`readiness.timeout`	`VISION_READINESS_TIMEOUT`	`5s`	Prazo total para o `/readyz`
`readiness.check_workers`	`VISION_READINESS_CHECK_WORKERS`	`true`	Inclui a atividade dos workers na prontidão
`readiness.check_schema`	`VISION_READINESS_CHECK_SCHEMA`	`true`	Inclui a verificação da versão do esquema
`readiness.worker_stale_multiplier`	`VISION_READINESS_WORKER_STALE_MULTIPLIER`	`2.0`	Um worker está obsoleto quando seu último heartbeat é mais antigo que `multiplier × tick`

Segurança e inicialização

Chave	Variável de ambiente	Padrão	Descrição
`security.csp_strict_mode`	`VISION_SECURITY_CSP_STRICT`	`false`	Ative para usar CSP estrito em desenvolvimento (sempre estrito em produção)
`startup.check_schema`	`VISION_STARTUP_CHECK_SCHEMA`	`true`	Verifica o esquema do banco de dados na inicialização
`startup.check_environment`	`VISION_STARTUP_CHECK_ENVIRONMENT`	`true`	Verifica o ambiente na inicialização
`startup.check_keyring`	`VISION_STARTUP_CHECK_KEYRING`	`true`	Verifica o chaveiro de criptografia na inicialização
`startup.check_alta`	`VISION_STARTUP_CHECK_ALTA`	`true`	Verifica o alcance do Alta na inicialização. Passa quando nenhum servidor foi adicionado ainda
`startup.timeout`	`VISION_STARTUP_TIMEOUT`	`10s`	Orçamento total para as verificações de inicialização

Limitação de taxa

Token bucket por usuário, indexado pelo ID do usuário. Os endpoints públicos (/healthz, /readyz, /metrics, /auth/verify) estão isentos.

O vídeo ao vivo (iniciar e parar streams) e o PTZ usam um orçamento separado de tempo real de 300 requisições por minuto, de modo que paginar um mosaico de vídeo nunca consome o orçamento de edição. Um 429 informa quanto tempo esperar.

Chave	Variável de ambiente	Padrão	Descrição
`rate_limit.enabled`	`VISION_RATE_LIMIT_ENABLED`	`true`	Habilita o limitador
`rate_limit.read_per_min`	`VISION_RATE_LIMIT_READ_PER_MIN`	`60`	Requisições de leitura por minuto
`rate_limit.write_per_min`	`VISION_RATE_LIMIT_WRITE_PER_MIN`	`60`	Requisições de escrita por minuto
`rate_limit.burst`	`VISION_RATE_LIMIT_BURST`	`0`	Margem de rajada (`0` = usar o orçamento por minuto)

Limitação e bloqueio de autenticação

Independente do limitador por usuário acima, isto protege as requisições não autenticadas de login, refresh e redefinição de senha. O login deve passar tanto pelo orçamento configurado por e-mail quanto por um orçamento fixo de 60/minuto por IP de origem. O bloqueio por e-mail é fixo de 60 segundos. O refresh de sessão é indexado pelo IP de origem e apenas sofre limitação de taxa, nunca bloqueio — uma rajada de recarregamentos de página espera alguns segundos em vez de desconectar o usuário. A redefinição de senha é indexada pelo IP de origem e usa as configurações de bloqueio progressivo abaixo. Os contadores ficam em memória no processo e são zerados na reinicialização.

Chave	Variável de ambiente	Padrão	Descrição
`auth_rate_limit.enabled`	`VISION_AUTH_RATE_LIMIT_ENABLED`	`true`	Habilita a limitação/bloqueio de autenticação
`auth_rate_limit.per_min`	`VISION_AUTH_RATE_LIMIT_PER_MIN`	`5`	Tentativas sustentadas por minuto por chave
`auth_rate_limit.burst`	`VISION_AUTH_RATE_LIMIT_BURST`	`5`	Capacidade do bucket (`0` = usar `per_min`)
`auth_rate_limit.max_failures`	`VISION_AUTH_RATE_LIMIT_MAX_FAILURES`	`5`	Falhas consecutivas antes do bloqueio
`auth_rate_limit.lockout_base`	`VISION_AUTH_RATE_LIMIT_LOCKOUT_BASE`	`1m`	Primeiro bloqueio; dobra a cada nova falha
`auth_rate_limit.lockout_max`	`VISION_AUTH_RATE_LIMIT_LOCKOUT_MAX`	`15m`	Limite máximo do backoff progressivo
`auth_rate_limit.ttl`	`VISION_AUTH_RATE_LIMIT_TTL`	`15m`	Janela de inatividade antes de uma chave ser removida
`auth_rate_limit.max_keys`	`VISION_AUTH_RATE_LIMIT_MAX_KEYS`	`4096`	Limite rígido de chaves rastreadas (limita a memória)