Como funciona

O Vision é um plano de controle sobre o Cesbo Alta. O Alta recebe e entrega os streams das câmeras; o Vision gerencia câmeras, usuários, gravações e alertas, e faz o proxy do vídeo para o navegador.

Binário único

O servidor é um único binário Go com a interface web em Vue 3 e o mecanismo de banco de dados SQLite embutidos. A interface é incorporada em tempo de compilação via //go:embed, então não há mais nada para instalar — sem Node.js, sem servidor web separado, sem banco de dados externo. O estado fica em um único arquivo SQLite (modo WAL); as migrações de esquema são executadas automaticamente na inicialização.

Integração com o Alta

O Vision se comunica com cada servidor Alta via REST para CRUD e status das câmeras, e intermedeia o vídeo para o navegador:

sequenceDiagram
    participant B as Browser
    participant V as Vision
    participant A as Cesbo Alta
    B->>V: Open camera
    V->>A: Negotiate stream (signed token)
    B-->>A: WHEP (WebRTC) — low latency
    Note over B,A: falls back to HLS if WebRTC fails
    A-->>B: Live video

Toda chamada de saída ao Alta é envolvida por novas tentativas, um circuit breaker e um bulkhead que limita a concorrência. Se um servidor Alta se tornar inacessível, o Vision reduz a carga apenas para esse servidor e continua atendendo os demais — um Alta degradado nunca derruba o processo. O vídeo ao vivo tem seu próprio breaker por servidor, de modo que uma rajada de requisições de vídeo com falha nunca pausa o PTZ, o arquivo nem as verificações de integridade.

Uma breve oscilação de conectividade ou uma reinicialização rápida do Alta é distinguida de uma interrupção prolongada: o Vision corrobora uma suspeita de falha em duas verificações consecutivas — e, no caso de uma reinicialização, com o ID da instância e o uptime informados pelo Alta — antes de colocar as câmeras offline. Oscilações não fazem as câmeras alternarem de estado, interrupções reais são detectadas em poucos segundos, e um servidor que oscila repetidamente é reportado como fora do ar uma única vez, em vez de uma tempestade de eventos.

Streaming

A reprodução usa WHEP (WebRTC) primeiro para baixa latência, recorrendo automaticamente ao HLS. Uma câmera pode ter um segundo stream de baixa resolução, o Sub: o Alta recebe um segundo receptor no mesmo canal, e os mosaicos densos reproduzem o Sub enquanto as visualizações grandes reproduzem o Main — veja streams Main e Sub. O acesso ao stream é autorizado com JWTs HS256 de curta duração assinados por servidor Alta, de modo que as requisições de playlist e WebRTC não podem ser reutilizadas indefinidamente.

Workers em segundo plano

O trabalho que não deve bloquear requisições é executado em workers, cada um dos quais degrada de forma independente: health_server (status do servidor Alta e detecção de desvio de configuração), health_camera (status da câmera), alta_prober (sondagem rápida de disponibilidade), clips (exportação via ffmpeg), alerts, notifications, reconcile (limpeza de recursos órfãos do Alta) e cleanup (retenção). O conjunto habilitado é configurável.

Capturas de tela manuais são iniciadas pelo navegador. O antigo nome de worker screenshots é inválido; io foi retirado do conjunto padrão e permanece apenas opcional, por compatibilidade.

A entrega de alertas e notificações é durável: as entregas pendentes são persistidas e repetidas com backoff, e sobrevivem a uma reinicialização.

O worker reconcile só exclui um recurso que consiga provar que o Vision criou — um registro de propriedade gravado no momento da criação, e não um palpite a partir do nome do recurso — de modo que duas instalações que compartilham um mesmo servidor Alta nunca podem excluir os recursos uma da outra. Veja Conectar um servidor Alta para a visão voltada ao operador.

Segurança

• Autenticação com sessões JWT; senhas com hash Argon2id.
• Controle de acesso baseado em papéis — administrador global mais operador/visualizador por grupo.
• Criptografia em repouso (AES-256-GCM) para campos sensíveis, como as credenciais do Alta, com suporte à rotação de chaves.
• Proteção reforçada — CSP e HSTS estritos em produção, limitação de taxa por usuário e um usuário de sistema dedicado sem login quando instalado como serviço.

Observabilidade

O servidor expõe /healthz, /readyz e /metrics do Prometheus, emite logs JSON estruturados e propaga um X-Request-ID em cada requisição e em cada chamada de saída ao Alta para rastreamento de ponta a ponta.