# AIOps 智能运维平台 — Agent 工作指南

> 本文档面向 AI 编程助手。阅读前默认不了解本项目。所有结论均来自项目实际文件，未做假设。
> 项目注释、文档、提交信息主要使用中文；新增/修改代码时注释末尾需署名 `// Logan.Li`。

---

## 1. 项目概述

**AIOps** 是一个企业级云原生智能运维平台，聚焦三大核心能力：

1. **资产管理** — 服务器 CRUD、批量导入、WebShell、云账号/域名/账单、Kubernetes 多集群。
2. **监控告警** — Agent 采集 `/proc` 指标、告警引擎（阈值/离线/日志告警）、告警中心、监控大屏、Prometheus/Zabbix/SNMP/站点拨测/中间件监控。
3. **自动化运维 / AIOps** — CI/CD 流水线、定时任务/脚本库、Go-native SSH 远程执行、资源申请审批、AI 智能助手、Agent CLI（ReAct + Evolver）。

项目采用前后端分离架构，但通过 `go:embed` 支持将前端构建产物嵌入后端二进制，实现单文件 / 单容器部署。

### 1.1 三种核心产物

| 产物 | 技术 | 说明 |
|------|------|------|
| `frontend/` | React 19 + TypeScript + Vite | Web 控制台 |
| `backend/` | Go 1.24 + Gin + GORM | HTTP API + WebSocket + 前端静态资源服务 |
| `agent/` | Go 1.24（CGO_ENABLED=0） | 主机指标采集 + 远程任务执行 |

### 1.2 默认账号（生产必须修改）

| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | 123456 | 超级管理员 |
| ops01 | 123456 | 运维 |
| dev01 | 123456 | 开发 |

---

## 2. 技术栈与关键配置

### 2.1 关键配置文件

项目不存在 `pyproject.toml`、`Cargo.toml`、`pom.xml` 等配置。核心配置文件为：

| 文件 | 说明 |
|------|------|
| `backend/go.mod` | 后端 Go 模块定义，模块名 `ezops`，Go 1.24.0 |
| `agent/go.mod` | Agent 独立模块，模块名 `ezops/agent`，Go 1.22（与后端共用 1.24 工具链） |
| `frontend/package.json` | 前端 npm 依赖与脚本 |
| `frontend/vite.config.ts` | Vite 配置：端口 5173，代理 `/api`、`/ws`、`/health`、`/version`、`/agent` 到 `localhost:8080` |
| `frontend/eslint.config.js` | ESLint flat config，禁止显式 `any` |
| `frontend/tailwind.config.js` | CSS 变量主题体系 |
| `config.yaml` | 本地开发默认配置（SQLite + redka，端口 8080） |
| `docker-compose.yml` | 3 容器：MySQL 8.0 + Redis 7-alpine + AIOps（:8080） |
| `docker-compose.k8s.yml` | 单应用容器 + 外部 DB |
| `Dockerfile` | 4-stage Embed 镜像（前端→后端→Agent→Runtime），Compose 与 K8s 共用 |
| `.env.example` | Docker Compose 环境变量示例 |
| `deploy/kubernetes/` | K8s 清单：`devops` 命名空间、NodePort 30080 |
| `run.sh` | 统一入口：dev / build / docker / kubernetes / release / binary |
| `Makefile` | 快捷命令（dev / build / docker-up / lint 等），部分委托给 `run.sh`，部分已陈旧 |

> 注意：项目根目录使用 `Dockerfile`（4-stage embed 单容器方案）。前端构建嵌入后端二进制，`docker-compose.yml` 直接引用。

### 2.2 后端

- **语言 / 版本**：Go 1.24+
- **Web 框架**：Gin v1.9.1
- **ORM**：GORM v1.30.0
- **数据库**：SQLite（local 模式，开发本机）、MySQL 8.0（生产）、PostgreSQL（可选）
- **缓存**：Redis 7 或 redka（内嵌，local 模式默认）
- **认证**：JWT（`golang-jwt/jwt/v5`）
- **配置**：Viper
- **日志**：Zap
- **WebSocket**：Gorilla WebSocket
- **SSH/SFTP**：`golang.org/x/crypto` + `pkg/sftp`
- **PTY**：`creack/pty`
- **K8s 客户端**：自研轻量客户端（`net/http` + `crypto/tls`），不走 client-go

