通用、高性能、AI 驱动的告警管理与 OnCall 值班平台
快速开始 · 功能特性 · 架构设计 · 部署指南 · API 文档
--- ## 项目简介 OnCall 是一款公司内部使用的**开源自托管**的智能告警管理平台，我将其非核心的部分进行重构开源，大家一起学习交流。旨在替代 Grafana OnCall，其提供从告警接入、降噪聚合、关联分析、AI 根因诊断到值班通知的全链路自动化能力。 与传统告警工具不同，OnCall 采用 **事件驱动（Incident-Centric）** 架构，通过 7 维度关联评分引擎将海量告警自动聚合为故障事件，让运维团队关注的是"故障"而非"告警"。 ### 为什么选择 OnCall？ | 痛点 | OnCall 方案 | |------|------------| | 监控源分散（N9e/Zabbix/Prometheus/自定义） | 统一 Webhook 接入，5 种格式自动识别 | | 告警风暴淹没关键信息 | 指纹去重 + 聚合引擎 + 风暴检测 + 指数退避 | | 告警多但无法定位根因 | AI Function Calling + ReAct 循环自主诊断 + 安全分级 + 审批闭环 | | 告警独立无关联 | 7 维度关联评分，自动聚合为事件（Incident） | | AI 黑盒不可控 | 死循环检测 + LLM 熔断 + Token 追踪 + Prompt 热加载 + 操作审计 | | 值班排班混乱 | 分层排班模型（Schedule→Rotation→Override） | | Grafana OnCall 太重 | 纯 Go + PostgreSQL，单二进制部署，AI 服务可选 | --- ## 功能特性  ### 多源告警接入 - **5 种内置格式**：Nightingale（原生 + 自定义回调）、Alertmanager、Zabbix、自定义 Webhook - **自动格式识别**：根据请求体字段自动判断格式，无需手动配置 - **可配置标准化**：DB 驱动的 Normalizer 规则 + 模板渲染（`{{.field}}`、`{{split}}`、`{{default}}`） - **资源解析器**：DB 驱动的 Resolver 规则，从异构告警中提取 `resource_type`、`resource_id`、`fault_domain` - **批量接收**：单次请求可提交多条告警  ### 智能降噪与聚合 - **3 种去重模式**： - `n9e_hash`：基于 N9e 的 hash 字段（默认，向后兼容） - `resource`：基于资源指纹 `sha256(project+resource_type+resource_id+fault_domain)[:16]` - `dual`：双模式，resource 优先，n9e_hash 兜底 - **告警风暴检测**：单位时间内超过阈值自动触发紧急聚合 - **噪音识别**：统计告警频率，高频低处理率告警自动降低通知频率（指数退避） - **级别抑制**：critical 告警触发时自动抑制同资源的 warning 告警   ### 事件关联引擎（Correlation Engine） 参考 BigPanda 架构，采用 **7 维度评分模型**： | 维度 | 最高分 | 规则 | |------|--------|------| | Project Match | 50 | 同项目 +50，不同项目直接跳过 | | Resource Match | 60 | 同 type+id → 60，同 id → 40，同 type → 20 | | Time Decay | 30 | 半衰期 60s：`30 × 0.5^(diff/60)` | | Label Similarity | 20 | Jaccard(cluster, namespace, region, env) | | Category Match | 20 | 同 fault_domain → +20 | | Topology Match | 40 | CMDB parent_resource_id 直接匹配 → 40，service_relations 按深度 40/25/10 | | Change Match | 30 | 告警关联到近期变更 → +30 | **阈值 ≥120 分**判定为同一事件。每次新告警到来时，引擎在 30 分钟窗口内搜索活跃事件进行评分匹配。    ### 事件生命周期管理 7 状态状态机：`open → acknowledged → investigating → mitigating → monitoring → resolved → closed` | 自动流转 | 条件 | |----------|------| | 全恢复 → 观察 | 事件下每个 fingerprint 至少有 1 条 resolved 告警，且无 firing 告警 | | 观察期满 → 恢复 | monitoring 状态持续 15 分钟（可配置） | | 观察期新告警 → 回滚 | monitoring 期间收到关联告警，回滚到 open | | 恢复后自动关闭 | resolved 超过 24 小时（可配置） | ### AI 智能诊断 - **事件级诊断**：新事件创建后 30 秒聚合窗口，然后以事件维度（所有关联告警 + 变更上下文）触发 AI - **Function Calling + ReAct 循环**：LLM 自主调用工具，逐步推理定位根因 - **工具安全分级**： - L1（只读，自动执行）：查 Prometheus 指标、查主机指标、SSH 诊断（10 种白名单命令） - L2（写入，需审批）：重启服务、扩缩容 → 自动创建审批工单，前端审批闭环 - L3（危险，禁止执行）：任意命令执行 - **Agent 安全治理**： - **死循环检测**：同一工具+相同参数重复调用时自动熔断，防止 Agent 陷入循环 - **LLM 熔断器**：连续 3 次 LLM 调用失败后自动熔断，5 分钟后自动恢复 - **工具结果截断**：SSH 诊断输出限 800 字符/命令，总结果限 4000 字符，防止上下文爆炸 - **诊断结果缓存**：同一告警 fingerprint 30 分钟内复用诊断结果，`force=true` 可跳过缓存 - **知识库质量门禁**：LLM 失败/降级/未完成的诊断不存入知识库；成功诊断需人工审核后入库 - **Prompt 热加载**：系统 Prompt 外置到 `ai-service/prompts/` 目录，修改文件后自动生效，无需重启 - **Agent 可观测性**：Token 消耗追踪、工具调用成功率、诊断成功率/平均耗时、死循环/熔断计数 - **L2 操作审批闭环**：AI 诊断产生的 L2 操作（重启/扩缩容）自动创建审批工单 → 前端审批 → 状态流转 - **降级策略**：事件级 AI 失败 → 降级到首条 critical 告警级 AI → 降级到规则引擎 - **预警提前诊断**：指标达阈值 70-85% 时提前触发 AI 诊断，不等告警正式触发 - **模型可选**：DeepSeek V3/R1、MiMo GPT、通义千问、GLM-4、自定义 OpenAI 兼容模型  ### OnCall 值班管理 - **分层排班模型**：Schedule（排班表）→ Rotation（轮班规则，优先级排序）→ Override（临时替班，最高优先级） - **灵活轮班**： - 时间段白夜班分离（如 09:00-18:00 白班、18:00-09:00 夜班跨天） - 日期掩码（工作日 `[1,2,3,4,5]`、周末 `[0,6]`、每天 `[]`） - 公平轮换算法：`(daysSinceStart + daysSinceStart/7) % n`，每周偏移避免固定周几值班 - **交接提醒**：handoff_time 前 N 分钟发送提醒（Redis 去重 24h） - **代班申请/审批**：申请→审批→自动创建 Override→审计留痕 - **值班 Excel 导入**：批量导入排班数据，自动匹配用户  ### 通知系统 - **5 预置渠道**：钉钉机器人、企业微信机器人、飞书机器人（卡片消息）、邮件 SMTP、通用 Webhook - **数据驱动路由**：规则引擎（severity_filter + label_filters + time_ranges + notify_configs） - **30 秒聚合延迟**：事件创建后等待告警聚合，期间如已 resolved 则跳过 - **事件级通知**：通知卡片包含所有关联告警 + AI 诊断摘要 + 跳转链接 - **免登录详情页**：通知链接可直接打开事件详情（只读），登录后自动跳转   ### 权限管理 - **双层 RBAC**： - 全局角色：admin（超级管理员）、platform_admin（平台管理员）、normal_user（普通用户） - 团队内角色：team_admin（团队负责人）、oncall_user（值班人员）、team_member（普通成员） - **18 权限点**：8 模块（alert/incident/oncall/config/ai/user/team/role）× 3 操作（read/write/manage） - **动态权限配置**：前端角色管理页可视化配置权限树   ### 操作审计 - **中间件统一拦截**：所有写操作（POST/PUT/DELETE/PATCH）自动审计，无需手动埋点 - **操作人不可伪造**：用户 ID 取自 JWT 上下文，非请求体 - **异步落库**：通过 buffered channel + worker 批量写入，不阻塞业务请求 - **完整记录**：HTTP 方法、路由路径、脱敏请求体、响应状态码、耗时、IP、User-Agent - **敏感字段脱敏**：password/token/api_key/secret 等字段自动遮蔽 - **语义化标签**：自动从路由推导 action（create/update/delete/ack/resolve…）和 target_type/target_id - **失败登录审计**：记录用户名不存在、密码错误等登录失败事件 - **保留期自动清理**：默认 180 天，可通过 `system_configs: audit.retention_days` 配置 - **RBAC 查询**：管理员可查看全量日志并导出 CSV，普通用户仅可查看自己的操作 --- ## 架构设计 ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Web UI (:3000) │────▶│ oncall-api:8080 │────▶│ PostgreSQL 16 │ │ Vue3+Vite+TS │ CORS│ Go (Gin+GORM) │ GORM│ │ │ AntDesignVue@4 │ │ (pure REST API) │ │ │ └─────────────────┘ └────────┬─────────┘ └─────────────────┘ │ NATS JetStream ┌────────▼─────────┐ │ oncall-engine │ │ Go (cron+worker) │ └────────┬─────────┘ │ HTTP ┌────────▼─────────┐ ┌─────────────────┐ │ ai-service:8089 │────▶│ ChromaDB │ │ Python/FastAPI │ │ (RAG 知识库) │ └──┬─────┬────┬────┘ └─────────────────┘ │ │ │ ┌────────────┘ │ └──────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ DeepSeek API │ │VictoriaMetrics│ │ SSH (paramiko)│ │ (LLM推理) │ │ (指标查询) │ │ (主机诊断) │ └──────────────┘ └──────────────┘ └──────────────┘ ``` ### 两个 Go 二进制 | 二进制 | 角色 | 职责 | |--------|------|------| | `oncall-api` | HTTP API 服务 | 告警接入（Normalizer→Parser→Resolver）、CRUD、WebSocket、CORS | | `oncall-engine` | 后台 Worker | NATS 消费、关联引擎、事件构建、AI 诊断触发、升级链、风暴检测 | ### 告警处理链路 ``` 原始告警 (N9e/Prometheus/Zabbix/Custom) ↓ ① Normalizer (DB 规则 → 字段映射 + 模板渲染) ↓ ② Parser (自动识别 5 种格式 + N9e tags_map 提取) ↓ ③ Resource Resolver (DB 规则 → resource_type, resource_id, fault_domain) ↓ ④ CMDB 轻量查询 (resource_id → project/service/owner/parent, Redis 缓存 2h) ↓ ⑤ 指纹生成 (n9e_hash / resource / dual 模式) ↓ ⑥ 去重 (DB 按 fingerprint 查询，2 分钟窗口) ↓ ⑦ 写入 PostgreSQL (带 resource + CMDB 字段) ↓ ⑧ 发布到 NATS (alerts.critical / alerts.warning / alerts.info) ↓ ⑨ Engine: 关联评分 (7 维度，CMDB parent_resource_id 优先，阈值 ≥120) ├── 评分 ≥ 120 → 更新已有事件 (fingerprint 去重, timeline) └── 评分 < 120 → 创建新事件 ↓ ⑩ 事件生命周期检查 (fingerprint 级全恢复 → monitoring → 自动 resolved → 自动 closed) ↓ ⑪ AI 诊断 (按事件维度，非按告警维度) ↓ ⑫ 通知 (按事件维度，聚合后发送) ``` ### 数据库表（41 张） | 类别 | 表 | |------|-----| | 核心数据 | `alerts`（分区表）、`incidents`、`alert_events` | | 值班管理 | `oncall_schedules`、`oncall_rotations`、`oncall_rotation_users`、`oncall_overrides`、`substitute_requests`、`oncall_audit_logs` | | 升级链 | `escalation_chains` | | 通知系统 | `notification_channels`、`message_templates`、`notify_rules`、`notification_records` | | 配置规则 | `resource_rules`、`fault_domain_rules`、`normalizer_rules`、`aggregation_rules`、`silence_rules` | | 权限管理 | `users`、`teams`、`team_members`、`roles`、`permissions`、`role_permissions` | | AI/CMDB | `ai_diagnosis_logs`、`ai_action_approvals`、`incident_reviews`、`incident_changes`、`service_relations` | | 系统 | `system_configs`、`alert_sources`、`audit_logs`、`operation_logs` | --- ## 快速开始 > 推荐使用 **方式 A（Docker Compose 一键启动）**，一条命令拉起全栈（含数据库初始化），适合快速体验与生产部署。需要二次开发时再按 **方式 B（源码手动运行）**。 ### 方式 A：Docker Compose 一键启动（推荐） #### 环境要求 | 组件 | 版本要求 | |------|----------| | Docker | ≥ 24.0（含 Docker Compose v2） | | 服务器内存 | ≥ 4GB（推荐 8GB，含 ChromaDB + AI 服务） | | 开放端口 | `80`（前端）、`8080`（API） | #### 1. 克隆项目 ```bash git clone https://github.com/your-org/oncall.git cd oncall ``` #### 2. 准备环境配置 ```bash cp deploy/.env.docker .env ``` 编辑 `.env`，必填项： - `JWT_SECRET`：JWT 签名密钥，**必须 ≥ 32 字符**（生成：`openssl rand -base64 48`） - `LLM_API_KEY`：DeepSeek API Key，用于 AI 诊断；不配置也能跑通告警接入/降噪/事件链路 可选项： | 变量 | 说明 | |------|------| | `API_PORT` | API 对外端口（默认 `8080`） | | `DB_USER` / `DB_PASSWORD` / `DB_NAME` | 数据库账号密码（默认 `oncall` / `oncall123` / `oncall`，仅内网使用） | | `REDIS_PASSWORD` | Redis 密码（默认 `Psbc@1234`） | | `LLM_BASE_URL` / `LLM_MODEL` / `LLM_TIMEOUT` | LLM 参数（默认 DeepSeek） | | `VM_URL` / `SSH_USER` / `SSH_PASSWORD` | VictoriaMetrics / SSH 诊断工具（可选） | | `TAG` | 镜像版本标签，固定版本便于回滚 | #### 3. 构建并全栈启动 ```bash docker compose up -d --build ``` 启动顺序由 healthcheck + `depends_on` 保证： ``` postgres / redis / nats / chromadb (healthy) -> oncall-migrate 一次性导入 sql/oncall.clean.sql，完成建库与初始化 -> oncall-engine 后台 Worker（NATS 消费、关联引擎、AI 诊断触发） -> oncall-api HTTP API -> web / ai-service 前端与 AI 服务 ``` > `oncall-migrate` 为一次性服务（`restart: no`），数据库初始化成功后即退出（日志输出 `MIGRATE_OK`）；`oncall-api` / `oncall-engine` 依赖其成功完成才会启动。首次启动约 5~10 分钟（拉取镜像 + 编译），之后启动仅需秒级。 #### 4. 验证启动 ```bash docker compose ps # 全部 RUNNING（oncall-migrate 为 Exited(0)）即正常 docker compose logs oncall-migrate # 看到 MIGRATE_OK 表示数据库初始化成功 ``` 访问： - **前端**：http://localhost（默认管理员 `admin / admin123`，首次登录后请修改密码） - **API**：http://localhost:8080（`GET /health` 返回 200） #### 5. 常用运维命令 ```bash docker compose ps # 查看所有服务状态 docker compose logs -f oncall-api oncall-engine # 跟踪后端日志 docker compose logs -f web oncall-ai # 跟踪前端 / AI 日志 docker compose restart oncall-api # 重启单个服务 docker compose down # 停止并删除容器（保留数据卷） docker compose down -v # 彻底重置（连数据库数据一起删除，慎用） ``` 服务与端口： | 服务 | 容器名 | 对外端口 | 说明 | |------|--------|----------|------| | `web` | `oncall-web` | `80` | Nginx + 前端静态资源，反代 `/api`、`/webhook`、`/ws`、`/ai-svc` | | `oncall-api` | `oncall-api` | `${API_PORT:-8080}` | HTTP API 服务 | | `oncall-engine` | `oncall-engine` | - | 后台 Worker | | `ai-service` | `oncall-ai` | - | AI 诊断服务（仅内网，由 web 代理） | | `postgres` / `redis` / `nats` / `chromadb` | `oncall-*` | - | 基础设施，仅 `oncall-net` 内网，不对外暴露 | 安全说明： - postgres / redis / nats / chromadb 仅位于 `oncall-net` 内网网络，不向宿主机暴露端口；外部只需开放 `80`（前端）和可选 `8080`（API）。 - 所有容器均以**非 root 用户**运行。 - 镜像使用显式 tag：`TAG=v1.0 docker compose up -d --build` 可固定版本便于回滚。 - 生产环境请修改默认密码，并设置强随机 `JWT_SECRET`。 #### 6. 升级数据库 Schema `oncall-migrate` 导入的是**清洗后**的 `sql/oncall.clean.sql`（仅保留 admin 用户 + RBAC，剔除个人用户/告警/事件/AI 配置等敏感数据），由 `sql/sanitize-dump.ps1` 从源 dump `sql/oncall.sql` 生成。需要变更数据库结构时： ```bash # 1. 更新源 dump sql/oncall.sql（例如从开发库重新导出 pg_dump） # 2. 重新生成清洗文件 powershell -File sql/sanitize-dump.ps1 -Path sql/oncall.sql -OutFile sql/oncall.clean.sql # 3. 强制重建 oncall-migrate 以重新导入最新 SQL，随后重启应用服务 docker compose up -d --force-recreate oncall-migrate docker compose restart oncall-engine oncall-api ``` #### 7. 测试告警接入 ```bash # 创建告警源（获取 token），也可在 Web 前端「告警源」页面创建 curl -X POST http://localhost:8080/api/v1/sources \ -H "Content-Type: application/json" \ -d '{"name":"prometheus-demo","source_type":"prometheus"}' # 发送测试告警 curl -X POST "http://localhost:8080/webhook/alertmanager?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '[{ "status": "firing", "labels": { "alertname": "cpu_high", "severity": "critical", "instance": "10.0.0.1:9100", "service": "order-service" }, "annotations": { "summary": "CPU 使用率超过 90%", "value": "95" }, "startsAt": "2026-06-16T10:00:00Z", "fingerprint": "test-fp-001" }]' ``` ### 方式 B：源码手动运行（开发调试） #### 环境要求 | 组件 | 版本要求 | |------|----------| | Go | ≥ 1.21 | | Node.js | ≥ 18 | | Python | ≥ 3.10 | | PostgreSQL | ≥ 15 | | Redis | ≥ 6.0 | | NATS | ≥ 2.10（需启用 JetStream） | #### 1. 启动基础设施 如需容器化方式启动 PostgreSQL、Redis、NATS，可（使用根目录 `docker-compose.yml`）： ```bash docker compose up -d postgres redis nats ``` 这将启动 PostgreSQL、Redis、NATS 三个基础设施服务（`chromadb` / AI 服务按需另行启动）。 #### 2. 初始化数据库 ```bash # 连接到 PostgreSQL，创建 oncall 数据库 psql -h localhost -U postgres -c "CREATE DATABASE oncall;" # 执行初始化脚本 psql -h localhost -U postgres -d oncall -f sql/init.sql # 执行迁移（按顺序） psql -h localhost -U postgres -d oncall -f sql/migrations/phase1_standard_model.sql psql -h localhost -U postgres -d oncall -f sql/migrations/phase7_incident_lifecycle.sql psql -h localhost -U postgres -d oncall -f sql/migrations/phase8_cmdb_mvp1.sql psql -h localhost -U postgres -d oncall -f sql/migrations/phase16_roles_permissions.sql psql -h localhost -U postgres -d oncall -f sql/migrations/phase17_rotation_shift_time.sql psql -h localhost -U postgres -d oncall -f sql/migrations/phase17b_rotation_weekdays.sql psql -h localhost -U postgres -d oncall -f sql/migrations/phase17c_add_event_id.sql psql -h localhost -U postgres -d oncall -f sql/migrations/phase25_operation_audit.sql psql -h localhost -U postgres -d oncall -f sql/migrations/phase25b_ai_approval.sql ``` #### 3. 配置环境变量 ```bash cp .env.example .env # 编辑 .env，填写数据库、Redis、NATS 连接信息 # 必须设置 JWT_SECRET（至少 32 字符） ``` #### 4. 编译后端 ```bash # 编译 API 服务 go build -o bin/oncall-api.exe ./cmd/oncall-api/ # 编译 Engine Worker go build -o bin/oncall-engine.exe ./cmd/oncall-engine/ ``` #### 5. 启动后端 ```bash # 先启动 Engine（创建 NATS 流） ./bin/oncall-engine.exe # 再启动 API（新终端） ./bin/oncall-api.exe ``` #### 6. 启动前端 ```bash cd web npm install npm run dev ``` 访问 http://localhost:3000，默认管理员账号：`admin / admin123` #### 7. 启动 AI 服务（可选） ```bash cd ai-service pip install -r requirements.txt # 配置 .env cp .env.example .env # 填写 LLM_API_KEY 等配置 python -m uvicorn app.main:app --host 0.0.0.0 --port 8089 ``` #### 8. 测试告警接入 方式 A 步骤 7 的告警接入命令同样适用于源码运行（API 地址同为 `http://localhost:8080`）。 --- ## 配置说明 ### 环境变量（.env） | 分组 | 变量 | 说明 | |------|------|------| | **数据库** | `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | PostgreSQL 连接信息 | | **Redis** | `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` | Redis 连接信息 | | **NATS** | `NATS_URL` | NATS 服务器地址（如 `nats://localhost:4222`） | | **JWT** | `JWT_SECRET` | JWT 签名密钥（**必须 ≥32 字符**） | | **AI** | `AI_SERVICE_URL` | AI 服务地址（如 `http://localhost:8089`） | | **端口** | `API_PORT` / `ENGINE_PORT` | API 和 Engine 端口 | | **日志** | `LOG_LEVEL` / `LOG_FORMAT` | 日志级别和格式 | ### 运行时配置（system_configs 表） | Key | 默认值 | 说明 | |-----|--------|------| | `alert.dedup_mode` | `n9e_hash` | 去重模式：n9e_hash / resource / dual | | `alert.storm_threshold` | `100` | 风暴检测阈值（每分钟） | | `ai.model` | `deepseek-chat` | AI 诊断使用的模型 | | `ai.base_url` | `https://api.deepseek.com` | AI 模型 API 地址 | | `ai.api_key` | `""` | AI 模型 API Key | | `ai.auto_diagnose` | `false` | 是否开启事件自动 AI 诊断 | | `incident.monitoring_window` | `15m` | 事件观察期时长 | | `incident.auto_close_after_resolved` | `24h` | 恢复后自动关闭时长 | | `notify.frontend_url` | `http://localhost:3000` | 前端地址（用于通知链接） | | `cmdb.enabled` | `false` | 是否启用 CMDB 集成 | | `change.enabled` | `false` | 是否启用变更系统集成 | | `audit.retention_days` | `180` | 操作审计日志保留天数 | --- ## API 文档 ### 告警接入 | 方法 | 路径 | 说明 | |------|------|------| | `POST` | `/webhook/alertmanager?token=xxx` | Alertmanager/N9e Webhook | | `POST` | `/api/v1/alerts?token=xxx` | 单条告警接入 | | `POST` | `/api/v1/alerts/batch?token=xxx` | 批量告警接入 | ### 告警管理 | 方法 | 路径 | 说明 | |------|------|------| | `GET` | `/api/v1/alerts` | 告警列表（支持 status/severity/source/fingerprint 筛选） | | `GET` | `/api/v1/alerts/:id` | 告警详情 | | `POST` | `/api/v1/alerts/:id/ack` | 认领告警 | | `POST` | `/api/v1/alerts/:id/investigate` | 开始排查 | | `POST` | `/api/v1/alerts/:id/resolve` | 恢复告警 | | `POST` | `/api/v1/alerts/:id/close` | 关闭告警 | ### 事件管理 | 方法 | 路径 | 说明 | |------|------|------| | `GET` | `/api/v1/incidents` | 事件列表（支持 status/severity/project/fault_domain 筛选） | | `GET` | `/api/v1/incidents/:key` | 事件详情（公开，无需登录） | | `POST` | `/api/v1/incidents/:key/ack` | 认领事件 | | `POST` | `/api/v1/incidents/:key/investigate` | 开始排查 | | `POST` | `/api/v1/incidents/:key/mitigate` | 采取缓解措施 | | `POST` | `/api/v1/incidents/:key/resolve` | 恢复事件 | | `POST` | `/api/v1/incidents/:key/close` | 关闭事件 | | `POST` | `/api/v1/incidents/:key/extend` | 延期观察 | | `POST` | `/api/v1/incidents/:key/diagnose` | 手动触发 AI 诊断 | ### 值班管理 | 方法 | 路径 | 说明 | |------|------|------| | `GET` | `/api/v1/oncall/schedules` | 排班表列表 | | `POST` | `/api/v1/oncall/schedules` | 创建排班表 | | `GET` | `/api/v1/oncall/schedules/:id` | 排班详情 | | `POST` | `/api/v1/oncall/schedules/:id/rotations` | 添加轮班规则 | | `POST` | `/api/v1/oncall/schedules/:id/overrides` | 添加临时替班 | | `GET` | `/api/v1/oncall/current` | 当前值班人 | | `POST` | `/api/v1/oncall/schedules/import` | Excel 批量导入 | | `GET` | `/api/v1/oncall/import/template` | 下载导入模板 | ### 通知配置 | 方法 | 路径 | 说明 | |------|------|------| | `GET` | `/api/v1/notify/channels` | 通知渠道列表 | | `POST` | `/api/v1/notify/channels` | 创建通知渠道 | | `POST` | `/api/v1/notify/channels/:id/test` | 测试通知发送 | | `GET` | `/api/v1/notify/templates` | 消息模板列表 | | `GET` | `/api/v1/notify/rules` | 通知规则列表 | ### 系统配置 | 方法 | 路径 | 说明 | |------|------|------| | `GET` | `/api/v1/admin/users` | 用户列表 | | `POST` | `/api/v1/admin/users` | 创建用户 | | `GET` | `/api/v1/admin/teams` | 团队列表 | | `POST` | `/api/v1/admin/teams` | 创建团队 | | `GET` | `/api/v1/roles` | 角色列表 | | `GET` | `/api/v1/permissions` | 权限列表 | ### 操作审计 | 方法 | 路径 | 说明 | |------|------|------| | `GET` | `/api/v1/audit/all` | 操作日志列表（支持时间范围/操作类型/状态/关键字筛选） | | `GET` | `/api/v1/audit/export` | 导出操作日志 CSV（仅管理员） | | `GET` | `/api/v1/audit/logs` | 值班审计日志（legacy） | ### AI 诊断与审批 | 方法 | 路径 | 说明 | |------|------|------| | `GET` | `/api/v1/ai/diagnoses` | AI 诊断记录列表 | | `POST` | `/api/v1/ai/diagnoses/:alert_id/feedback` | 诊断结果评分反馈 | | `GET` | `/api/v1/ai/observability` | AI 可观测性面板（诊断统计/成功率/耗时/审批统计） | | `GET` | `/api/v1/ai-approvals` | L2 操作审批列表（支持状态筛选） | | `POST` | `/api/v1/ai-approvals/:id/approve` | 批准 L2 操作 | | `POST` | `/api/v1/ai-approvals/:id/reject` | 驳回 L2 操作 | ### 实时通信 | 方法 | 路径 | 说明 | |------|------|------| | `WebSocket` | `/ws/alerts` | 实时告警推送 | --- ## 技术栈 | 层级 | 技术 | 版本 | 用途 | |------|------|------|------| | **前端** | Vue 3 + TypeScript | 3.5+ | 响应式 UI 框架 | | | Vite | 6.x | 构建工具 + HMR | | | ant-design-vue | 4.x | UI 组件库 | | | Pinia | 2.x | 状态管理 | | | ECharts | 5.x | 数据可视化 | | **后端** | Go | 1.21+ | 核心运行时 | | | Gin | 1.12 | HTTP 框架 | | | GORM V2 | 1.31 | ORM | | | NATS JetStream | 2.10 | 消息队列 | | | go-redis/v9 | 9.19 | 缓存客户端 | | **AI 服务** | Python + FastAPI | 3.10+ | AI 推理服务 | | | OpenAI SDK | 1.12+ | LLM 调用（Function Calling） | | | ChromaDB | 0.4+ | 向量数据库（RAG） | | | paramiko | 3.0+ | SSH 远程诊断 | | **数据库** | PostgreSQL | 15+ | 主数据库（JSONB + 分区表） | | | Redis | 6.0+ | 缓存 + 去重 + 分布式锁 | | | NATS | 2.10+ | JetStream 持久化消息 | --- ## 项目结构 ``` oncall/ ├── cmd/ │ ├── oncall-api/ # API 服务入口 │ │ └── main.go │ └── oncall-engine/ # Engine Worker 入口 │ └── main.go ├── internal/ │ ├── config/ # 配置加载 │ ├── cron/ # 定时任务（分区管理） │ ├── handler/ # HTTP Handler（路由 + 业务入口） │ ├── middleware/ # 中间件（JWT 认证 + RBAC 权限） │ ├── model/ # 数据模型（GORM） │ ├── pkg/ # 内部包 │ │ ├── ai/ # AI 服务客户端 │ │ ├── cmdb/ # CMDB 集成客户端 │ │ ├── change/ # 变更系统集成客户端 │ │ ├── database/ # 数据库连接 │ │ ├── jwt/ # JWT 工具 │ │ ├── logger/ # 日志 │ │ ├── metrics/ # Prometheus 指标 │ │ ├── nats/ # NATS 连接 + 流管理 │ │ └── redis/ # Redis 连接 │ └── service/ # 业务逻辑层 │ ├── engine.go # NATS 消费 + 告警处理主流程 │ ├── alert.go # 告警接入 + 去重 + NATS 发布 │ ├── incident.go # 事件创建/更新 │ ├── correlation.go # 7 维度关联评分引擎 │ ├── lifecycle.go # 事件状态机 │ ├── notification.go # 通知服务 │ ├── aggregation.go # 聚合引擎 │ ├── normalizer.go # 标准化引擎 │ ├── resolver.go # 资源解析器 │ └── oncall_schedule.go # 排班管理 ├── ai-service/ │ ├── app/ │ │ ├── main.py # FastAPI 入口 │ │ ├── react.py # Function Calling + ReAct 循环（含熔断器/死循环检测） │ │ ├── tools.py # 工具注册（L1/L2/L3 安全分级 + 结果截断） │ │ ├── metrics.py # VictoriaMetrics 客户端 │ │ ├── knowledge.py # ChromaDB RAG 知识库（含质量过滤） │ │ ├── cache.py # 诊断结果缓存（30min TTL） │ │ ├── observability.py # Agent 可观测性指标收集 │ │ └── prompt_manager.py# Prompt 外置 + 热加载 │ ├── prompts/ # Prompt 模板文件（热加载） │ ├── .env.example │ └── requirements.txt ├── web/ │ ├── src/ │ │ ├── api/ # Axios API 封装 │ │ ├── router/ # Vue Router（16 路由） │ │ ├── stores/ # Pinia Stores │ │ ├── views/ # 页面组件（31 个 .vue 文件） │ │ └── styles/ # 全局样式 │ ├── package.json │ └── vite.config.ts ├── sql/ │ ├── init.sql # 数据库初始化 │ └── migrations/ # 迁移脚本 ├── deploy/ │ └── docker-compose.yml # 基础设施部署 ├── .env.example # 环境变量模板 ├── Makefile # 构建脚本 └── go.mod ``` --- ## 部署指南 ### 方式一：Linux 一键部署（推荐） 提供了一个自动化安装脚本，适用于 CentOS 7+/Ubuntu 18+/Debian 10+： ```bash # 1. 克隆项目并编译（在开发机上） git clone https://github.com/your-org/oncall.git cd oncall make build # 编译 Go 后端（输出到 bin/） cd web && npm install && npm run build && cd .. # 构建前端 # 2. 将整个项目目录上传到目标服务器 scp -r ./* user@server:/tmp/oncall/ # 3. 在服务器上执行安装脚本 ssh user@server cd /tmp/oncall sudo bash deploy/install.sh ``` 安装脚本会自动完成： - 创建 `oncall` 系统用户 - 安装二进制到 `/opt/oncall/bin/` - 初始化数据库和执行迁移 - 配置 Nginx 反向代理（前端 :3000 → API :8080） - 安装 AI 服务 Python 依赖 - 注册 systemd 服务并启动 - 自动生成 JWT_SECRET 安装完成后的服务管理： ```bash # 服务管理 systemctl start oncall-api # 启动 API systemctl start oncall-engine # 启动 Engine systemctl restart oncall-api # 重启 API systemctl restart oncall-engine # 重启 Engine systemctl status oncall-api # 查看状态 systemctl status oncall-engine # 查看状态 # 查看日志 journalctl -u oncall-api -f # 实时 API 日志 journalctl -u oncall-engine -f # 实时 Engine 日志 tail -f /var/log/oncall/api.log # API 日志文件 tail -f /var/log/oncall/engine.log # Engine 日志文件 ``` 服务文件位于： - `/etc/systemd/system/oncall-api.service` - `/etc/systemd/system/oncall-engine.service` ### 方式二：手动 Linux 部署 如果不使用一键脚本，按以下步骤手动部署： ```bash # 1. 编译（在开发机或服务器上） make build # 2. 创建目录 sudo mkdir -p /opt/oncall/{bin,web,ai-service,sql} sudo mkdir -p /var/log/oncall # 3. 复制文件 sudo cp bin/oncall-api /opt/oncall/bin/ sudo cp bin/oncall-engine /opt/oncall/bin/ sudo cp -r web/dist /opt/oncall/web/ sudo cp -r sql/* /opt/oncall/sql/ sudo cp -r ai-service /opt/oncall/ sudo cp .env /opt/oncall/ # 4. 配置 .env sudo vim /opt/oncall/.env # 必须修改：DB_HOST, DB_PASSWORD, REDIS_PASSWORD, JWT_SECRET, NATS_URL # 5. 初始化数据库 psql -h