diff --git a/README.md b/README.md index c4dde97..522433d 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/PROJECT_SUMMARY.md b/docs/PROJECT_SUMMARY.md index 7f8b4e6..f2d773e 100644 --- a/docs/PROJECT_SUMMARY.md +++ b/docs/PROJECT_SUMMARY.md @@ -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) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 4224b9b..19860ac 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 协议接入 | + ## 部署速查 | 场景 | 命令 | diff --git a/docs/dev-log.md b/docs/dev-log.md index 2c70326..1b2630f 100644 --- a/docs/dev-log.md +++ b/docs/dev-log.md @@ -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 项目初始化 ### 完成项 diff --git a/docs/development-guide.md b/docs/development-guide.md index a83604f..0d44cd4 100644 --- a/docs/development-guide.md +++ b/docs/development-guide.md @@ -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 ( + } + actions={} + toolbar={} + tabs={[{ id: 'list', label: t('myModule.tabList') }]} + activeTab="list" + onTabChange={() => {}} + variant="list" + > + {/* 页面内容 */} + + ); +} +``` + +`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(); +{t('server.batchImport')} + +// ❌ 禁止硬编码中文（已迁移模块） +批量导入 +``` + +双语同步：修改 `zh-CN.json` 时必须同步更新 `en-US.json`。 + ### UI 设计原则 - 能去掉的装饰都去掉（无边框、无多余分隔线） - 选中态用 `bg-surface-active`，不用彩色高亮 - 页面打开即用，不需要额外的"新建"按钮跳转 -- 操作成功不弹 toast，仅在失败时提示 +- 主题感知 — 使用 CSS 变量 `var(--dg-xxx)`，不硬编码颜色 +- 按钮文案 2–4 字 +- 禁止 `window.confirm()` / `alert()`，使用 `useConfirm()` + `toast` +- Radix Dialog 必须包含 `` ### 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 +``` + ## 日志 | 级别 | 使用场景 | @@ -195,4 +262,4 @@ npx tsc --noEmit # 类型检查（提交前零错误） ```go log.Info("server started", zap.String("port", cfg.Port)) log.Error("database error", zap.Error(err)) -``` +``` \ No newline at end of file diff --git a/docs/project-structure.md b/docs/project-structure.md index c7079ab..2eba5c3 100644 --- a/docs/project-structure.md +++ b/docs/project-structure.md @@ -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: -│ ├── 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 | - | 结构化日志 |