关键文件：

- `backend/main.go` — 应用入口、CLI 参数解析、配置加载、优雅关闭
- `backend/embed.go` — `go:embed static`，SPA fallback 逻辑
- `backend/config/config.go` — `Config` 结构体与默认配置
- `backend/router/routes.go` — 所有路由注册（实际约 1054 行，核心入口）

### 2.3 前端

- **框架**：React 19.2+
- **语言**：TypeScript 5.9+
- **构建工具**：Vite 7+
- **样式**：Tailwind CSS 3.4+ + `tailwindcss-animate`
- **UI 组件**：shadcn/ui（Radix UI 封装）
- **状态管理**：Zustand 5+
- **数据请求**：TanStack Query 5+
- **路由**：React Router 7+
- **图表**：Recharts
- **图标**：Lucide React
- **编辑器**：CodeMirror 6（`@uiw/react-codemirror` + `@codemirror/lang-yaml`）
- **终端**：xterm.js
- **国际化**：i18next + react-i18next（中/英双语）
- **表单校验**：Zod + React Hook Form

### 2.4 Agent

- **模块名**：`ezops/agent`
- **Go 版本**：go 1.22（文件声明），与后端共用 1.24 工具链
- **依赖**：仅 `golang.org/x/sys`
- **架构**：`collector/`（采集器）、`task/`（远程任务）、`reporter/`（HTTP 上报）、`client/`（HTTP 客户端）、`model/`（数据结构）

---

## 3. 项目结构与模块划分

### 3.1 顶层目录

```
aiops/
├── frontend/            # React SPA
├── backend/             # Go API + embed 静态资源
├── agent/               # 监控 Agent（独立 Go module）
├── deploy/              # 部署脚本与 K8s 清单
├── docs/                # 中文开发文档
├── tests/               # 集成测试脚本
├── scripts/             # 构建辅助脚本（kubectl 安装、alpine 镜像源等）
├── run.sh               # 统一入口
├── Dockerfile     # 推荐生产镜像
├── docker-compose.yml
├── docker-compose.k8s.yml
├── config.yaml
└── README.md / CLAUDE.md / AGENTS.md
```

### 3.2 后端目录职责

| 目录 | 职责 |
|------|------|
| `backend/main.go` / `embed.go` | 应用入口 + 前端嵌入 |
| `backend/controller/` | HTTP 处理器（60+ 个文件，按领域拆分；总代码行约 27K） |
| `backend/model/` | GORM 数据模型（约 30 个文件，86+ 张表） |
| `backend/dto/` | 请求/响应 DTO（当前 `dto.go` 一个文件） |
| `backend/service/` | 业务逻辑层（V2 Services，当前 `service.go`） |
| `backend/repository/` | 数据访问层（当前 `repo.go`） |
| `backend/router/` | 路由注册 |
| `backend/middleware/` | JWT、Admin、PipelineAccess、CORS、日志 |
| `backend/config/` | Viper 配置加载 |
| `backend/seed/` | 种子数据（默认账号、菜单等） |
| `backend/pkg/` | 公共包：database、redis、logger、kubernetesclient、remoteexec、agentcli、toolinstaller、wshub 等 |
| `backend/static/` | 前端构建产物（embed 目标目录） |

主要业务模块（按 controller 文件划分）：

