diff --git a/Build_Process_Guide.md b/Build_Process_Guide.md new file mode 100644 index 0000000..b4012dd --- /dev/null +++ b/Build_Process_Guide.md @@ -0,0 +1,84 @@ +# ⚙️ Como Funciona o Processo de Build + +Este guia descreve os detalhes internos, comandos, fluxos de compilação e versionamento do ecossistema NewWhats. + +--- + +## 🛠️ Visão Geral do Ciclo de Compilação + +O processo de compilação transforma os códigos fontes TypeScript em Javascript nativo otimizado para produção. O build é estruturado em 4 grandes etapas ordenadas: + +``` +[1. Incremento de Versão] ──► [2. Build Backend (TSC)] ──► [3. Build Plugins (TSC)] ──► [4. Build Frontend (Next.js)] +``` + +--- + +## 🗂️ As Etapas de Compilação em Detalhes + +### 1️⃣ Etapa 1: Controle de Versão Semântica (`v1.+1`) +O script `update-version.js` gerencia de forma segura o registro de deploys em dois locais para serem consumidos em tempo real pelo front e back-end: + +* **Arquivos Gerados:** `deploys.json` e `version.json` (gravados na raiz e na pasta `/public` do frontend). +* **Mapeamento de Informações:** + * Incrementar a versão menor (ex: `v1.0.8` para `v1.0.9`). + * Incrementar o número do build de deploy (ex: `build #9`). + * Capturar o hash abreviado do último commit do Git. + * Capturar a mensagem do commit e o autor. + * Registrar a data e hora UTC exatas da compilação. + +--- + +### 2️⃣ Etapa 2: Compilação do Backend (TypeScript) +O backend reside em `/backend`. +* **Instalação de Dependências:** `npm install` baixa e sintoniza as dependências em produção. +* **Compilação TS:** `npm run build` executa o compilador TypeScript `tsc` mapeado no [tsconfig.json](file:///home/deploy/stack/clube67/newwhats.local/backend/tsconfig.json). +* **Geração Prisma Client:** `npx prisma generate` sintoniza os modelos de dados ORM e expõe os arquivos de tipagem estática do banco de dados na pasta `node_modules/@prisma/client`. +* **Destino:** Todo o código transpilado é gravado na pasta `/backend/dist/`. + +--- + +### 3️⃣ Etapa 3: Compilação Modular de Plugins +Como o NewWhats usa um carregador dinâmico de plugins em produção, os plugins (localizados em `/plugins`) devem ser compilados de forma unificada. +* **Mapeamento de Dependências:** O compilador aponta para as dependências instaladas no core do backend utilizando as chaves `"paths"` no [tsconfig.json](file:///home/deploy/stack/clube67/newwhats.local/plugins/tsconfig.json) do diretório de plugins: + ```json + "paths": { + "*": ["../backend/node_modules/*"] + } + ``` +* **Comando de Compilação:** + ```bash + /backend/node_modules/.bin/tsc -p /plugins/tsconfig.json + ``` +* **Arquivos Gerados:** Os arquivos Javascript correspondentes (`.js` e `.js.map`) são criados dentro de cada pasta específica do plugin correspondente (ex: `/plugins/UnifiedStorageProvider/index.js`), que serão consumidos pelo loader do backend. + +--- + +### 4️⃣ Etapa 4: Compilação do Frontend (Next.js) +O frontend reside em `/frontend`. +* **Injeção de Variáveis:** O build do Next.js estaticiza parâmetros de API e URLs do servidor. Passamos a chave correspondente no disparo: + ```bash + NEXT_PUBLIC_API_URL=https://clube67.com npm run build + ``` +* **Compilação Next.js:** O comando `next build` executa o bundler SWC/Webpack, minifica o HTML/CSS/JS, divide os chunks de carregamento e otimiza as páginas. +* **Destino:** A pasta oculta `/frontend/.next/` e a pasta `/frontend/public/` recebem todos os arquivos finais estáticos prontos para renderização acelerada no navegador. + +--- + +## 🚀 Comandos Úteis p/ Execução Manual (VPS 4) + +```bash +# Entrar no backend e buildar manualmente +cd /home/deploy/stack/clube67/newwhats.local/backend +npm run build + +# Gerar Prisma client manualmente +npx prisma generate + +# Buildar plugins individualmente +npx tsc -p ../plugins/tsconfig.json + +# Testar compilação Next.js localmente +cd ../frontend +npm run build +``` diff --git a/Deploy_VPS_Flow.md b/Deploy_VPS_Flow.md new file mode 100644 index 0000000..c1c9505 --- /dev/null +++ b/Deploy_VPS_Flow.md @@ -0,0 +1,86 @@ +# 🚀 Fluxo de Deploy Multi-VPS (VPS 1, VPS 3 e VPS 4) + +Este guia descreve detalhadamente o fluxo GitOps e despacho de arquivos compilados entre os servidores do ecossistema NewWhats. + +--- + +## 🗺️ Mapa de Papéis dos Servidores + +``` + [ VPS 4: Builder ] ───(git push)───► [ VPS 3: Git/DB ] + │ ▲ + │ │ + (rsync compiles) (DB Connections) + │ │ + ▼ │ + [ VPS 1: Produção ] ───────────────────────────┘ +``` + +| Servidor | IP VPN | Função Principal | Fluxo de Código | +|---|---|---|---| +| **VPS 1 (App Server)** | `10.99.0.1` | Execução em Produção | Recebe os arquivos compilados da VPS 4 | +| **VPS 3 (Data Server)** | `10.99.0.3` | Banco PostgreSQL & Gitea | Centraliza o Git e o banco de dados | +| **VPS 4 (Build Server)**| `10.99.0.4` | Desenvolvimento & Compilação | Compila a plataforma e despacha via Rsync | + +--- + +## 🔄 Fluxo de Deploy Passo a Passo + +O ciclo de deploy adota o modelo **Builder-to-Host** para garantir que servidores de execução de produção (VPS 1) não consumam recursos excessivos de CPU com compilações pesadas de Webpack/Next.js e TypeScript. + +```mermaid +sequenceDiagram + participant Dev as Desenvolvedor (VPS 4) + participant Gitea as Gitea (VPS 3) + participant Builder as Build Process (VPS 4) + participant Prod as Produção Docker (VPS 1) + + Dev->>Gitea: git push origin main + Dev->>Builder: Executa deploy-prod-builder.sh + Builder->>Gitea: git fetch & reset --hard + Builder->>Builder: Incrementa versão (update-version.js) + Builder->>Builder: Compila Backend, Plugins & Frontend + Builder->>Prod: rsync /dist e /node_modules + Builder->>Prod: ssh restart containers +``` + +--- + +## 🖥️ Detalhamento por Máquina + +### 1️⃣ VPS 4 — O Motor de Compilação (Build / Builder) +Todas as modificações de código e atualizações são criadas e validadas nesta máquina. +1. O desenvolvedor realiza as alterações no código local. +2. Faz o commit e envia para a VPS 3: + ```bash + git add . + git commit -m "feat: minha nova funcionalidade" + git push origin main + ``` +3. Executa o script centralizador de deploy: + ```bash + bash /home/deploy/stack/clube67/deploy-prod-builder.sh + ``` + * *O script limpa e reseta a pasta local para bater com a origin/main.* + * *Roda `update-version.js` para incrementar o build (ex: `v1.0.9 (build #9)`).* + * *Compila o backend, gera tipos Prisma, compila plugins e roda `next build`.* + +### 2️⃣ VPS 3 — O Orquestrador e Repositório (Git & Banco de Dados) +A VPS 3 é o coração dos dados do ecossistema. Ela roda o banco PostgreSQL diretamente no host e serve o Gitea. +* **Recebimento de Alterações (Push):** Quando a VPS 4 faz `git push`, a VPS 3 valida a autenticação de chaves SSH ou JWT e atualiza o branch `main`. +* **Disponibilização (Pull):** Durante o deploy automático, a VPS 4 executa `git fetch` e `git reset` apontando de volta para a VPS 3 para garantir consistência. + +### 3️⃣ VPS 1 — O Servidor de Produção (App Server) +A VPS 1 roda os containers Docker `newwhats-backend-prod` e `newwhats-frontend-prod`. +* **Sem Compilação Local:** Ela nunca roda `npm run build` ou instala dependências de desenvolvimento. +* **Recebimento de Binários:** O script da VPS 4 envia apenas as pastas `/dist`, `/node_modules`, `package.json` e os arquivos do frontend prontos (`.next/`, `/public/`) via **rsync** de alta velocidade. +* **Reinício de Containers:** Após os arquivos serem transferidos para a pasta local da VPS 1, a VPS 4 faz um comando SSH seguro que dispara: + ```bash + docker compose restart newwhats-backend-prod newwhats-frontend-prod + ``` + +--- + +## 🚦 Boas Práticas e Resolução de Conflitos +* **Nunca altere código diretamente na VPS 1:** Qualquer edição em produção será apagada no próximo deploy, pois o `rsync --delete` substitui todos os arquivos pelos compilados na VPS 4. +* **Commite antes de Buildar:** Lembre-se sempre de subir suas alterações para o Gitea (`git push`) antes de rodar o deploy-prod-builder.sh, pois o script reseta a árvore de diretórios local para bater com o Git remoto. diff --git a/Home.md b/Home.md index d7b035a..9796d5a 100644 --- a/Home.md +++ b/Home.md @@ -8,16 +8,21 @@ Esta Wiki centraliza toda a documentação arquitetural, resoluções de erros d Selecione um tópico abaixo para acessar o guia detalhado: -### ⚙️ 1. Infraestrutura e Rede +### 🚀 1. Guia de Operações e Deploy (Urgente / Operacional) +* [Fluxo de Deploy Multi-VPS](Deploy_VPS_Flow.md): Passo a passo detalhado do deploy em cada VPS (VPS 1, VPS 3 e VPS 4 - push, pull, etc.). +* [Como Funciona o Processo de Build](Build_Process_Guide.md): Detalhamento técnico de todas as fases de compilação da plataforma. +* [Rede VPN e Segurança Zero-Trust](VPN_Network_Architecture.md): Como as VPSs se comunicam por meio da VPN privada e o modelo de isolamento lateral de rede. + +### ⚙️ 2. Infraestrutura e Rede * [Resolução de Erros de SSL e Proxy](SSL_Proxy_SSL_Fix.md): Como corrigimos o erro crítico de Mixed Content do SSL por proxy reverso. * [Contador de Versões e Painel de Deploy](Versions_Deploy_System.md): Detalhamento do controle de deploys automáticos em ambiente multi-VPS. -### 🔌 2. Arquitetura de Plugins e Core +### 🔌 3. Arquitetura de Plugins e Core * [Sincronização de Caminhos de Plugins](Plugins_Production_Loader.md): Como configurar caminhos relativos de importação em produção (Docker vs Host) de forma automática. * [Troca do Engine Baileys](Baileys_Engine_Swap.md): Comparação e controle entre a engine Baileys Oficial e o fork InfiniteAPI para mensagens ricas. * [Correção de Wasabi Storage](Wasabi_Storage_Correction.md): Detalhes da resolução de acúmulo de arquivos de mídia locais no servidor Wasabi. -### 🏢 3. Integração Multi-Tenant SaaS +### 🏢 4. Integração Multi-Tenant SaaS * [Integração de Empresa e Plugins Clientes](Plugin_Empresa_Integration.md): Visão geral da comunicação entre o Motor NewWhats e o plugin `newwhats-client` embarcado. --- diff --git a/VPN_Network_Architecture.md b/VPN_Network_Architecture.md new file mode 100644 index 0000000..09c0915 --- /dev/null +++ b/VPN_Network_Architecture.md @@ -0,0 +1,70 @@ +# 🛡️ Arquitetura da Rede VPN e Segurança Zero-Trust + +Este documento explica o funcionamento da rede privada virtual (VPN) que interconecta as instâncias de VPS do ecossistema Clube67 de forma segura. + +--- + +## 🔒 Princípio de Segurança: Isolamento de Movimentação Lateral + +Por motivos rígidos de segurança digital e boas práticas de rede corporativa: +1. **Nenhum Servidor de Produção** (como a VPS 1) possui portas de bancos de dados ou serviços críticos expostas diretamente para a internet pública. +2. **Isolamento de Credenciais (Zero-Trust):** As VPSs não possuem chaves SSH automáticas e irrestritas para acessar umas às outras sem controle. Isso impede que, caso um hacker ou malware consiga comprometer a aplicação na VPS 1, ele obtenha acesso de controle imediato para alterar códigos na VPS 4 (Build) ou ler/deletar o banco de dados principal na VPS 3 (Data). +3. **Orquestrador de Fluxo Assíncrono:** Em vez de conexões diretas síncronas entre servidores, o **Gitea (VPS 3)** e o **Servidor de Deploy (VPS 4)** atuam como as pontes controladoras de fluxo de estado de forma assíncrona. + +--- + +## 🌐 Mapeamento de IPs na Rede VPN (WireGuard) + +A VPN funciona em uma faixa de IP isolada, permitindo que as máquinas se comuniquem internamente de forma criptografada por meio de portas UDP seguras configuradas com o protocolo **WireGuard**: + +``` + [ VPN WireGuard privada ] + Subrede: 10.99.0.0 / 24 + │ + ┌───────────────────────┼───────────────────────┐ + ▼ ▼ ▼ + [ VPS 1: App ] [ VPS 3: Data ] [ VPS 4: Build ] + 10.99.0.1 10.99.0.3 10.99.0.4 +``` + +### 📋 Mapeamento de Conexões e Serviços por IP + +#### 📶 VPS 1 — Servidor de Aplicação (`10.99.0.1`) +* **Serviços Ativos na VPN:** Porta do Nginx reverso e SSH restrito. +* **Acesso do Backend:** O backend do NewWhats (que roda em container Docker nesta máquina) conecta-se de forma direta e segura ao banco de dados PostgreSQL apontando para o IP da VPN: + `DATABASE_URL=postgresql://deploy:senha@10.99.0.3:5432/newwhats` +* **Acesso ao Cache:** O backend conecta-se ao DragonflyDB apontando para: + `REDIS_URL=redis://10.99.0.3:6379` + +#### 📶 VPS 3 — Servidor de Dados e Repositórios (`10.99.0.3`) +* **Serviços Ativos na VPN:** + * PostgreSQL (porta `5432` - escutando apenas na interface `10.99.0.3`). + * DragonflyDB (porta `6379` - escutando apenas na interface `10.99.0.3`). + * Gitea (porta `3000` / SSH `22` - gerenciamento Git). +* **Segurança:** Portas de dados cruciais (Postgres e Cache/Redis) são totalmente invisíveis e inacessíveis a partir da internet externa, bloqueando qualquer tentativa de força bruta de IPs desconhecidos. + +#### 📶 VPS 4 — Servidor de Build / Automação (`10.99.0.4`) +* **Serviços Ativos na VPN:** SSH interno para o builder iniciar comandos locais. +* **Acesso ao Git:** O repositório git local aponta para o endereço seguro da VPS 3: + `ssh://git@10.99.0.3/ruicesar/clube67_newwhats.local.git` +* **Despacho de Build:** Realiza comandos `rsync` de alta velocidade e criptografados pela VPN direcionados à pasta local da VPS 1 (`10.99.0.1`) para implantar as builds geradas. + +--- + +## 🛠️ Comandos de Diagnóstico e Rede Úteis + +Se você precisar testar se a VPN está ativa e saudável a partir de qualquer uma das máquinas: + +```bash +# Verificar se as outras VPSs estão respondendo na VPN +ping 10.99.0.1 -c 3 +ping 10.99.0.3 -c 3 +ping 10.99.0.4 -c 3 + +# Testar se a porta do banco de dados na VPS 3 está aberta e escutando +nc -zvw3 10.99.0.3 5432 + +# Testar conexão com o DragonflyDB/Redis na VPS 3 +nc -zvw3 10.99.0.3 6379 +``` +O isolamento por WireGuard garante alto desempenho de tráfego, baixíssima latência e criptografia robusta a nível de kernel para toda a infraestrutura da plataforma Clube67!