Files

phamnazage-jpg fc54ba84b2 chore: initial import

2026-05-12 17:48:22 +08:00

16 KiB

Raw Permalink Blame History

AI-Ops 功能清单（模块级）

版本：v1.1 日期：2026-05-11 说明：模块级功能清单，仅到达"功能级"精度。具体的按钮、动画、色彩、字体等前端实现细节由 Engineer 和前端工程师在开发阶段自行决定，不在 PM 规划范围内。

**PM 范围：**模块定义、功能边界、数据模型、接口契约、验收标准。 **Engineer 范围：**代码实现、前端组件选型、动画/交互细节、测试用例实现。

总工期估算：34 人天（含 20% 协调缓冲） + 15% 风险缓冲 = 39 人天。估算方法：简单任务 0.5d / 中等任务 1d / 复杂任务 2d，模块级汇总后加缓冲。

Phase 1：监控看板 + 日志查询（不触发自动动作）

工期估算：8 人天（含 20% 协调缓冲）

模块 1.1：监控首页

1.1.1 首页基础布局

任务：实现首页路由 /ops/dashboard，返回监控首页 HTML 模板

1.1.2 指标数据获取

任务：实现 GET /api/v1/ai-ops/metrics/realtime 接口，返回当前 QPS、平均延迟、P99、错误率
任务：实现 GET /api/v1/ai-ops/metrics/suppliers/count 接口，返回活跃供应商数量
任务：实现 GET /api/v1/ai-ops/alerts/open/count 接口，返回未关闭告警数量

1.1.3 指标下钻

任务：实现 GET /api/v1/ai-ops/metrics/query 接口，支持 service/path/supplier 维度过滤

模块 1.2：日志查询

1.2.1 日志查询页

任务：实现日志查询页路由 /ops/dashboard/logs

1.2.2 日志结果展示

任务：日志列表以表格展示，每行显示：时间 / 服务名 / 路径 / 状态码 / 延迟 / 用户ID / 供应商ID
任务：日志列表支持分页，每页 100 条，显示总条数
任务：实现日志查询结果"导出 CSV"按钮，导出上限 10000 条

1.2.3 日志查询性能

任务：日志查询接口添加查询超时逻辑，超时返回部分结果并提示
任务：实现日志查询结果缓存（Redis，5分钟 TTL），同一筛选条件命中缓存时直接返回

Phase 2：告警规则引擎 + 通知渠道（告警只通知，不执行自愈）

工期估算：12 人天（含 20% 协调缓冲）

模块 2.1：告警规则管理

2.1.1 告警规则列表页

任务：实现告警规则列表页路由 /ops/dashboard/alerts/rules
任务：规则列表支持分页，每页 50 条

2.1.2 创建/编辑告警规则

任务：实现规则创建页路由 /ops/dashboard/alerts/rules/create
任务：实现规则创建表单，包含字段：规则名称（必填）、监控指标（下拉：QPS/延迟/错误率/供应商健康度/Token消耗）、阈值类型（下拉：> / < / = / 正则匹配）、阈值数值（必填）、持续时间（分钟，必填）、告警级别（下拉：P0/P1/P2/P3，必填）、通知渠道（多选：Webhook/邮件/飞书/企微）
任务：编辑页路由 /ops/dashboard/alerts/rules/{rule_id}/edit，回填已有数据

2.1.3 告警规则引擎（后端）

任务：实现规则引擎从 PostgreSQL 加载所有启用规则，每 30 秒刷新
任务：实现规则引擎对每个指标数据点执行阈值评估
任务：实现持续时间判定（指标超阈值必须持续 N 分钟才触发）
任务：实现告警事件生成，写入 ai_ops_alert_events 表，状态 = triggered
任务：实现同一规则同一目标 5 分钟抑制期逻辑（5 分钟内相同告警不重复生成）
任务：实现告警升级逻辑（P2 持续 2 小时未确认 → 升级 P1）

模块 2.2：告警事件与处置

2.2.1 告警事件列表

任务：实现告警事件列表页路由 /ops/dashboard/alerts/events
任务：事件列表每行显示：事件ID / 规则名称 / 级别 / 触发时间 / 持续时长 / 状态 / 操作

2.2.2 告警集群聚合

