docs: release Swarm Doctrine v1.0.5 with RAM-injected priority
+2
-1
@@ -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.4 (Atual)](v1.0.4)
|
||||
* [📖 Doutrina Swarm - Versão v1.0.5 (Atual)](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)
|
||||
* [📜 Doutrina Swarm - Versão v1.0.2 (Histórico)](v1.0.2)
|
||||
* [📜 Doutrina Swarm - Versão v1.0.1 (Histórico)](v1.0.1)
|
||||
|
||||
@@ -40,13 +40,20 @@ graph TD
|
||||
### 🔍 Passo 1: Autocognição e Sincronização (Onde estou?)
|
||||
Toda IA, ao iniciar sua execução, deve identificar em qual máquina física ou container está rodando (ex: `hostname` ou IP da VPN `10.99.0.x`).
|
||||
|
||||
**IMEDIATAMENTE APÓS**, o agente DEVE OBRIGATORIAMENTE executar um `git pull` no diretório de instruções (`/home/deploy/instrucoes/`) e **verificar a versão ativa da Doutrina Swarm registrada no Gitea Wiki** (ex: buscando a versão `v1.x.x` ativa indicada na página `Home.md`).
|
||||
**IMEDIATAMENTE APÓS**, o agente DEVE OBRIGATORIAMENTE sincronizar e carregar seu contexto seguindo a **Relação de Prioridade de Acesso a Instruções**:
|
||||
|
||||
1. 🚀 **[PRIORIDADE MÁXIMA] Injeção Direta em Memória (API REST Gitea)**:
|
||||
A IA deve prioritariamente requisitar suas instruções e a Doutrina atualizada via API REST do Gitea, mantendo todo o conteúdo estritamente na memória RAM da execução. Isso impede o vazamento de chaves e garante que o agente nunca trabalhe com instruções locais alteradas ou desatualizadas no disco.
|
||||
2. 📁 **[FALLBACK 1] Disco Local (Filesystem)**:
|
||||
Caso o Gitea esteja fora do ar ou inacessível, o agente deve ler o diretório local `/home/deploy/instrucoes/` (após efetuar um `git pull` local) como contingência temporária.
|
||||
3. 🔐 **[TRANSPORTE E DEPLOY] Autenticação via Chaves SSH**:
|
||||
Para qualquer operação de escrita, clonagem ou atualização remota de repositórios, a IA deve utilizar a chave SSH privada do usuário `deploy` (`~/.ssh/id_ed25519`), eliminando o uso de senhas ou chaves em texto plano.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Versionamento de Wiki Obrigatório**:
|
||||
> Trabalhar com documentação local desatualizada ou desalinhada com a versão da Wiki é um risco crítico de SecOps. A verificação do versionamento garante que o agente siga rigorosamente as diretrizes, firewalls, logs e políticas da release atualizada do Swarm.
|
||||
|
||||
* *Exemplo:* "Identificado que estou na **VPS 3**. Realizado `git pull` em `/instrucoes/` e verificado alinhamento com a **Doutrina Swarm v1.0.3** na Wiki para garantir contexto atualizado."
|
||||
* *Exemplo:* "Identificado que estou na **VPS 3**. Contexto carregado prioritariamente via **Injeção em Memória (API REST)** e alinhado com a **Doutrina Swarm v1.0.4** na Wiki."
|
||||
|
||||
### 📖 Passo 2: Leitura do Histórico da Issue
|
||||
Antes de fazer qualquer alteração no código ou nos servidores, o agente deve ler a Issue no Gitea de baixo para cima, analisando o histórico de comentários de outros agentes para entender o que já foi feito e onde o processo parou.
|
||||
|
||||
+107
@@ -0,0 +1,107 @@
|
||||
# 🧠 Doutrina Mestre dos Agentes (Multi-VPS) - Versão v1.0.5 (Atual)
|
||||
|
||||
> [!NOTE]
|
||||
> **Histórico de Atualização (Versão v1.0.5 - 17/05/2026)**:
|
||||
> * **Hierarquia de Sincronização de Instruções**: Inserido e documentado o protocolo de injeção em memória RAM via API REST (Gitea API) como prioridade máxima dos agentes, aumentando a segurança de SecOps.
|
||||
> * **Versão v1.0.4 (17/05/2026)**: Documentação do Loop de Auto-Cura e Tuning de PostgreSQL & DragonflyDB.
|
||||
> * **Versão v1.0.3 (17/05/2026)**: Protocolo de Auto-Configuração de Novos Projetos.
|
||||
> * **Versão v1.0.2 (17/05/2026)**: Micro-segmentação de Firewall (SecOps Hardening) na VPS 3.
|
||||
> * **Versão v1.0.1 (17/05/2026)**: Hardening de terminal (.bash_logout) e carregamento dinâmico JIT via API REST do Gitea.
|
||||
> * **Versão v1.0.0 (16/05/2026)**: 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/<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.
|
||||
Reference in New Issue
Block a user