- 用户/角色/权限：`user.go`, `user_admin.go`, `item_role.go`
- LDAP：`ldap.go`, `ldap_users.go`, `ldap_ou.go`
- 资产：`server.go`, `cloud_accounts.go`, `cloud_sync.go`, `cloud_domain.go`, `cloud_platform.go`, `cloud_region.go`, `billing.go`, `billing_alert.go`, `resource_model.go`
- K8s：`kubernetes.go`, `k8s_cluster.go`, `k8s_node.go`, `k8s_pod.go`, `k8s_workload.go`, `k8s_yaml.go`, `k8s_resource.go`, `k8s_namespace.go`, `k8s_events.go`, `k8s_compare.go`, `k8s_export.go`, `k8s_hpa_cronjob.go`, `k8s_pod_files.go`, `kubectl_shell.go`
- 监控告警：`alert.go`, `alert_rules.go`, `alert_engine.go`, `alert_channels.go`, `alert_contacts.go`, `alert_silence.go`, `metrics.go`, `health_probe.go`, `site.go`, `snmp.go`, `custom_dashboard.go`, `middleware_monitor.go`
- 数据源代理：`prometheus_proxy.go`, `prom_ds.go`, `zabbix_proxy.go`, `zabbix_ds.go`, `log_proxy.go`, `log_datasource.go`, `trace_datasource.go`
- 日志中心：`UnifiedQueryPanel.tsx`, `EsQueryPanel.tsx`, `LokiQueryPanel.tsx`, `LogDatasourcePage.tsx`, `LogDatasourceDialog.tsx`, `TimeRangePicker.tsx`
- 应用发布/部署：`pipeline.go`, `pipeline_executor.go`, `deploy.go`, `deploy_groups.go`, `deploy_environments.go`, `tool_config.go`
- 自动化运维：`automation.go`, `automation_cron.go`, `automation_script.go`, `remote_exec.go`, `ansible.go`
- 审批：`approval.go`, `approval_process.go`, `approval_workflow.go`
- 审计：`audit.go`, `audit_hub.go`, `terminal_session.go`, `session_command.go`, `login_log.go`
- AI：`llm.go`, `llm_chat.go`, `llm_history.go`, `agent_cli.go`, `agent_cli_api.go`
- Agent：`agent.go`, `agent_task.go`, `agent_install.go`
- 系统：`navigation.go`, `credential.go`, `credential_assign.go`

### 3.3 前端目录职责

| 目录 | 职责 |
|------|------|
| `frontend/src/components/` | 业务组件（按领域分子目录） |
| `frontend/src/components/ui/` | shadcn/ui 基础组件 |
| `frontend/src/api/` | API 封装（按领域拆分为 `api.ts` 及子目录） |
| `frontend/src/hooks/` | 自定义 Hooks |
| `frontend/src/store/` | Zustand 状态管理 |
| `frontend/src/lib/` | 工具函数 |
| `frontend/src/types/` | TypeScript 类型 |
| `frontend/src/i18n/` / `locales/` | 国际化（zh-CN / en-US 双语） |
| `frontend/src/pages/` | 少量页面级组件 |
| `frontend/src/assets/` | 静态资源 |

业务组件子目录与后端模块基本对应：`dashboard/`, `server/`, `cloud/`, `k8s/`, `monitor/`, `deploy/`, `approval/`, `automation/`, `aiops/`, `system/`, `agent/`, `layout/` 等。

### 3.4 Agent 目录职责

| 目录 | 职责 |
|------|------|
| `agent/main.go` | CLI 入口、采集上报循环、任务轮询 |
| `agent/collector/` | CPU / 内存 / 磁盘 / 网络 / 端口 / 进程 / FD / Swap / 上下文切换 / 健康探针 |
| `agent/task/` | 远程任务执行器与轮询客户端 |
| `agent/reporter/` | HTTP 上报 |
| `agent/client/` | HTTP 客户端 |
| `agent/model/` | 上报数据结构 |
| `agent/deploy/` | `install.sh` + systemd 服务文件 |

### 3.5 代码规模（实测）

| 层级 | 文件数 | 说明 |
|------|--------|------|
| 前端 `frontend/src` | 约 426 个 `.ts` / `.tsx` | 含组件、API、Hooks、Store、类型等 |
| 后端 `backend` | 约 172 个 `.go` | 含 controller、model、pkg、router 等 |
| Agent `agent` | 21 个 `.go` | 独立模块，仅依赖 `golang.org/x/sys` |

---

## 4. 构建与运行命令

