ruicesar/instrucoes_gerais
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: v1.1.1
Pages
Arquitetura Geral Auto Cura Self Healing Clube67 Baileys Swap Clube67 Development Clube67 Plano de Negocio Comandos Agentes Referencia Home Instrucoes Antigravity Instrucoes Claude Loop Auto Cura Self Healing Otimizacao PostgreSQL Protocolo Agentes Swarm Protocolo Deploy e Staging SSH Calendar Monitor ScoreOdonto Arquitetura ScoreOdonto Deploy Seguranca Deploy User Setup VPS1 Production Setup VPS3 Brain Setup VPS4 Lab Sincronizacao Instrucoes Tuning Database e DragonflyDB VPN WireGuard Setup v1.0.0 v1.0.1 v1.0.2 v1.0.3 v1.0.4 v1.0.5 v1.0.6 v1.0.7 v1.0.8 v1.0.9 v1.1.0 v1.1.1
Clone
1
v1.1.1
ruicesar edited this page 2026-05-19 01:59:18 +02:00
Table of Contents

🧠 Doutrina Mestre dos Agentes (Multi-VPS) - Versão v1.1.1 (Atual)

Important

Histórico de Atualização (Versão v1.1.1 - 18/05/2026):

  • Duplicação de Banco de Dados Sob Demanda: Esclarecimento crucial no protocolo de clonagem de projetos. A duplicação de bancos de dados, a criação de novas tabelas ou importação de dumps durante a clonagem de ambientes/projetos NÃO deve ser realizada automaticamente pela IA. A IA deve obrigatoriamente aguardar a solicitação explícita do Administrador. Caso a ordem seja dada pelo Humano, aplica-se o isolamento absoluto de banco (credenciais e bases dedicadas).
  • Versão v1.1.0: Obrigatoriedade de Staging (Domínio Coringa) e bancos de staging isolados (scoreodonto_staging), unificação e simetria absoluta de agentes (Claude & Antigravity).
  • Versão v1.0.9: Protocolo de Clonagem e Isolamento de Dados, Protocolo de Conversão Dialética MySQL para PostgreSQL (tipagem, sequences, sandbox).
  • Versão v1.0.8: Protocolo de Migração de Contexto (Domínio ⇄ Subdomínio), webhooks, DNS, proxy e mapeamento de atritos.
  • Versão v1.0.7: Protocolo Fail-Safe de Parada Imediata e Lei de Ouro (Proibição Absoluta de Build na 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:

{
  "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/<nome-do-projeto>/ 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.