# AIOps 模块文档规划

> 更新：2026-07-05
> 目标：把 AIOps 的大模块沉淀成“其他项目看文档也能复刻”的工程文档，而不是零散功能说明。// Logan.Li

---

## 当前已拆清楚的文档域

| 文档域 | 目录 | 说明 |
|--------|------|------|
| AI Agent / Agent CLI | `docs/ai-agent/` | ReAct、工具调用、Evolver、安全确认、会话管理 |
| 客户端 Agent | `docs/client-agent/` | 主机采集、上报、任务轮询、安装升级 |
| 字符终端 | `docs/terminal/` | WebSSH、Pod exec、kubectl、Workspace、审计回放 |
| RDP 图形桌面 | `docs/rdp/` | 自研 RDP、剪贴板、RDPDR 虚拟盘、文件传输、录像 |
| 安全审计与堡垒机 | `docs/security-bastion/` | 会话、录像、命令、策略、审批 |
| 监控中心 | `docs/monitoring/` | 指标、数据源、告警引擎、通知 |
| 日志中心 | `docs/log-center/` | Loki/ES 查询、数据源、日志告警、RBAC |
| 资产与凭证 | `docs/asset-credential/` | 资产模型、统一凭证、云同步 |
| Kubernetes 管理 | `docs/kubernetes/` | 自研客户端、Pod exec/files、YAML、AI 排障 |
| 自动化运维与发布 | `docs/automation-deploy/` | 脚本、任务、远程执行、流水线、Workspace |

---

## 已建立的一级模块文档

### 1. 日志中心

目录：

```text
docs/log-center/
├── README.md
├── query-engine.md
├── datasource.md
├── alerting.md
└── rbac.md
```

应覆盖：

| 主题 | 当前代码落点 | 文档重点 |
|------|--------------|----------|
| Loki / ES 查询代理 | `backend/controller/log_proxy*.go` | 查询 DSL、时间范围、分页、字段解析 |
| 日志数据源 | `backend/controller/log_datasource.go`、`frontend/src/components/monitor/log-center/LogDatasourcePage.tsx` | 数据源配置、连通性检测、索引/标签发现 |
| 统一查询 UI | `UnifiedQueryPanel.tsx`、`QueryAutocompleteInput.tsx` | 查询体验、自动补全、URL 状态 |
| 日志告警 | `LogAlertFromQueryDialog.tsx`、`alert_engine.go` | 从查询生成告警、触发/恢复策略 |
| 日志 RBAC | `log_scope_role.go`、`LogRBAC.tsx` | 数据源/索引/标签级授权 |

当前已建立 [docs/log-center/README.md](../log-center/README.md)。日志中心链路复杂，后续优先补 `query-engine.md`、`datasource.md`、`alerting.md`。

### 2. 监控中心

目录：

```text
docs/monitoring/
├── README.md
├── metrics-model.md
├── alert-engine.md
├── datasource-proxy.md
├── middleware-monitor.md
└── dashboard.md
```

应覆盖：

| 主题 | 当前代码落点 | 文档重点 |
|------|--------------|----------|
| Agent 指标 | `backend/controller/agent.go`、`frontend/src/components/agent/` | 指标模型、最新值、历史趋势、离线判断 |
| 告警引擎 | `alert_engine*.go`、`alert_rules.go` | 规则、状态机、触发、恢复、静默 |
| 告警通知 | `alert_channels.go`、`alert_notify_*.go` | 联系人、渠道、策略、消息模板 |
| Prometheus / Zabbix | `prometheus_proxy.go`、`zabbix_proxy.go` | 数据源代理、鉴权、查询转换 |
| SNMP / 站点拨测 | `snmp*.go`、`site*.go` | 采集模型、历史存储、告警接入 |
| 中间件监控 | `middleware_monitor*.go` | Redis/MySQL 直连采集、指标目录 |

当前已建立 [docs/monitoring/README.md](../monitoring/README.md)。监控是平台中台能力，后续优先补 `metrics-model.md`、`alert-engine.md`。

### 3. 安全审计与堡垒机

目录：

```text
docs/security-bastion/
├── README.md
├── audit-model.md
├── session-policy.md
├── terminal-audit.md
├── approval-integration.md
└── hardening-roadmap.md
```

应覆盖：