统一入口是 `./run.sh`，优先使用它。`Makefile` 仅作为快捷别名，且部分命令已落后于 `run.sh`（例如 `make dev` 调用 `./run.sh start` 实际不存在）。

### 4.1 本地开发

```bash
# 前后端热重载（前端 :5173，后端 :8080，SQLite + redka）
./run.sh dev

./run.sh stop        # 停止
./run.sh restart     # 重启
./run.sh status      # 状态
./run.sh logs        # 实时日志
```

后端本地单独运行：

```bash
cd backend
CGO_ENABLED=1 go build -o aiops .
./aiops
# 或
go run .
```

前端本地单独运行：

```bash
cd frontend
npm install
npm run dev
```

### 4.2 独立二进制（推荐边缘/本机）

```bash
./run.sh build                     # 产物 ./aiops（项目根目录）
./run.sh build tag v1.5.0          # 指定版本
./aiops version                    # 查看版本
./aiops --mode local --port 8080   # 前台运行
./run.sh binary upgrade            # 停服 → 重编译 → 后台启动
./run.sh binary stop
./run.sh binary status
```

> ⚠️ Mac 上 `./run.sh build` 产出 darwin 二进制，不能直接在 Linux 服务器运行；Linux 部署请用 Docker 镜像或在 Linux 上构建。

### 4.3 Docker Compose

```bash
./run.sh docker up                 # 增量构建 + 启动（MySQL + Redis + AIOps :8080）
./run.sh docker up v1.5.0          # 指定版本
./run.sh docker up fresh           # 无缓存全量重建
./run.sh docker down               # 停止
./run.sh docker logs               # 实时日志
./run.sh docker push v1.5.0        # 构建并推送 lghost/aiops:v1.5.0
```

### 4.4 Kubernetes

```bash
./run.sh kubernetes deploy         # 构建镜像 + 全量部署（devops 命名空间，NodePort 30080）
./run.sh kubernetes upgrade v1.5.0 # 滚动更新
./run.sh kubernetes push v1.5.0    # 构建并推送镜像
./run.sh kubernetes status
./run.sh kubernetes logs
./run.sh kubernetes delete         # 清理（保留 PVC）
```

### 4.5 Agent 构建

```bash
./run.sh build agent               # 交叉编译 linux-amd64 + linux-arm64，macOS 额外产出 darwin-arm64
```

### 4.6 一键发版

```bash
docker login
./run.sh release v1.5.0            # 打 tag → 编译二进制 → 构建镜像 → 推送 Docker Hub → 更新 K8s manifest
```

版本来源优先级：`run.sh` 显式参数 > `VERSION` 环境变量 > `git describe --tags --always` > `dev`。

---

## 5. 测试说明

### 5.1 当前测试现状

- **后端 Go 单元测试**：`backend/` 下目前 **没有 `*_test.go` 文件**。若新增功能，请按 Go 惯例补充测试。
- **集成测试**：`tests/integration_test.py` 提供基于 HTTP 的端到端验证。

### 5.2 运行集成测试

```bash
# 默认访问 localhost:80（适合 Docker Compose 后）
python3 tests/integration_test.py

# 本地开发模式（后端端口 8080）
python3 tests/integration_test.py --host localhost --port 8080
```

测试覆盖：健康检查、登录、用户、仪表盘、服务器 CRUD、导航、凭证、流水线、环境、角色。

### 5.3 前端类型与构建检查

```bash
cd frontend
npm run build          # 生产构建（含 tsc -b）
npx tsc --noEmit       # 类型检查（提交前必须零错误）
npm run lint           # ESLint 检查
```

### 5.4 后端静态检查

```bash
cd backend
go vet ./...
go build -o aiops .
```

---

## 6. 开发规范

### 6.1 注释规范

- 新增或修改代码必须写**中文注释**。
- 注释末尾署名 `// Logan.Li`。

### 6.2 文件大小红线

| 类型 | 上限 | 超出处理 |
|------|------|----------|
| Go handler | 400 行 | 按 sub-domain 拆分 |
| Go model | 300 行 | 按模块拆分 |
| React 组件 (.tsx) | 700 行 | 提取子组件 |
| 任何文件 | 700 行（硬上限） | 必须拆分 |

