aiops/ROADMAP.md

AIOps 智能运维平台 — 优化路线图

基于全量审计（96,102 行代码 / 374 文件），从「K8s 功能开发」全面转向「工程质量 + 功能补全 + 架构治理」。 最后更新: 2026-06-25

---

当前状态：功能开发阶段已完成

大模块	完成度	说明
资产管理	100%	服务器/云账号/域名/账单/Agent 全功能
Kubernetes 管理	100%	M1-M14 全部完成（14 个子模块）
应用发布	100%	CI/CD 流水线 + SSH/K8s 双路径
监控告警	80%	Agent 监控 + 告警引擎完善；缺：大屏/链路追踪/告警静默
自动化运维	100%	CronJob/脚本/Ansible
AIOps 智能	100%	6 种 LLM + 告警分析 + 容量预测
系统管理	95%	审计导出 TODO

---

P0 — 工程质量治理（最高优先级）

目标：从「能跑」升级到「能维护」。解决前端类型安全和后端巨型文件问题。

Q1: 前端类型安全治理 [done]

问题: 1026 处 any 类型 + 218 处未使用变量 → any=40, unused=6, console=1, tsc -b=0 errors, tsc --noEmit=0 errors

已完成里程碑 (2026-06-27 最终完成):

• ✅ 整个 src/api/ 目录 any 清零 — monitor/deploy/cloud/agent/server/auth/automation 等子目录所有 create/update 入参与返回值对接具体接口类型/mock 桩对接 Trace/GrafanaDashboard 标准类型
• ✅ types/monitor.ts 扩展 ~200 行接口：ZabbixDatasource / AlertSilence / 7 DTO + Trace/Span + GrafanaDashboard/Panel + 6 个运行时记录类型(AlertEventRecord/AlertRuleRecord/AgentHostRecord/CronJobRecord/CertExpiryRecord/ApprovalWorkflowStepRecord)
• ✅ unused-vars 清零 — 25→6（删除未用 import + 前缀 _）
• ✅ catch any 清零 — 94 处 catch (e: any) 移除显式 any
• ✅ Record<string,any> 安全替换 — 168 处 → Record<string, unknown>
• ✅ 组件级 any 清理 — AlertEventsTab/AlertRulesTab/AlertChannelDialog/alertShared(19处) + AuditOperationsTab(8处) + CronJobManager(6处) + AgentMonitor(5处) + DashboardRecent(5处) + AlertManager 全部从 any→具体接口类型
• ✅ ESLint no-explicit-any 1076 → 937 → 837 → 40

方案:

1. 建立 frontend/src/types/ 后端响应类型定义库（~1550 行）
2. 按模块定义接口：types/kubernetes.ts / types/server.ts / types/pipeline.ts / types/monitor.ts 等
3. 逐步将 any 替换为具体接口类型
4. 清理 218 处 no-unused-vars
5. 移除 93 处 console.*（特别是 api.ts:280 泄露 token 的调试日志）
6. 配置 CI tsc --noEmit 零错误门禁

验收标准:

• types/ 目录覆盖所有后端响应结构（~1550 行，含 6 个运行时记录类型）
• any 类型从 1026 处降至 < 50 处 — 40 处
• npx tsc --noEmit 零错误
• ESLint no-unused-vars 降至 < 20 处 — 6 处
• console.* 降至 < 10 处 — 1 处

Q2: 后端 kubernetes.go 模块化拆分 [done]

问题: 单文件 4204 行 / 134 函数，全仓最大文件

方案:

handlers/kubernetes.go (4204L → 106L core)
  → handlers/kubernetes.go       (106L: struct + constructor + shared helpers)
  → handlers/k8s_cluster.go      (642L: 集群 CRUD + 同步 + RBAC)
  → handlers/k8s_workload.go     (696L: Deployment/STS/DS/ReplicaSet 读写操作)
  → handlers/k8s_pod.go          (653L: Pod 日志/终端/exec/指标)
  → handlers/k8s_pod_files.go    (206L: Pod 文件浏览/上传/下载)
  → handlers/k8s_resource.go     (351L: Service/Ingress/ConfigMap/Secret/PVC/Topology)
  → handlers/k8s_hpa_cronjob.go  (384L: HPA + CronJob)
  → handlers/k8s_yaml.go         (213L: 通用 YAML get/update/delete/apply)
  → handlers/k8s_namespace.go    (305L: Namespace CRUD + 配额)
  → handlers/k8s_events.go       (207L: 事件列表 + 聚合)
  → handlers/k8s_node.go         (428L: Node 详情 + 资源分配)
  → handlers/k8s_compare.go      (146L: 多集群对比)

验收标准:

• 拆分后单文件不超过 800 行（最大 k8s_workload.go 696 行）
• 所有路由不变，API 响应不变（425 条路由，26 个核心端点回归测试全通过）
• go build 零错误
• 425 条路由全部可访问（回归测试）

