feat: sincronização de desenvolvimento local da VPS 4 para o Gitea

2026-05-10 07:38:54 +02:00
parent 621fbfba64
commit 3396fa0598
402 changed files with 234697 additions and 0 deletions
@@ -0,0 +1,95 @@
+# 📝 Relatório Técnico de Implementação — NewWhats SaaS
+
+Este relatório descreve as ações executadas, decisões arquiteturais consolidadas, riscos mapeados e próximos passos recomendados para o ecossistema NewWhats.
+
+---
+
+## 🏗️ Decisões Arquiteturais e Infraestrutura
+
+Para atender à premissa de manter o host limpo (sem dependências locais de Node/npm/PM2) e em conformidade com o design "V8 Bunker", a aplicação foi **100% containerizada**:
+
+1. **Estrutura de Containerização (Multi-Stage) e Resolução do Erro do Prisma**:
+   * **newwhats-backend**: Inicialmente construído com `node:20-alpine`. Identificamos que a engine binária do Prisma requer `libssl.so.1.1` (Glibc/OpenSSL 1.1) que foi removido no Alpine moderno. 
+   * **Solução Proativa**: Migramos a base do backend para `node:20-slim` (Debian-based) e instalamos nativamente as dependências `openssl` e `ca-certificates`.
+   * Adicionamos `"debian-openssl-3.0.x"` no bloco `binaryTargets` do `schema.prisma` para compilar o driver otimizado. O backend agora compila e inicializa instantaneamente em conformidade de segurança máxima.
+2. **Reverse Proxy Unificado e Resiliente (Nginx + Traefik)**:
+   * Mantivemos o Traefik gerenciando os certificados SSL (`HTTPS`) de forma nativa e automática na borda (Portas `80/443`).
+   * **Correção no Nginx (`default.conf`)**: Corrigimos o typo da variável de cabeçalho (`$proxy_add_x_forwarded-for` para `$proxy_add_x_forwarded_for` com sublinha).
+   * **Configuração de Alta Resiliência**: Para evitar que o Nginx falhasse caso o backend estivesse em inicialização, adicionamos a dependência `depends_on` no Compose e configuramos o resolver DNS interno do Docker (`resolver 127.0.0.11 valid=30s`) com variáveis dinâmicas de proxy. O Nginx agora inicia de forma instantânea e tolerante a falhas.
+3. **Persistência de Sessões**:
+   * O Baileys armazena os arquivos físicos de conexões das contas do WhatsApp. Criamos um volume compartilhado que mapeia o diretório interno do container para a pasta física do host `/home/deploy/newwhats-sessions`, garantindo que os usuários não precisem re-escanear o QR code quando os containers forem atualizados ou recriados.
+
+---
+
+## 📂 Arquivos Modificados e Criados
+
+* 📝 [docker-compose.yml](file:///home/deploy/stack/clube67/docker-compose.yml): Registra os novos serviços, regras de dependências e volumes compartilhados.
+* 📝 [default.conf](file:///home/deploy/stack/clube67/nginx/default.conf): Mapeamento de proxies Nginx resilientes e regras de conexões WebSockets.
+* 📝 [Dockerfile (Backend)](file:///home/deploy/stack/clube67/newwhats.local/backend/Dockerfile): Definição de build modular baseada em Debian Slim com suporte total ao Prisma Engine.
+* 📝 [schema.prisma](file:///home/deploy/stack/clube67/newwhats.local/backend/prisma/schema.prisma): Configuração de compilação multi-target para garantir compatibilidade OpenSSL 3.0.
+* 📝 [TAREFAS.md](file:///home/deploy/stack/clube67/newwhats.local/TAREFAS.md): Planejamento detalhado por entregáveis.
+
+---
+
+## 🚨 Pontos de Atenção e Homologação da VPS 3
+
+> [!WARNING]
+> **Status das Dependências de Rede na VPS 3 (`10.99.0.3`)**:
+> Ao inicializar o backend, verificamos nos logs do container que a conexão com o DragonflyDB (Redis local no compose) conectou perfeitamente (`{"msg":"DragonflyDB conectado"}`), mas o Prisma parou na barreira de inicialização:
+> 
+> `Can't reach database server at 10.99.0.3:5432`
+> 
+> * **Diagnóstico**: O IP da VPS 3 responde aos pings da VPN instantaneamente, mas a porta `5432` retorna `Connection Refused` do host de destino.
+
+---
+
+## 🛡️ Guia de Ativação do PostgreSQL na VPS 3
+
+Para liberar o acesso do backend (VPS 1) ao PostgreSQL na VPS 3 de forma totalmente segura, siga os passos abaixo diretamente na VPS 3 (como usuário `deploy`):
+
+### 1. Configurar escuta do PostgreSQL na interface VPN
+Abra o arquivo de configuração principal (o caminho exato depende da versão instalada, ex: `14` ou `15`):
+```bash
+sudo nano /etc/postgresql/15/main/postgresql.conf
+```
+Procure pela linha `listen_addresses` e altere para:
+```ini
+listen_addresses = 'localhost,10.99.0.3'
+```
+*(Isso instrui o PostgreSQL a aceitar conexões locais e conexões vindas apenas da interface segura do WireGuard, mantendo a porta fechada para a internet pública).*
+
+### 2. Autorizar o IP da VPS 1 no controle de acesso do PostgreSQL
+Abra o arquivo de controle de conexões do cliente:
+```bash
+sudo nano /etc/postgresql/15/main/pg_hba.conf
+```
+Adicione a seguinte linha de liberação ao final do arquivo:
+```text
+# Liberar conexões seguras da VPS 1 (Produção) para o NewWhats
+host    newwhats        newwhats        10.99.0.1/32            scram-sha-256
+```
+*(Substitua `scram-sha-256` por `md5` se o seu banco estiver configurado com criptografia legado).*
+
+### 3. Reiniciar o serviço do PostgreSQL
+Aplique as novas configurações recarregando o serviço:
+```bash
+sudo systemctl restart postgresql
+```
+
+### 4. Validar as regras de Firewall (nftables) na VPS 3
+Se a VPS 3 usar `nftables` (como indicado no layout "V8 Bunker"), verifique se as regras atuais permitem o tráfego de entrada na porta `5432` vindo de `10.99.0.1`.
+Para listar e validar as regras atuais na VPS 3:
+```bash
+sudo nft list ruleset
+```
+Certifique-se de que há uma regra de aceitação similar a esta na tabela de entrada da VPN:
+```text
+ip saddr 10.99.0.1 tcp dport 5432 accept
+```
+
+---
+
+## ⏭️ Próximos Passos
+
+1. **Liberar PostgreSQL na VPS 3**: Execute os passos acima na VPS 3 para abrir o canal seguro de conexão.
+2. **Atualização Automática**: Assim que a porta `5432` estiver liberada, o container `clube67-newwhats-backend-1` (que está configurado para tentar se reconectar automaticamente) se conectará instantaneamente, executará as rotinas de inicialização e o painel em `clube67.com` estará 100% no ar!