rlwj-lab/aiops
0
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 同步 README 与 docs 文档至当前代码状态

Browse Source 
- README 补充 PageShell、i18n、Agent CLI、中间件监控等近期功能
- project-structure 重写 api/pages/locales 目录约定
- development-guide 新增 PageShell 与 i18n 开发规范
- PROJECT_SUMMARY 整体重写，移除过时 internal/ 结构
- docs/README 新增 Agent CLI 设计文档索引与近期变更摘要
- dev-log 追加 2026-07-01 变更记录
This commit is contained in:
Logan committed 2026-07-01 12:50:58 +08:00
1 parent e363ded445
commit 4cb0e62857
6 files changed
+299 -277
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+32 -12
View File
@@ -6,8 +6,9 @@
### 前端
- React 19 + TypeScript + Vite
- Tailwind CSS + shadcn/ui
- Tailwind CSS + shadcn/ui + **PageShell 统一页面骨架**（`dg-page*` 设计令牌）
- Zustand (状态管理) / TanStack Query (数据获取)
- i18next 国际化（中/英双语，`zh-CN` / `en-US`）
- Recharts (图表) / Lucide React (图标)
- CodeMirror 6 (YAML 编辑器) / xterm.js (WebSocket 终端)
@@ -18,6 +19,7 @@
- WebSocket (Gorilla) / PTY 终端 (creack/pty)
- 自研轻量 Kubernetes HTTP 客户端（channel.k8s.io WebSocket 协议）
- go:embed 嵌入前端静态资源（单二进制 / 单容器部署）
- Agent CLI 引擎（`pkg/agentcli/`）：ReAct + Evolver + 双协议 LLM（OpenAI / Anthropic）
### Agent
- Go 1.24 静态编译 (CGO_ENABLED=0)
@@ -115,20 +117,30 @@ curl http://localhost:8080/version # 查看运行版本
```
aiops/
├── frontend/ # 前端 (React + TypeScript)
│ ├── src/components/ # dashboard/server/k8s/monitor/deploy/aiops...
│ ├── src/
│ │ ├── api/ # API 封装（按菜单域拆分：server/k8s/monitor/deploy/...）
│ │ ├── pages/ # 复杂页面（monitor/approval/audit 等域级页面）
│ │ ├── components/ # 业务组件 + layout（PageShell/PageTabs/...）
│ │ ├── locales/ # i18n 翻译文件 (zh-CN / en-US)
│ │ ├── i18n/ # i18next 初始化
│ │ ├── hooks/ # 自定义 Hooks（useTheme / useConfirm 等）
│ │ ├── store/ # Zustand 状态管理
│ │ └── types/ # TypeScript 类型
│ └── Dockerfile # [legacy] 独立 Nginx 镜像，Compose 已改用 embed
│
├── backend/ # 后端 (Go + Gin)
│ ├── main.go # 应用入口
│ ├── embed.go # go:embed 前端静态资源
│ ├── static/ # 前端构建产物（embed 目标目录）
│ ├── controller/ # HTTP 处理器
│ ├── controller/ # HTTP 处理器（60+ 文件按领域拆分）
│ ├── router/ # 路由注册
│ ├── model/ # GORM 数据模型
│ ├── pkg/ # database/kubernetesclient/remoteexec/...
│ ├── model/ # GORM 数据模型（86+ 表）
│ ├── pkg/ # agentcli/remoteexec/kubernetesclient/...
│ └── Dockerfile # [legacy] 分离式后端镜像
│
├── agent/ # 监控 Agent（独立 Go module）
├── docs/ # 开发文档
│ └── agent/ # Agent CLI 设计文档集
├── deploy/kubernetes/ # K8s 部署清单 (devops 命名空间)
├── docker-compose.yml # MySQL + Redis + AIOps embed（3 容器）
├── docker-compose.k8s.yml # 单应用容器（连接外部 DB）
@@ -143,13 +155,19 @@ aiops/
|------|------|
| 仪表盘 | 成本统计、告警聚合、Top 资源、SSL 提醒、趋势图表 |
| 资产管理 | 服务器 CRUD、批量导入、WebShell、云账号/域名/账单 |
| Kubernetes 管理 | 多集群、Deployment 三模式编辑器、Pod 终端/文件浏览、事件聚合 |
| 应用发布 | CI/CD 流水线、发布配置、SSH + K8s 双路径部署 |
| 监控中心 | 监控大屏、主机指标、告警引擎、飞书/钉钉通知 |
| 自动化运维 | 定时任务、脚本库、远程执行（Go-native SSH） |
| AIOps 智能 | AI 助手、告警分析、容量预测 |
| Kubernetes 管理 | 多集群、Deployment 三模式编辑器、Pod 终端/文件浏览、拓扑图、国际化 |
| 应用发布 | CI/CD 流水线、发布配置、SSH + K8s 双路径部署、凭证管理 |
| 监控中心 | 监控大屏、主机指标、SNMP/站点拨测、**中间件监控**（Redis/MySQL 直连采集）、日志中心（Loki/ES）、**日志告警引擎** |
| 自动化运维 | 定时任务、脚本库、**远程执行**（Go-native SSH，执行/上传） |
| AIOps 智能 | AI 助手、告警分析、容量预测、**Agent CLI**（ReAct + WebSocket 实时回传 + 终端审计回放） |
| 资源申请 | 云服务器/应用部署申请审批 |
| 系统管理 | 用户/角色、操作审计、凭证配置 |
| 系统管理 | 用户/角色、操作审计、终端会话审计、凭证配置（7 种类型）、大模型设置（OpenAI + Anthropic 双协议） |
### UI 与体验
- **PageShell 设计系统**：全站统一页面骨架（标题区 / 指标条 / 工具栏 / Tab / 内容区），CSS 变量驱动
- **7 套主题**：跟随系统、深海蓝、明亮白 + One Dark / Dracula / Tokyo Night / Catppuccin
- **国际化**：i18next 框架，已覆盖 dashboard / server / alert / approval / audit / deploy / k8s 等模块
## 文档
@@ -159,9 +177,11 @@ aiops/
|------|------|
| [快速开始](./docs/quick-start.md) | 环境准备、本地开发 |
| [部署指南](./docs/deployment.md) | 二进制 / Docker / K8s / 版本发版 |
| [开发规范](./docs/development-guide.md) | 代码规范、Git 工作流 |
| [开发规范](./docs/development-guide.md) | 代码规范、Git 工作流、PageShell / i18n |
| [项目结构](./docs/project-structure.md) | 目录结构说明 |
| [Agent CLI 设计](./docs/agent/00-README.md) | ReAct 引擎、Evolver、安全系统 |
| [CLAUDE.md](./CLAUDE.md) | AI 助手指引（完整命令参考） |
| [AGENTS.md](./AGENTS.md) | AI Agent 工作指南 |
## License
docs/PROJECT_SUMMARY.md
+86 -227
View File
@@ -1,266 +1,125 @@
# AIOps 智能运维平台 - 项目总结
> 最新目录结构见 [project-structure.md](./project-structure.md)，部署见 [deployment.md](./deployment.md)。
## 项目概述
AIOps 是一个专业的 AIOps 智能运维平台，包含完整的前后端代码，支持云平台服务器资产管理、Kubernetes 集群管理、应用发布、监控告警、审批流程等核心功能。
AIOps 是一个企业级云原生智能运维平台，包含完整的前后端代码与独立 Agent 模块。平台聚焦资产管理、Kubernetes 管理、应用发布、监控告警、自动化运维、审批流程和 AI 智能分析。
## 项目结构
```
/mnt/okcomputer/output/
├── frontend/ # 前端项目 (React + TypeScript + Vite)
│ ├── src/
│ │ ├── components/ # 组件目录
│ │ │ ├── layout/ # 布局组件
│ │ │ ├── dashboard/ # 仪表盘组件
│ │ │ ├── server/ # 服务器管理组件
│ │ │ ├── cloud/ # 云资源管理组件
│ │ │ ├── k8s/ # K8s 管理组件
│ │ │ ├── monitor/ # 监控告警组件
│ │ │ ├── deploy/ # 应用发布组件
│ │ │ ├── approval/ # 审批流程组件
│ │ │ ├── navigation/ # 站内导航组件
│ │ │ ├── automation/ # 自动化运维组件
│ │ │ ├── system/ # 系统管理组件
│ │ │ └── ui/ # UI 组件库
│ │ ├── mocks/ # Mock 数据
│ │ ├── store/ # 状态管理
│ │ ├── types/ # TypeScript 类型定义
│ │ ├── hooks/ # 自定义 Hooks
│ │ ├── lib/ # 工具函数
│ │ ├── App.tsx # 应用入口
│ │ └── main.tsx # 主入口
│ ├── package.json
│ ├── vite.config.ts
│ ├── tailwind.config.js
│ └── ...
aiops/
├── frontend/ # React 19 + TypeScript + Vite
│ ├── src/api/ # API 封装（按菜单域拆分）
│ ├── src/pages/ # 复杂域级页面
│ ├── src/components/ # 业务组件 + layout（PageShell 等）
│ ├── src/locales/ # i18n 翻译 (zh-CN / en-US)
│ └── src/i18n/ # i18next 初始化
│
├── backend/ # 后端项目 (Go + Gin)
│ ├── cmd/
│ │ └── main.go # 应用入口
│ ├── internal/
│ │ ├── api/
│ │ │ ├── handlers/ # HTTP 处理器
│ │ │ ├── middleware/ # 中间件
│ │ │ └── routes/ # 路由注册
│ │ ├── config/ # 配置管理
│ │ └── models/ # 数据模型
│ ├── pkg/
│ │ ├── database/ # 数据库连接
│ │ └── logger/ # 日志工具
│ ├── scripts/ # 脚本文件
│ ├── config.yaml.example # 配置文件示例
│ ├── docker-compose.yml # Docker Compose 配置
│ ├── Dockerfile # Docker 构建文件
│ ├── Makefile # 构建脚本
│ ├── nginx.conf # Nginx 配置
│ ├── go.mod # Go 模块定义
│ └── README.md # 项目说明
├── backend/ # Go 1.24 + Gin + GORM
│ ├── main.go # 应用入口
│ ├── embed.go # go:embed 前端静态资源
│ ├── controller/ # HTTP 处理器（60+ 文件）
│ ├── model/ # GORM 数据模型（86+ 表）
│ ├── router/ # 路由注册
│ └── pkg/ # agentcli / remoteexec / kubernetesclient 等
│
├── BACKEND_SUMMARY.md # 后端项目详细说明
└── PROJECT_SUMMARY.md # 项目总结（本文档）
├── agent/ # 监控 Agent（独立 Go module）
├── docs/ # 开发文档 + Agent CLI 设计文档集
├── deploy/kubernetes/ # K8s 部署清单
├── Dockerfile.embed # 推荐生产镜像
├── docker-compose.yml # 3 容器部署
└── run.sh # 统一入口脚本
```
## 功能特性
### 1. 仪表盘
- 资源概览统计
- 成本费用分析（按云平台、按月维度）
- 告警消息展示
- 资源概览统计、成本费用分析
- Top5 CPU/内存/磁盘使用率
- 证书到期提醒
- 最近告警和发布记录
- 证书到期提醒、最近告警和发布记录
- 国际化支持（dashboard 命名空间）
### 2. 服务器资产管理
- 服务器列表管理
- 批量导入（云主机导入、Excel 导入）
- 远程 WebShell
- 服务器列表 CRUD、批量导入（云主机 / Excel）
- 远程 WebShell（WebSocket + PTY）
- 云账号 / 域名 / 区域 / 云平台 / 账单管理
- 资源模型管理
- 云账号管理
- 域名管理（SSL 证书到期提醒）
- 区域管理
- 云平台管理
### 3. Kubernetes 集群管理
- 集群管理
- 节点管理
- Pod 管理
- Deployment 详情
- Service 详情
- Ingress 详情
- 拓扑架构图
- 多集群接入、节点 / Pod / Workload 管理
- Deployment 三模式编辑器（表单 / YAML / 可视化）
- Pod 终端 / 文件浏览、拓扑架构图
- 国际化支持（k8s 命名空间，184+ 翻译键）
### 4. 监控告警
- 告警规则管理
- 告警事件处理
- 通知渠道配置
- 指标数据展示
- 告警规则 / 事件 / 通知渠道 / 静默规则
- 主机指标采集（Agent 双通道）、SNMP / 站点拨测
- **中间件监控**：Redis / MySQL 后端直连采集
- **日志中心**：Loki / ES 统一查询、日志告警引擎
- Prometheus / Zabbix / Grafana 数据源代理
### 5. 应用发布
- CI/CD 流水线管理
- 发布审批流程
- 发布记录追踪
- 回滚功能
- CI/CD 流水线（GitLab CI 风格可视化）
- 发布配置 / 环境 / 权限管理
- SSH + K8s 双路径部署
- 凭证管理（7 种统一类型）
### 6. 自动化运维
- 定时任务（CronJob）
- 脚本库管理
- 定时任务（CronJob）、脚本库管理
- **远程执行**（Go-native SSH，执行 / 上传）
- 任务执行记录
- Playbook 编排
### 7. 审批流程
- 审批模板管理
- 审批流程创建
- 审批/驳回操作
### 7. AIOps 智能
- AI 智能助手、告警分析、容量预测
- **Agent CLI**：ReAct 16 轮循环 + WebSocket 实时回传 + Evolver 自进化
- 大模型设置（OpenAI 兼容 + Anthropic Messages 双协议）
- 终端审计回放
### 8. 站内导航
- 导航分组管理
- 导航链接管理
- 收藏功能
### 8. 审批流程
- 审批模板 / 流程 / 分类 / 权限管理
- 云服务器 / 应用部署申请
- 国际化支持（approval 命名空间）
### 9. 审计日志
- 操作日志记录
- 日志查询、筛选
- 日志导出
- 日志统计
- 日志清理
### 9. 系统管理
- 用户 / 角色 / RBAC 权限
- 操作审计 / 登录日志 / 终端会话审计
- LDAP 集成、凭证配置
- 7 套主题（CSS 变量驱动）
### 10. 系统管理
- 用户管理
- 角色权限管理
- 系统设置
## UI 设计系统
## 技术栈
- **PageShell**：全站统一页面骨架（标题 / 指标条 / 工具栏 / Tab / 内容区）
- **CSS 设计令牌**：`dg-page*` 类名 + `var(--dg-xxx)` 主题变量
- **7 套主题**：跟随系统、深海蓝、明亮白 + One Dark / Dracula / Tokyo Night / Catppuccin
### 前端
- **框架**: React 18
- **语言**: TypeScript
- **构建工具**: Vite
- **样式**: Tailwind CSS
- **UI 组件**: shadcn/ui
- **状态管理**: Zustand
- **数据获取**: TanStack Query (React Query)
- **路由**: React Router
- **图表**: Recharts
- **图标**: Lucide React
## 技术亮点
### 后端
- **框架**: Gin Web Framework
- **语言**: Go 1.21+
- **ORM**: GORM
- **数据库**: MySQL 8.0+ / PostgreSQL 14+
- **缓存**: Redis (可选)
- **认证**: JWT
- **日志**: Zap
- **配置**: Viper
- **文档**: Swagger
| 特性 | 说明 |
|------|------|
| 单二进制部署 | go:embed 嵌入前端，零外部依赖 |
| 轻量 K8s 客户端 | 自研 HTTP 客户端，不引入 client-go |
| Go-native SSH | 替代 Ansible，零新增依赖 |
| Agent 双通道 | 指标 10s 上报 + 任务 5s 轮询 |
| 凭证驱动 | 7 种凭证类型统一加密存储 |
| 工具懒加载 | kubectl / maven / helm 首次使用自动下载 |
| 国际化 | i18next 中/英双语，按模块命名空间管理 |
## 快速开始
## 部署方式
### 前端
| 方式 | 命令 | 说明 |
|------|------|------|
| 本地开发 | `./run.sh dev` | 5173 + 8080 热重载 |
| 独立二进制 | `./run.sh build` | 产出 `./aiops` |
| Docker Compose | `./run.sh docker up` | MySQL + Redis + AIOps |
| Kubernetes | `./run.sh kubernetes deploy` | devops 命名空间 |
| 一键发版 | `./run.sh release v1.5.0` | tag + 镜像 + 推送 |
```bash
cd app
## 相关文档
# 安装依赖
npm install
# 启动开发服务器
npm run dev
# 构建生产版本
npm run build
```
### 后端
```bash
cd backend
# 安装依赖
go mod download
# 复制配置文件
cp config.yaml.example config.yaml
# 启动数据库
docker-compose up -d mysql redis
# 运行（推荐统一入口）
./run.sh dev
# 或仅后端
cd backend && go run .
```
## API 文档
启动后端服务后，访问 http://localhost:8080/swagger/index.html 查看 Swagger API 文档。
## 部署
> 最新部署方式见 [deployment.md](./deployment.md)。
```bash
# 独立二进制
./run.sh build tag v1.5.0 && ./aiops --mode local
# Docker Compose（embed 单容器 + MySQL + Redis）
./run.sh docker up
# Kubernetes
./run.sh kubernetes deploy
# 发版推送 Docker Hub
./run.sh release v1.5.0 # → lghost/aiops:v1.5.0
```
## 默认账号
- **用户名**: admin
- **密码**: 123456
## 注意事项
1. 生产环境请修改默认的 JWT Secret 和数据库密码
2. 建议启用 HTTPS
3. 配置适当的日志轮转策略
4. 定期备份数据库
5. 启用审计日志功能
## 开发计划
### 已完成
- [x] 前端项目搭建
- [x] 后端项目搭建
- [x] 用户认证系统
- [x] 服务器资产管理
- [x] K8s 集群管理
- [x] 监控告警系统
- [x] 应用发布系统
- [x] 自动化运维
- [x] 审批流程
- [x] 站内导航
- [x] 审计日志
### 待完成
- [ ] WebSocket 实时通知
- [ ] 云平台 API 集成
- [ ] K8s 集群实际连接
- [ ] 告警通知渠道集成
- [ ] 流水线实际执行
- [ ] 自动化任务调度
- [ ] 更多图表和报表
- [ ] 多语言支持
## 贡献指南
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/xxx`)
3. 提交更改 (`git commit -am 'Add xxx'`)
4. 推送到分支 (`git push origin feature/xxx`)
5. 创建 Pull Request
## 许可证
MIT License
- [开发文档索引](./README.md)
- [Agent CLI 设计集](./agent/00-README.md)
- [后端摘要](./BACKEND_SUMMARY.md)
- [API 接口](./api-reference.md)
- [数据库设计](./database-schema.md)
docs/README.md
+16 -1
View File
@@ -9,7 +9,7 @@
| [快速开始](./quick-start.md) | 环境准备、本地开发、常见问题 |
| [部署指南](./deployment.md) | 二进制 / Docker / K8s 部署、版本发版、镜像推送 |
| [项目结构](./project-structure.md) | 前后端目录结构说明 |
| [开发规范](./development-guide.md) | 代码规范、Git 工作流 |
| [开发规范](./development-guide.md) | 代码规范、Git 工作流、PageShell / i18n |
| [API 接口](./api-reference.md) | 后端 API 接口文档 |
| [数据库设计](./database-schema.md) | 数据模型和表结构 |
| [开发日志](./dev-log.md) | 详细开发日志（按日期记录） |
@@ -19,6 +19,7 @@
| 文档 | 说明 |
|------|------|
| [Agent CLI 设计集](./agent/00-README.md) | ReAct 引擎、Evolver、安全系统、会话管理（10 篇） |
| [PDD 计划](./PDD_PLAN.md) | 产品驱动开发计划 |
| [项目摘要](./PROJECT_SUMMARY.md) | 项目整体概述 |
| [后端摘要](./BACKEND_SUMMARY.md) | 后端架构概述 |
@@ -29,8 +30,22 @@
|------|------|
| [README.md](../README.md) | 项目主说明 |
| [CLAUDE.md](../CLAUDE.md) | AI 助手指引（完整命令与规范） |
| [AGENTS.md](../AGENTS.md) | AI Agent 工作指南 |
| [ROADMAP.md](../ROADMAP.md) | K8s 管理功能演进路线图 |
## 近期重要变更（2026-06 ~ 2026-07）
| 变更 | 说明 |
|------|------|
| PageShell 设计系统 | 全站统一页面骨架，`dg-page*` CSS 变量 + 7 套主题 |
| 前端架构对齐 | `api/` + `pages/` 按菜单域拆分，复杂页面迁入 `pages/` |
| 国际化 (i18n) | i18next 中/英双语，已覆盖 dashboard / server / alert / approval / audit / deploy / k8s |
| Agent CLI 优化 | 终端审计回放、ssh-key 连接修复、会话管理增强 |
| 中间件监控 | Redis / MySQL 后端直连采集引擎 |
| 日志告警 | AlertEngine 支持 `type=log` 规则，查询 Loki / ES 触发/恢复 |
| 远程执行 | 新增远程执行页（执行/上传），移除 ansible 命名 |
| 大模型双协议 | OpenAI 兼容 + Anthropic Messages 协议接入 |
## 部署速查
| 场景 | 命令 |
docs/dev-log.md
+18
View File
@@ -1,5 +1,23 @@
# AIOps 开发日志
## 2026-07-01 文档同步 + PageShell 设计系统
### 完成项
| 项目 | 状态 | 说明 |
|------|------|------|
| PageShell 设计系统 | ✅ | 全站统一页面骨架，`dg-page*` CSS 变量 + 7 套主题 |
| Agent CLI 优化 | ✅ | 终端审计回放、ssh-key 连接修复、会话管理增强 |
| 国际化 (i18n) | ✅ | dashboard / server / alert / approval / audit / deploy / k8s 模块迁移 |
| 中间件监控 | ✅ | Redis / MySQL 后端直连采集引擎 |
| 日志告警引擎 | ✅ | AlertEngine 支持 type=log，查询 Loki / ES 触发/恢复 |
| 远程执行页 | ✅ | 执行/上传功能，移除 ansible 命名 |
| 大模型双协议 | ✅ | OpenAI 兼容 + Anthropic Messages 协议 |
| 前端架构对齐 | ✅ | api/ + pages/ 按菜单域拆分 |
| 文档更新 | ✅ | README + docs/ 同步至当前代码状态 |
---
## 2026-06-13 项目初始化
### 完成项
docs/development-guide.md
+76 -9
View File
@@ -52,7 +52,8 @@ feat: 添加服务器批量导入功能
| `router/` | 路由注册 |
| `service/` / `repository/` | 业务逻辑 / 数据访问 |
| `pkg/database/` | 数据库连接 + AutoMigrate |
| `pkg/logger/` | 日志工具 |
| `pkg/agentcli/` | Agent CLI 引擎（ReAct + Evolver） |
| `pkg/remoteexec/` | Go-native SSH 远程执行 |
| `static/` | 前端 embed 静态资源 |
### 命名规范
@@ -121,6 +122,7 @@ func (h *ServerHandler) CreateServer(c *gin.Context) {
- Go 编译前设置 `GOPROXY=https://goproxy.cn,direct`
- SQLite 需要 `CGO_ENABLED=1`
- JWT 使用 `golang-jwt/jwt/v5`，`jwt.TimeFunc()` 已移除，用 `time.Now()`
- 新增或修改代码注释末尾署名 `// Logan.Li`
## 前端规范（React + TypeScript）
@@ -128,14 +130,17 @@ func (h *ServerHandler) CreateServer(c *gin.Context) {
| 目录 | 职责 |
|------|------|
| `src/components/*/` | 业务组件 |
| `src/api/` | API 封装（按菜单域分子目录，`http.ts` 自动解包 `.data`） |
| `src/pages/` | 复杂域级页面（多 Tab / 多子面板） |
| `src/components/*/` | 可复用业务组件 |
| `src/components/layout/` | PageShell / Sidebar / Header / ThemePicker |
| `src/components/ui/` | shadcn/ui 基础组件 |
| `src/locales/` | i18n 翻译文件（zh-CN.json / en-US.json） |
| `src/i18n/` | i18next 初始化 |
| `src/hooks/` | 自定义 Hooks |
| `src/lib/` | 工具函数 |
| `src/services/` | API 封装 |
| `src/store/` | Zustand 状态管理 |
| `src/types/` | TypeScript 类型 |
| `src/mocks/` | Mock 数据 |
| `src/types/` | TypeScript 类型（按域拆分） |
| `src/utils/` | 主题 / 权限 / 导出等工具 |
### 命名规范
@@ -143,12 +148,65 @@ func (h *ServerHandler) CreateServer(c *gin.Context) {
- 工具文件：`camelCase.ts`（如 `formatDate.ts`）
- 组件名：`PascalCase`
### PageShell 页面骨架
新页面优先使用 `PageShell` 统一布局：
```tsx
import { PageShell } from '@/components/layout/PageShell';
import { useTranslation } from 'react-i18next';
export function MyPage() {
const { t } = useTranslation();
return (
<PageShell
title={t('myModule.title')}
subtitle={t('myModule.subtitle')}
icon={<ServerIcon className="h-5 w-5" />}
actions={<Button>操作</Button>}
toolbar={<SearchInput />}
tabs={[{ id: 'list', label: t('myModule.tabList') }]}
activeTab="list"
onTabChange={() => {}}
variant="list"
>
{/* 页面内容 */}
</PageShell>
);
}
```
`variant` 取值：`default` | `list` | `config` | `workspace`。
### 国际化 (i18n)
- 框架：i18next + react-i18next
- 语言：`zh-CN`（默认）/ `en-US`
- 翻译文件：`src/locales/zh-CN.json` / `en-US.json`
- 命名空间按模块划分：`common`、`menu`、`dashboard`、`server`、`alert`、`approval`、`audit`、`deploy`、`k8s` 等
新增文案规范：
```tsx
// ✅ 使用翻译键
const { t } = useTranslation();
<span>{t('server.batchImport')}</span>
// ❌ 禁止硬编码中文（已迁移模块）
<span>批量导入</span>
```
双语同步：修改 `zh-CN.json` 时必须同步更新 `en-US.json`。
### UI 设计原则
- 能去掉的装饰都去掉（无边框、无多余分隔线）
- 选中态用 `bg-surface-active`，不用彩色高亮
- 页面打开即用，不需要额外的"新建"按钮跳转
- 操作成功不弹 toast，仅在失败时提示
- 主题感知 — 使用 CSS 变量 `var(--dg-xxx)`，不硬编码颜色
- 按钮文案 2–4 字
- 禁止 `window.confirm()` / `alert()`，使用 `useConfirm()` + `toast`
- Radix Dialog 必须包含 `<DialogDescription>`
### API 调用
@@ -156,7 +214,9 @@ func (h *ServerHandler) CreateServer(c *gin.Context) {
```typescript
// 开发环境请求会被代理到 http://localhost:8080
fetch('/api/v1/servers')
// http.ts 已自动提取 Response.Data，列表返回 { list, total }
import { getServers } from '@/api/server';
const { list, total } = await getServers({ page: 1 });
```
## 测试
@@ -165,7 +225,8 @@ fetch('/api/v1/servers')
```bash
cd backend
go test -v ./...
go vet ./...
go build -o aiops-server .
```
### 前端构建测试
@@ -183,6 +244,12 @@ npx tsc --noEmit # 类型检查（提交前零错误）
./aiops version
```
### 集成测试
```bash
python3 tests/integration_test.py --host localhost --port 8080
```
## 日志
| 级别 | 使用场景 |
docs/project-structure.md
+71 -28
View File
@@ -6,25 +6,45 @@
aiops/
├── frontend/ # 前端 (React 19 + TypeScript + Vite)
│ ├── src/
│ │ ├── components/ # 业务组件（单文件 <700 行）
│ │ │ ├── agent/ # Agent 监控
│ │ │ ├── aiops/ # AI 智能运维
│ │ ├── api/ # API 封装（按菜单域拆分，http.ts 自动解包 .data）
│ │ │ ├── server/ # 服务器 / 区域 / 资源模型
│ │ │ ├── kubernetes/ # K8s 集群 / Pod / Workload
│ │ │ ├── monitor/ # 告警 / 指标 / 数据源 / Grafana
│ │ │ ├── log/ # 日志中心（Loki / ES 代理查询）
│ │ │ ├── deploy/ # 流水线 / 发布 / 凭证
│ │ │ ├── task/ # 定时任务 / 脚本库 / 远程执行
│ │ │ ├── approval/ # 审批流程
│ │ │ ├── automation/ # 自动化运维
│ │ │ ├── cloud/ # 云平台管理
│ │ │ ├── audit/ # 操作审计 / 终端审计
│ │ │ ├── aiops/ # AI 助手 / Agent CLI
│ │ │ ├── cloud/ # 云账号 / 域名 / 账单
│ │ │ ├── system/ # 用户 / 角色
│ │ │ └── agent/ # Agent 监控
│ │ ├── pages/ # 复杂域级页面（从 components 迁入）
│ │ │ ├── monitor/ # 监控中心 / 主机监控 / 中间件 / SNMP / 站点
│ │ │ ├── approval/ # 审批分类 / 流程 / 权限
│ │ │ └── audit/ # 操作审计 / 登录日志 / 终端审计回放
│ │ ├── components/ # 业务组件 + 布局
│ │ │ ├── layout/ # PageShell / Sidebar / Header / ThemePicker
│ │ │ ├── dashboard/ # 仪表盘
│ │ │ ├── deploy/ # CI/CD 部署
│ │ │ ├── k8s/ # K8s 集群管理
│ │ │ ├── monitor/ # 监控告警
│ │ │ ├── server/ # 服务器管理
│ │ │ ├── k8s/ # K8s 集群管理
│ │ │ ├── monitor/ # 告警中心 / 日志中心 / 数据源
│ │ │ ├── deploy/ # CI/CD 流水线
│ │ │ ├── task/ # 定时任务 / 脚本库 / 远程执行
│ │ │ ├── aiops/ # AI 助手 / Agent CLI / 大模型设置
│ │ │ ├── cloud/ # 云资源
│ │ │ ├── approval/ # 审批组件（对话框 / 流程图）
│ │ │ ├── system/ # 系统管理
│ │ │ └── ui/ # shadcn/ui 基础组件
│ │ ├── hooks/ # 自定义 Hooks
│ │ ├── services/ # API 封装 (api.ts / http.ts)
│ │ ├── locales/ # i18n 翻译 (zh-CN.json / en-US.json)
│ │ ├── i18n/ # i18next 初始化
│ │ ├── hooks/ # useTheme / useConfirm / usePermission 等
│ │ ├── store/ # Zustand 状态管理
│ │ └── types/ # TypeScript 类型
│ │ ├── types/ # TypeScript 类型（按域拆分）
│ │ ├── utils/ # 主题 / 权限 / 导出 / 校验工具
│ │ └── lib/ # 通用工具（cn 等）
│ ├── package.json
│ ├── vite.config.ts
│ ├── vite.config.ts # 代理 /api、/ws、/health、/version 到 :8080
│ └── Dockerfile # [legacy] 独立 Nginx 镜像
│
├── backend/ # 后端 (Go 1.24 + Gin + GORM)
@@ -32,10 +52,10 @@ aiops/
│ ├── embed.go # go:embed 前端静态资源
│ ├── static/ # 前端构建产物（embed 目录）
│ ├── config/ # Viper 配置加载
│ ├── controller/ # HTTP 处理器
│ ├── middleware/ # JWT / 日志 / CORS
│ ├── router/ # 路由注册
│ ├── model/ # GORM 数据模型
│ ├── controller/ # HTTP 处理器（60+ 文件按领域拆分）
│ ├── middleware/ # JWT / Admin / PipelineAccess / CORS / 日志
│ ├── router/ # 路由注册（~1000 行）
│ ├── model/ # GORM 数据模型（86+ 表）
│ ├── dto/ # 请求/响应 DTO
│ ├── service/ # 业务逻辑层
│ ├── repository/ # 数据访问层
@@ -43,8 +63,12 @@ aiops/
│ ├── pkg/ # 公共包
│ │ ├── database/ # DB 连接 + AutoMigrate
│ │ ├── kubernetesclient/ # 轻量 K8s 客户端
│ │ ├── remoteexec/ # Go-native SSH
│ │ └── toolinstaller/ # 工具懒加载
│ │ ├── remoteexec/ # Go-native SSH 远程执行
│ │ ├── agentcli/ # AI 运维 Agent 引擎（ReAct + Evolver）
│ │ ├── toolinstaller/ # 工具懒加载（kubectl/maven/helm 等）
│ │ ├── redis/ # Redis 连接
│ │ ├── logger/ # Zap 日志
│ │ └── wshub/ # WebSocket Hub
│ ├── config.yaml # 默认配置
│ └── Dockerfile # [legacy] 分离式后端镜像
│
@@ -55,13 +79,9 @@ aiops/
│ ├── reporter/ # HTTP 上报
│ └── deploy/ # install.sh + systemd
│
├── docs/ # 开发文档
│ └── agent/ # Agent CLI 设计文档集（10 篇）
├── deploy/kubernetes/ # K8s 清单 (devops 命名空间)
│ ├── namespace.yaml
│ ├── deployment.yaml # embed 单容器, lghost/aiops:<tag>
│ ├── mysql.yaml / redis.yaml
│ └── ...
│
├── docs/ # 开发文档（本目录）
├── docker-compose.yml # MySQL + Redis + AIOps embed
├── docker-compose.k8s.yml # 单应用 + 外部 DB
├── Dockerfile.embed # embed 单容器镜像（推荐）
@@ -70,6 +90,28 @@ aiops/
└── README.md
```
## 前端目录约定
### api/ vs pages/ vs components/
| 目录 | 职责 | 示例 |
|------|------|------|
| `api/` | HTTP 请求封装，按菜单域分子目录 | `api/monitor/alert.ts`、`api/task/remote-exec.ts` |
| `pages/` | 复杂多 Tab / 多子面板页面，域级路由入口 | `pages/monitor/HostMonitor.tsx`、`pages/audit/TerminalAuditTab.tsx` |
| `components/` | 可复用业务组件、对话框、列表项 | `components/monitor/log-center/LogCenter.tsx` |
> 迁移原则：简单 CRUD 页面留在 `components/`，多 Tab + 子模块拆分的复杂页面迁入 `pages/`。
### 布局与设计系统
| 组件 / 类名 | 说明 |
|-------------|------|
| `PageShell` | 统一页面骨架：标题 / 指标条 / 工具栏 / Tab / 内容区 |
| `PageTabs` | Tab 切换栏（`dg-page-tab` 样式） |
| `ContentPanel` | 内容区面板容器 |
| `dg-page*` | CSS 设计令牌（定义于 `index.css`，主题变量驱动） |
| `ThemePicker` | 7 套主题切换（跟随系统 + 6 款配色） |
## 部署相关文件
| 文件 | 用途 |
@@ -91,16 +133,17 @@ aiops/
| Vite | 7+ | 构建工具 |
| Tailwind CSS | 3+ | 样式框架 |
| shadcn/ui | - | UI 组件库 |
| Zustand | - | 状态管理 |
| TanStack Query | - | 数据请求 |
| Zustand | 5+ | 状态管理 |
| TanStack Query | 5+ | 数据请求 |
| i18next | - | 国际化（zh-CN / en-US） |
### 后端
| 技术 | 版本 | 用途 |
|------|------|------|
| Go | 1.24+ | 编程语言 |
| Gin | v1.10+ | Web 框架 |
| GORM | v1.25+ | ORM |
| Gin | v1.9+ | Web 框架 |
| GORM | v1.30+ | ORM |
| JWT | v5 | 认证 |
| Viper | - | 配置管理 |
| Zap | - | 结构化日志 |