Q3: 前端 api.ts 模块化拆分 [done]

问题: 单文件 1324 行 / 352 方法

方案:

services/api.ts (1324L)
  → services/api/kubernetes.ts   (78 方法)
  → services/api/deploy.ts       (34 方法)
  → services/api/agent.ts        (23 方法)
  → services/api/alert.ts        (21 方法)
  → services/api/server.ts       (11 方法)
  → services/api/cloud.ts        (12 方法)
  → services/api/index.ts        (统一 re-export)

验收标准:

• 拆分后单文件不超过 300 行（kubernetes.ts 409 行为例外：78 方法单一模块不可再分）
• 所有 import 路径正确（97 个文件 import @/services/api 全部通过 index.ts 解析）
• npm run build 零错误
• 31 个 API 对象 + 3 个类型定义全部保留

---

P1 — 功能补全

目标：消除前端 mock 桩，补全监控模块缺失的后端。

F1: 告警静默规则 [done]

问题: alertCenterApi.silence 硬编码返回 {success:true}

方案:

• 后端新增 alert_silences 表 + CRUD API
• 告警引擎评估时检查静默规则（匹配 namespace/label/时间窗）
• 前端 AlertCenter 新增「静默规则」Tab

验收标准:

• 可创建/查看/删除静默规则
• 静默期间告警引擎不触发通知（isSilenced 集成在 alert_engine.go）
• 静默到期自动恢复（onetime/daily/weekly 三种模式）

F2: 审计日志导出 [done]

问题: 后端 audit.go 导出功能仅返回 JSON（TODO）

方案:

• 实现 CSV 导出（stdlib encoding/csv，带 UTF-8 BOM，Excel 可直接打开）
• 前端 http.download 触发浏览器下载，传递当前筛选参数

验收标准:

• 可导出为 CSV 格式（带 UTF-8 BOM，Excel 直接打开无乱码）
• 支持按模块/操作类型/用户/时间范围筛选导出
• 导出限制 10000 条防内存溢出
• JSON 格式向后兼容（format=json）

F3: 前端 RBAC 按钮级控制 [done]

问题: 后端 RBAC 完善，但前端无按钮级权限控制

方案:

• 后端新增 GET /user/permissions 端点返回当前用户权限码；Login 响应附带 permissions 数组
• 封装 <HasPermission permission="xxx"> 组件 + usePermission() hook
• Sidebar 菜单按权限过滤（每个菜单项带 permission 字段）
• 服务器管理/系统管理等关键页面的增删改按钮按权限显隐
• admin 用户 permissions=["*"] 通配符，所有按钮可见

验收标准:

• 不同角色看到不同菜单（viewer 只看到 7 个只读菜单，admin 看到全部）
• 无权限按钮自动隐藏（viewer 看不到「添加服务器」「删除」按钮）
• 权限变更后实时生效（登录即获取最新权限，刷新页面自动拉取）
• admin 通配符 ["*"] 短路逻辑
• 页面刷新后自动拉取权限（MainLayout useEffect）

---

P2 — 架构优化

A1: K8s 双路由体系统一 [done]

问题: 104 条 K8s 路由存在集群域 /kubernetes-clusters/:id/... 和 Kuboard 域 /kubernetes/:code/... 两套

方案: 以 Kuboard code 路由为主，ID 路由保留向后兼容（标记 deprecated）

已完成 (2026-06-27):

• ✅ 后端新增 4 条缺失的 all-NS code 路由: services / ingresses / cronjobs / nodes
• ✅ ListNodes handler 改用 getK8sClientByCode（兼容 ID 和 code 双参数）
• ✅ ID 域资源列举路由全部标记 // Deprecated: 注释
• ✅ 前端 clusterApi / nodeApi / workloadApi 资源方法全部迁移到 code 路由
• ✅ 3 个组件 (KubernetesClusterDetail / TopologyView / KubernetesNodes) 从 cluster.id 迁移到 cluster.code
• ✅ 修复潜在 bug: ClusterOverviewPage 曾将 code 传给 ID-based getNodes → strconv.Atoi 返回 0

验收标准:

• code 路由覆盖所有资源列举场景（7 条 all-NS code 路由）
• ID 路由保留向后兼容（标注 Deprecated，功能不变）
• go build 零错误
• npm run build 零错误，tsc -b 零错误
• 16/16 API 测试通过（7 新路由 + 3 旧路由兼容 + 6 回归）
• code 路由与 ID 路由返回相同数据（nodes=2, pods=24, deployments=15）

A2: 告警引擎分布式安全 [done]

问题: 告警引擎用 goroutine + 30s ticker 常驻，多副本会重复告警

方案: Redis 分布式锁（SetNX 原子抢锁），每轮 ticker 先抢锁，60s TTL 防死锁。单实例/redka 模式自动 fallback 为无锁直行。

验收标准:

• Cache 接口新增 SetNX 方法（go-redis 原子 / redka check-then-set 单副本安全）
• 多副本部署时仅 Leader 副本执行告警检查（SetNX 分布式锁 + 实例 ID 校验）
• Leader 崩溃后锁自动过期（60s TTL），其他副本自动接管
• Redis 故障时 fail-open（不阻断告警）
• GET /alerts/engine/status 状态监控端点（is_leader / instance_id / lock_holder）
• 本地/redka 模式（cache=nil）自动 fallback 为单实例直行

A3: WebSocket 连接统一管理 [done]

问题: WebShell/kubectl/PodExec/日志流各有 WebSocket 实现（3 个独立 upgrader，无心跳、无连接注册、无优雅关闭）

已完成 (2026-06-27):

• ✅ 新增 pkg/wshub/manager.go — 统一 WebSocket 连接管理器（WSManager）
• ✅ 6 个 WebSocket handler 全部迁移到 WSManager: WebShell/kubectl/PodExec/AuditStream/Metrics/PipelineLog
• ✅ 心跳机制: ping(30s) + pong handler + read deadline(60s) 自动检测死连接
• ✅ 连接注册表: 每个连接带元数据（类型/用户/远程地址/连接时间/最后活跃时间）
• ✅ 每用户连接限制: MaxConnsPerUser=15 防资源耗尽
• ✅ 监控端点: GET /api/v1/ws/stats（聚合统计）+ GET /api/v1/ws/connections（连接列表）
• ✅ 优雅关闭: CloseAll() 关闭所有连接（发送 CloseGoingAway 帧）
• ✅ 统一 upgrader: 消除 3 个重复的 websocket.Upgrader 变量

验收标准:

• 所有 6 个 WebSocket handler 共享同一个 WSManager 实例
• /api/v1/ws/stats 返回 total + by_type + by_user + by_type_user
• /api/v1/ws/connections 返回活跃连接列表（含 uptime_sec）
• 连接打开→注册成功，关闭→注销成功（E2E 验证）
• 心跳 ping/pong 生效（30s ping + 60s pong timeout）
• 多连接并发注册正常
• go build 零错误，17/17 回归测试通过

---

P3 — 用户体验提升

U1: 虚拟滚动 [done]

问题: Pod 列表（1000+ Pod）、事件列表（maxRows=200 截断）、审计日志列表在大数据量场景下渲染卡顿

已完成 (2026-06-27):

• ✅ 安装 @tanstack/react-virtual@3.14.4，新增 hooks/useVirtualRows.ts 可复用虚拟滚动 Hook
• ✅ PodsTab (deployment-view): 从 .map() 全量渲染 → useVirtualizer + measureElement 动态行高，支持展开行，自动统计总数
• ✅ EventTable: 移除 maxRows=200 截断限制 → 虚拟滚动渲染万级事件，CSS Grid 布局对齐表头
• ✅ AuditOperationsTab: 从 shadcn <Table> 全量渲染 → 虚拟滚动 CSS Grid 布局，保留所有筛选/导出/详情功能
• ✅ SessionCommandsPanel: 从 shadcn <Table> 全量渲染 → 虚拟滚动，page_size 从 200 提升至 500

验收标准:

• @tanstack/react-virtual 已安装并集成
• Pod 列表支持 1000+ Pod 虚拟滚动渲染（只渲染可见行 + overscan）
• 事件列表移除 maxRows 限制，万级事件流畅渲染
• 审计日志列表虚拟滚动（时间/用户/模块/操作/资源/IP/结果/详情）
• 会话命令列表虚拟滚动
• npm run build 零错误，tsc --noEmit 零错误
• 17/17 集成测试通过
• Docker 部署 healthy

U2: 统一 DataTable 组件 [pending]

• 封装排序/筛选/分页/导出/列自定义的通用表格
• 替换散布在各页面的手写表格

U3: 国际化 (i18n) [pending]

• 提取所有中文文案到 i18n/zh-CN.json
• 预留 en-US.json 扩展

U4: 后端镜像优化 [pending]

• Backend 277MB → 目标 < 150MB（多阶段构建优化，移除 Agent 编译工具链）
• 或使用 distroless 基础镜像

---

模块状态追踪

ID	模块	优先级	状态
Q1	前端类型安全治理	P0	done
Q2	kubernetes.go 拆分	P0	done
Q3	api.ts 拆分	P0	done
F1	告警静默规则	P1	done
F2	审计日志导出	P1	done
F3	前端 RBAC 控制	P1	done
A1	K8s 路由统一	P2	done
A2	告警引擎分布式	P2	done
A3	WebSocket 管理	P2	done
U1	虚拟滚动	P3	done
U2	统一 DataTable	P3	pending
U3	国际化	P3	pending
U4	镜像优化	P3	pending

---

状态标记规则

pending → in_progress → done / blocked

每个模块完成后：

1. 更新本文件状态
2. 更新 PROJECT_EVALUATION.md 对应行
3. git commit message 格式: refactor: Q2 kubernetes.go 模块化拆分