### 6.3 Go 代码规范

1. **所有 handler 返回必须包裹 `model.Response{Code:200, Data:...}`**。
2. **统一响应格式**：

   ```go
   type Response struct {
       Code    int         `json:"code"`
       Message string      `json:"message"`
       Data    interface{} `json:"data"`
   }
   type ListResponse struct {
       List  interface{} `json:"list"`
       Total int64       `json:"total"`
   }
   ```

3. **新增 handler 不直接绑 model**，使用独立 request struct。
4. **GORM 指针字段必须解引用**后再使用（`*field`）。
5. **Update handler 禁止复用 CreateRequest**，使用 `map[string]interface{}` 接收。
6. **编译参数**：`unset http_proxy https_proxy && export GOPROXY=https://goproxy.cn,direct && GOTOOLCHAIN=local CGO_ENABLED=1 go build -o aiops .`
7. **GORM `First()` 连续查询会带上次 ID**，请用 `Take()` 代替。
8. 文件名使用 `snake_case.go`；类型/方法 `PascalCase`；变量 `camelCase`。

### 6.4 React / TypeScript 规范

1. **列表响应自动解包**：`http.ts` 已提取 `.data`，组件拿到的是 `Response.Data`；列表返回 `{list, total}`。
2. **禁止 `window.confirm()` / `alert()`**，使用 `useConfirm()` + `toast`。
3. **Radix Dialog 必须包含 `<DialogDescription>`**。
4. **Token 双保险**：`useUserStore.getState().token || localStorage.getItem('token')`。
5. ESLint 禁止显式 `any`（`@typescript-eslint/no-explicit-any: error`）。
6. 组件文件 `PascalCase.tsx`；工具文件 `camelCase.ts`。

### 6.5 UI 设计原则

- 能去掉的都去掉 — 不要多余边框、装饰线。
- 按钮文案 2–4 字。
- 不留占位按钮；功能没完成就不放按钮。
- 页面打开即用，不需要额外“新建”按钮跳转。
- 主题感知 — 使用 CSS 变量 `var(--dg-xxx)` / Tailwind 语义色，不硬编码颜色。

### 6.6 Git 工作流

| 分支 | 说明 |
|------|------|
| `master` | 生产分支，保护分支 |
| `dev` | 开发集成分支 |
| `feature/*` | 功能分支 |
| `fix/*` | 修复分支 |
| `hotfix/*` | 紧急修复 |

提交规范：

```
<type>: <description>

- 变更点 1
- 变更点 2
```

Type：`feat`, `fix`, `refactor`, `docs`, `style`, `test`, `chore`。

---

## 7. 关键架构约定

### 7.1 认证流程

```
Login(本地/LDAP fallback) → JWT Token
→ 前端 Zustand persist + localStorage 双写
→ http.ts 自动注入 Bearer
→ JWTAuth 中间件
→ AdminAuth 中间件（管理类路由）
```

WebSocket 无法设置自定义 header → 后端 `JWTAuth` 支持 `?token=` query param 回退。

### 7.2 Agent 双通道架构

```
指标通道: ticker(10s) → collect(/proc) → POST /agent/report
任务通道: ticker(5s)  → GET /agent/tasks/poll → execute → POST /agent/tasks/:id/result
```

### 7.3 K8s 客户端

自研轻量 K8s HTTP 客户端，基于 `channel.k8s.io` WebSocket 协议实现 Pod exec/日志/文件浏览，不引入 client-go（控制镜像体积）。

### 7.4 缓存策略

- `local` 模式：SQLite + redka（内嵌 Redis 兼容层）。
- 生产模式：MySQL + Redis。
- 告警引擎使用 Redis 分布式锁（SetNX + 60s TTL）保证多副本仅 Leader 执行检查。

### 7.5 健康检查

- 推荐探针：`GET /version`（无 DB 依赖）。
- `GET /health` 包含 DB 检查，启动早期可能不响应，因此 K8s 探针使用 `/version`。

### 7.6 工具懒加载

