575 lines
25 KiB
Markdown
575 lines
25 KiB
Markdown
# AIOps 智能运维平台 — Agent 工作指南
|
||
|
||
> 本文档面向 AI 编程助手。阅读前默认不了解本项目。所有结论均来自项目实际文件，未做假设。
|
||
> 项目注释、文档、提交信息主要使用中文；新增/修改代码时注释末尾需署名 `// Logan.Li`。
|
||
|
||
---
|
||
|
||
## 0. 规格驱动开发（SDD，强制）
|
||
|
||
本项目采用 **Specification-Driven Development**。对于会改变行为、接口、数据或运维方式的工作，规格不是完成后的说明，而是实现前的约束和验收依据。
|
||
|
||
权威规范与模板：
|
||
|
||
- 流程、分级、质量门禁：`docs/specs/README.md`
|
||
- 新规格模板：`docs/specs/_template.md`
|
||
|
||
### 0.1 变更分级
|
||
|
||
| 级别 | 典型范围 | 规格要求 |
|
||
|------|----------|----------|
|
||
| S0 | 文案、注释、格式、无行为变化的机械修改 | 不创建规格文件，但必须验证受影响文件 |
|
||
| S1 | 局部缺陷修复、内部重构、单模块小改动 | 在任务计划中写清问题、约束、验收标准 |
|
||
| S2 | 新功能、跨模块流程、API/数据模型/配置变更 | 实现前必须创建或更新 `docs/specs/<domain>/<slug>.md` |
|
||
| S3 | 认证授权、账单、安全、数据库迁移、数据清理、生产部署 | 按 S2 执行，并补充风险、兼容性、可观测性、发布与回滚方案 |
|
||
|
||
级别取最高影响，不以代码行数判断。用户已给出明确需求时可以直接形成规格并继续；只有缺失选择会显著改变结果或扩大权限时才暂停询问。
|
||
|
||
### 0.2 强制工作流
|
||
|
||
1. **Discover**：先读现有代码、接口、模型、测试和工作区差异，以证据确认当前行为。
|
||
2. **Specify**：写清目标、非目标、行为规则、接口/数据契约、验收标准和风险；S2/S3 必须落盘。
|
||
3. **Design**：确定最小实现边界、复用点、迁移和回滚路径，禁止把未决问题留给编码阶段猜测。
|
||
4. **Implement**：按规格逐项实现；发现规格错误时先更新规格，再改代码，禁止静默偏离。
|
||
5. **Verify**：每条验收标准必须映射到自动化测试、构建检查或明确的人工验证证据。
|
||
6. **Deliver**：交付说明必须列出实现结果、验证证据、未覆盖项和剩余风险；S2/S3 同步更新规格状态。
|
||
|
||
### 0.3 不可绕过的门禁
|
||
|
||
- API 改动必须先明确请求、响应、错误码、权限和兼容策略，再同步前后端。
|
||
- 数据库改动必须使用版本化幂等迁移，说明数据回填、旧版本兼容、备份和回滚；禁止用启动期 `AutoMigrate` 代替生产迁移。
|
||
- 认证、审批、远程执行、账单和密钥相关变更必须包含权限边界、审计行为和失败路径。
|
||
- 监控、Agent 上报、日志等高频数据必须定义保留期、容量影响和清理可观测性。
|
||
- 金额必须明确原币、报告币、汇率来源和精度；时间必须明确时区、统计窗口和边界日期。
|
||
- 新增行为必须有测试。无法自动化的验收项要记录原因、人工步骤和结果，不能用“已检查”代替证据。
|
||
- 实现不得夹带规格外重构；发现必要的额外工作，应先补入规格的范围或后续事项。
|
||
|
||
### 0.4 完成定义（Definition of Done）
|
||
|
||
代码编译通过不等于完成。S1 及以上变更至少满足：规格/计划与实现一致、验收标准全部有证据、相关测试通过、错误与空状态可用、权限和兼容性已检查、文档已同步、发布与回滚可执行。任一项缺失时必须明确标记未完成，不得宣称任务已完成。
|
||
|
||
---
|
||
|
||
## 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.25 + Gin + GORM | HTTP API + WebSocket + 前端静态资源服务 |
|
||
| `agent/` | Go 1.22 模块（Go 1.25 工具链，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.25.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.25+
|
||
- **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（通用 UI）+ Simple Icons（技术品牌按需导入）
|
||
- **编辑器**：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=auto 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`。
|
||
7. 通用操作、状态和导航使用 `lucide-react`；云厂商、CI/CD、监控和中间件等产品实体使用 `TechnologyBrandIcon` 或 `CloudBrandIcon`。
|
||
8. 技术品牌图标从 `simple-icons` 按需导入并随构建产物发布；禁止使用 CDN、远程图片 URL 或 `master` 分支资源。云厂商缺失图标使用仓库本地 SVG 或官方资源。
|
||
|
||
### 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.4.1 数据保留与清理（强制）
|
||
|
||
- 对监控指标、Agent 原始上报、日志和审计等时序/高频数据，必须实现可配置的保留期与定时清理；禁止无限累积。
|
||
- 清理任务不能只调用 `DELETE`：必须记录并校验受影响行数，处理关联的明细/索引数据，并将执行结果写入系统任务状态，确保清理可审计、失败可发现。
|
||
- SQLite 的 `DELETE` 仅释放可复用页，不会缩小 `sqlite3.db` 文件。生产维护窗口内必须在备份成功、应用停写后执行 `PRAGMA wal_checkpoint(TRUNCATE)` 和 `VACUUM`，确认 WAL 与主库空间实际回收；不得在高峰期或存在活跃写入时执行 `VACUUM`。
|
||
- 大表不得在每次应用启动时无条件触发全表重建。结构变更必须使用可追踪、幂等的迁移，并评估 SQLite 下 GORM `AutoMigrate` 的重建与 WAL 写放大风险。
|
||
|
||
### 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=auto` |
|
||
| 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`（大变更前先提交，方便回滚）
|
||
|
||
> 代码改完不算完成，端到端验证通过才算完成。
|