Argus Agent - SRE 助手
用于TOTVS Protheus日志分析的AI代理,采用模块化架构构建,使用了LangGraph、FastAPI、Angular以及MCP(模型上下文协议)。
🏗️ 建筑
该项目由三个主要部分组成:
1. API(api/)
- 框架使用LangGraph进行FastAPI编排
- Porta(在意大利语中意为“门”)8000
- 职责:
- 使用 PostgreSQL 的 JWT 认证
- 日志分析工作流(初步分析、深入分析、聊天分析)
- 与大型语言模型(LLM)提供商(OpenAI、Google、Anthropic)的集成
2. MCP服务器(mcp-server/)
- 框架FastMCP(基于FastAPI)
- Porta(意大利语,意为“门”)8002
- 职责:
- 用于日志搜索的MCP工具(Elasticsearch)
- 使用ChromaDB的RAG进行历史背景分析
- 时间序列中的异常检测
3. UI(用户界面)ui/)
- 框架Angular 18 独立版 + NGINX
- Porta(意大利语)8080(开发),80(生产)
- 职责:
- 用于浏览日志的网页界面
- 带有AI的聊天机器人
- TOTVS设计系统
基础设施
- PostgreSQL(译文:波斯特格瑞斯,但通常直接使用原名)用于身份验证的数据库(端口5433)
- Elasticsearch(中文可译为“Elastic搜索引擎”或根据具体语境简化为“Elastic”)日志数据源(外部)
图表(概览)```mermaid
flowchart LR
subgraph UI
A[Frontend Angular Browser]
end
subgraph API
APIRoutes[FastAPI API 8000 - Auth Metrics Users]
end
subgraph MCP
Tools[MCP Server MCP 8002 - FastMCP Tools: search_logs RAG anomalies]
end
subgraph Data
ES[(Elasticsearch)]
CH[(ChromaDB)]
PG[(PostgreSQL)]
end
A -->|HTTP| APIRoutes
A -->|HTTP| Tools
APIRoutes <-->|JWT| A
Tools <-->|JWT or Service Token| A
Tools -->|Query| ES
Tools -->|RAG| CH
APIRoutes -->|Users/Auth| PG
## 🚀 快速设置
### 1. 先决条件
- **Docker 和 Docker Compose** (推荐)
- **或者**Python 3.11+,Node.js 20+,PostgreSQL 16,ChromaDB
- **可选**kubectl,Helm 3,Tilt(用于Kubernetes)
### 2. 环境配置```bash
# Clone o repositório
git clone
cd argus-mcp-agent
# Copie o arquivo de configuração
cp .env.example .env
# Edite o .env com suas credenciais
# - Chaves de API (OPENAI_API_KEY, GOOGLE_API_KEY, ANTHROPIC_API_KEY)
# - Credenciais do Elasticsearch (ES_HOST, ES_USER, ES_PASSWORD)
# - Configurações de banco de dados (se necessário)
3. 使用Make进行执行(推荐)
该项目包括一个 Makefile 完整配置以促进发展:```bash
Ver todos os comandos disponíveis
make help
Setup inicial (cria .env e venv)
make setup
Desenvolvimento com Docker Compose
make dev
Build e push de imagens para GCP
make docker-release
## 🔧 如何运行
### 选项1:Docker Compose(推荐)
执行整个项目的最简单方法:```bash
# Subir todos os serviços (postgres, chromadb, api, mcp-server, ui)
docker-compose up
# Ou com rebuild
docker-compose up --build
# Parar os serviços
docker-compose down
访问应用程序:
- 用户界面(UI)地址:http://localhost:8080
- API: http://localhost:8000
- MCP 服务器:http://localhost:8002
选项2:Docker Compose 开发(带调试功能)```bash
Com suporte a debugging e hot-reload
docker-compose -f docker-compose.dev.yml up
### 选项3:本地开发(无容器)
针对每个组件的单独开发:
#### API```bash
cd api
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
MCP 服务器```bash
cd mcp-server
pip install -r requirements.txt
uvicorn tools.server:app --host 0.0.0.0 --port 8002 --reload
#### 用户界面(UI)```bash
cd ui
npm install
npm start # ou ng serve
# Acesse http://localhost:4200
选项4:Tilt(Kubernetes开发)
在本地 Kubernetes 环境中进行开发:```bash
tilt up
Acesse a Tilt UI em http://localhost:10350
## 📦 部署到生产环境
### 使用 Helm 的 Kubernetes```bash
# Development
helm install argus-dev ./helm/argus-agent \
--namespace argus-dev \
--create-namespace \
--values k8s/dev/values.yaml
# Production
helm install argus-prod ./helm/argus-agent \
--namespace argus-production \
--create-namespace \
--values k8s/prod/values.yaml
构建和推送镜像```bash
Login no GCP Artifact Registry
make docker-login
Build e push com tags latest + timestamp
make docker-release
Ou manualmente
make docker-build
make docker-push
请咨询 完整的部署文档 以了解更多详情。
### 图表(Kubernetes/Helm)```mermaid
flowchart TB
subgraph Namespace[argus]
subgraph Deployments
API[Deployment: argus-api
Pods x N]
MCP[Deployment: argus-mcp-server
Pods x N]
UI[Deployment: argus-ui
Pod x 1]
CHD[Deployment: chromadb]
PGD[Deployment: postgres]
end
SVC_API[Service: api 8000]
SVC_MCP[Service: mcp 8002]
SVC_UI[Service: ui 80]
Ingress[Ingress NGINX]
end
UI --> SVC_UI --> Ingress
API --> SVC_API --> Ingress
MCP --> SVC_MCP --> Ingress
MCP --> CHD
MCP --> ES[(Elastic externo)]
API --> PGD
📚 项目结构```
argus-mcp-agent/
├── api/ # FastAPI + LangGraph (porta 8000)
│ ├── app/ # Código da aplicação
│ │ ├── agent/ # Workflows LangGraph
│ │ ├── api/ # Rotas da API
│ │ └── auth/ # Lógica de autenticação
│ ├── config/ # Arquivos de configuração
│ ├── prompts/ # Templates de prompts
│ ├── Dockerfile # Imagem de produção
│ └── requirements.txt # Dependências Python
│
├── mcp-server/ # FastMCP Server (porta 8002)
│ ├── tools/ # Implementação das ferramentas MCP
│ │ ├── server.py # Servidor principal
│ │ ├── auth.py # Autenticação
│ │ └── rag_manager.py # ChromaDB RAG
│ ├── Dockerfile
│ └── requirements.txt
│
├── ui/ # Angular 18 + NGINX (porta 8080)
│ ├── src/
│ │ ├── app/
│ │ │ ├── core/ # Auth, guards, interceptors
│ │ │ ├── features/ # Log Explorer, Login
│ │ │ └── shared/ # Componentes reutilizáveis
│ │ └── styles/ # TOTVS Design System
│ ├── nginx.conf
│ ├── Dockerfile
│ └── package.json
│
├── helm/ # Helm charts para Kubernetes
│ └── argus-agent/
│
├── k8s/ # Manifestos Kubernetes
│ ├── base/ # Configuração base
│ ├── dev/ # Ambiente de desenvolvimento
│ ├── staging/ # Ambiente de staging
│ └── prod/ # Ambiente de produção
│
├── docs/ # Documentação completa
├── scripts/ # Scripts de automação
├── docker-compose.yml # Ambiente de desenvolvimento local
├── docker-compose.dev.yml # Desenvolvimento com debugging
├── Makefile # Comandos de build/deploy
└── Tiltfile # Configuração Tilt para K8s dev
## 📖 文档
- 📚 书籍或学习的象征 完整文件
- 🔐(锁形符号,常用于表示保密、安全或密码等) 环境变量
### 部署与基础设施
- 🐳 水獭(或波浪中的海豚) 集装箱化指南
- 船 部署指南
- 🎯 目标(靶心) 部署沙盒
### 组件
- 🔌(电源插头) API 文档
- 🎨(彩笔或涂鸦的符号,常用于表示绘画、艺术创作等) 用户界面文档
- 🌐(地球/网络) 外部访问MCP(管理控制面板/主控处理器等,具体含义根据上下文确定)
### 测试与验证
- ✅ 测试结果
- 🔒(锁形符号,常用于表示安全、保密或锁定状态) 身份验证测试
## 🛠️ 有用的Make命令
该项目包括一个 `Makefile` 配备各种实用命令的完整版:
### 发展```bash
make help # Mostra todos os comandos disponíveis
make setup # Setup inicial (cria .env e venv)
make dev # Sobe ambiente de desenvolvimento
make dev-build # Build e sobe com docker-compose
make dev-down # Para o ambiente
make dev-logs # Ver logs do desenvolvimento
Docker 构建与推送```bash
make docker-login # Login no GCP Artifact Registry
make docker-build # Build das 3 imagens (api, mcp-server, ui)
make docker-push # Push para GCP registry
make docker-release # Login + build + push (latest + timestamp)
### Kubernetes & Helm```bash
make helm-lint # Lint do Helm chart
make helm-template # Gera manifestos K8s
make helm-install-dev # Instala no namespace dev
make helm-upgrade-dev # Atualiza deployment dev
make k8s-dev-deploy # Deploy direto com kubectl
倾斜```bash
make tilt-up # Inicia Tilt
make tilt-down # Para Tilt
### 测试与代码检查(或代码规范检查)```bash
make test # Executa testes
make test-cov # Testes com cobertura
make lint # Linting
make clean # Limpa artifacts de build
🌐 MCP服务器的远程使用
MCP服务器可以通过带有JWT认证的HTTP进行远程访问。
终端沙盒: https://argus.sandbox.tcloud-devops.cloudtotvs.com.br/mcp/
可用工具:
search_logs- 在Elasticsearch中搜索日志retrieve_historical_context- 通过RAG(检索增强生成)的历史背景save_analysis_summary- 在RAG中持续进行分析detect_timeseries_anomalies- 异常检测
如需详细了解,请参阅:
- MCP服务器 README
- 外部访问MCP
快速示例```bash
1. Login e obtenção do token
TOKEN=$(curl -s -X POST https://argus.sandbox.tcloud-devops.cloudtotvs.com.br/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":""}' | jq -r .access_token)
2. Buscar logs
curl -X POST https://argus.sandbox.tcloud-devops.cloudtotvs.com.br/mcp/tools/search_logs \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"index":"logs_prod_app","window":"1h"}'
```
