# 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` 零错误门禁

**验收标准**:
- [x] `types/` 目录覆盖所有后端响应结构（~1550 行，含 6 个运行时记录类型）
- [x] `any` 类型从 1026 处降至 < 50 处 — **40 处**
- [x] `npx tsc --noEmit` 零错误
- [x] ESLint `no-unused-vars` 降至 < 20 处 — **6 处**
- [x] `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: 多集群对比)
```

**验收标准**:
- [x] 拆分后单文件不超过 800 行（最大 k8s_workload.go 696 行）
- [x] 所有路由不变，API 响应不变（425 条路由，26 个核心端点回归测试全通过）
- [x] `go build` 零错误
- [x] 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)
```

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

---

## P1 — 功能补全

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

### F1: 告警静默规则 [done]

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

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

**验收标准**:
- [x] 可创建/查看/删除静默规则
- [x] 静默期间告警引擎不触发通知（`isSilenced` 集成在 alert_engine.go）
- [x] 静默到期自动恢复（onetime/daily/weekly 三种模式）

### F2: 审计日志导出 [done]

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

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

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

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

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

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

**验收标准**:
- [x] 不同角色看到不同菜单（viewer 只看到 7 个只读菜单，admin 看到全部）
- [x] 无权限按钮自动隐藏（viewer 看不到「添加服务器」「删除」按钮）
- [x] 权限变更后实时生效（登录即获取最新权限，刷新页面自动拉取）
- [x] admin 通配符 `["*"]` 短路逻辑
- [x] 页面刷新后自动拉取权限（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

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

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

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

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

**验收标准**:
- [x] Cache 接口新增 `SetNX` 方法（go-redis 原子 / redka check-then-set 单副本安全）
- [x] 多副本部署时仅 Leader 副本执行告警检查（SetNX 分布式锁 + 实例 ID 校验）
- [x] Leader 崩溃后锁自动过期（60s TTL），其他副本自动接管
- [x] Redis 故障时 fail-open（不阻断告警）
- [x] `GET /alerts/engine/status` 状态监控端点（is_leader / instance_id / lock_holder）
- [x] 本地/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` 变量

**验收标准**:
- [x] 所有 6 个 WebSocket handler 共享同一个 WSManager 实例
- [x] `/api/v1/ws/stats` 返回 total + by_type + by_user + by_type_user
- [x] `/api/v1/ws/connections` 返回活跃连接列表（含 uptime_sec）
- [x] 连接打开→注册成功，关闭→注销成功（E2E 验证）
- [x] 心跳 ping/pong 生效（30s ping + 60s pong timeout）
- [x] 多连接并发注册正常
- [x] `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

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

### U2: 统一 DataTable 组件 [done]

**问题**: 37 个文件各自手写表格（搜索/排序/分页/导出/选择全部重复实现），维护成本高

**方案**:
- 封装 `DataTable<T>` 泛型组件（`components/ui/data-table.tsx`），声明式列定义 + 内置功能开关
- 替换散布在各页面的手写表格

**已完成 (2026-06-27)**:
- ✅ 新增 `DataTable<T>` 组件 — 支持声明式列定义、排序（三态 asc/desc/null）、全局搜索（指定字段）、客户端分页（可配置 pageSize）、行选择（受控 selectedIds）、CSV 导出（UTF-8 BOM）、列可见性面板（DropdownMenu toggle）、加载骨架、空状态自定义渲染、行点击、CSS 变量主题适配
- ✅ 迁移 3 个代表性页面:
  - **RegionManager.tsx** — 区域管理（CRUD + 搜索 + 选择 + 排序 + 导出 + 列可见性 + 云商筛选）
  - **LoginLogsTab.tsx** — 登录日志（搜索 + 排序 + 分页 + 导出 + 列可见性 + 状态筛选）
  - **LogDatasourcePage.tsx** — 日志数据源管理（搜索 + 排序 + CRUD + 测试连接）
- ✅ 所有功能内建（搜索/排序/分页/选择/导出/列可见性），无需在各页面重复实现

**验收标准**:
- [x] `DataTable<T>` 组件封装排序/搜索/分页/导出/列自定义/行选择
- [x] `tsc -b` 零错误，`npm run build` 零错误（✓ built in 18.05s）
- [x] 迁移的页面功能不变（CRUD/搜索/选择/排序/导出全部保留）
- [x] ESLint any=43（<50），4 个迁移文件零 ESLint 错误
- [x] 17/17 集成回归测试通过

### 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 | **done** |
| U3 | 国际化 | P3 | pending |
| U4 | 镜像优化 | P3 | pending |

---

## 状态标记规则

```
pending → in_progress → done / blocked
```

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