| 主题 | 当前代码落点 | 文档重点 |
|------|--------------|----------|
| 操作审计 | `audit.go`、`login_log.go` | 操作日志模型、筛选、导出、保留策略 |
| 会话审计 | `terminal_session.go`、`rdp_session.go`、`session_command.go` | SSH/RDP 会话、命令、录像、回放 |
| 会话策略 | `audit_setting.go`、`SystemSettingsTab.tsx` | 水印、录像、剪贴板、上传、下载、审批 |
| 堡垒机能力 | `docs/terminal/`、`docs/rdp/` | WebSSH/RDP/Pod/kubectl 的统一访问控制 |
| 审批集成 | `approval*.go`、Agent CLI/RDP 预留策略 | 高危操作审批、生产环境变更 |

当前已建立 [docs/security-bastion/README.md](../security-bastion/README.md)。RDP 和终端已成形，下一步需要补 `audit-model.md`、`session-policy.md`。

### 4. 资产与凭证

目录：

```text
docs/asset-credential/
├── README.md
├── server-model.md
├── credential-vault.md
├── cloud-sync.md
└── permission.md
```

应覆盖：

| 主题 | 文档重点 |
|------|----------|
| 服务器资产 | 字段模型、状态、Agent 自动注册、云同步 |
| 凭证系统 | SSH/RDP/API/AKSK/TLS/DB/Generic 七类凭证、加密存储、授权 |
| 云资产 | 云账号、地域、实例同步、账单 |
| 资产权限 | 用户/角色/资源授权 |

当前已建立 [docs/asset-credential/README.md](../asset-credential/README.md)。资产与凭证是堡垒机和自动化的底座。

### 5. Kubernetes 管理

目录：

```text
docs/kubernetes/
├── README.md
├── api-client.md
├── pod-exec-files.md
├── yaml-editor.md
└── aiops-integration.md
```

应覆盖：

| 主题 | 文档重点 |
|------|----------|
| 自研 K8s HTTP 客户端 | 为什么不用 client-go、认证、TLS、分页 |
| Pod exec / 文件 | channel.k8s.io、文件浏览、上传下载 |
| YAML 管理 | 可视化编辑、diff、apply、风险提示 |
| Agent CLI K8s 模式 | AI 查询/排障/变更的安全边界 |

当前已建立 [docs/kubernetes/README.md](../kubernetes/README.md)。K8s 功能多，适合继续拆专题。

### 6. 自动化运维与发布

目录：

```text
docs/automation-deploy/
├── README.md
├── script-library.md
├── cron-task.md
├── remote-exec.md
├── pipeline.md
└── workspace.md
```

应覆盖：

| 主题 | 文档重点 |
|------|----------|
| 脚本库 / 定时任务 | 任务模型、执行历史、日志 |
| 远程执行 | SSH 执行、上传、权限、审计 |
| CI/CD Pipeline | 阶段、日志、产物、Workspace |
| 发布审批 | 环境、发布单、审批和回滚 |

当前已建立 [docs/automation-deploy/README.md](../automation-deploy/README.md)。可与 AI Agent 打通，把成功排障沉淀为 Runbook。

---

## 推荐执行顺序

1. `docs/security-bastion/`：统一审计、终端、RDP、会话策略、审批，直接服务专业堡垒机目标。
2. `docs/monitoring/`：统一 Agent 指标、Prometheus/Zabbix、告警引擎、通知策略。
3. `docs/log-center/`：日志中心查询、数据源、RBAC、日志告警，和监控中心形成可观测闭环。
4. `docs/asset-credential/`：资产和凭证是所有远程能力的权限底座。
5. `docs/kubernetes/`：K8s 管理和 AI K8s 排障单独成册。
6. `docs/automation-deploy/`：自动化、发布、任务、Runbook 联动。

---

## 每个模块文档的标准模板

每个大模块建议至少包含：

| 章节 | 内容 |
|------|------|
| 定位与边界 | 解决什么问题，不解决什么问题 |
| 功能矩阵 | 已完成、部分完成、未做能力 |
| 架构链路 | 前端、API、后端、数据模型、外部依赖 |
| 数据模型 | 表、字段、状态机、索引建议 |
| API 契约 | 请求、响应、错误码、鉴权 |
| 权限与审计 | RBAC、策略、操作日志、敏感字段 |
| 失败处理 | 超时、重试、降级、幂等 |
| 验收清单 | 自动测试、手工验证、联调场景 |
| 演进路线 | P0/P1/P2 优先级 |