From 2c81342d4986fada38da39a21135c92a0a39fa24 Mon Sep 17 00:00:00 2001 From: VPS 4 Builder Date: Sun, 24 May 2026 05:30:13 +0200 Subject: [PATCH] docs: update doutrina with PGS protocol, webhooks, postgres and routing rules --- global/doutrina_agentes.md | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/global/doutrina_agentes.md b/global/doutrina_agentes.md index 5ca90f7..c71017b 100644 --- a/global/doutrina_agentes.md +++ b/global/doutrina_agentes.md @@ -42,27 +42,24 @@ Todo arquivo `.vps_identity` deve conter exatamente a seguinte estrutura: - 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) +## 🔄 Protocolo de Criação e Configuração de Novos Projetos (GitOps Rootless) -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). +Sempre que um novo projeto for criado no ecossistema Swarm, os agentes **não precisam** configurar Webhooks locais. O Webhook Global (`https://git.clube67.com/-/admin/hooks` -> `http://10.99.0.4:9000/webhook`) já cuida do roteamento universal dos eventos de Push. > [!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. +> Se você (o Agente de IA) identificar que está trabalhando em um **novo projeto**: +> 1. Você **NÃO DEVE** criar Webhooks via API no repositório individual para evitar conflitos. > 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. +> 4. **Exposição de Portas (VPS 4)**: Contêineres na VPS 4 não devem mapear a porta `80` ou `443` diretamente no Host físico, para evitar conflitos com múltiplos projetos de staging. Use redes internas ou labels (Docker Overlay) para que a **VPS 1 (Traefik)** faça o encaminhamento do tráfego. +> 5. **Bancos de Dados**: É terminantemente **proibido** subir contêineres de Banco de Dados (`postgres`, `mysql`, etc) localmente nos projetos da VPS 4. Todos os serviços devem obrigatoriamente apontar para a VPS 3 (10.99.0.3). ## 🗣️ Comunicação - Todo o desenvolvimento, comentários e commits devem ser em **PORTUGUÊS**. -- Use o protocolo **PGS (Protocolo Gitea Swarm)** para hand-offs. +- Use o protocolo **PGS (Protocolo Gitea Swarm)** para hand-offs multi-VPS: + - *Nenhum agente edita serviços ou acessa infraestrutura de outra VPS.* + - *Sempre use a API do Gitea para criar uma Issue marcando a VPS destino. O Redis (`swarm:tasks`) despertará as IAs (GPT/Claude) nas respectivas máquinas (ex: VPS 1, VPS 3) para realizarem a tarefa e finalizarem a Issue.* ## 📂 Diretórios de Projetos e Stacks Ativos (Mapeamento de Preservação) @@ -112,15 +109,22 @@ Em vez de configurar Deploy Keys individuais para cada repositório, a chave pú ### 🔌 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). +* Configuramos um único **Webhook do Sistema** em `/admin/hooks` (`https://git.clube67.com/-/admin/hooks`) que atua globalmente. * **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). + * **URL de Destino**: `http://10.99.0.4:9000/webhook` (Redirecionamento nativo via VPN para o Listener da VPS 4). * **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. +* **Filtragem**: O Swarm Dispatcher recebe os pushes globais e executa os deploys do enxame em segundo plano sem 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. +* 🏷️ **Rótulos Padrão (Global Labels)**: Padronização de etiquetas de Issues (ex: `bug-self-healing`, `deploy-staging`, `security-incident`, `Autônomo`) herdadas automaticamente por qualquer novo repositório, agilizando a triagem de erros. + +--- + +## 🗄️ Padrões de Bancos de Dados (DB Standards) + +- **PostgreSQL**: Todos os projetos novos e legados do ecossistema devem, obrigatoriamente, ser concebidos ou migrados para **PostgreSQL**. Fica desencorajada a utilização de SQLite em produção ou MySQL sem justificativa explícita. +- **DragonflyDB**: Sempre que houver necessidade de mensageria, filas (Redis) ou cache, os agentes de IA devem priorizar a implementação e avaliação de ganhos utilizando o **DragonflyDB**, por atuar como um drop-in nativo, escalável e de altíssima performance em relação ao Redis tradicional.