Instalação e operação

Local

Node.js 24+, FFmpeg no PATH, npm ci, npm start. Padrão: host 127.0.0.1, porta 3417. Uma única instância do processo por diretório de dados. Para configuração, copie .env.example para .env e ajuste sem versionar segredos.

GET /health comprova apenas processo HTTP vivo; /api/diagnostics autenticado mostra WhatsApp, filas e armazenamento. Logs não devem receber tokens, URLs de mídia assinadas ou payloads de clientes. data/ contém banco, chave de cifra e chave administrativa: acesso restrito e backup protegido são obrigatórios para preservar sessões.

Servidor próprio

O Compose fornece volume persistente, reinício automático e healthcheck. Configure ADMIN_TOKEN forte e PUBLIC_ORIGIN=https://seu-dominio antes de iniciar. Opcional: CLIENT_TOKEN para segunda credencial das rotas alternativas.

docker compose up -d --build
docker compose logs --tail=50 connect

Coloque proxy TLS (Caddy/Nginx equivalente) na frente de 127.0.0.1:3417. Não exponha a porta sem TLS. Configure limite de corpo pelo menos 45 MiB e timeout suficiente para conversão/download. Não registrar caminhos com tokens na URL da API alternativa. O limite HTTP atual usa IP da conexão TCP (atrás do proxy, pode ser compartilhado por todos os clientes); dimensione e adapte esse limite antes de alto volume. Não habilite trust proxy irrestrito.

O acesso automático local fica desativado em produção; o painel exige chave administrativa. A chave é poderosa e não substitui RBAC multiusuário. Não entregar chave administrativa aos apps consumidores: usar chaves por instância/sistema.

Publicado em 19/10/2026 em https://connect.labregoia.com.br, em VPS KVM 4 no Brasil com Ubuntu 24.04 LTS, Docker e Caddy. Certificado HTTPS válido com renovação automática. Código no repositório privado Labrego-IA/labrego-connect. Os 35 testes automatizados passaram também no contêiner Linux. A Lola foi migrada e reconectou sem novo QR; o processo local foi parado. Isso não substitui homologação de carga e de todas as mídias/webhooks.

A configuração de produção está em deploy/. O aplicativo usa volume persistente e reinício automático; a porta 3417 não é publicada. A chave administrativa de produção é diferente da local. O servidor ainda exige rotina de backups externos e monitoramento de disponibilidade antes da migração geral dos sistemas.

Backup e restauração

Antes de copiar arquivos do banco, pare o processo graciosamente ou use a API SQLite de backup. Nunca copie somente connect.sqlite enquanto houver WAL ativo sem um snapshot consistente.

Backup deve conter banco consistente + encryption.key + admin-token (se chave gerada localmente). Quem possui banco e chave pode decifrar os dados. Mantenha backup com permissões restritas e, fora do computador, armazenamento cifrado com controle de acesso. Não publique em repositório ou anexo.

Uma cópia privada anterior à atualização foi criada em data/backups/. Para restaurar: pare o serviço, preserve o estado atual, restaure banco e chave do mesmo snapshot em diretório limpo e reinicie. Verifique conexão, filas e mídia. Não use uma chave de outro snapshot. Nunca inicie simultaneamente a sessão restaurada e a sessão atual.

Falhas

• Desconexão transitória: até 12 reconexões progressivas; confira motivo no painel. Após esgotar, acione conexão novamente.
• Sessão revogada: gere novo QR. Pausar preserva sessão; desvincular apaga credenciais.
• uncertain: envio pode ter ocorrido. Consulte destinatário/recibo antes de criar novo envio; não retentar automaticamente com nova chave.
• Webhook falho: veja tentativas e HTTP no painel; corrija o consumidor. Após oito tentativas pode reprocessar manualmente, mantendo ID original.
• Mídia recebida: até quatro tentativas de download; falha terminal entrega metadados com downloadAvailable:false. Não interpretar como arquivo recebido com sucesso.
• Disco: acompanhe /api/diagnostics.storage. Mídia fica cifrada no SQLite; backup e volume aumentam com uso. Não existe quota global automática nesta versão.
• Retenção: limpeza horária; mensagens/eventos 30 dias, mídia 30 dias, estatísticas 90 dias. Filas ainda pendentes são preservadas para processamento. Backups não são apagados automaticamente.

Atualizações

Executar testes, snapshot consistente, parar graciosamente, atualizar e iniciar um único processo. Verificar Lola conectada sem novo QR. Migrações de esquema são aditivas no início do serviço. Dependências estão fixadas no lockfile. A biblioteca WhatsApp Web pode exigir atualizações quando o protocolo mudar.

Acesso ao painel com e-mail e senha

O painel aceita contas administrativas criadas por convite. A API técnica continua usando chaves independentes das senhas do painel.

Um administrador autenticado pode criar um convite com POST /api/admin/invites, corpo {"email":"pessoa@empresa.com.br"}. A resposta contém um token de uso único válido por uma hora. Abrir o painel com /#activate=TOKEN&email=EMAIL_CODIFICADO para que a pessoa defina sua senha; o navegador remove o fragmento do endereço assim que carrega o formulário. Não publicar esse link ou registrá-lo em logs.

As senhas exigem de 12 a 128 caracteres e são armazenadas com scrypt e salt aleatório. O cadastro exige convite válido, impede reutilização e verifica a origem. O login limita tentativas por e-mail, usa mensagens genéricas de erro e cria cookie HttpOnly/SameSite=Strict/Secure em produção. Sessões expiram em oito horas ou no reinício do processo. A chave administrativa permanece disponível em “Acesso técnico” para operação; não é a senha pessoal.

Não há e-mail transacional nem recuperação automática de senha nesta versão. A criação de convites é administrativa, sem cadastro público aberto.