AIRegulation/aiops-docs

Fork 0

Files

guangfei.zhao 3c1c40a2a2 add platform and tools docs

2026-03-31 09:41:03 +08:00

13 KiB

Raw Blame History

AIOps Platform Requirements

1. 文档目标

本文档用于定义 aiops-platform 项目的职责边界、MVP 范围、核心对象模型、主要页面能力、接口要求与非功能要求。

本文档重点回答以下问题：

aiops-platform 在三层架构中究竟负责什么。
平台层为什么必须作为唯一主控层存在。
MVP 阶段平台必须先交付哪些核心能力。
平台如何与 aiops-workflow 和 aiops-tools 协同。

本文档是平台层的正式需求清单，和 workflow/、tools/ 下的文档共同构成当前架构的三层需求基线。

2. 项目定位

2.1 核心定义

aiops-platform 负责“事件如何流转、谁来审批、结果如何展示”。

它是整个系统的唯一主控层，持有核心业务状态，负责对事件、Incident、审批、执行、审计和展示进行统一编排。

平台层的核心职责是：

接收并管理 Incident 主流程
维护 Incident 生命周期与状态机
触发 aiops-workflow 获取结构化 RCA 和动作建议
调用 aiops-tools 执行查询代理和受控动作
提供页面、接口、审计、审批、时间线与运营视图

2.2 不负责的事情

aiops-platform 明确不负责：

具体 AI 工作流编排细节
Prompt 管理、RAG 检索策略管理
直接对接底层 Prometheus / Loki / K8s / Ansible 协议
直接持有工具查询逻辑和执行器实现细节

2.3 为什么平台层必须独立

平台层必须独立存在，原因在于：

Incident 主状态不能放在 workflow 层
审批和执行控制不能放在 AI 层
页面与业务对象不能散落在工具层
审计、时间线、审批、展示必须有统一业务中枢

如果没有独立平台层，系统会很快变成：

状态分散
页面和业务逻辑耦合不清
AI 建议与真实执行缺少边界
审计链路断裂

3. 与其他两层的边界关系

3.1 与 `aiops-workflow` 的关系

平台层调用 aiops-workflow 获取：

结构化 RCA
证据链
影响范围
动作建议

但平台层始终保留以下控制权：

Incident 状态是否推进
动作是否展示
动作是否需要审批
动作是否允许执行

3.2 与 `aiops-tools` 的关系

平台层调用 aiops-tools 获取：

受控查询结果
动作执行结果
工具调用与执行审计关联信息

但平台层始终保留以下业务控制：

谁可以发起执行
哪些动作需要审批
哪些结果进入时间线
哪些数据进入页面展示和 KPI 统计

3.3 平台层的绝对职责

只有平台层应当持有以下对象的业务主状态：

incident
incident_timeline
ai_rca_result
remediation_action
approval_record
audit_log

4. 目标用户

4.1 一线响应人

NOC / L1 值班人员
SRE / 运维工程师
应用负责人

核心诉求：

快速看到当前事件
快速进入 Incident 详情
快速理解 RCA、影响和建议动作
快速执行或提交审批

4.2 高级响应人与负责人

L2 / L3 工程师
Incident Commander
运维负责人

核心诉求：

管理重大 Incident
分配责任人
查看完整时间线
审核执行动作和审批状态

4.3 安全与审计角色

安全管理员
审批人
审计人员

核心诉求：

看到谁提了什么动作
看到谁审批了什么动作
看到执行结果与回滚入口
看到完整可追踪审计链路

5. MVP 成功标准

MVP 阶段，平台层至少应达到以下结果：

能形成统一 Incident 主流程。
能稳定维护 Incident 状态机。
能展示结构化 RCA 与动作建议。
能对动作执行进行审批与控制。
能沉淀统一 Timeline 与审计记录。
能输出基础运营指标。

建议的 MVP 指标：

