ohdasdiego/oncall-assistant
GitHub: ohdasdiego/oncall-assistant
一款 AI 驱动的值班事件响应工具，通过聚合 Runbook、历史事件和系统健康等多源上下文，由 Claude 自动生成结构化响应计划并追踪事件全生命周期。
Stars: 0 | Forks: 0
# 值班助手
一款由 AI 驱动的事件响应工具，能够在警报触发时，从整个 ADOStack 聚合上下文并生成可操作的响应计划。
## 在线演示
🔗 **[oncall.ado-runner.com](https://oncall.ado-runner.com)**
## 功能介绍
当通过 Web UI、Webhook 或 Telegram 机器人命令创建事件时，值班助手会立即并行从三个 ADOStack 数据源拉取上下文：
- **RAG Runbook Assistant** — 检索与事件类型相关的 Runbook 步骤
- **AI Incident Logger** — 呈现类似的历史事件及其解决方案
- **AI Infra Monitor** — 快照当前系统健康状况
这些上下文将被提供给 Claude，由其综合生成结构化的响应计划：严重性评估、可能的根本原因、即时行动步骤、关注点以及升级触发条件。随后，系统将对该事件进行全生命周期跟踪，并记录带有时间戳的每个事件的时间线。
**事件接入路径：**
- **Web UI** — 在仪表板手动创建事件
- **Webhook** — `POST /webhooks/infra-monitor` 自动接收来自 AI Infra Monitor 的警报
- **Telegram 机器人** — `/oncall [high] disk full on prod-db-01`
**生命周期跟踪：**
- 状态流转：`OPEN → INVESTIGATING → MITIGATED → RESOLVED`
- 完整时间线：记录每一次上下文获取、AI 计划、状态变更和备注
- Telegram 通知：在事件创建、每次状态变更和解决（包含持续时长）时发送通知
- 交接班备注 — 为下一任值班工程师生成 AI 摘要
**优雅降级：**
- 在 ADOStack 部分可用的情况下正常运作
- 针对每个事件，清晰标记哪些数据源可达、哪些处于离线状态
## 输出示例
### AI 响应计划
```
## Severity 评估
HIGH — elevated CPU sustained above threshold on primary host; risk of cascading
service degradation if not addressed within 15 minutes.
## 可能根因
- Runaway process or unbounded cron job consuming CPU cycles
- Sudden traffic spike without load shedding
- Memory pressure forcing excessive swapping
## 紧急行动
1. Run `top` or `htop` to identify the highest CPU consumer
2. Check cron logs: `journalctl -u cron --since "10 min ago"`
3. If a known process: restart via `sudo systemctl restart `
4. Verify infra-monitor metrics to confirm trend direction
## Watch Points
- CPU trend over next 3 readings (rising vs. stabilizing)
- Memory pressure — OOM risk if swap is active
- Network I/O — rule out a traffic-driven cause
## Escalation 触发器
Escalate if CPU remains above 85% after two remediation attempts or if a second
service shows degradation within the same window.
```
### Telegram 警报
```
🔴 INCIDENT OPENED [HIGH]
#4 — High CPU on claw-gateway1
Source: `infra_monitor`
🔗 View Incident
```
### API 响应 — `/api/incidents`
```
[
{
"id": 4,
"title": "High CPU on claw-gateway1",
"severity": "high",
"status": "INVESTIGATING",
"source": "infra_monitor",
"created_at": "2026-04-25T17:00:00",
"updated_at": "2026-04-25T17:04:22"
}
]
```
## 架构
```
Alert Intake
├── Flask UI → manual incident creation
├── POST /webhooks/infra-monitor → AI Infra Monitor alerts (HMAC-signed)
└── Telegram /oncall → bot command
↓
Context Aggregator (parallel fetch, 8s timeout per source)
├── runbooks.ado-runner.com → relevant runbook steps (RAG)
├── localhost:5001/api/incidents → similar past incidents
└── localhost:5000/api/health → current system health
↓
Claude (claude-haiku) → structured response plan
↓
SQLite — incidents + timeline_events + context_cache
↓
Telegram → notification at each lifecycle event
```
```
Browser ──► Cloudflare (SSL/DDoS) ──► Nginx (CF IPs only) ──► Gunicorn:5005
│
Claude API (Anthropic)
ADOStack services
```
**关键设计决策：**
- Gunicorn 仅绑定到 `127.0.0.1:5005` — 绝不直接对外暴露
- Nginx 将入站流量限制为 Cloudflare IP 范围 — 阻止直接 IP 访问
- 上下文聚合采用并行处理且带有独立数据源超时机制 — 某个离线服务绝不会阻塞其他服务
- 使用 SQLite 进行事件存储 — 简单、零依赖、可审计
- Webhook HMAC 验证 — 使用共享密钥对 Infra Monitor 警报进行验证
## 技术栈
| 层级 | 技术 |
|---|---|
| AI 响应规划 | Anthropic Claude API (`claude-haiku-4-5`) |
| 上下文聚合 | Python 3, requests (并行拉取) |
| API / Web UI | Flask 3, Gunicorn |
| 数据库 | SQLite (事件、时间线、上下文缓存) |
| Telegram 集成 | Bot API (Webhook + 通知) |
| 反向代理 | Nginx (Cloudflare IP 白名单) |
| CDN / SSL | Cloudflare |
| 进程管理 | systemd |
| 操作系统 / 托管 | Ubuntu 24.04 VPS |
## API 端点
| 端点 | 方法 | 描述 |
|---|---|---|
| `GET /` | GET | 事件仪表板 UI |
| `GET /incidents/new` | GET | 新建事件表单 |
| `POST /incidents/new` | POST | 手动创建事件 |
| `GET /incidents/` | GET | 事件详情 + 时间线 |
| `POST /incidents//status` | POST | 更新事件状态 |
| `GET /incidents//handoff` | GET | 生成交接班备注 |
| `GET /api/incidents` | GET | 列出所有事件 (筛选：`?status=OPEN`) |
| `GET /api/incidents/` | GET | 事件详情 + 时间线 + 上下文 |
| `GET /api/health` | GET | 服务存活探针 |
| `POST /webhooks/infra-monitor` | POST | 接收 Infra Monitor 警报 (HMAC) |
| `POST /webhooks/telegram` | POST | Telegram Bot Webhook |
## 安装设置
### 1. 克隆并安装依赖
```
git clone https://github.com/ohdasdiego/oncall-assistant.git
cd oncall-assistant
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
### 2. 配置环境变量
```
cp .env.example .env
# 编辑 .env — 添加 ANTHROPIC_API_KEY, TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID
```
### 3. 本地运行
```
python wsgi.py
# → Dashboard 位于 http://localhost:5005
```
### 4. 部署为 systemd 服务
```
sudo cp oncall-assistant.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable oncall-assistant
sudo systemctl start oncall-assistant
```
### 5. Nginx 反向代理
```
sudo cp nginx.conf /etc/nginx/sites-available/oncall-assistant
sudo ln -sf /etc/nginx/sites-available/oncall-assistant /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```
### 6. Telegram 机器人设置
通过 [@BotFather](https://t.me/BotFather) 创建一个机器人，获取你的 Token，在 `.env` 中设置 `TELEGRAM_BOT_TOKEN` 和 `TELEGRAM_CHAT_ID`，然后注册 Webhook：
```
curl -X POST "https://api.telegram.org/bot/setWebhook" \
-d "url=https://oncall.ado-runner.com/webhooks/telegram"
```
**Bot 命令：**
```
/oncall Open a new incident (medium severity)
/oncall [high] disk full Open with explicit severity
/status List all open incidents
```
## 成本分析
所有 AI 调用均采用 `claude-haiku-4-5` 计费标准（输入 $1.00/百万 Token，输出 $5.00/百万 Token）：
| 场景 | 每月调用次数 | 每月输入 Token | 每月输出 Token | 预估每月成本 |
|---|---|---|---|---|
| 5 次事件/天 | 150 | ~225K | ~150K | ~$0.98 |
| 20 次事件/天 | 600 | ~900K | ~600K | ~$3.90 |
| 50 次事件/天 | 1,500 | ~2.25M | ~1.5M | ~$9.75 |
**成本控制手段：**
- 降低 `CONTEXT_TIMEOUT_SECONDS` 以限制每个数据源的拉取时间
- 针对交接班备注和响应计划切换使用更轻量级的模型
- 缓存每个事件的上下文 — 已通过 `context_cache` 表实现
## 展示的技能
该项目刻意贴近生产标准 — 而非本地实验品：
- **Agentic AI 设计** — 多源上下文聚合驱动结构化 AI 推理，并具备优雅降级能力
- **事件管理** — 完整的生命周期跟踪、时间线事件、状态工作流、交接班
- **API 集成** — 带有独立超时的并行 HTTP 拉取、HMAC Webhook 验证、Telegram Bot API
- **系统运维** — systemd 服务管理、Nginx 反向代理、Cloudflare IP 白名单
- **安全卫生** — 密钥存放在 `.env` 中（已添加至 .gitignore）、仅绑定本地回环地址、Nginx 仅允许 CF 访问、HMAC 签名的 Webhook
- **数据库设计** — 规范化的 SQLite schema（事件、时间线、上下文缓存）并带有适当的外键
- **服务架构** — 5 服务 ADOStack 平台的一部分；专为服务间通信和优雅的局部可用性而设计
## ADOStack
| 工具 | 角色 |
|------|------|
| [AI Infra Monitor](https://monitor.ado-runner.com) | 指标收集 + AI 健康分析 |
| [AI Incident Logger](https://incidents.ado-runner.com) | 阈值告警 + 事件记录 |
| [RAG Runbook Assistant](https://runbooks.ado-runner.com) | IT Runbook 的向量搜索 |
| # | 项目 | 在线链接 | 角色 |
|---|---------|------|------|
| 1 | [AI Infra Monitor](https://github.com/ohdasdiego/ai-infra-monitor) | [monitor.ado-runner.com](https://monitor.ado-runner.com) | 指标收集 + AI 健康分析 |
| 2 | [AI Incident Logger](https://github.com/ohdasdiego/ai-incident-logger) | [incidents.ado-runner.com](https://incidents.ado-runner.com) | 阈值告警 + 事件记录 |
| 3 | [Code Auditor](https://github.com/ohdasdiego/code-auditor) | CLI | 由 AI 驱动的代码审查 |
| 4 | [RAG Runbook Assistant](https://github.com/ohdasdiego/rag-runbook-assistant) | [runbooks.ado-runner.com](https://runbooks.ado-runner.com) | IT Runbook 的向量搜索 |
| 5 | [K8s Event Summarizer](https://github.com/ohdasdiego/k8s-event-summarizer) | [k8s.ado-runner.com](https://k8s.ado-runner.com) | Kubernetes 集群健康摘要 |
| 6 | [AI Incident Orchestrator](https://github.com/ohdasdiego/ai-incident-orchestrator) | [orchestrator.ado-runner.com](https://orchestrator.ado-runner.com) | 多 Agent 分流管道 |
| **7** | **值班助手** | **[oncall.ado-runner.com](https://oncall.ado-runner.com)** | **← 你正在这里** |
## 🗺️ 路线图
- [x] Webhook 集成 — AI Infra Monitor 在阈值被突破时自动向 `/webhooks/infra-monitor` 发送数据，状态自动推进至 INVESTIGATING
- [x] 升级路由 — 高/严重级别事件会触发 Telegram 操作按钮；低/中级别事件自动处理
- [ ] 自动解决确认 — 当 Infra Monitor 报告异常已清除时，发送 Telegram 提示
- [ ] 上下文刷新 — 在事件处理过程中随着情况变化重新拉取 ADOStack 数据源
- [ ] 升级跟踪 — 当满足升级触发条件时进行记录和通知
- [ ] 事件搜索 — 按关键字、严重性或来源筛选和搜索历史事件
- [ ] 多用户支持 — 为写入端点提供基础认证或基于 Token 的访问控制
## 作者
**Diego Perez** · [github.com/ohdasdiego](https://github.com/ohdasdiego/oncall-assistant)
标签：ADOStack, AIOps, AI智能运维, Claude, CSV输出, CVE检测, DLL 劫持, IT运维, On-Call助手, RAG, Runbook, Socks5代理, Telegram机器人, Webhook, 上下文聚合, 事件追踪, 事故生命周期管理, 全栈运维, 力导向图, 告警聚合, 基础设施监控, 大语言模型, 故障排查, 根因分析, 运维自动化