Visão geral da configuração

O Vision lê o config.yaml do seu diretório de trabalho e, em seguida, sobrepõe as variáveis de ambiente. As variáveis de ambiente sempre prevalecem sobre os valores do arquivo, de modo que os segredos podem ficar fora do arquivo de configuração.

Quando instalado via vision install, o diretório de trabalho é /etc/vision/ e o serviço carrega:

• /etc/vision/config.yaml — configurações não secretas
• /etc/vision/vision.env — segredos, carregados como variáveis de ambiente pelo systemd

Um config.yaml ausente não é problema — o servidor recorre aos padrões incorporados (modo de desenvolvimento, porta 3303, banco de dados em ./data/vision.db).

A configuração é validada na inicialização. Valores inválidos — timeouts não positivos, concorrências iguais a zero, TTLs fora do intervalo — abortam a inicialização com um erro config: validate: no journal do serviço que nomeia a chave com problema.

Verifique uma edição de configuração antes de reiniciar com vision config validate, ou imprima a configuração efetiva mesclada (segredos ocultados) com vision config print — consulte a Referência da CLI. vision config print --reference imprime todas as chaves, o padrão de cada uma e uma descrição, sem exigir uma configuração instalada.

sudo vision config validate
sudo vision restart

Seleção de ambiente

O valor env (development, staging ou production) altera o rigor da validação:

Comportamento	development	production
CORS allowed_origins	curinga / vazio permitido	origens concretas obrigatórias
jwt_secret	opcional (efêmero)	obrigatório
Chave de criptografia	opcional (stub)	obrigatória
Cabeçalhos de segurança / CSP estrito	relaxados	aplicados

O staging segue a coluna de produção para as validações estritas: origens CORS concretas, jwt_secret e a chave de criptografia também são obrigatórios nele.

Obrigatório em produção

Uma implantação em produção precisa destes segredos e dos valores iniciais do administrador. O instalador os gera automaticamente:

/etc/vision/vision.env

VISION_ENCRYPTION_KEY=<base64 32 bytes>     # openssl rand -base64 32
VISION_AUTH_JWT_SECRET=<base64 32 bytes>    # openssl rand -base64 32
ADMIN_EMAIL=admin@localhost
ADMIN_PASSWORD=<password>

O segredo JWT e a chave de criptografia devem ser dois valores diferentes — a inicialização falha se forem idênticos.

Também são necessárias origens CORS concretas no config.yaml:

env: production
http:
  allowed_origins:
    - "https://vms.example.com"

Atrás de um proxy reverso

Quando o Vision fica atrás de um proxy que termina o TLS (nginx, Caddy, Traefik), defina http.secure_cookies: true (o instalador grava false) e garanta que o proxy encaminhe o Host original e os cabeçalhos de upgrade de WebSocket/SSE. O HSTS é habilitado automaticamente quando env: production; http.tls_enabled não é mais uma opção de configuração.

Mantenha http.secure_cookies: false somente enquanto os usuários abrirem o Vision diretamente por HTTP simples. A URL que o servidor Alta usa para alcançar o Vision na autorização WHEP é definida explicitamente para cada servidor (sua callback base URL) quando você o adiciona — consulte Conectar um servidor Alta.

Banco de dados e migrações

O banco de dados é SQLite (modo WAL). As migrações de esquema são executadas automaticamente a cada inicialização — não há uma etapa de migração separada, e as migrações são somente para frente: não existe caminho de downgrade. Use sudo vision backup antes de uma atualização, de modo que o backup seja o seu plano de reversão — consulte Backup e restauração.

Consulte a referência completa para ver todas as opções e suas variáveis de ambiente.