指标	说明	MVP 目标
Incident creation success rate	Incident 创建成功率	高于 99%
Timeline completeness	时间线事件沉淀完整率	100%
Approval trace completeness	审批链可追踪率	100%
RCA display availability	RCA 展示可用率	高于 99%
Action execution traceability	动作执行可回溯率	100%
Dashboard data availability	指标看板可用率	高于 99%

6. 范围边界

6.1 MVP 必须范围

Incident API
Incident 状态机
事件列表页
Incident 详情页
Timeline
RCA 结果展示卡
动作建议展示与执行面板
审批流基础能力
审计中心基础能力
KPI / Dashboard 基础能力

6.2 MVP 可选增强

更强的筛选与搜索
更丰富的批量操作
更细粒度的角色与权限视图
通知中心
Postmortem 入口联动

6.3 明确不在 MVP

完整 CMDB 平台
完整 ITSM / 工单替代
高复杂度多租户商业化后台
深度 AI 配置管理界面
复杂可视化编排中心

7. 核心设计原则

平台层是唯一主控层
状态和展示必须统一归平台持有
AI 结果必须结构化接入平台
执行动作必须经过平台确认或审批
所有关键操作都要进入 Timeline 和审计
页面围绕 Incident 主流程组织，而不是围绕底层技术组件组织

8. 核心对象模型

建议平台层至少围绕以下对象建模：

对象	说明	关键字段
`Incident`	主事件实体	incident_id, title, status, severity, service, owner
`IncidentTimeline`	时间线事件	incident_id, event_type, payload, operator
`IncidentContext`	事件上下文摘要	service, env, topology, recent_changes
`AIRCAResult`	AI 诊断结果	conclusion, confidence, impact_scope, evidence
`RemediationAction`	建议动作或待执行动作	action_id, risk, mode, approval
`ApprovalRecord`	审批记录	approval_id, approver, status, comment
`AuditLog`	审计记录	trace_id, actor, resource, operation, result
`DashboardMetric`	指标聚合对象	metric_name, value, time_range

9. MVP 功能需求

9.1 Incident API

9.1.1 能力目标

平台层必须作为 Incident 的统一入口和唯一事实来源。

9.1.2 基础能力

创建 Incident
查询 Incident
更新 Incident 状态
关闭 Incident
重开 Incident
触发诊断
追加时间线事件

9.1.3 验收标准

Incident 状态只能通过平台层接口变更。
所有状态变更都能被审计。
Incident 可以和 AI 结果、审批、执行记录关联。

9.2 Incident 状态机

9.2.1 推荐状态

new
triaged
diagnosing
remediating
resolved
closed

9.2.2 必须能力

校验合法状态跳转
拒绝非法状态变更
状态变更写入时间线
状态变更写入审计

9.2.3 验收标准

平台能明确控制状态机流转。
不能绕过平台直接改 Incident 主状态。

9.3 事件列表页

9.3.1 页面目标

这是平台的主入口，用于让用户快速掌握当前故障状态。

9.3.2 必须展示内容

Incident 标题
状态
严重级别
服务
责任人
开始时间
最近更新时间
是否有 RCA
是否有待审批动作

9.3.3 必须操作

筛选
搜索
进入详情页
快速确认接手或关闭

9.4 Incident 详情页

9.4.1 页面目标

这是平台最核心的业务页面，应承载大部分响应、诊断查看、审批和执行入口。

9.4.2 页面模块建议

基础信息卡
状态与责任人
RCA 卡片
证据链引用
影响范围
动作建议与执行面板
Timeline
审批记录
审计摘要

9.4.3 必须操作

变更状态
触发诊断
查看和刷新 RCA
发起审批
执行动作
查看执行结果

9.5 RCA 展示模块

9.5.1 平台职责

平台层不负责生成 RCA，但必须负责承接、展示和落库 aiops-workflow 返回的结构化结果。

9.5.2 必须展示内容

诊断结论
置信度
影响范围
证据链
建议动作列表

9.5.3 验收标准

平台无需解析自由文本即可展示核心结果。
低置信度结果有明确提示。