`kubectl`、`maven`、`nodejs`、`helm` 等首次使用时自动下载；国内网络自动优先国内镜像。见 `backend/pkg/toolinstaller/`。

---

## 8. 安全注意事项

### 8.1 已具备的安全机制

- **认证**：JWT Bearer Token。
- **授权**：RBAC 角色权限（后端路由 + 前端 `usePermission` / `<HasPermission>` + Sidebar 过滤）。
- **密码**：Bcrypt 存储。
- **SQL 注入防护**：全参数化查询（GORM）。
- **XSS 防护**：React 默认转义。
- **凭证加密**：7 种统一凭证类型（SSH/Docker/TLS/AKSK/DB/API/Generic）加密存储。
- **高危命令**：Agent CLI 通过 WebSocket `confirm` 事件 + 前端 `useConfirm()` 二次确认。

### 8.2 生产必须处理

1. **修改默认密码**：admin / ops01 / dev01 均为 `123456`。
2. **更换 JWT Secret**：`config.yaml` 中 `jwt.secret` 或环境变量 `JWT_SECRET`。
3. **启用 HTTPS**：Ingress 或前置 Nginx 终止 TLS。
4. **数据库密码**：`.env` / `config.yaml` 中 MySQL 密码不能使用默认值。
5. **定期备份**：MySQL 数据、PVC、SQLite 文件。
6. **审计日志**：确保审计中间件记录敏感操作。
7. **命令注入审计**：后端存在 `exec.Command` + `bash -c` 调用场景，需校验用户输入路径。

---

## 9. 常见陷阱速查

| # | 陷阱 | 解决 |
|---|------|------|
| Go1 | `go build` 超时 | `unset proxy + GOPROXY=https://goproxy.cn,direct + GOTOOLCHAIN=local` |
| Go2 | handler 不包裹 Response | 必须 `model.Response{Code:200, Data:...}` |
| Go3 | GORM 指针字段 | `*field` 解引用后再用 |
| Go4 | Update 复用 CreateRequest | 用 `map[string]interface{}` |
| Go5 | `CGO_ENABLED=0` + redka → 缓存静默失败 | MySQL 模式必须显式 `--redis-driver redis` |
| FE1 | 白屏无堆栈 | 90% 是列表 `{list,total}` 未解包 |
| FE2 | `confirm()` 冻结自动化 | 用 `useConfirm()` |
| FE3 | Token 获取 | `useUserStore.getState().token` + `localStorage` |
| FE4 | Radix Dialog 警告 | 必须有 `<DialogDescription>` |
| FE5 | Select.Item 空字符串 value | 用 sentinel 值 `__manual` |
| FE6 | API 字段名不匹配 | 检查前后端命名一致性 |
| Build | Mac 构建 Linux 二进制 | 不能直接用 `./run.sh build`；用 `Dockerfile` 或在 Linux 构建 |

---

## 10. 参考文档

| 文档 | 说明 |
|------|------|
| `README.md` | 项目主说明、快速开始 |
| `CLAUDE.md` | AI 助手完整命令参考与关键设计决策 |
| `docs/development-guide.md` | 开发规范、Git 工作流 |
| `docs/deployment.md` | 部署方式、版本发版 |
| `docs/project-structure.md` | 目录结构说明 |
| `docs/reference/api-reference.md` | API 接口文档 |
| `docs/reference/database-schema.md` | 数据模型和表结构 |
| `PROJECT_EVALUATION.md` | 全量项目评估（规模、技术债、评分） |
| `ROADMAP.md` | K8s 管理功能演进路线 |

---

## 11. 快速验证清单

修改代码后，按以下顺序验证：

1. `cd backend && go build -o aiops .`（零错误）
2. `cd frontend && npx tsc --noEmit`（零错误）
3. `./run.sh docker up` 或 `./run.sh dev` 启动完整环境
4. `python3 tests/integration_test.py --host localhost --port 8080` 通过
5. 手动验证相关页面 / API
6. `git commit`（大变更前先提交，方便回滚）

> 代码改完不算完成，端到端验证通过才算完成。