ruicesar/instrucoes_gerais
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update doutrina with PGS protocol, webhooks, postgres and routing rules

Browse Source
This commit is contained in:
VPS 4 Builder
2026-05-24 05:30:13 +02:00
parent d94cd96a66
commit 2c81342d49
1 changed files with 20 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
global/doutrina_agentes.md
+20 -16
View File
@@ -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/<nome-do-projeto>/` 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.