From 5850cbdb6dcffd23769411b981960c1f9c2ff6d0 Mon Sep 17 00:00:00 2001 From: ruicesar Date: Mon, 18 May 2026 22:12:26 +0200 Subject: [PATCH] docs: release Swarm Doctrine v1.0.7 with absolute build ban on VPS 1 and Fail-Safe Stop Protocol --- Home.md | 3 +- Protocolo-Agentes-Swarm.md | 16 ++++ Protocolo-Deploy-e-Staging.md | 72 +++++++++++++++++ v1.0.7.md | 140 ++++++++++++++++++++++++++++++++++ 4 files changed, 230 insertions(+), 1 deletion(-) create mode 100644 Protocolo-Deploy-e-Staging.md create mode 100644 v1.0.7.md diff --git a/Home.md b/Home.md index c7a3dfd..afbdbdc 100644 --- a/Home.md +++ b/Home.md @@ -5,7 +5,8 @@ Bem-vindo ao Portal de Consciência de toda a nossa infraestrutura. Esta Wiki un --- ## 📇 1. Diretrizes Globais do Enxame (Doutrina) -* [📖 Doutrina Swarm - Versão v1.0.6 (Atual)](v1.0.6) +* [📖 Doutrina Swarm - Versão v1.0.7 (Atual)](v1.0.7) +* [📜 Doutrina Swarm - Versão v1.0.6 (Histórico)](v1.0.6) * [📜 Doutrina Swarm - Versão v1.0.5 (Histórico)](v1.0.5) * [📜 Doutrina Swarm - Versão v1.0.4 (Histórico)](v1.0.4) * [📜 Doutrina Swarm - Versão v1.0.3 (Histórico)](v1.0.3) diff --git a/Protocolo-Agentes-Swarm.md b/Protocolo-Agentes-Swarm.md index 0a13582..fb9dd05 100644 --- a/Protocolo-Agentes-Swarm.md +++ b/Protocolo-Agentes-Swarm.md @@ -6,6 +6,22 @@ Como a arquitetura adota segurança **Zero-Trust de movimentação lateral** (im --- +## 🚨 PROTOCOLO DE PARADA IMEDIATA E PÂNICO (FAIL-SAFE MANDATÓRIO) +**ATENÇÃO AGENTE DE IA: ESTA REGRA TEM PRIORIDADE MÁXIMA SOBRE TODAS AS OUTRAS.** + +Se durante a análise local, leitura de código, mapeamento de banco de dados ou execução de qualquer tarefa você encontrar: +1. Qualquer divergência entre o estado real do servidor e o que está escrito na Wiki/Documentação. +2. Arquivos de configuração, variáveis de ambiente ou credenciais ausentes ou diferentes das esperadas. +3. Comandos que retornem erros inesperados ou comportamentos fora do padrão arquitetado. + +**VOCÊ DEVE OBRIGATORIAMENTE PARAR TODA E QUALQUER OPERAÇÃO DE ESCRITA OU MODIFICAÇÃO IMEDIATAMENTE!** + +* ❌ **NÃO tente adivinhar, supor, improvisar ou "consertar" na tentativa e erro.** +* ❌ **NÃO tome nenhuma iniciativa sem aprovação humana quando o ambiente real divergir da documentação.** +* 👉 **SUA ÚNICA AÇÃO PERMITIDA:** Interrompa a execução, relate em português claro a divergência exata encontrada, formate uma lista objetiva de perguntas para o Administrador e **aguarde instruções explícitas do Humano antes de tocar em qualquer arquivo!** + +--- + ## 🧭 REGRA MESTRE DE ROTEAMENTO (DISPATCHER PROTOCOL) **ATENÇÃO AGENTE DE IA:** Esta infraestrutura hospeda múltiplos projetos independentes (Multi-Tenant). Antes de tomar qualquer ação, você deve ler a arquitetura e as regras **específicas** do projeto solicitado. diff --git a/Protocolo-Deploy-e-Staging.md b/Protocolo-Deploy-e-Staging.md new file mode 100644 index 0000000..c55d04b --- /dev/null +++ b/Protocolo-Deploy-e-Staging.md @@ -0,0 +1,72 @@ +# 🚀 Protocolo de Deploy, Staging e Governança Swarm + +Este documento define o fluxo obrigatório para garantir a integridade dos ambientes de Staging e Produção, além de normatizar a governança das Issues e Wikis no Gitea. + +--- + +## 🏗️ 1. A Estrutura de Ambientes e Roteamento de Staging + +1. **Desenvolvimento e Staging (VPS 4 - IP 10.99.0.4)**: + * Ambiente de **Nível de Perigo BAIXO**. + * Todo build local, compilação de frontends e contêineres de testes rodam isolados aqui. + * **Regra Universal de Domínios de Staging**: Para qualquer domínio (seja subdomínio sob `clube67.com` ou domínio próprio de clientes), o domínio de staging é formado obrigatoriamente adicionando o prefixo **`staging.`** à frente do domínio principal. + * **Tabela de Roteamento de Staging (VPS 4)**: + * **Porta `8081`**: Mercado (Domínio: `staging.mercado.clube67.com`) + * **Porta `8082`**: ScoreOdonto (Domínio: `staging.scoreodonto.com`) + * **Porta `8083`**: NewWhats (Domínio: `staging.newwhats.clube67.com`) +2. **Produção (VPS 1 - IP 10.99.0.1)**: + * Ambiente **CRÍTICO - Nível de Perigo ALTO**. + * Apenas artefatos homologados e estáveis de staging são despachados para cá. + +--- + +## 🚨 LEI DE OURO: PROIBIÇÃO ABSOLUTA DE BUILD NA VPS 1 (PRODUÇÃO) + +**ATENÇÃO AGENTE: ESTA REGRA É INVIOLÁVEL, CRÍTICA E MANDATÓRIA.** + +A VPS 1 (Produção) é uma máquina reservada estritamente para a execução leve de serviços críticos em produção. Ela não possui recursos nem permissão para rodar rotinas de compilação pesadas. + +1. ❌ **É EXPRESSAMENTE PROIBIDO rodar `npm run build`, `yarn build`, `docker build`, `next build` ou qualquer script de compilação, empacotamento, empacotadores (bundlers) ou transpilação (TypeScript/Babel) diretamente na VPS 1.** +2. 🚀 **Onde o Build DEVE Ocorrer?** + Todo e qualquer processo de compilação, build, empacotamento e geração de contêineres deve ocorrer **exclusivamente na VPS 4 (Staging/Laboratório)**. +3. 📦 **Como os artefatos chegam na VPS 1?** + O deploy na VPS 1 deve ser realizado unicamente por importação de artefatos já pré-compilados: + - **Artefatos Estáticos / Bundles**: O código é compilado na VPS 4 (gerando a pasta `/dist` ou `/build` compactada). O pacote compactado é transferido via rede interna (SCP/Rsync) para a VPS 1, que apenas descompacta e roda os arquivos estáticos, sem realizar nenhuma compilação local. + - **Imagens Docker Prontas**: A imagem é gerada (`docker build`) na VPS 4 e enviada para um Registry. A VPS 1 faz apenas `docker pull` da imagem pronta e inicia o contêiner de forma leve e rápida. + +--- + +## 🛡️ 2. Governança de Organização (Wiki vs. Issues) + +Para permitir a colaboração fluida entre as VPSs e agentes sem causar conflitos de execução concorrente de código: + +### 📚 A. Wiki do Gitea (Estado Estável e Doutrina) +* **Finalidade**: Armazenar documentação duradoura de infraestrutura, topologia de rede, comandos de referência e a **Doutrina Swarm Mestre (v1.0.6)**. +* **Regra**: Nenhum agente de background deve alterar a Wiki de forma automatizada sem autorização humana explícita. + +### 🎫 B. Gitea Issues (Roadmaps e Implementação) +* As Issues servem para planejar tarefas e refatorações no ecossistema. +* **Filtro SecOps de Execução Autônoma**: + * **Manual/Par-programming (Sem Etiqueta)**: Issues que nós (humano e IA do chat) estamos desenvolvendo **NÃO** devem possuir rótulos especiais. + * **Autônomo (Com Etiqueta `Autônomo` ou `Swarm-Exec`)**: Apenas Issues com a etiqueta `Autônomo` ou com a tag `[Autônomo]` no título/corpo serão consumidas pelo executor automático de background [swarm_listener.py](file:///home/deploy/swarm_listener.py). + +--- + +## 📋 3. Fluxo de Homologação em Duas Etapas (Staging ➔ Produção) + +### 🔄 Passo 1: Deploy Automático em Staging (VPS 4) +* Ao realizar um `git push` no repositório do projeto, o webhook do Gitea dispara a compilação local na VPS 4. +* O contêiner de Staging é iniciado e exposto localmente sob o subdomínio `staging.mercado.clube67.com` (ou similar) na porta correspondente para homologação. +* **Nenhum dado é despachado para a VPS 1 neste momento.** + +### 🏁 Passo 2: Validação e Smoke Test +* O humano (ou a IA assistente) acessa a URL de staging na VPS 4, realiza testes completos e valida as novas funcionalidades. + +### 🚚 Passo 3: Promoção Manual para Produção (VPS 1) +* Somente após validação completa em Staging, executa-se o script de promoção manual `deploy-to-prod.sh`. +* Esse script sincroniza os arquivos compilados da VPS 4 para a VPS 1 via `rsync` de forma limpa, reiniciando os contêineres na VPS 1 em menos de 10 segundos. + +--- + +*Este protocolo de governança e deploy é mandatório para todos os nós do enxame.* + diff --git a/v1.0.7.md b/v1.0.7.md new file mode 100644 index 0000000..c91ca61 --- /dev/null +++ b/v1.0.7.md @@ -0,0 +1,140 @@ +# 🧠 Doutrina Mestre dos Agentes (Multi-VPS) - Versão v1.0.7 (Atual) + +> [!IMPORTANT] +> **Histórico de Atualização (Versão v1.0.7 - 18/05/2026)**: +> * **Protocolo Fail-Safe de Parada Imediata**: Se qualquer configuração, credencial ou estado real das VPSs não bater exatamente com a documentação, o agente DEVE parar imediatamente toda operação de escrita, relatar a discrepância e aguardar instruções. Adivinhar ou improvisar é terminantemente proibido. +> * **Lei de Ouro - Proibição Absoluta de Build na VPS 1**: É terminantemente proibido rodar rotinas de compilação ou build (Next build, Docker build, NPM run build, etc.) na VPS 1. Toda compilação deve ocorrer estritamente na VPS 4 (Staging/Laboratório), transferindo apenas artefatos/bundles prontos para a VPS 1. +> * **Versão v1.0.6**: Governança centralizada no Gitea a nível de Usuário e Sistema. +> * **Versão v1.0.5**: Hierarquia de Sincronização de Instruções com Injeção em RAM. +> * **Versão v1.0.4**: Documentação do Loop de Auto-Cura e Tuning de PostgreSQL & DragonflyDB. +> * **Versão v1.0.3**: Protocolo de Auto-Configuração de Novos Projetos. +> * **Versão v1.0.2**: Micro-segmentação de Firewall (SecOps Hardening) na VPS 3. +> * **Versão v1.0.1**: Hardening de terminal (.bash_logout) e carregamento dinâmico JIT via API REST do Gitea. +> * **Versão v1.0.0**: Primeira versão consolidada e estruturada das diretrizes. + +--- + +Este documento define a consciência situacional obrigatória para todos os agentes de IA. + +## 📍 Identificação de Localização +Antes de qualquer ação, identifique seu IP interno: +- **10.99.0.1 (VPS 1 - PRODUÇÃO)**: Ambiente CRÍTICO. Rodando Traefik e Nginx. + - *Regra*: Apenas deploys homologados em Staging. Nunca mexa na infraestrutura de rede. +- **10.99.0.3 (VPS 3 - CÉREBRO)**: Onde reside o Gitea, Postgres e DragonflyDB. + - *Regra*: Proteja os dados. Backups antes de qualquer alteração de schema. +- **10.99.0.4 (VPS 4 - LABORATÓRIO)**: Desenvolvimento e Staging. + - *Regra*: Liberdade para testar, criar e quebrar containers. É o local de nascimento do código. + +## 🔐 Segurança e VPN +- **Interface wg0**: É a sua linha de vida. Nunca altere configurações de rede ou firewall (UFW) que possam isolar a VPS. +- **Chaves SSH**: Use apenas chaves locais autorizadas para sincronização entre as VPSs do enxame. + +## 📇 Protocolo de Identidade Estática (`~/.vps_identity`) +Para garantir 100% de consciência situacional à prova de falhas sem depender de chamadas de rede externas, cada máquina do enxame possui um arquivo de identidade em `/home/deploy/.vps_identity`. + +### 📄 Estrutura Obrigatória do JSON: +Todo arquivo `.vps_identity` deve conter exatamente a seguinte estrutura: +```json +{ + "vps_id": 4, + "vps_name": "VPS-4-LABORATORIO", + "ip_vpn": "10.99.0.4", + "role": "Desenvolvimento, Builds e Staging", + "danger_level": "BAIXO - Liberdade para testar e recriar" +} +``` + +### 🚨 Obrigações das IAs e Agentes: +1. **Verificação Obrigatória**: Toda execução de script ou agente deve prioritariamente ler e interpretar o arquivo `/home/deploy/.vps_identity` para calibrar o seu escopo de atuação. +2. **Respeito ao Danger Level (Nível de Perigo)**: + - **Nível de Perigo ALTO** (ex: VPS 1, VPS 3): Agentes **NÃO PODEM** rodar comandos experimentais, mutações não homologadas de bancos de dados ou reinstalar dependências críticas sem backups nítidos e aprovação explícita. + - **Nível de Perigo BAIXO** (ex: VPS 4): O agente possui total autonomia para realizar testes, compilar códigos, reinstalar pacotes e reiniciar contêineres Docker de staging. +3. **Resiliência (Fallback)**: Caso o arquivo `.vps_identity` não exista ou esteja ilegível, o agente deve fazer o fallback dinâmico (buscando o IP `10.99.x.x` via `hostname -I`) e assumir o perfil de segurança mais restritivo por padrão. + +## 🚫 NUNCA... +- Nunca tente acessar servidores fora da rede 10.99.0.x. +- Nunca exponha senhas ou chaves privadas em logs ou comentários. +- Nunca altere o serviço `swarm-listener` sem autorização. + +## 🔄 Protocolo de Criação e Configuração de Novos Projetos (Auto-Config de Webhook) + +Sempre que um novo projeto for criado no ecossistema Swarm, os agentes e desenvolvedores **devem** seguir e configurar automaticamente a seguinte rotina de integração de CI/CD para que o GitOps funcione perfeitamente: + +### 1. Criação Obrigatória do Webhook de Deploy +Todo novo repositório criado no Gitea **DEVE** possuir um Webhook de deploy ativo configurado da seguinte forma: +* **URL de Destino**: `http://10.99.0.3:5000/webhook` (Se configurado externamente) ou `http://127.0.0.1:5000/webhook` (Se configurado de dentro da VPS 3). +* **Tipo de Conteúdo**: `application/json` +* **Segredo (Secret)**: Em branco ou chave secreta padrão. +* **Eventos que disparam**: Apenas o evento de **Push** (Commit enviado). + +> [!IMPORTANT] +> **Autonomia do Agente (Auto-Identificação)**: +> Se você (o Agente de IA) identificar que está trabalhando em um **novo projeto** ou que o repositório do projeto atual **não possui** o webhook do Swarm Dispatcher (`http://127.0.0.1:5000/webhook`) configurado no Gitea: +> 1. Você **DEVE** usar a API REST do Gitea para criar ou corrigir esse webhook automaticamente. +> 2. Você **DEVE** garantir a criação do arquivo `.vps_identity` apropriado nas VPSs correspondentes. +> 3. Você **DEVE** estruturar o `docker-compose.yml` do projeto sob a pasta `/home/deploy/stack//` seguindo o padrão rootless. + +## 🗣️ Comunicação +- Todo o desenvolvimento, comentários e commits devem ser em **PORTUGUÊS**. +- Use o protocolo **PGS (Protocolo Gitea Swarm)** para hand-offs. + +## 📂 Diretórios de Projetos e Stacks Ativos (Mapeamento de Preservação) + +### 🖥️ VPS 1 - Produção (10.99.0.1) +Os seguintes diretórios são de infraestrutura e serviços críticos ativos e **DEVEM SER ESTRITAMENTE PRESERVADOS** contra qualquer alteração ou limpeza na VPS 1: +* 📁 `/home/deploy/stack/traefik/`: Roteador de borda central e proxy reverso da infraestrutura. +* 📁 `/home/deploy/stack/portainer/`: Interface de gerenciamento e monitoramento de contêineres Docker. +* 📁 `/home/deploy/stack/soc/`: Rotinas de CrowdSec, firewall e auditoria de segurança ativa. + +### 🖥️ VPS 4 - Laboratório (10.99.0.4) +Os seguintes diretórios dentro de `/home/deploy/stack/` contêm contêineres de desenvolvimento e staging ativos e **DEVEM SER ESTRITAMENTE PRESERVADOS** na VPS 4: +* 📁 `scoreodonto.com/`: Aplicação e contêineres de staging do ecossistema ScoreOdonto. +* 📁 `subdominio.clube67.com/`: Branding, front-end e back-end do Gerenciador de Subdomínios. +* 📁 `self-healing/`: Rotinas e scripts locais de auto-recuperação de serviços. +* 📁 `webhook-listener/`: Ouvinte de webhooks de GitOps (porta `9000`) para deploys automatizados. + +> [!WARNING] +> Quaisquer pastas como `/home/deploy/stack/traefik/`, `/home/deploy/stack/portainer/` ou `/home/deploy/stack/soc/` que sejam encontradas na **VPS 4** são duplicatas inativas e obsoletas e **devem ser deletadas** na limpeza dos agentes. + +--- + +## 🚀 Protocolo de Acesso a Contexto e Instruções (Prioridade de Memória Injetada) + +Para evitar vazamentos de credenciais no disco e garantir imunidade absoluta contra dados desatualizados locais, os agentes devem respeitar a seguinte ordem de prioridade de sincronização ao inicializar: + +1. 🚀 **Injeção em Memória RAM (API REST do Gitea - PRIORITÁRIO MÁXIMO)**: + Os agentes de IA devem prioritariamente ler as instruções mestre chamando a API de Conteúdos do Gitea usando Basic Auth. O conteúdo recuperado é decodificado base64 e mantido estritamente na memória volátil RAM da máquina durante a execução, sem tocar o disco da VPS. +2. 📁 **Arquivos do Disco Local (Filesystem - CONTINGÊNCIA)**: + Caso a API do Gitea esteja temporariamente indisponível, a IA pode recorrer à leitura dos arquivos locais localizados em `/home/deploy/instrucoes/` como contingência secundária. +3. 🔐 **Transporte Remoto e Escrita (Chaves SSH - ESTÁVEL)**: + Para operações de sincronização, deploys ou pushes do Git, os agentes devem usar exclusivamente a chave SSH do usuário `deploy` (`~/.ssh/id_ed25519`), prevenindo qualquer exposição de chaves privadas em logs ou variáveis de ambiente. + +--- + +## 🌐 Governança e Integração Centralizada no Gitea (Nível de Usuário/Sistema) + +Para maximizar a segurança (SecOps), a agilidade de deploy (GitOps) e a escalabilidade do enxame de agentes, adotamos uma arquitetura de governança unificada no **Gitea no nível de Usuário e Sistema**, contornando configurações isoladas e repetitivas por repositório. + +### 🔑 1. Autenticação Unificada por Chave SSH Global (User Settings) +Em vez de configurar Deploy Keys individuais para cada repositório, a chave pública SSH de cada VPS (nó do enxame) é cadastrada diretamente no perfil global do Usuário Administrador (`ruicesar`) em `/user/settings/keys`. +* **Permissão herdada**: Qualquer conexão Git disparada a partir dos nós do enxame possui automaticamente as permissões do usuário em todos os repositórios atuais e futuros. +* **Padrão de Endereços SSH dos Projetos ( VPS 4 & Swarm )**: + * 📁 **instrucoes_gerais**: `ssh://git@10.99.0.3/ruicesar/instrucoes_gerais.git` + * 📁 **scoreodonto.com**: `ssh://git@10.99.0.3/ruicesar/scoreodonto.com.git` + * 📁 **mercado.clube67.com**: `ssh://git@10.99.0.3/ruicesar/mercado.clube67.com.git` + * 📁 **subdominio.clube67.com**: `ssh://git@10.99.0.3/ruicesar/subdominio.clube67.com.git` + +### 🔌 2. Integração Global por Webhook do Sistema (System Webhook) +Em vez de criar Webhooks de push repetitivos para cada repositório das aplicações: +* Configuramos um único **Webhook do Sistema** em `/admin/hooks` que atua de forma global em todos os repositórios (atuais e futuros). +* **Parâmetros de Produção**: + * **URL de Destino**: `http://127.0.0.1:5000/webhook` (Disparo direto local em localhost na VPS 3 do Gitea). + * **Content Type**: `application/json` + * **Gatilho**: Apenas o evento de **Push**. +* **Filtragem**: O Swarm Dispatcher recebe os pushes globais e executa apenas os repositórios mapeados no fluxo de deploys do enxame, mantendo o processo 100% limpo e livre de redundâncias. + +### 🎯 3. Outros Recursos Unificados a Nível de Usuário/Sistema +Para mantermos o ecossistema no estado da arte de DevOps, utilizamos os seguintes recursos globais do Gitea: +* 📁 **Gitea Organizations (Organizações - ex: clube67)**: Agrupa todos os repositórios sob um único tenant corporativo, permitindo gerenciar permissões de equipes (Teams) e IAs de uma única vez para todos os projetos. +* 🔑 **Personal Access Tokens (PAT - Nível de Usuário)**: Criação de um Token de Acesso único do usuário administrador injetado na RAM dos agentes, dando autorização de API para ler issues, wikis e logs de todos os repositórios atuais e futuros de forma centralizada. +* 🏷️ **Rótulos Padrão (Global Labels)**: Padronização de etiquetas de Issues (ex: `bug-self-healing`, `deploy-staging`, `security-incident`) herdadas automaticamente por qualquer novo repositório, agilizando a triagem de erros.