Topologia de referência

O desenho

                    Internet / rede corporativa
                               │
                               ▼
                   ┌───────────────────────┐
                   │     Proxy reverso     │  TLS, nome de domínio
                   │  (Traefik, Nginx…)    │  read timeout ≥ 600 s
                   └───────────┬───────────┘
                               │  HTTP :80
                   ┌───────────▼───────────┐
                   │      Aplicação        │  sem volume, sem estado
                   │   (1..N contêineres)  │  /healthz
                   └─────┬───────────┬─────┘
                         │           │
             :5432 ──────▼──         ▼────── :9000
         ┌────────────────────┐  ┌────────────────────┐
         │     PostgreSQL     │  │ Armazenamento S3   │
         │  dados, esquema,   │  │ anexos, evidências,│
         │  auditoria, SLA    │  │ arquivos, backups  │
         └────────────────────┘  └────────────────────┘
                         ▲
                         │  (opcional)
              ┌──────────┴──────────┐
              │   Evolution API     │  mensageria de WhatsApp
              └─────────────────────┘

   Agentes de endpoint (Windows) ──HTTPS──► Proxy reverso ──► Aplicação
                                  └──HTTPS──► Armazenamento S3 (evidências, por URL assinada)

As camadas, e por que estão separadas

Borda: proxy reverso

Termina o TLS, resolve o nome e — o detalhe que mais causa problema — sustenta conexões longas. O produto usa consulta longa para manter telas atualizadas, com espera de até 600 segundos. Proxy com o padrão de 60 segundos derruba a conexão no meio, e o sintoma não é erro: é interface que pisca e recarrega sem explicação no log da aplicação.

Configure read timeout de no mínimo 600 segundos. A aplicação já vem com HTTP_REQUEST_TIMEOUT_MS=660000, deliberadamente maior, para que a ponta que desiste primeiro seja sempre a do cliente e não o meio do caminho.

Aplicação

Contêiner sem estado: não tem volume, e nada do que importa vive dentro dele. Consequências práticas:

• Escalar é horizontal. Suba mais cópias apontando para o mesmo banco. Não há sessão presa a um processo.
• Atualizar é substituir. docker compose pull && up -d — nenhum dado a preservar no contêiner.
• Perder a máquina não perde dado. O que precisa de backup é o banco e o armazenamento de objetos.

Dentro de um único contêiner, MANAGER_WORKERS distribui as requisições entre processos. Como o gargalo é CPU da aplicação, é o primeiro ajuste a fazer quando o número de atendentes simultâneos cresce — antes de pensar em mais máquinas.

PostgreSQL

Todos os dados: chamados, ativos, telemetria, auditoria, permissões, configuração. É o que precisa de backup e de plano de restauração.

Use banco dedicado. O produto cria e migra o próprio esquema na subida, e compartilhar banco com outro sistema transforma cada atualização em risco desnecessário.

Armazenamento de objetos

Anexos de chamado, evidências de auditoria, arquivos do File Server e destinos de backup. Os agentes de endpoint enviam evidência direto para o armazenamento, por URL assinada — o arquivo não passa pela aplicação, o que evita transformar o processo da aplicação em gargalo de upload.

Isso tem uma consequência de rede: as máquinas com agente precisam alcançar o armazenamento, não só a aplicação. Ver Portas e exposição.

Agentes de endpoint

Instalados nas máquinas Windows, conectam de dentro para fora: enviam sinal de vida, buscam trabalho pendente e reportam telemetria. Nada abre porta na máquina do usuário, e nada precisa de rota da rede da empresa para a estação.

Cadência padrão: sinal de vida a cada 60 s, busca de trabalho a cada 30 s. Ambas configuráveis — e ambas com efeito direto no crescimento do banco, ver dimensionamento.

Onde o estado vive

Vale a tabela, porque ela define o que backup precisa cobrir:

Onde	O que	Backup
PostgreSQL	Todos os dados e a configuração	Obrigatório
Armazenamento S3	Anexos, evidências, arquivos	Obrigatório
Contêiner da aplicação	Nada	Não se aplica
.env	Segredos, inclusive a chave de cifra do cofre	Obrigatório, e fora do repositório

A chave em MANAGER_SECRET_ENC_KEY merece menção separada: sem ela, um backup do banco restaurado não consegue decifrar os segredos do cofre. Guarde-a onde guarda as demais chaves da organização, não apenas no arquivo do servidor.

Instalação de avaliação

Tudo em uma máquina, com a porta publicada direto e sem proxy: serve para conhecer o produto. Não use assim com dado real — sem TLS, o cookie de sessão trafega em claro.

Instalação com folga

• Proxy reverso na borda, com TLS
• Duas cópias da aplicação atrás dele, mesmo banco
• PostgreSQL em máquina própria, com backup e ponto de restauração
• Armazenamento de objetos em máquina própria, com disco que possa crescer
• Rede interna separada: só o proxy é alcançável de fora