xuw/iiis-oncall-agent
GitHub: xuw/iiis-oncall-agent
基于 Claude 大模型的 AI 驱动基础设施事件响应系统，自动诊断和修复 Kubernetes 集群及 AI 服务故障。
Stars: 0 | Forks: 0
# IIIS OnCall Agent
面向清华大学（IIIS，交叉信息研究院）的 AI 驱动的基础设施事件响应系统。
## 概述
IIIS OnCall Agent 是一个自动化的事件响应系统，通过 AI agent 处理基础设施工单。用户通过 Web 界面（带有 SSO 认证）提交工单，agent 会自动连接到 Kubernetes 集群、检查服务、分析日志并尝试修复，从而诊断问题。
### 主要特性
- **SSO 认证**：通过 Keycloak PKCE 流程进行安全用户登录
- **智能队列管理**：自动进行工单排队与位置追踪
- **重复检测**：基于 Claude 的语义分析以识别重复工单
- **实时诊断**：通过 Server-Sent Events (SSE) 流提供实时的 agent 更新
- **邮件通知**：在工单生命周期内发送确认和结果邮件
- **管理员仪表盘**：全面展示所有工单、统计信息和事件日志的综合视图
- **自动化诊断与修复**：配备 20 多种诊断和修复工具的 AI agent
## 系统架构
```
┌─────────────────────────────────────────────────────────────┐
│ User (Browser) │
│ https://p0.ai.iiis.co:9445 │
└────────────────────┬────────────────────────────────────────┘
│ HTTPS/SSE
│
┌────────────────────▼────────────────────────────────────────┐
│ FastAPI Application │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Web UI (static/) │ │
│ │ - index.html: Ticket submission │ │
│ │ - admin.html: Admin dashboard │ │
│ │ - callback.html: OAuth PKCE redirect │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ API Layer (app.py) │ │
│ │ - Keycloak JWT verification │ │
│ │ - Ticket CRUD + SSE streaming │ │
│ │ - Admin endpoints │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Agent Worker (agent.py) │ │
│ │ - asyncio.Queue for ticket processing │ │
│ │ - Claude Sonnet 4 with tool use │ │
│ │ - Max 3 repair attempts per ticket │ │
│ └────────────┬─────────────────────────────────────────┘ │
│ │ │
│ ┌────────────▼─────────────────────────────────────────┐ │
│ │ Tools (tools.py) │ │
│ │ - check_litellm_health() │ │
│ │ - check_k8s_pods() │ │
│ │ - restart_proxy_service() │ │
│ │ - test_model_call() │ │
│ │ - 20+ diagnostic/repair functions │ │
│ └────────────┬─────────────────────────────────────────┘ │
│ │ │
│ ┌────────────▼─────────────────────────────────────────┐ │
│ │ SSH Manager (ssh_manager.py) │ │
│ │ - kubectl via local tunnel │ │
│ │ - Direct SSH to AWS proxy │ │
│ └────────────┬─────────────────────────────────────────┘ │
└───────────────┼──────────────────────────────────────────┘
│
│ kubectl (via autossh tunnel)
│
┌───────────────▼──────────────────────────────────────────┐
│ IIIS Kubernetes Cluster (iiis) │
│ - Namespace: weixu │
│ - LiteLLM Router (Deployment: litellm) │
│ - Harbor Registry (harbor.ai.iiis.co:9443) │
└───────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────┐
│ AWS Japan Proxy (p0.ai.iiis.co) │
│ - Anthropic Proxy: port 9443 (api-proxy.service) │
│ - Codex/GPT Proxy: port 9444 (codex-proxy.service) │
└───────────────────────────────────────────────────────────┘
```
## 快速开始
### 前置条件
- Python 3.11+
- 拥有 IIIS Kubernetes 集群的访问权限（`~/.kube/config` 中包含 `weixu-k8s.iiis` context）
- 拥有 AWS 代理服务器（`p0.ai.iiis.co`）的 SSH 访问权限
- Keycloak SSO 凭证
- SSL 证书（`/etc/letsencrypt/live/p0.ai.iiis.co/`）
### 安装说明
1. **克隆仓库**：
git clone https://github.com/xuw/iiis-oncall-agent.git
cd iiis-oncall-agent
2. **创建虚拟环境**：
python3 -m venv venv
source venv/bin/activate
3. **安装依赖**：
pip install -r requirements.txt
4. **配置环境**：
cp .env.example .env
# 使用你的凭证编辑 .env 文件
5. **初始化数据库**：
python -c "import asyncio; from database import init_db; asyncio.run(init_db())"
6. **本地运行（开发环境）**：
python app.py
# 访问地址: https://localhost:9445
### 生产部署
1. **部署到服务器**：
./deploy.sh
2. **启用 systemd 服务**：
sudo cp oncall-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable oncall-agent
sudo systemctl start oncall-agent
3. **启用 K8s API 隧道**：
sudo cp autossh-k8s-tunnel.service /etc/systemd/system/
sudo systemctl enable autossh-k8s-tunnel
sudo systemctl start autossh-k8s-tunnel
4. **验证部署**：
./acceptance_test.sh
## 配置说明
### 环境变量 (`.env`)
```
# Anthropic API (用于 agent Claude 模型)
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_BASE_URL=https://p0.ai.iiis.co:9443
# LiteLLM Router (用于基础设施查询)
LITELLM_MASTER_KEY=sk-...
LITELLM_PROXY_URL=https://router.ai.iiis.co:9443
# 认证
AUTH_PASSWORD=your-admin-password
KEYCLOAK_ISSUER=https://sso.iiis.co:9443/realms/iiis
KEYCLOAK_CLIENT_ID=litellm
# SSH 配置
SSH_KEY_PATH=/home/ec2-user/.ssh/iiis_ai
SSH_JUMP_HOST=ailab@js.ai.iiis.co
SSH_JUMP_PORT=9022
# 电子邮件 (SMTP)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=oncall@iiis.edu.cn
SMTP_PASS=password
SMTP_FROM=oncall@iiis.edu.cn
ADMIN_EMAIL=admin@iiis.edu.cn
# Agent 约束
MAX_ITERATIONS=100
MAX_TICKETS_PER_MINUTE=5
MAX_AGENT_RUNS_PER_HOUR=20
TOOL_TIMEOUT=30
TICKET_TIMEOUT=300
# 数据库
DB_PATH=oncall.db
```
## API 参考
### 身份验证
所有端点都需要通过以下方式进行身份验证：
- **Keycloak JWT**：`Authorization: Bearer `
- **管理员会话**（回退机制）：`Authorization: Bearer `
### 端点
#### `POST /api/tickets`
创建新工单。在排队前会执行重复检测。
**请求**：
```
{
"category": "litellm|model_error|cluster|deployment|other",
"title": "LiteLLM 502 gateway error",
"description": "Detailed problem description",
"user_email": "user@iiis.edu.cn"
}
```
**响应**：
```
{
"id": 123,
"category": "litellm",
"title": "LiteLLM 502 gateway error",
"status": "open",
"queue_position": 2,
"queue_total": 5,
"created_at": "2025-03-31T12:00:00",
...
}
```
#### `GET /api/tickets/{ticket_id}/stream`
用于实时 agent 诊断的 Server-Sent Events 流。
**事件**：
- `history`：客户端连接时的历史事件
- `status`：工单状态已更改
- `tool_call`：Agent 正在调用诊断工具
- `tool_result`：工具执行结果
- `thinking`：Agent 推理输出
- `done`：Agent 已完成（已解决/已升级）
**示例**：
```
const eventSource = new EventSource('/api/tickets/123/stream');
eventSource.onmessage = (e) => {
const msg = JSON.parse(e.data);
if (msg.type === 'tool_call') {
console.log(`Tool: ${msg.data.tool}`);
}
};
```
#### `GET /api/my/tickets`
获取当前用户的工单历史。
**查询参数**：
- `limit` (默认: 50)
- `offset` (默认: 0)
#### `GET /api/my/tickets/{ticket_id}`
获取工单的详细视图（仅限所有者或管理员）。
**响应**：
```
{
"ticket": { /* TicketResponse */ },
"events": [
{
"id": 1,
"actor": "agent",
"type": "diagnosis",
"content": "检查 LiteLLM health...",
"created_at": "2025-03-31T12:01:00"
}
]
}
```
#### `GET /api/admin/tickets` (仅限管理员)
列出所有工单，支持可选的状态过滤。
**查询参数**：
- `status`：`open|investigating|resolved|escalated|duplicate`
- `limit`，`offset`
#### `GET /api/admin/stats` (仅限管理员)
获取系统统计信息。
**响应**：
```
{
"total_tickets": 156,
"resolved_count": 98,
"escalated_count": 12,
"avg_resolution_time_minutes": 3.5,
"categories": {
"litellm": 45,
"model_error": 32,
"cluster": 19
}
}
```
#### `GET /api/sso/config`
获取用于前端 PKCE 流程的 SSO 配置。
#### `POST /api/login` (回退机制)
使用密码的传统管理员登录方式。
## Agent 工具
Agent 可以访问 20 多种用于诊断和修复的工具：
### 诊断工具 (只读)
- `check_litellm_health`：LiteLLM 路由的健康检查
- `check_litellm_models`：列出可用模型
- `test_model_call`：测试模型 API 调用
- `check_proxy_health`：检查 AWS 代理服务
- `check_proxy_logs`：检索代理服务日志
- `check_proxy_token_status`：检查 Codex token 池状态
- `check_proxy_cert`：验证 SSL 证书有效性
- `check_k8s_pods`：列出 namespace 中的 pod
- `check_k8s_pod_logs`：获取 pod 日志
- `describe_k8s_pod`：详细的 pod 信息
- `check_k8s_nodes`：列出集群节点
- `check_gpu_status`：GPU 分配信息
- `run_kubectl_readonly`：执行只读 kubectl 命令
### 修复工具 (自动修复)
- `restart_proxy_service`：重启 AWS 代理服务 (api-proxy/codex-proxy)
- `restart_litellm`：滚动重启 LiteLLM deployment
- `restart_model_pod`：重启特定的模型服务器 pod
**安全限制**：
- 每个工单最多执行 3 次修复操作
- namespace 限制：`weixu`、`gpu-operator`、`kube-system`
- 服务名称验证
## 测试说明
### 运行测试
```
# 所有测试
pytest
# 带覆盖率
pytest --cov=. --cov-report=html
# 特定测试文件
pytest tests/test_database.py -v
```
### 测试结构
```
tests/
├── conftest.py # Fixtures (test DB, mock auth)
├── test_database.py # DB operations
├── test_models.py # Pydantic model validation
└── test_api.py # API endpoints (mocked agent)
```
### 部署前检查
```
./pre_deploy_check.sh
```
## 开发指南
### 项目结构
```
.
├── app.py # FastAPI application
├── agent.py # AI agent logic
├── tools.py # Agent tool definitions
├── database.py # SQLite async operations
├── models.py # Pydantic models
├── config.py # Configuration settings
├── ssh_manager.py # SSH/kubectl wrapper
├── static/ # Frontend HTML/JS
│ ├── index.html # User ticket form
│ ├── admin.html # Admin dashboard
│ └── callback.html # OAuth callback
├── tests/ # Test suite
├── requirements.txt # Python dependencies
├── .env.example # Environment template
├── deploy.sh # Deployment script
├── oncall-agent.service # systemd service
└── autossh-k8s-tunnel.service # K8s API tunnel
```
### 添加新工具
1. 在 `tools.py` 中定义工具：
async def my_diagnostic_tool(param: str) -> dict:
"""工具文档字符串 (展示给 agent)"""
# 实现
return {"status": "ok", "result": ...}
2. 添加到 `TOOL_DEFINITIONS`：
{
"name": "my_diagnostic_tool",
"description": "此工具的功能描述",
"input_schema": {
"type": "object",
"properties": {
"param": {"type": "string", "description": "..."}
},
"required": ["param"]
}
}
3. 在 `execute_tool()` 调度器中注册
### 扩展 Agent 系统提示词
编辑 `agent.py` 中的 `SYSTEM_PROMPT` 以添加新的操作手册或基础设施上下文。
## 运维维护
### 日志
```
# 服务日志
sudo journalctl -u oncall-agent -f
# K8s 隧道日志
sudo journalctl -u autossh-k8s-tunnel -f
# 应用日志 (如果直接运行)
tail -f oncall.log
```
### 数据库
```
# 备份
cp oncall.db oncall.db.backup
# 检查
sqlite3 oncall.db
> SELECT * FROM tickets ORDER BY created_at DESC LIMIT 10;
```
### SSL 证书续期
证书由 K8s 中的 cert-manager 管理。如需更新 AWS 代理：
```
# 在 AWS 服务器上
kubectl get secret p0-ai-iiis-co-tls -n weixu -o jsonpath='{.data.tls\.crt}' | base64 -d > /etc/letsencrypt/live/p0.ai.iiis.co/fullchain.pem
kubectl get secret p0-ai-iiis-co-tls -n weixu -o jsonpath='{.data.tls\.key}' | base64 -d > /etc/letsencrypt/live/p0.ai.iiis.co/privkey.pem
sudo systemctl restart api-proxy codex-proxy oncall-agent
```
## 开源许可证
MIT License - 详情请见 [LICENSE](LICENSE) 文件。
## 技术支持
如有问题或疑问，请联系：
- **GitHub Issues**：https://github.com/xuw/iiis-oncall-agent/issues
- **管理员邮箱**：admin@iiis.edu.cn
- **内部文档**：请参阅 `DESIGN.md` 了解架构详情
标签：AIOps, AI智能体, AV绕过, Claude, CVE检测, DLL 劫持, FastAPI, Keycloak, LLM, Python, Server-Sent Events, SSE, SSO单点登录, Syscall, Unmanaged PE, Web开发, 交叉信息研究院, 人工智能, 内存分配, 基础设施运维, 大语言模型, 子域名突变, 工单系统, 排队系统, 无后门, 智能运维, 清华大学, 用户模式Hook绕过, 管理后台, 网络研究, 自动修复, 自动化诊断, 运维自动化, 逆向工具, 邮件通知, 重复检测