任务：实现告警聚合逻辑：同一服务/资源 1 分钟内触发 >20 条告警时，生成 1 条集群告警
任务：集群告警列表每行显示：集群ID / 涉及规则数 / 累计告警数 / 首条时间 / 最新时间 / 级别

模块 2.3：通知渠道配置

2.3.1 通知配置页

任务：实现通知配置页路由 /ops/dashboard/alerts/channels

2.3.2 通知发送后端

任务：实现通知发送队列（内存队列 + Redis 持久化）
任务：实现 P0/P1 通知 30 秒内发送，P2 通知 120 秒内发送
任务：实现通知失败时自动切换备用渠道（Webhook 失败 → 邮件 → 飞书 → 企微）
任务：实现通知日志记录，每次发送记录成功/失败原因到 ai_ops_notification_logs

Phase 3：自愈引擎 + 审计回滚

工期估算：14 人天（含 20% 协调缓冲）

模块 3.1：自愈规则配置

3.1.1 自愈规则创建

任务：在告警规则创建/编辑页，添加"自愈动作"可选配置区块
任务：自愈动作类型下拉：无 / 切换备用路由 / 限流 / 重启实例 / 触发脚本
任务：当选择"切换备用路由"时，显示供应商下拉框（选择目标备用供应商）
任务：配置"沙盒模式"开关，默认开启（沙盒模式下自愈动作仅记录，不实际执行）
任务："保存"按钮同时保存告警规则和自愈动作配置

3.1.2 自愈执行后端

任务：自愈引擎监听 triggered 状态的告警事件
任务：当告警关联自愈动作且沙盒模式关闭时，执行自愈动作
任务：执行切换备用路由：调用 gateway 管理接口，将流量切换到备用供应商
任务：执行限流：调用 gateway 管理接口，设置速率限制
任务：执行重启实例：通过 K8s API 或主机 agent 调用重启指定服务实例，配置超时 60 秒、最大重试 2 次
任务：执行触发脚本：在隔离环境中执行指定的 shell/Python 脚本，超时 30 秒
任务：自愈动作执行后 60 秒内评估监控指标是否恢复正常
任务：自愈成功：事件状态更新为 resolved，记录动作结果
任务：自愈失败（重试 1 次仍失败）：升级为 P0 人工告警（电话/短信），事件状态更新为 escalated

3.1.3 自愈级联失败处理

任务：切换备用路由后，监控新路由健康状态 2 分钟
任务：若新路由也触发告警，立即回退到原始路由
任务：回退完成后，升级为 P0 人工告警（电话/短信），注明"自愈级联失败"

模块 3.2：配置审计

3.2.1 审计日志查询页

任务：实现审计日志页路由 /ops/dashboard/audit
任务：审计列表每行显示：审计ID / 操作时间 / 操作人 / 操作类型 / 资源类型 / 资源ID / 操作后值摘要
任务：审计列表支持导出（最多 10000 条，按时间范围导出）

3.2.2 审计后端

任务：拦截所有配置变更操作（CREATE/UPDATE/DELETE），在事务内同步写入审计日志
任务：审计日志写入使用追加模式（不支持 UPDATE/DELETE），数据库层设置禁止删除策略
任务：审计日志保留期 >= 90 天，后台 job 每天清理过期数据

模块 3.3：配置回滚

3.3.1 回滚操作入口

任务：回滚成功提示："回滚成功，已恢复到 {时间} 的状态，耗时 X 秒"
任务：回滚失败时显示错误码和原因（如 OPS_AUD_4101）

3.3.2 回滚后端

任务：实现回滚接口，根据审计记录 ID 查找操作前值
任务：回滚前检查目标资源是否仍存在，不存在时返回错误码 AUDIT_ROLLBACK_TARGET_LOST
任务：回滚操作在独立事务中执行，更新目标资源值
任务：回滚成功后生成新审计记录，关联原始审计记录 ID（字段 rolled_back_from_audit_id）

Phase 4：容量主板与高级分析

模块 4.1：容量视图

4.1.1 容量主页

任务：实现容量主页路由 /ops/dashboard/capacity

4.1.2 容量数据后端

任务：实现容量数据聚合 job（每小时执行），将原始指标聚合为小时级数据
任务：实现增长率计算算法（基于过去 7 天数据线性回归）
任务：实现负载等级判定（可配置阈值，默认为：正常 < 60% 利用率 < 警告 < 80% < 过载）

全局模块

模块 G1：认证与权限

