rlwj-lab/aiops
0
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f22e5751249992ae58170bacf0b22e4ad7562493
aiops/AGENTS.md
T

21 KiB
Raw Blame History

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 本地开发

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

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

后端本地单独运行：

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

前端本地单独运行：

cd frontend
npm install
npm run dev

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

./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

./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

./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 构建

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

4.6 一键发版

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 运行集成测试

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

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

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

5.3 前端类型与构建检查

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

5.4 后端静态检查

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. 统一响应格式：

    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.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=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（大变更前先提交，方便回滚）

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

Reference in new issue View Git Blame Copy Permalink