9.6 动作建议与执行控制台

9.6.1 平台职责

平台层负责展示建议动作，并决定这些动作是：

仅展示
需要审批
可以执行

9.6.2 必须展示内容

动作名称
风险等级
模式 auto | approval | suggest_only
当前审批状态
当前执行状态
回滚入口提示

9.6.3 必须操作

提交审批
审批通过 / 驳回
执行动作
查看执行结果

9.6.4 验收标准

平台能统一展示动作清单。
平台能和 aiops-tools 的执行结果正确关联。
高风险动作不会绕过平台控制直接执行。

9.7 审批流

9.7.1 MVP 范围

平台层需要有基础审批能力，但不必一开始就做复杂 BPM 引擎。

9.7.2 必须能力

为动作创建审批请求
指定审批人
审批通过
审批驳回
记录审批意见
审批记录进入 Timeline 和审计

9.7.3 验收标准

动作执行前能校验审批状态。
审批记录可在 Incident 详情页查看。

9.8 Incident Timeline

9.8.1 目标

Timeline 是平台层的关键基础设施，是 Incident 回放、审计联动和复盘的核心数据源。

9.8.2 必须进入 Timeline 的事件

Incident 创建
状态变更
诊断触发
RCA 结果写入
动作建议更新
审批发起
审批通过 / 驳回
执行动作
执行成功 / 失败
Incident 关闭 / 重开

9.8.3 验收标准

关键动作不会遗漏时间线记录。
Timeline 可作为 Incident 回放依据。

9.9 审计中心

9.9.1 平台职责

平台层负责持有业务主审计记录，并与工具层、workflow 层的执行记录关联。

9.9.2 必须支持

按 incident_id 查询
按操作人查询
按动作类型查询
按时间范围查询
导出审计结果

9.9.3 必须记录内容

操作人
资源对象
操作类型
请求摘要
结果摘要
时间
trace 关联信息

9.10 Dashboard 与 KPI

9.10.1 MVP 范围

平台层需要提供最基础的运营指标视图。

9.10.2 建议指标

Incident 数量趋势
MTTA
MTTR
RCA 可用率
动作执行成功率
审批通过率
自动恢复率

9.10.3 目标用户

运维负责人
团队负责人
项目管理者

10. 页面与信息架构建议

10.1 首批页面建议

Incident List
Incident Detail
Action Review Panel
Audit Center
Dashboard

10.2 页面组织原则

Incident 是主导航中心
RCA 和动作展示贴着 Incident 展开
审批和执行入口贴着动作展开
审计与 Dashboard 属于辅助管理视角

11. 与 `workflow` 的接口要求

11.1 触发诊断

平台需要能向 aiops-workflow 发起诊断请求。

建议接口语义：

POST /api/v1/incidents/{incident_id}/diagnose

11.2 查询任务结果

平台需要支持异步拿回任务结果。

建议接口语义：

GET /api/v1/ai/tasks/{task_id}

11.3 平台侧处理要求

平台负责把 workflow 返回结果落库
平台负责把 workflow 返回结果映射到页面对象
平台负责把关键结果写入 Timeline

12. 与 `tools` 的接口要求

12.1 查询类能力

平台可在必要时通过平台代理方式调用工具层，但不建议平台散落直接调用底层系统。

12.2 执行类能力

平台需要通过 aiops-tools 发起执行请求，并接收结构化结果。

建议接口语义：

POST /api/v1/incidents/{incident_id}/actions/{action_id}/execute

12.3 平台侧处理要求

校验审批状态
校验执行条件
接收执行结果
写入 Timeline 和审计

13. 非功能要求

13.1 安全性

高风险动作必须审批
审计日志完整留痕
权限分层明确

13.2 可用性

Incident 主流程高可用
查询与展示路径稳定
关键详情页响应可接受

13.3 可维护性

业务对象清晰
与 workflow/tools 边界清晰
平台逻辑不要下沉到工具层或 AI 层

13.4 可扩展性

