feat: adicionar sistema de feedback por comentário do agente
This commit is contained in:
Rui
@@ -1,72 +0,0 @@
|
||||
# 🤖 Protocolo Gitea Swarm (PGS): Coordenação de Multi-Agentes em Ambiente Multi-VPS
|
||||
|
||||
Este documento estabelece o protocolo de comunicação padrão, obrigatório e imutável para todos os Agentes de Inteligência Artificial (IAs) que atuarem no gerenciamento, desenvolvimento ou manutenção da infraestrutura do **Clube67** distribuída em múltiplos servidores.
|
||||
|
||||
Como a arquitetura adota segurança **Zero-Trust de movimentação lateral** (impedindo que agentes em uma VPS acessem outras máquinas via SSH automático), o **Gitea** atua como o **Orquestrador de Estado Assíncrono** do enxame de agentes.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Regras de Engajamento para Agentes
|
||||
|
||||
Sempre que um agente for invocado para resolver uma Issue ou realizar uma implementação, ele deve obrigatoriamente seguir os 4 passos de ciclo de vida abaixo:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[1. Autocognição: Onde estou?] --> B[2. Leitura de Histórico na Issue]
|
||||
B --> C[3. Execução Local na VPS Atual]
|
||||
C --> D[4. Comentário de Hand-off e Status]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🔍 Passo 1: Autocognição (Em qual VPS estou?)
|
||||
Toda IA, ao iniciar sua execução, deve identificar em qual máquina física ou container está rodando, executando comandos como `hostname` ou inspecionando o IP da VPN WireGuard local.
|
||||
* *Exemplo:* "Identificado que estou rodando na **VPS 3 (Data Server - 10.99.0.3)**."
|
||||
|
||||
### 📖 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.
|
||||
|
||||
### 🛠️ Passo 3: Execução Local Estrita
|
||||
O agente deve realizar apenas as alterações correspondentes à VPS onde ele está ativamente rodando. Ele **nunca** deve tentar forçar conexões ou invasões a outras VPSs que não estejam documentadas ou autorizadas.
|
||||
|
||||
### 💬 Passo 4: Comentário de Hand-off (O Passe de Bastão)
|
||||
Ao concluir sua tarefa local, o agente **não deve simplesmente fechar a tarefa**, caso ela dependa de ações em outros servidores. Ele deve postar um comentário estruturado seguindo o modelo abaixo:
|
||||
|
||||
---
|
||||
|
||||
## 📝 Modelo Padrão de Comentário de Hand-off ( PGS )
|
||||
|
||||
O comentário de encerramento do agente na Issue deve conter obrigatoriamente os seguintes blocos:
|
||||
|
||||
```markdown
|
||||
### 🖥️ [VPS ATUAL]: [Nome da VPS, ex: VPS 3 (Data Appliance)]
|
||||
* **O que foi realizado localmente:** [Lista clara de arquivos modificados, bancos criados ou serviços configurados].
|
||||
* **Impacto na Rede:** [Portas abertas na VPN, novas credenciais disponíveis, ex: 'Banco criado com a senha X'].
|
||||
|
||||
### ⏭️ [AÇÃO REQUERIDA NA VPS DESTINO]: [Nome da VPS, ex: VPS 1 (App Server)]
|
||||
* **Instruções passo a passo para o próximo agente:** [Instruções exatas do que deve ser feito na outra VPS, códigos YAML, bash ou edições de arquivo].
|
||||
* **Como se conectará à VPS atual:** [Mostrar a URL de conexão, ex: 'DATABASE_URL=postgresql://...'].
|
||||
|
||||
### 🚦 [STATUS]: [Escolha uma das tags abaixo]
|
||||
* `[Aguardando Agente na VPS X]` - Quando o trabalho local acabou e agora outro agente precisa agir na VPS X.
|
||||
* `[Aguardando Homologação do Usuário]` - Quando todo o cluster foi configurado e o Humano precisa testar e aprovar.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Exemplo de Aplicação Real (Issue #2 - newwhats)
|
||||
|
||||
1. **Agente A (na VPS 3 - Banco):**
|
||||
* Cria o banco `newwhats` e configura DragonflyDB.
|
||||
* Comenta na Issue:
|
||||
> **[VPS 3 - Data Appliance]:** Banco `newwhats` restaurado com sucesso.
|
||||
> **[REQUERIDO NA VPS 1]:** Próximo agente, edite o `docker-compose.yml` da aplicação apontando para `10.99.0.3` usando a senha `X`. Comente quando terminar.
|
||||
> **[STATUS]:** `[Aguardando Agente na VPS 1]`
|
||||
2. **Agente B (na VPS 1 - Frontend):**
|
||||
* Inicia na VPS 1, lê o comentário acima, altera o `docker-compose.yml` local e sobe o container.
|
||||
* Comenta na Issue:
|
||||
> **[VPS 1 - App Server]:** docker-compose.yml atualizado e container reiniciado. Conexão com VPS 3 validada e healthy.
|
||||
> **[STATUS]:** `[Aguardando Homologação do Usuário]`
|
||||
|
||||
---
|
||||
*Este protocolo garante consistência, segurança máxima e clareza absoluta na comunicação humana e de inteligência artificial em nosso ecossistema.*
|
||||
@@ -1,106 +0,0 @@
|
||||
# 🛡️ Guia de Segurança e Liberdade para o Usuário `deploy`
|
||||
|
||||
Na cultura de DevOps moderna, a "lenda" do usuário `deploy` poder trabalhar com total liberdade sem ter acesso ao usuário `root` é, na verdade, uma **melhor prática de segurança chamada "Princípio do Menor Privilégio" (Least Privilege)**.
|
||||
|
||||
Se o usuário `deploy` pudesse dar `sudo su` e virar `root` a qualquer momento, qualquer vulnerabilidade na sua aplicação web (ex: um upload de arquivo malicioso ou injeção de código) daria controle total do servidor inteiro para um invasor.
|
||||
|
||||
Para dar ao usuário `deploy` toda a liberdade de desenvolvimento e publicação de aplicações com **segurança absoluta**, implementamos 4 pilares práticos:
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Pilar 1: Controle Total do Diretório Web (Sem `sudo`)
|
||||
O usuário `deploy` não precisa de permissão de root para alterar os arquivos da aplicação. Basta torná-lo dono dos diretórios de publicação.
|
||||
|
||||
### Prática:
|
||||
Geralmente usamos a pasta `/var/www/` ou criamos um diretório de aplicações na própria Home do usuário (`/home/deploy/apps/`).
|
||||
Para dar controle total ao `deploy` sem precisar de `sudo` para editar arquivos:
|
||||
|
||||
```bash
|
||||
# Criar a pasta do seu projeto
|
||||
sudo mkdir -p /var/www/meu-app
|
||||
|
||||
# Definir o usuário deploy como proprietário da pasta
|
||||
sudo chown -R deploy:deploy /var/www/meu-app
|
||||
|
||||
# Aplicar permissões recomendadas (pastas 755 e arquivos 644)
|
||||
find /var/www/meu-app -type d -exec chmod 755 {} \;
|
||||
find /var/www/meu-app -type f -exec chmod 644 {} \;
|
||||
```
|
||||
|
||||
**Resultado**: O usuário `deploy` agora pode usar Git, SFTP, VSCode, criar arquivos, deletar e subir atualizações dentro de `/var/www/meu-app` com total liberdade e **zero** necessidade de usar `sudo`.
|
||||
|
||||
---
|
||||
|
||||
## 🐋 Pilar 2: Gerenciamento do Docker sem Root
|
||||
Se as suas aplicações rodam em Docker (ou Docker Compose), o usuário `deploy` não precisa usar `sudo docker` para gerenciar os containers.
|
||||
|
||||
### Prática:
|
||||
Adicionamos o usuário `deploy` ao grupo do Docker no Linux:
|
||||
|
||||
```bash
|
||||
sudo usermod -aG docker deploy
|
||||
```
|
||||
|
||||
**Resultado**: Após fazer logout e login novamente, o usuário `deploy` poderá rodar comandos como `docker ps`, `docker compose up -d`, `docker restart` e fazer builds de imagens diretamente, com total liberdade, sem nunca usar `sudo`.
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Pilar 3: Sudoers com Limitação Cirúrgica (Segurança Avançada)
|
||||
Muitas vezes, a aplicação precisa apenas de tarefas muito específicas do sistema operacional, como por exemplo:
|
||||
* Reiniciar o servidor web Nginx (`systemctl restart nginx`).
|
||||
* Recarregar as configurações do Nginx (`systemctl reload nginx`).
|
||||
* Reiniciar um serviço específico da sua aplicação em NodeJS/Python criado no Systemd (`systemctl restart api-app`).
|
||||
|
||||
### Prática:
|
||||
Em vez de dar acesso total ao `sudo` para o `deploy`, nós liberamos **apenas estes comandos específicos**, sem requisição de senha!
|
||||
|
||||
1. Criamos um arquivo de configuração exclusivo no Sudoers para o `deploy`:
|
||||
```bash
|
||||
sudo nano /etc/sudoers.d/deploy
|
||||
```
|
||||
2. Adicionamos a regra cirúrgica:
|
||||
```text
|
||||
# Permite que o usuário deploy execute APENAS estes comandos listados como root, sem pedir senha:
|
||||
deploy ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart nginx, /usr/bin/systemctl reload nginx, /usr/bin/systemctl status nginx
|
||||
```
|
||||
3. Aplicamos a permissão correta ao arquivo do sudoers:
|
||||
```bash
|
||||
sudo chmod 440 /etc/sudoers.d/deploy
|
||||
```
|
||||
|
||||
**Resultado**: O usuário `deploy` agora pode rodar `sudo systemctl reload nginx` para aplicar uma mudança de domínio na web com total liberdade, mas se ele tentar rodar `sudo apt update` ou `sudo userdel`, o sistema **negará o acesso**.
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Pilar 4: Processos em Espaço de Usuário (PM2 / Systemd User)
|
||||
Se a sua aplicação web não roda em Docker e precisa ficar ativa em segundo plano (ex: aplicações Node.js, Python FastAPI, Go), o usuário `deploy` pode gerenciá-la de duas formas sem root:
|
||||
|
||||
### A. Utilizando o PM2 (NodeJS Process Manager)
|
||||
O PM2 roda diretamente no espaço de memória do usuário `deploy`.
|
||||
```bash
|
||||
# Como usuário deploy, instalar e rodar apps:
|
||||
pm2 start app.js --name "minha-api"
|
||||
pm2 save
|
||||
```
|
||||
O `deploy` tem controle total para reiniciar (`pm2 restart minha-api`), parar, e ver logs sem precisar do root.
|
||||
|
||||
### B. Serviços Systemd do Usuário (`systemd --user`)
|
||||
O Linux moderno permite que usuários criem seus próprios arquivos de serviço que rodam sob sua conta na pasta:
|
||||
`~/.config/systemd/user/`
|
||||
|
||||
Você pode gerenciar o serviço rodando:
|
||||
```bash
|
||||
systemctl --user daemon-reload
|
||||
systemctl --user restart meu-servico.service
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Tabela de Comparação de Segurança:
|
||||
|
||||
| Ação | Como o Root faria (Inseguro) | Como o `deploy` faz com segurança |
|
||||
| :--- | :--- | :--- |
|
||||
| **Subir arquivos Web** | Usa `sudo` ou loga como `root` | Altera livremente dentro de `/var/www/` (Dono da pasta) |
|
||||
| **Gerenciar Containers** | `sudo docker compose restart` | `docker compose restart` (Membro do grupo `docker`) |
|
||||
| **Reiniciar Nginx** | `sudo systemctl restart nginx` | `sudo systemctl restart nginx` (Autorizado via Sudoers Cirúrgico) |
|
||||
| **Atualizar Código (Git)** | Roda `git pull` como root | Roda `git pull` usando suas chaves SSH do usuário |
|
||||
Reference in New Issue
Block a user