任务：实现登录页路由 /ops/login，支持账号密码登录
任务：实现 JWT Token 签发，Token 有效期 8 小时
任务：实现中间件，所有 /api/v1/ai-ops/* 接口需携带有效 JWT
任务：实现角色权限中间件：查看者（GET only）、运维人员（可写告警规则）、管理员（可回滚、可管理用户）
任务：实现权限不足时返回 HTTP 403，响应体包含错误码 OPS_AUTH_1001

模块 G2：健康检查

任务：实现 GET /actuator/health 接口，返回整体健康状态
任务：实现 GET /actuator/health/live 接口，用于 K8s liveness probe
任务：实现 GET /actuator/health/ready 接口，用于 K8s readiness probe（依赖 DB + Redis 连通性）

模块 G3：OpenAPI 文档

任务：实现 OpenAPI 3.0 JSON spec 生成，端点 /openapi.json
任务：确保所有对外 API（路由/请求/响应/错误码）均在 spec 中体现

技术基础设施（各 Phase 共享）

T1：项目骨架

任务：初始化 Go module github.com/lijiaoliao/ai-ops
任务：创建 cmd/ai-ops/main.go 入口，支持 api 和 worker 两种运行模式
任务：创建 internal/ 目录结构（domain/service/handler/infrastructure/repository）
任务：配置 Viper 读取 config.yaml，支持环境变量覆盖
任务：配置 log/slog 结构化日志，输出 JSON 格式
任务：创建 PostgreSQL schema migration（使用 golang-migrate），表前缀 ai_ops_
任务：创建 Redis 连接池配置
任务：配置 Dockerfile 和 docker-compose.yml
任务：编写 DEPLOYMENT.md 中的 docker-compose 启动命令

T2：单元测试骨架

任务：为每个 domain 层函数编写单元测试，覆盖率 >= 70%
任务：为每个 service 层函数编写单元测试，覆盖率 >= 80%
任务：配置 CI（GitHub Actions），PR 必须通过全部测试和覆盖率检查

T3：IntegrationPlugin 接口

任务：实现 IntegrationPlugin 接口（Init() error / Serve() error / Shutdown() error）
任务：实现插件模式下各模块的开关配置（viper 读取 ops.enabled_modules）
任务：编写集成测试：插件模式启动，所有功能正常运作

任务估算汇总

Phase	模块	任务数	估计工时
Phase 1	1.1 首页 + 1.2 日志查询	28	3 人天
Phase 2	2.1 告警规则 + 2.2 事件处置 + 2.3 通知渠道	30	4 人天
Phase 3	3.1 自愈引擎 + 3.2 审计 + 3.3 回滚 + 3.4 供应商切换	26+16=42	4 人天 + 2 人天
Phase 4	4.1 容量视图	10	1.5 人天
全局	G1 认证 + G2 健康 + G3 文档	14	1.5 人天
技术基础设施	T1 骨架 + T2 测试 + T3 插件	14	2 人天
合计		122+16=138	~16+2=18 人天

模块 3.4：供应商智能切换（参考 FreeRide 思路）

FreeRide 是 OpenClaw 的自动模型切换插件，核心思路：实时排行 → 自动选择 → Fallback 链 → 限速无感知切换。对应到 AI-Ops 的供应商切换场景，可以把这个思路产品化。

3.4.1 供应商质量监控

任务：定时任务（每 5 分钟）调用各中转供应商的 /models 接口，记录可用模型列表
任务：对每个供应商执行探测请求（测试请求），记录响应时间和错误率
任务：探测结果写入 supplier_health 表，记录字段：supplier_id、probe_at、latency_ms、error_rate、available_models、elo_score
任务：GET /api/v1/ai-ops/suppliers/health 接口返回所有供应商的实时健康状态
任务：GET /api/v1/ai-ops/suppliers/health/{supplier_id} 接口返回指定供应商的详细健康状态
任务：在供应商管理页显示健康状态标签（健康 / 延迟高 / 错误率高 / 不可用）
任务：健康状态数据保留 7 天，支持趋势查看

3.4.2 供应商 Fallback 链管理

任务：为每个接入的模型配置主供应商 + 备用供应商列表（至少 1 主 + 1 备）

任务：供应商配置数据结构：

type SupplierChain struct {
    Model         string   // 模型名
    Primary       string   // 主供应商ID
    Fallbacks     []string // 备用供应商ID列表（按优先级排序）
    CooldownSec   int      // 故障后多少秒内不切换回来（默认300s）
}

任务：配置页支持拖拽排序 Fallback 顺序
任务：切换后的冷却期内，即使主供应商恢复也不同质（避免震荡）
任务：切换记录写入审计日志，包含：切换时间、原供应商、目标供应商、切换原因

3.4.3 智能切换策略

任务：切换策略下拉：成本优先 / 质量优先 / 延迟优先 / 手动
任务：成本优先：按 input_cost_per_token + output_cost_per_token 排序，选择最低者
任务：质量优先：按最近 24h 成功率排序，选择最高者
任务：延迟优先：按最近 probe 的 latency_ms 排序，选择最低者
任务：手动：每次切换需人工确认
任务：当主供应商触发告警（P1/P2），自动检查 Fallback 链是否可用
任务：选择最佳备用供应商后，自动执行切换（若策略不是"手动"）
任务：切换完成后发送通知（飞书/企微/钉钉），告知：原供应商、目标供应商、切换原因

3.4.4 供应商切换执行

任务：POST /api/v1/ai-ops/suppliers/switch 接口：传入 model + target_supplier，执行切换
任务：调用 gateway 的 /internal/suppliers/switch 接口完成实际路由切换
任务：切换后立即执行一次探针验证，确认新供应商可服务工作
任务：验证失败时，回退到上一个供应商，并记录切换失败原因
任务：供应商切换作为自愈动作之一，可关联告警规则（Phase 3.1 已覆盖）

3.4.5 供应商健康看板

任务：路由 /ops/dashboard/suppliers 显示供应商健康一览
任务：卡片展示：今日切换次数 / 当前不可用供应商数 / 各供应商平均延迟 / 各供应商错误率
任务：表格展示所有供应商：名称 / 健康状态 / 最后探针时间 / 平均延迟 / 24h 成功率 / 可用模型数
任务：支持按健康状态筛选（全部 / 健康 / 延迟高 / 不可用）

3.4.6 参考 FreeRide 的非破坏性配置更新

任务：供应商配置更新采用原子替换策略：写临时文件 → 验证 → 原子替换
任务：防止配置损坏导致系统不可用
任务：配置更新前先在内存中验证 JSON Schema，不合法则拒绝更新

16 KiB Raw Permalink Blame History Unescape Escape

AI-Ops 功能清单（模块级）

Phase 1：监控看板 + 日志查询（不触发自动动作）

模块 1.1：监控首页

1.1.1 首页基础布局

1.1.2 指标数据获取

1.1.3 指标下钻

模块 1.2：日志查询

1.2.1 日志查询页

1.2.2 日志结果展示

1.2.3 日志查询性能

Phase 2：告警规则引擎 + 通知渠道（告警只通知，不执行自愈）

模块 2.1：告警规则管理

2.1.1 告警规则列表页

2.1.2 创建/编辑告警规则

2.1.3 告警规则引擎（后端）

模块 2.2：告警事件与处置

2.2.1 告警事件列表

2.2.2 告警集群聚合

模块 2.3：通知渠道配置

2.3.1 通知配置页

2.3.2 通知发送后端

Phase 3：自愈引擎 + 审计回滚

模块 3.1：自愈规则配置

3.1.1 自愈规则创建

3.1.2 自愈执行后端

3.1.3 自愈级联失败处理

模块 3.2：配置审计

3.2.1 审计日志查询页

3.2.2 审计后端

模块 3.3：配置回滚

3.3.1 回滚操作入口

3.3.2 回滚后端

Phase 4：容量主板与高级分析

模块 4.1：容量视图

4.1.1 容量主页

4.1.2 容量数据后端

全局模块

模块 G1：认证与权限

模块 G2：健康检查

模块 G3：OpenAPI 文档

技术基础设施（各 Phase 共享）

T1：项目骨架

T2：单元测试骨架

T3：IntegrationPlugin 接口

任务估算汇总

模块 3.4：供应商智能切换（参考 FreeRide 思路）

3.4.1 供应商质量监控

3.4.2 供应商 Fallback 链管理

3.4.3 智能切换策略

3.4.4 供应商切换执行

3.4.5 供应商健康看板

3.4.6 参考 FreeRide 的非破坏性配置更新

16 KiB

Raw Permalink Blame History