docs(wiki): add detailed multi-vps deploy steps, build process guides, and vpn network architecture docs
Antigravity AI Agent
@@ -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
|
||||
```
|
||||
@@ -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.
|
||||
+8
-3
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
@@ -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!
|
||||
Reference in New Issue
Block a user