314 lines
12 KiB
Markdown
314 lines
12 KiB
Markdown
# CLAUDE.md — AIOps
|
||
|
||
本文档为 Claude Code / Hermes 等 AI 编程助手提供在代码库中工作的指导说明。
|
||
|
||
> 作者：Logan.Li
|
||
> 语言：中文（代码注释和文档主要使用中文，注释署名 `// Logan.Li`）
|
||
|
||
## 项目概述
|
||
|
||
**AIOps** 是一个企业级智能运维平台，聚焦三大核心能力：
|
||
|
||
1. **资产管理** — 服务器管理、云资源（云账号/域名/账单）、K8s 集群
|
||
2. **监控告警** — Agent 采集指标、告警引擎（资源阈值/离线检测）、告警中心、日志能力、链路追踪、监控大屏
|
||
3. **自动化运维 / AIOps** — CronJob/Script/Ansible 自动化、资源申请审批、AI 智能运维（告警分析/故障诊断/脚本生成）
|
||
|
||
### 核心特性
|
||
|
||
- **Agent 双通道** — 指标采集通道（10s 上报 `/proc`）+ 远程任务通道（5s 轮询执行命令）
|
||
- **LDAP 集成** — 配置管理、用户导入、OU 管理、LDAP 用户 CRUD
|
||
- **资源申请审批** — 云服务器申请、应用部署申请（Git 地址/端口/Nacos 等配置），动态表单
|
||
- **5 套主题** — CSS 变量驱动，暗色/亮色/紫色/绿色/玫红一键切换
|
||
- **WebShell** — WebSocket 终端，在线 SSH 操作服务器
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 | 端口 |
|
||
|---|---|---|
|
||
| 后端 | Go 1.21 + Gin + GORM + SQLite (CGO) + JWT + Zap | 8080 |
|
||
| 前端 | React 19 + TypeScript + Vite + Tailwind + shadcn/ui + Zustand + TanStack Query | 5173 |
|
||
| Agent | Go 1.24 (CGO_ENABLED=0 静态二进制, amd64+arm64) | — |
|
||
|
||
## 常用命令
|
||
|
||
### 快速启动
|
||
|
||
```bash
|
||
./run.sh start # 启动前后端
|
||
./run.sh stop # 停止服务
|
||
./run.sh restart # 重启服务
|
||
./run.sh status # 查看服务状态
|
||
./run.sh logs # 查看实时日志
|
||
```
|
||
|
||
### 后端 (backend/)
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 编译（每次修改后端必须执行）
|
||
unset http_proxy https_proxy && export GOPROXY=https://goproxy.cn,direct && GOTOOLCHAIN=local CGO_ENABLED=1 go build -o aiops-server ./cmd/
|
||
|
||
# 直接运行
|
||
go run ./cmd/
|
||
|
||
# 代码检查
|
||
go vet ./...
|
||
```
|
||
|
||
### 前端 (frontend/)
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run dev # 开发服务器 (端口 5173)
|
||
npm run build # 生产构建
|
||
npx tsc --noEmit # 类型检查（提交前必须零错误）
|
||
```
|
||
|
||
### Agent (agent/)
|
||
|
||
```bash
|
||
cd agent
|
||
|
||
# 本地构建（macOS 测试用）
|
||
CGO_ENABLED=0 go build -o aiops-agent .
|
||
|
||
# 交叉编译
|
||
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o aiops-agent-linux-amd64 .
|
||
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o aiops-agent-linux-arm64 .
|
||
|
||
# 运行 Agent
|
||
./aiops-agent --server http://localhost:8080 --token <JWT_TOKEN>
|
||
```
|
||
|
||
## 架构说明
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
aiops/
|
||
├── backend/
|
||
│ ├── cmd/
|
||
│ │ ├── main.go # 应用入口
|
||
│ │ └── seed.go # 种子数据（用户/角色/审批模板/LDAP配置）
|
||
│ ├── internal/
|
||
│ │ ├── config/config.go # Viper 配置
|
||
│ │ ├── models/ # GORM 模型（每模块独立文件）
|
||
│ │ └── api/
|
||
│ │ ├── handlers/ # HTTP handler（按模块拆分，每文件 <400 行）
|
||
│ │ ├── middleware/auth.go # JWT + Admin 中间件
|
||
│ │ └── routes/routes.go # 路由注册
|
||
│ ├── pkg/database/database.go # DB 连接 + AutoMigrate
|
||
│ └── scripts/mock.go # Mock 种子（已废弃）
|
||
│
|
||
├── frontend/
|
||
│ ├── src/
|
||
│ │ ├── components/
|
||
│ │ │ ├── dashboard/ # 仪表盘（统计/图表/最近活动）
|
||
│ │ │ ├── server/ # 服务器管理
|
||
│ │ │ ├── cloud/ # 云资源管理
|
||
│ │ │ ├── k8s/ # K8s 集群管理
|
||
│ │ │ ├── deploy/ # 应用发布（CI/CD 流水线）
|
||
│ │ │ ├── monitor/ # 监控告警（指标/告警中心/日志/大屏/Agent告警）
|
||
│ │ │ ├── automation/ # 自动化运维（CronJob/Script/Ansible）
|
||
│ │ │ ├── approval/ # 资源申请审批
|
||
│ │ │ ├── aiops/ # AI 智能运维
|
||
│ │ │ ├── system/ # 系统管理（用户/LDAP/审计）
|
||
│ │ │ ├── navigation/ # 站内导航
|
||
│ │ │ └── layout/ # 布局（Sidebar/Header）
|
||
│ │ ├── services/
|
||
│ │ │ ├── api.ts # API 定义（按模块分组）
|
||
│ │ │ └── http.ts # Axios 封装（拦截器自动注入 Token）
|
||
│ │ ├── store/ # Zustand 状态管理
|
||
│ │ ├── hooks/ # React hooks（useConfirm 等）
|
||
│ │ └── types/index.ts # 全局类型
|
||
│ └── App.tsx # 路由 + 顶层 Provider
|
||
│
|
||
├── agent/ # 监控 Agent（独立 Go module）
|
||
│ ├── main.go # CLI 入口
|
||
│ ├── collector/ # /proc 采集器（CPU/内存/磁盘/端口）
|
||
│ ├── task/ # 远程任务执行器（command/script）
|
||
│ ├── reporter/http.go # HTTP 上报
|
||
│ └── model/model.go # 数据结构
|
||
│
|
||
└── run.sh # 一键启动脚本
|
||
```
|
||
|
||
### 后端分层
|
||
|
||
```
|
||
handlers/ (HTTP 处理) → models/ (GORM 数据操作)
|
||
↓
|
||
middleware/auth.go (JWT 验证)
|
||
```
|
||
|
||
**新增模块 4 步**:
|
||
1. `models/xxx.go` — 定义 GORM 模型
|
||
2. `handlers/xxx.go` — 实现 handler（所有返回必须用 `models.Response{Code:200}` 包裹）
|
||
3. `routes/routes.go` — 注册路由
|
||
4. `pkg/database/database.go` — 添加 AutoMigrate
|
||
|
||
### API 响应格式
|
||
|
||
```go
|
||
// 统一响应（所有 handler 必须遵循）
|
||
type Response struct {
|
||
Code int `json:"code"`
|
||
Message string `json:"message"`
|
||
Data interface{} `json:"data"`
|
||
}
|
||
|
||
// 列表响应（Data 内层）
|
||
type ListResponse struct {
|
||
List interface{} `json:"list"`
|
||
Total int64 `json:"total"`
|
||
}
|
||
```
|
||
|
||
**前端 http.ts 已自动提取 `.data`**，所以组件中拿到的是 `Response.Data`。列表 API 返回 `{list, total}`，组件中需 `.list` 提取数组。
|
||
|
||
### 认证流程
|
||
|
||
```
|
||
Login(本地/LDAP fallback) → JWT Token → 前端 Zustand persist 存储
|
||
→ http.ts 自动注入 Bearer → JWTAuth 中间件验证 → AdminAuth 中间件（管理类路由）
|
||
```
|
||
|
||
### Agent 双通道架构
|
||
|
||
```
|
||
指标通道: ticker(10s) → collect(/proc) → POST /agent/report
|
||
任务通道: ticker(5s) → GET /agent/tasks/poll → execute → POST /agent/tasks/:id/result
|
||
```
|
||
|
||
### 告警引擎
|
||
|
||
- 内嵌后端 cron 定时器，每分钟扫描 AgentReport
|
||
- **资源阈值告警** — CPU/内存/磁盘超阈值（需配置规则）
|
||
- **主机离线告警** — 内置检测（3 分钟无数据上报即告警，不需配置规则）
|
||
- **端口告警** — 监控端口消失
|
||
|
||
## 开发规范
|
||
|
||
### ⛔ 文件大小红线
|
||
|
||
| 类型 | 上限 | 超出处理 |
|
||
|------|------|----------|
|
||
| Go handler | **400 行** | 按 sub-domain 拆分到独立文件（同一 package） |
|
||
| Go model | **300 行** | 按模块拆分 |
|
||
| React 组件 (.tsx) | **700 行** | 提取子组件到同目录 |
|
||
| 任何文件 | **700 行（硬上限）** | 必须拆分 |
|
||
|
||
```bash
|
||
# 检查超限文件
|
||
find backend -name "*.go" -not -path "*/vendor/*" | xargs wc -l | awk '$1 > 400 && $2 != "total"'
|
||
find frontend/src -name "*.tsx" -o -name "*.ts" | xargs wc -l | awk '$1 > 700 && $2 != "total"'
|
||
```
|
||
|
||
### ⛔ Go 代码规范
|
||
|
||
1. **所有 handler 返回必须用 `models.Response{Code:200, Data:...}` 包裹** — 前端 `http.ts` 从 `json.data` 取值，裸 `gin.H{}` 会导致前端拿到 undefined 静默失败
|
||
2. **编译命令**（每次必须）:
|
||
```bash
|
||
cd backend && unset http_proxy https_proxy && export GOPROXY=https://goproxy.cn,direct && GOTOOLCHAIN=local CGO_ENABLED=1 go build -o aiops-server ./cmd/
|
||
```
|
||
3. **新增 handler 不绑 model** — 用独立 request struct 接收 `ShouldBindJSON`，再映射到 GORM model
|
||
4. **GORM 指针字段必须解引用** — model 中 `*int`/`*string` 字段传给 `fmt.Sprintf` 时先 `*field`
|
||
5. **SQLite 必须 CGO_ENABLED=1**（macOS 默认开）
|
||
|
||
### ⛔ React 前端规范
|
||
|
||
1. **API 列表响应解包** — 后端返回 `{code, data: {list: T[], total: N}}`，http.ts 提取 `.data` 后仍是 `{list, total}` 对象，组件中必须 `.list` 提取数组
|
||
2. **禁止 `window.confirm()`/`alert()`** — 用 `ConfirmProvider`（`useConfirm()` hook）替代，用 `toast.error()`/`toast.success()` 替代 alert
|
||
3. **Radix Dialog 必须有 `<DialogDescription>`** — 至少加 `<DialogDescription className="sr-only">`
|
||
4. **Token 不在 localStorage** — 用 `useUserStore.getState().token`（Zustand persist）
|
||
5. **新增组件 2 步**: API 层(`services/api.ts` 添加) → 组件+路由(`App.tsx` 加 Route，`Sidebar.tsx` 加菜单)
|
||
|
||
### ⛔ UI 设计原则
|
||
|
||
- **能去掉的都去掉** — 不要多余边框、高亮框、装饰性分隔线
|
||
- **按钮文案 2-4 字** — "批量导入" 而非 "批量导入用户"
|
||
- **不留占位按钮** — 功能没做好就不放按钮，不要 `toast.info('开发中')`
|
||
- **页面打开即用** — 不需要额外"新建"按钮跳转
|
||
- **主题感知** — 用 CSS 变量 `bg-[var(--dg-bg-secondary)]`，不用硬编码颜色
|
||
- **表单操作按钮在字段下方** — 用 `mt-4 pt-4 border-t` 分隔，不放 Card 标题右侧
|
||
- **主动排查同类问题** — 用户报一个 UI 问题，全局搜索同类一次性修复
|
||
|
||
### ⛔ 通用开发流程
|
||
|
||
```
|
||
分析需求 → 写代码 → go build + tsc --noEmit → ./run.sh restart → 浏览器验证 → git commit + push
|
||
```
|
||
|
||
- **修改前端后必须在浏览器实际测试**，不能只说"刷新试试"
|
||
- **提交前编译验证**：后端 `go build ./...`，前端 `npx tsc --noEmit && npm run build`
|
||
- **Git 提交**: `git add -A && git commit -m "feat: 描述" && git push origin master`
|
||
- **大变更前先 git commit** — 方便回滚
|
||
- **开发日志**: 每次开发后更新 `docs/dev-log.md`
|
||
|
||
## 默认账号
|
||
|
||
| 用户名 | 密码 | 角色 |
|
||
|--------|------|------|
|
||
| admin | 123456 | 超级管理员 |
|
||
| ops01 | 123456 | 运维 |
|
||
| dev01 | 123456 | 开发 |
|
||
| logan | zxc987 | LDAP 用户 |
|
||
|
||
⚠️ **生产环境请修改默认密码**
|
||
|
||
## 主题系统
|
||
|
||
5 套预设主题（CSS 变量驱动）：
|
||
|
||
| Key | 名称 | 场景 |
|
||
|-----|------|------|
|
||
| `ocean-deep` | 深海蓝（默认） | 暗色主界面 |
|
||
| `light-professional` | 专业亮色 | 亮色模式 |
|
||
| `midnight-purple` | 午夜紫 | 个性化 |
|
||
| `forest-green` | 森林绿 | 个性化 |
|
||
| `dark-rose` | 暗夜玫红 | 个性化 |
|
||
|
||
所有组件必须用 `var(--dg-xxx)` 变量，禁止硬编码颜色值。
|
||
|
||
## 访问地址
|
||
|
||
- 前端：`http://localhost:5173`
|
||
- 后端：`http://localhost:8080`
|
||
- 健康检查：`http://localhost:8080/health`
|
||
- Agent 下载：`http://localhost:8080/agent/arch`
|
||
|
||
## 常见陷阱速查
|
||
|
||
| # | 陷阱 | 解决 |
|
||
|---|------|------|
|
||
| Go1 | go build 超时 | `unset proxy + GOPROXY=goproxy.cn + GOTOOLCHAIN=local` |
|
||
| Go2 | handler 不包裹 Response | 必须 `models.Response{Code:200, Data:...}` |
|
||
| Go3 | GORM 指针字段 | `*field` 解引用后再用 |
|
||
| Go4 | GORM First() 连续查带上次 ID | 用 `Take()` |
|
||
| Go5 | go map literal 不能有 duplicate key | 检查重复键 |
|
||
| FE1 | 白屏无堆栈 | 90% 是列表 `{list,total}` 未解包 |
|
||
| FE2 | confirm() 冻结自动化 | 用 `useConfirm()` |
|
||
| FE3 | Token 获取 | `useUserStore.getState().token`，不是 localStorage |
|
||
| FE4 | Radix Dialog 警告 | 必须有 `<DialogDescription>` |
|
||
| FE5 | browser_click 不触发 toggle | 改用 `browser_console` 注入 `.click()` |
|
||
| FE6 | API 字段名不匹配 | 前端 `base_dn` vs 后端 `ou_dn` 类型问题 |
|
||
|
||
## 注释规范
|
||
|
||
新增或修改代码必须写中文注释，注释结尾署名 `// Logan.Li`。
|
||
|
||
```go
|
||
// ListServers 获取服务器列表 // Logan.Li
|
||
func (h *ServerHandler) ListServers(c *gin.Context) {
|
||
// 业务逻辑
|
||
}
|
||
```
|
||
|
||
## 远程仓库
|
||
|
||
```
|
||
https://gitee.com/attacker/aiops.git
|
||
Git 用户: attacker / attacker@gitee.com
|
||
```
|