可增加更多 Dashboard 视图
可增加更多审批规则
可增加更多动作类型与展示模块

14. 分阶段实施建议

Phase 1

Incident API
Incident 状态机
Incident List / Detail 基础页
RCA 展示卡
Timeline

Phase 2

动作建议展示
执行控制台
基础审批流
基础审计中心

Phase 3

Dashboard
更强的筛选与检索
更强的审批与审计能力
和 Postmortem / Knowledge 回流联动

15. 推荐的仓库内文档与资产结构

如果后续 aiops-platform 独立成仓，可参考如下结构：

platform/
  AIOps_Platform_Requirements.md
  pages/
  api-contracts/
  state-machine/
  approval/
  audit/

16. 结论

aiops-platform 的本质不是一个“展示层前端 + 普通后端 API”，而是整个系统的业务主控中枢。

如果 aiops-workflow 负责“如何做诊断”，aiops-tools 负责“如何安全地查和做”，那么 aiops-platform 负责的就是：

事件如何进入主流程
状态如何被维护
RCA 如何被承接和展示
动作如何被审批和执行
所有结果如何进入时间线与审计

因此，平台层的第一优先级不是做最复杂的 AI 管理后台，而是先把以下主链路做稳：

Incident
状态机
RCA 承接
动作审批执行
Timeline
Audit

只有这条业务主链路稳住，workflow 和 tools 的价值才能真正落地。

13 KiB Raw Blame History Unescape Escape

AIOps Platform Requirements

1. 文档目标

2. 项目定位

2.1 核心定义

2.2 不负责的事情

2.3 为什么平台层必须独立

3. 与其他两层的边界关系

3.1 与 aiops-workflow 的关系

3.2 与 aiops-tools 的关系

3.3 平台层的绝对职责

4. 目标用户

4.1 一线响应人

4.2 高级响应人与负责人

4.3 安全与审计角色

5. MVP 成功标准

6. 范围边界

6.1 MVP 必须范围

6.2 MVP 可选增强

6.3 明确不在 MVP

7. 核心设计原则

8. 核心对象模型

9. MVP 功能需求

9.1 Incident API

9.1.1 能力目标

9.1.2 基础能力

9.1.3 验收标准

9.2 Incident 状态机

9.2.1 推荐状态

9.2.2 必须能力

9.2.3 验收标准

9.3 事件列表页

9.3.1 页面目标

9.3.2 必须展示内容

9.3.3 必须操作

9.4 Incident 详情页

9.4.1 页面目标

9.4.2 页面模块建议

9.4.3 必须操作

9.5 RCA 展示模块

9.5.1 平台职责

9.5.2 必须展示内容

9.5.3 验收标准

9.6 动作建议与执行控制台

9.6.1 平台职责

9.6.2 必须展示内容

9.6.3 必须操作

9.6.4 验收标准

9.7 审批流

9.7.1 MVP 范围

9.7.2 必须能力

9.7.3 验收标准

9.8 Incident Timeline

9.8.1 目标

9.8.2 必须进入 Timeline 的事件

9.8.3 验收标准

9.9 审计中心

9.9.1 平台职责

9.9.2 必须支持

9.9.3 必须记录内容

9.10 Dashboard 与 KPI

9.10.1 MVP 范围

9.10.2 建议指标

9.10.3 目标用户

10. 页面与信息架构建议

10.1 首批页面建议

10.2 页面组织原则

11. 与 workflow 的接口要求

11.1 触发诊断

11.2 查询任务结果

11.3 平台侧处理要求

12. 与 tools 的接口要求

12.1 查询类能力

12.2 执行类能力

12.3 平台侧处理要求

13. 非功能要求

13.1 安全性

13.2 可用性

13.3 可维护性

13.4 可扩展性

13 KiB

Raw Blame History

3.1 与 `aiops-workflow` 的关系

3.2 与 `aiops-tools` 的关系

11. 与 `workflow` 的接口要求

12. 与 `tools` 的接口要求