462 lines
25 KiB
Markdown
462 lines
25 KiB
Markdown
# 智能运维系统 PRD
|
||
|
||
> 版本：v1.0
|
||
> 负责人：PM
|
||
> 目标读者：TechLead、QA、SRE、运营人员
|
||
> 状态：待 TechLead 评审
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
### 一句话价值
|
||
通过自动化监控、告警辅助决策、故障自愈与配置变更管理，将立交桥平台的运维从人工排查转为机器主导的实时保障，降低 MTTR、减少人工成本、提升运行稳定性。
|
||
|
||
### 用户问题
|
||
1. 当前运维严重依赖人工定期检查日志，问题发现与处置耗时过长，MTTR 超过 30 分钟。
|
||
2. 告警规则缺乏分类与阈值动态调整，导致要么漏告警、要么误告警爆炸。
|
||
3. 故障发生时无自动恢复机制，必须等待运维人员手动参与，产生可避免的服务中断。
|
||
4. 配置变更无审计追溯能力，回滚窗口不明确，引发过多次生产故障。
|
||
5. 规模扩张中缺乏量化的容量管理视角，出现无计划的资源短缺。
|
||
|
||
### 业务意义
|
||
- 从 Demo 级运维向生产级运维过渡，建立可重复、可审计、可回滚的运维体系。
|
||
- 在人员规模不增的前提下，支撑接入商家数、API 调用量与 Token 数量级的增长。
|
||
|
||
---
|
||
|
||
## 2. 目标
|
||
|
||
### 业务目标
|
||
1. 将平台核心故障 MTTR 从 >30min 压缩至 <10min。
|
||
2. 自动化处理覆盖 P1/P2 级告警事件的 60%以上（含自愈和故障匿离）。
|
||
3. 告警噪声率降低至 5% 以下（误告警 / 总告警数）。
|
||
4. 实现 100% 生产配置变更的审计追溯，回滚时间窗口 <5min。
|
||
|
||
### 用户目标
|
||
| 用户 | 目标 |
|
||
|---|---|
|
||
| SRE | 不再 7x24 手动守候日志，告警可触达、可分类、可动作化 |
|
||
| 运营人员 | 缺陷发现后能在同一平台完成定位、分析、处置，无需切换多套工具 |
|
||
| 平台管理员 | 对任何配置变更能看到影响范围、执行记录、快速回滚能力 |
|
||
| 技术负责人 | 获取量化的运维健康度指标，支撑容量与稳定性决策 |
|
||
|
||
### 成功定义
|
||
- 必要条件：运维主控台可访问、监控数据可查、告警规则可配。
|
||
- 充分条件：自愈规则生效、告警噪声率 <5%、审计日志完整。
|
||
- 失败判定：开发期间任何一周内告警噪声率 >20%或自愈规则误触发导致生产事故，即判定失败。
|
||
|
||
---
|
||
|
||
## 3. 范围
|
||
|
||
### In Scope
|
||
1. 立交桥平台本身的运行时监控（不含下游大模型服务），包含但不限于：
|
||
- gateway/ 请求量、延迟、错误率、降级/稳定性规则命中率
|
||
- supply-api/ 供应商健康状态与审计异常
|
||
- platform-token-runtime/ 令牌耗尽、资源约束触发、异常恢复周期
|
||
2. 告警规则引擎：多维度阈值、分级告警（P0/P1/P2/P3）、告警抑制与聚合。
|
||
3. 故障自愈引擎：自动重启、切换路由、限流、隔离异常节点。
|
||
4. **供应商智能切换（In Scope）**：含供应商健康探测、故障时的多级 Fallback 切换、策略化路由调度、切换后的健康状态监测与回滚。
|
||
5. 配置管理与审计：配置变更审计日志、版本化、回滚。
|
||
6. 容量视图：以 Token 数量、QPS、响应延迟、资源利用率为核心指标的容量主板。
|
||
7. 日志/指标查询与下钻：支持按时间范围、服务、错误码、用户维度筛选。
|
||
|
||
### Out of Scope
|
||
1. 下游大模型服务的监控与告警（如 OpenAI、Claude 本身的稳定性）。
|
||
2. 基础设施层监控（如物理机器 CPU/内存/磁盘，由云厂商或 Prometheus Node Exporter 覆盖）。
|
||
3. **AI 负载预测/自动规模扩缩（本阶段仅提供容量视图与阈值提示，不做自动扩容决策）。**
|
||
- 供应商智能切换（如故障时切换到备用供应商）属于故障应对策略，In Scope。
|
||
- 自动规模扩缩（如 K8s HPA 类似的自动扩缩容决策）属于资源调度策略，Out of Scope。
|
||
4. 外部监控系统（如 Datadog、New Relic）的整合，仅提供标准 Prometheus 格式接口供自取。
|
||
|
||
### 假设与依赖
|
||
1. 假设已有 Prometheus 或类似时序数据库存储指标，可接受定期 PromQL 查询。
|
||
2. 假设平台日志已统一格式化，可通过标准化查询接口读取。
|
||
3. 假设 gateway/internal/metrics/ 与 gateway/internal/alert/ 现有模块的接口契约在本项目中可延续或克隆。
|
||
4. 依赖 supply-api/ 的供应商健康检查接口与审计日志接口。
|
||
5. 依赖 platform-token-runtime/ 的运行时状态与异常恢复状态接口。
|
||
|
||
---
|
||
|
||
## 4. 用户场景
|
||
|
||
### 主流程
|
||
|
||
#### 场景 A：监控实时看板查看平台健康状态
|
||
1. SRE 登录运维主控台。
|
||
2. 首页展示实时 QPS、平均延迟、P99 延迟、错误率、活跃供应商数量、异常告警数量。
|
||
3. SRE 点击任意指标卡片，下钻至分钟级趋势图与按服务/路径/供应商的分布。
|
||
4. 如果某指标超过预设阈值，卡片变红并显示最近 3 条相关告警摘要。
|
||
|
||
#### 场景 B：配置审计与回滚
|
||
1. 平台管理员修改供应商接口地址或路由规则。
|
||
2. 系统自动记录操作人、操作前后值、时间戳、IP 地址，并生成唯一审计 ID。
|
||
3. 管理员可以在审计日志中搜索该变更。
|
||
4. 发现变更引发异常后，管理员在审计页面选择该记录执行回滚，系统在 60 秒内恢复原值并验证恢复后状态。
|
||
|
||
#### 场景 C：告警接收与处置
|
||
1. 监控引擎检测到 P1 告警触发条件（如某供应商错误率 >10%持续 2min）。
|
||
2. 告警在 30 秒内通过配置的通知渠道（Webhook/邮件/飞书/企业微信）发送给负责人。
|
||
3. 自愈引擎判断该 P1 告警是否存在已配置自愈动作：
|
||
- 若有：执行自愈（如切换备用供应商、限流、重启异常实例），并在事件中记录动作结果。
|
||
- 若无：仅发送通知，等待人工处理。
|
||
4. SRE 在控台中对该告警进行确认/忽略/规避，并填写处置结果。
|
||
5. 告警事件自动关闭或转为持续告警，根据反馈调整当前期的实时效果。
|
||
|
||
### 异常流程
|
||
|
||
#### 场景 D：自愈动作失败
|
||
1. 自愈引擎尝试执行自愈动作（如切换供应商接口）。
|
||
2. 动作执行失败（API 返回非 200 或超时）。
|
||
3. 系统在 10 秒内尝试重试 1 次，若仍失败，停止自动尝试并升级为 P0 人工告警（电话/短信）。
|
||
4. 记录失败原因与日志，保留事件状态供人工排查。
|
||
|
||
#### 场景 E：告警飙升（波浪式告警）
|
||
1. 某基础故障导致成百上千个服务实例同时触发告警。
|
||
2. 告警引擎检测到同一资源/服务在 1 分钟内触发 >20 条告警。
|
||
3. 自动触发聚合：生成一条 "集群告警"，将细节收拢为附件，停止单条通知爆炸。
|
||
4. SRE 在控台中批量确认/忽略/属于同一根因的告警。
|
||
|
||
#### 场景 F：回滚失败
|
||
1. 管理员发起回滚。
|
||
2. 回滚目标值已被后续修改覆盖（关联记录不存在或已被删除）。
|
||
3. 系统拒绝执行，返回明确错误码 `OPS_AUD_4101`（回滚目标不存在）。
|
||
4. 记录回滚失败事件，告警通知技术负责人。
|
||
|
||
### 边缘流程
|
||
|
||
#### 场景 G：无人处理的持续告警
|
||
1. P2 告警持续 2 小时未被确认。
|
||
2. 系统自动将该告警升级为 P1，并通知上级负责人。
|
||
|
||
#### 场景 H：监控数据源丢失
|
||
1. 指标采集器在 5 分钟内未收到任何新数据点。
|
||
2. 控制台显示 "数据源丢失"标识，不显示过期数据，触发 P2 级别的内部告警。
|
||
3. 恢复后自动补入缺失时段的空值标记，不伪造数据。
|
||
|
||
#### 场景 I：运维人员误触发配置变更
|
||
1. 管理员提交一个将某供应商日请求上限从 10000 降为 10 的变更。
|
||
2. 系统检测到该变更带来的影响面 > 预设阈值（比如触发将导致 90% 流量被拒绝）。
|
||
3. 在审计日志中标记该变更为 "高风险"，并在执行前弹窗警告管理员需要二次确认。
|
||
|
||
### 用户故事
|
||
|
||
- 作为 SRE，我希望在午夜收到有效告警而不是噪音，以便在 10 分钟内完成定位和处置，避免影响生产。
|
||
- 作为运营人员，我希望能在同一个控制台查看所有服务的健康状态和日志，而不需要登录多套系统。
|
||
- 作为平台管理员，我希望任何配置变更都有日志和回滚能力，让我在发生问题时能快速恢复而不会黄乱找原始值。
|
||
- 作为技术负责人，我希望看到量化的运维健康指标，以便在要求增量资源时有数据支撑。
|
||
|
||
---
|
||
|
||
## 5. 验收标准（AC）
|
||
|
||
### AC-1 实时监控看板
|
||
- 当访问运维主控台时，首页加载时间 <2s。
|
||
- 首页必须显示以下 6 个指标数值：当前 QPS、平均响应延迟(ms)、P99 响应延迟(ms)、5xx 错误率(%)、活跃供应商数量、未关闭告警数量。
|
||
- 每个指标卡片需在数据更新后 15s 内刷新显示。
|
||
|
||
### AC-2 指标下钻
|
||
- 点击任何指标卡片后，页面展示该指标过去 1 小时的分钟级趋势图。
|
||
- 趋势图支持按 `service`（gateway/supply-api/platform-token-runtime）、`path`（URL path）、`supplier`（供应商 ID）维度下钻分割。
|
||
- 下钻结果查询时间 <3s。
|
||
|
||
### AC-3 告警规则配置
|
||
- 控制台支持创建、编辑、启用、禁用告警规则。
|
||
- 单条规则必须包含：规则名称、监控指标、阈值类型（>、<、=、匹配正则）、持续时间(min)、级别（P0/P1/P2/P3）、通知渠道。
|
||
- 规则变更后 30s 内生效，无需重启服务。
|
||
- 最少支持同时运行 50 条告警规则。
|
||
|
||
### AC-4 告警通知触达
|
||
- P0/P1 级告警必须在触发后 30s 内完成通知发送。
|
||
- P2 级告警必须在 120s 内完成通知发送。
|
||
- 通知渠道必须支持 Webhook、邮件、飞书/企业微信至少 2 种。
|
||
- 通知模板必须包含：告警级别、规则名称、触发时间、当前值、阈值、事件 ID、查看链接。
|
||
|
||
### AC-5 告警聚合与抑制
|
||
- 当同一资源/服务在 1 分钟内触发 >20 条告警时，系统必须自动生成 1 条集群告警，停止单条通知爆炸。
|
||
- 集群告警的通知内容必须包含：累计数量、涉及规则列表、时间范围。
|
||
- 抑制周期：同一规则同一目标在 5 分钟内只发送 1 次告警（除非级别升级）。
|
||
|
||
### AC-6 自动自愈
|
||
- 系统必须支持为每个告警规则配置可选的自愈动作：无、切换备用路由、限流、重启实例、触发程序化脚本。
|
||
- 自愈动作必须在告警触发后 60s 内执行完成（含重试 1 次的时间）。
|
||
- 自愈执行结果（成功/失败/拒绝）必须记录在告警事件中。
|
||
- 自愈动作触发后，监控必须在 2 分钟内评估是否解除告警条件，若未解除则升级为人工告警。
|
||
|
||
### AC-7 配置审计日志
|
||
- 任何对生产配置的增、删、改操作必须在 1s 内生成审计日志记录。
|
||
- 审计日志必须包含：唯一 ID、操作人、操作类型、目标资源类型与 ID、操作前值(JSON)、操作后值(JSON)、时间戳(到毫秒)、IP 地址、请求 ID。
|
||
- 审计日志必须不可篡改，存储保留期 >=90 天。
|
||
- 控制台必须支持按时间范围、操作人、资源类型、关键词筛选查询，结果返回时间 <3s。
|
||
|
||
### AC-8 配置回滚
|
||
- 对于任何审计日志记录，只要目标资源仍存在且操作前值有效，必须支持执行回滚。
|
||
- 回滚执行时间必须 <60s，并在执行前显示所有会被覆盖的子资源列表。
|
||
- 回滚必须生成新的审计记录，关联原始操作 ID。
|
||
- 回滚失败时必须返回明确错误码，不得静默失败。
|
||
|
||
### AC-9 容量主板
|
||
- 容量主板必须显示过去 7 天的 Token 数量、QPS、P99 延迟、各供应商资源利用率趋势。
|
||
- 必须对每个服务标出当前负载等级：正常/警告/过载，判定依据可配置阈值。
|
||
- 提供 "按当前增长率预测触达资源上限时间"的算法结果（仅供参考，不自动执行扩容）。
|
||
|
||
### AC-10 日志/指标查询
|
||
- 控制台必须支持按时间范围、服务名称、HTTP 状态码、错误码、用户 ID、供应商 ID、关键词筛适日志。
|
||
- 日志查询结果支持分页，单页最大 100 条，首页返回时间 <3s。
|
||
- 支持将日志结果导出为 CSV 文件，单次导出上限 10000 条。
|
||
|
||
### AC-11 监控数据保存
|
||
- 原始指标数据必须保留 >=7 天，用于短期查询与告警评估。
|
||
- 分钟级聚合数据必须保留 >=30 天，用于趋势分析。
|
||
- 小时级聚合数据必须保留 >=90 天，用于容量规划与月度报告。
|
||
|
||
### AC-12 角色与权限
|
||
- 必须支持以下角色及其基本权限控制：
|
||
- 查看者：可查看监控看板、日志、告警事件，不可修改配置。
|
||
- 运维人员：可确认/忽略/规避告警，可管理告警规则，不可执行回滚。
|
||
- 管理员：可执行所有操作，包括回滚与高风险变更确认。
|
||
|
||
---
|
||
|
||
## 6. 边缘情况与失败路径
|
||
|
||
| 编号 | 边缘/失败场景 | 系统行为 | 人工介入时机 |
|
||
|---|---|---|---|
|
||
| F-1 | 自愈动作重试均失败 | 停止自动尝试，升级为 P0 人工告警 | 立即，电话/短信通知 |
|
||
| F-2 | 告警通知渠道失效（如 Webhook 8xx/5xx） | 记录发送失败，使用备用渠道（邮件→飞书→短信） | 三次切换后仍失败，通知 TechLead |
|
||
| F-3 | 回滚目标已不存在 | 拒绝回滚，返回错误码 `OPS_AUD_4101` | 需要运维人员手动修复或联系开发人员 |
|
||
| F-4 | 指标采集器连续 5min 无数据 | 显示数据源丢失标识，触发内部 P2 告警 | 检查采集器/网络/存储状态 |
|
||
| F-5 | 审计日志存储满盘/写入失败 | 丢弃非关键字段或改为异步上报，不阻断业务操作 | 存储计量触发预警，SRE 扩容或清理 |
|
||
| F-6 | 自愈动作触发后形成级联故障（如切换路由后导致新节点故障） | 自动恢复上一步操作前的状态（回退），然后升级为人工告警 | 立即，电话通知 |
|
||
| F-7 | 监控数据库丢失（全面中断） | 控制台进入只读/降级模式，告警引擎依赖本地缓存持续运行 | 立即，检查存储层 |
|
||
| F-8 | 实时看板指标计算结果超时 | 显示上次成功结果并标注时间戳，不等待当前请求 | 检查查询引擎性能或检索时间范围 |
|
||
|
||
---
|
||
|
||
## 7. 上线与运营准备
|
||
|
||
### 发布策略
|
||
- 阶段 1：监控看板 + 日志/指标查询。只提供可视化，不触发任何自动动作。
|
||
- 阶段 2：告警规则引擎 + 通知渠道，告警只通知、不执行自愈。
|
||
- 阶段 3：自愈引擎 + 审计回滚。
|
||
- 阶段 4：容量主板与高级分析。
|
||
|
||
### 灰度与回滚
|
||
- 每个阶段必须在单个可控集群部署 >=72h，无 P1 以上告警才进入下一环境。
|
||
- 自愈规则必须通过 "沙盒模式"验证：先在非生产环境模拟触发 10 次以上，确认动作结果符合预期后才允许关联生产告警规则。
|
||
- 回滚能力必须在发布前进行 1 次演练，涉及至少 3 个不同资源类型。
|
||
- 如阶段 3 中自愈规则出现误触发导致生产事故，立即停用自愈引擎（通过权限开关），所有告警退化为仅通知模式。
|
||
|
||
### 埋点与监控
|
||
- 必须实现以下事件埋点：
|
||
- `运维控制台页面加载`、`指标下钻`、`日志查询执行`、`告警规则创建/编辑/删除`、`告警确认/忽略/规避`、`自愈动作执行`、`自愈失败`、`回滚执行`、`回滚失败`。
|
||
- 必须对自身监控层（指标采集器、告警引擎、通知发送器）进行健康检查，检查失败时触发内部 P2 告警。
|
||
|
||
### FAQ（预先准备）
|
||
| 问题 | 答案 |
|
||
|---|---|
|
||
| 告警通知没收到怎么办？ | 检查通知渠道配置中的接收地址/密钥；检查通知日志中的发送结果与失败原因。 |
|
||
| 自愈动作为什么没有触发？ | 确认规则中已开启自愈动作并选择了具体动作；确认沙盒测试已通过。 |
|
||
| 回滚为什么报错 `OPS_AUD_4101`？ | 该配置在变更后已被删除或覆盖，无法找到操作前状态，需要手动恢复。 |
|
||
| 数据看板为什么卡住？ | 检查页面顶部是否有 "数据源丢失"标识；尝试缩小时间范围或筛选条件。 |
|
||
| 如何避免误触发自愈规则？ | 在非生产环境测试自愈规则 10 次以上并验证结果正确后才关联生产告警规则。 |
|
||
|
||
---
|
||
|
||
## 8. 商业化与价值闭环
|
||
|
||
### 收益路径
|
||
1. 内部效益：减少运维人员 7x24 值班压力，释放人力至产品功能开发。
|
||
2. 外部收益：提升平台 SLA 从 99.5% 至 99.9%，支撑企业客户签约与续费。
|
||
3. 成本节省：将运维人工时长每月减少 40% 以上，可量化计算为节省人力成本。
|
||
|
||
### 北极星指标
|
||
- 平台核心故障 MTTR（从 >30min 到 <10min）。
|
||
- 自动化处理覆盖率（目标 >=60%）。
|
||
- 告警噪声率（目标 <5%）。
|
||
|
||
### 失败判定线
|
||
- 上线 30 天内 MTTR 未下降至 <20min。
|
||
- 自动化覆盖率 <30%。
|
||
- 告警噪声率 >15%。
|
||
- 自愈规则误触发导致 1 次生产故障事件。
|
||
任意一项触发，即进入救援模式。
|
||
|
||
### 止损条件
|
||
- 自愈引擎误触发导致 2 次以上生产事故：立即锁定自愈功能，退回仅通知模式，启动事故复盘。
|
||
- 监控数据丢失超过 24h：停用依赖监控数据的自动化规则，级联退化至人工处理。
|
||
|
||
---
|
||
|
||
## 9. 依赖与风险
|
||
|
||
### 技术依赖
|
||
| 依赖 | 风险等级 | 备选方案 |
|
||
|---|---|---|
|
||
| Prometheus 或类似时序数据库 | 高 | 支持 VictoriaMetrics / Thanos 作为替代后端，提供存储适配层，不锁死单一存储 |
|
||
| 通知渠道（Webhook/邮件/飞书） | 中 | 必须支持多渠道且自动切换，单渠道不得作为唯一依赖 |
|
||
| 审计日志存储 | 中 | 主存储失败时转至本地文件缓存 + 异步上报，不阻断业务 |
|
||
| supply-api/ 审计接口 | 中 | 如接口不可用，运维平台自己写审计记录，后续补同步 |
|
||
|
||
### 业务风险
|
||
1. 自愈规则设计不当导致正常流量被掩断或重定向，影响客户请求。
|
||
2. 告警规则过于敏感或缺乏抑制，导致噪音爆炸，运营人员麻木对待真实故障。
|
||
3. 回滚操作不当导致配置状态更深层次的损坏，如回滚了一个依赖于新配置的下游变更。
|
||
4. 审计日志丢失导致故障定责和合规审查受阻。
|
||
|
||
### 缓解措施
|
||
1. 自愈规则必须经历 "沙盒模式"验证才能生效。
|
||
2. 所有自愈动作支持通过权限开关一键关闭，关闭后所有告警退化为仅通知。
|
||
3. 回滚执行前显示子资源影响范围，必须经二次确认。
|
||
4. 审计日志存储采用主备双写，存储期 >=90 天。
|
||
|
||
---
|
||
|
||
## 10. 技术栈与集成约束
|
||
|
||
### 统一技术栈
|
||
本项目必须与立交桥主项目保持一致：
|
||
- **语言**: Go 1.22+
|
||
- **HTTP框架**: 标准库 `net/http` + 自定义中间件（禁止引入 Gin/Echo 等第三方框架，保持与 gateway/ 和 supply-api/ 的一致性）
|
||
- **数据库**: PostgreSQL 15+ ，驱动 `jackc/pgx/v5`
|
||
- **缓存**: Redis，客户端 `redis/go-redis/v9`
|
||
- **配置**: YAML + Viper，环境变量覆盖敏感字段
|
||
- **日志/审计**: 结构化日志，审计事件模型与 supply-api/ 一致
|
||
- **错误码**: `{SOURCE}_{CATEGORY}_{CODE}` 格式，例如 `OPS_ALT_4001`
|
||
- **健康检查**: `/actuator/health` 、 `/actuator/health/live` 、 `/actuator/health/ready`
|
||
- **测试**: Go testing + testify，覆盖率门槛 domain ≥ 70%、service/handler ≥ 80%
|
||
|
||
### 独立运行与集成运行
|
||
本系统必须同时支持两种运行模式：
|
||
|
||
| 模式 | 特征 | 部署方式 | 适用场景 |
|
||
|------|------|---------|---------|
|
||
| **独立运行** | 自有 `cmd/ai-ops/main.go`，独立数据库 schema，独立 docker-compose | `docker-compose up` 或单独容器 | 外部用户只需要运维能力，不想接入立交桥全套 |
|
||
| **集成运行** | 作为 Go module 被 `gateway/` 或 `supply-api/` 引入，共享数据库连接池和配置，通过内部接口注册 | 编译时作为子模块编译，运行时挂载到立交桥主进程 | 立交桥用户希望获得一体化运维能力 |
|
||
|
||
**集成约束**:
|
||
- 独立运行时，系统必须提供完整的 HTTP API 和管理后台。
|
||
- 集成运行时，系统必须提供 `IntegrationPlugin` 接口，允许主程序通过配置开关启用/禁用各模块。
|
||
- 数据库 schema 必须使用独立的 `ai_ops_` 前缀，避免与主项目表名冲突。
|
||
- 配置文件必须支持分离加载：独立运行时读取自己的 `config.yaml`，集成运行时合并到主项目配置。
|
||
|
||
### NewAPI / Sub2API 适配支持
|
||
本系统的核心能力必须能够对接 NewAPI 和 Sub2API 系统：
|
||
- **监控数据推送**: 提供 Prometheus 格式的 `/metrics` 接口，NewAPI/Sub2API 可通过 Prometheus scrape 获取运维数据。
|
||
- **告警回调**: 支持 Webhook 告警通知，NewAPI/Sub2API 可配置接收本系统的告警事件。
|
||
- **自愈脚本扩展**: 自愈动作中的"触发程序化脚本"支持调用 NewAPI/Sub2API 的管理 API（如切换供应商、限流配置、重启实例）。
|
||
- **独立部署时**: 通过配置文件指定 NewAPI/Sub2API 的管理端点地址和鉴权信息，本系统通过适配层与之交互。
|
||
- **集成部署时**: 若立交桥 gateway/ 已接入 NewAPI/Sub2API，本系统通过 gateway/ 的内部路由接口操作上游状态。
|
||
|
||
### 对外接口契约
|
||
- 必须提供 OpenAPI 3.0 接口文档，确保 NewAPI/Sub2API 开发者可以独立接入。
|
||
- 接口路径前缀默认为 `/api/v1/ai-ops/`，集成运行时可通过配置改为 `/internal/ai-ops/` 。
|
||
|
||
---
|
||
|
||
## 11. 阶段门控结论
|
||
|
||
### 当前状态
|
||
- 需求范围已明确界定，In Scope / Out of Scope 清晰。
|
||
- 验收标准已精确到可测试粒度，包含时间、数值、错误码、状态等维度。
|
||
- 异常流程、边缘流程、失败路径已全面覆盖。
|
||
- 上线策略、灰度方案、回滚路径、埋点检查已明确。
|
||
- 技术栈与集成约束已明确（统一 Go 标准库、独立/集成双模式、NewAPI/Sub2API 适配）。
|
||
- 北极星指标与失败判定线已量化。
|
||
- 依赖与风险已识别，缓解措施已制定。
|
||
|
||
### 门控结论
|
||
可进入 TechLead 阶段。
|
||
|
||
> 备注：TechLead 阶段需要完成的事项
|
||
> 1. 确认现有 gateway/internal/metrics/ 与 gateway/internal/alert/ 的契约可延续性。
|
||
> 2. 确认存储层技术选型（Prometheus / VictoriaMetrics / 自建时序库）。
|
||
> 3. 确认通知渠道具体实现方案（Webhook / 飞书 / 邮件）。
|
||
> 4. 确认审计日志与回滚是否复用 supply-api/ 既有审计能力还是独立实现。
|
||
> 5. 确认角色权限体系是否复用平台统一认证系统。
|
||
|
||
---
|
||
|
||
## 自检清单
|
||
|
||
- [x] 已明确真实目标，不是只复述功能
|
||
- [x] 已写清 In Scope / Out of Scope
|
||
- [x] 每个 AC 都可被 QA 或测试用例直接验证
|
||
- [x] 已覆盖异常流、边缘流与失败路径
|
||
- [x] 已补齐上线、运营、监控、回滚要求
|
||
- [x] 已定义商业化/价值闭环
|
||
- [x] 已明确成功指标与失败判定线
|
||
- [x] 已明确当前可进入 TechLead 阶段
|
||
- [x] 没有使用"优化、支持、友好、尽量、快速"等模糊词替代明确要求
|
||
|
||
---
|
||
---
|
||
|
||
## 附：供应商智能切换（参考 FreeRide 思路）
|
||
|
||
### 背景
|
||
|
||
[FreeRide](https://github.com/openclaw/skills/tree/main/skills/shaivpidadi/free-ride) 是 OpenClaw 的一个 Skill 插件，核心功能：
|
||
- 实时拉取 OpenRouter 免费模型列表，按 ELO 评分排序
|
||
- 自动选择最强模型作为主模型
|
||
- 配置 5 个高质量备用模型作为 Fallback 链
|
||
- 主模型限速 → 自动切换下一个，用户无感知
|
||
- 非破坏性配置更新，只改 model 相关字段
|
||
|
||
FreeRide 的设计哲学（自动选择 + 智能降级）对 AI-Ops 的供应商切换场景有直接参考价值。
|
||
|
||
### 智能供应商切换 vs FreeRide
|
||
|
||
| 维度 | FreeRide | AI-Ops 供应商切换 |
|
||
|------|----------|-------------------|
|
||
| **目标用户** | 个人用户/极客 | 企业运维团队 |
|
||
| **模型来源** | OpenRouter 免费模型 | 多供应商中转 API |
|
||
| **核心价值** | 零成本用最强模型 | 供应商故障无感切换 |
|
||
| **Failover 粒度** | 模型级别 | 供应商级别 |
|
||
| **切换策略** | 固定轮询 | 成本优先/质量优先/延迟优先/手动 |
|
||
| **监控告警** | 无 | 多渠道告警 + 运维大盘 |
|
||
| **用量统计** | 无 | 成本分摊到部门/项目 |
|
||
| **自愈能力** | 仅切换 | 切换 + 通知 + 锁定 + 升级 |
|
||
|
||
### 供应商切换策略
|
||
|
||
| 策略 | 决策依据 | 适用场景 |
|
||
|------|----------|----------|
|
||
| **成本优先** | input_cost + output_cost 最低 | 预算敏感型业务 |
|
||
| **质量优先** | 最近 24h 成功率最高 | 高可用要求业务 |
|
||
| **延迟优先** | 最近 probe 响应时间最低 | 低延迟要求业务 |
|
||
| **手动** | 每次切换需人工确认 | 高风险变更管控 |
|
||
|
||
### 设计约束（继承 HLD）
|
||
|
||
- 切换后冷却期默认 300s，防止震荡（同一供应商反复切换）
|
||
- 每次切换写入审计日志（切换时间、原供应商、目标供应商、切换原因）
|
||
- 供应商配置更新采用原子替换（写临时文件 → 验证 → 原子替换），防止配置损坏
|
||
- 切换执行后立即验证新供应商可服务性，失败则回退并升级告警
|
||
|
||
### 参考实现
|
||
|
||
供应商探针任务（每 5 分钟执行）：
|
||
```go
|
||
type SupplierProbe struct {
|
||
SupplierID string `json:"supplier_id"`
|
||
ProbeAt time.Time `json:"probe_at"`
|
||
LatencyMs int `json:"latency_ms"`
|
||
ErrorRate float64 `json:"error_rate"` // 0.0~1.0
|
||
ELOHistory []float64 `json:"elo_history"` // 最近7天 ELO 趋势
|
||
}
|
||
```
|
||
|
||
供应商 Fallback 链配置：
|
||
```go
|
||
type SupplierChain struct {
|
||
Model string `json:"model"`
|
||
Primary string `json:"primary"` // 主供应商ID
|
||
Fallbacks []string `json:"fallbacks"` // 备用供应商列表（按优先级排序）
|
||
CooldownSec int `json:"cooldown_sec"` // 冷却秒数，默认300
|
||
Strategy string `json:"strategy"` // cost/quality/latency/manual
|
||
}
|
||
```
|
||
|