ruicesar/instrucoes_gerais
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
instrucoes_gerais/global/doutrina_agentes.md
T
VPS 4 Builder e93f0edbe9 docs: renomeia terminologia "staging" -> "dev" em todo o ecossistema 
O "staging" nunca foi implementado (sem banco *_staging nem container ativo em
nenhum projeto). Padroniza para "dev" (VPS4 = desenvolvimento) em docs de
arquitetura, doutrina, protocolo de deploy e configs de VPN (comentários).
Renomeia: protocolo_deploy_staging.md -> protocolo_deploy_dev.md;
nginx_wildcard_staging.conf -> nginx_wildcard_dev.conf.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-16 03:35:52 +02:00

131 lines
10 KiB
Markdown
Raw Permalink Blame History

# 🧠 Doutrina Mestre dos Agentes (Multi-VPS)
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 Dev. 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 Dev.
- *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 Dev",
"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 dev.
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 (GitOps Rootless)
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**:
> 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 dev. 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 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)
### 🖥️ 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 dev ativos e **DEVEM SER ESTRITAMENTE PRESERVADOS** na VPS 4:
* 📁 `scoreodonto.com/`: Aplicação e contêineres de dev 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` (`https://git.clube67.com/-/admin/hooks`) que atua globalmente.
* **Parâmetros de Produção**:
* **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 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-dev`, `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.
Reference in New Issue View Git Blame Copy Permalink