aiops/docs/project-structure.md

项目结构

整体结构

aiops/
├── frontend/                    # 前端 (React 19 + TypeScript + Vite)
│   ├── src/
│   │   ├── api/                 # API 封装（按菜单域拆分，http.ts 自动解包 .data）
│   │   │   ├── server/          # 服务器 / 区域 / 资源模型
│   │   │   ├── kubernetes/      # K8s 集群 / Pod / Workload
│   │   │   ├── monitor/         # 告警 / 指标 / 数据源 / Grafana
│   │   │   ├── log/             # 日志中心（Loki / ES 代理查询）
│   │   │   ├── deploy/          # 流水线 / 发布 / 凭证
│   │   │   ├── task/            # 定时任务 / 脚本库 / 远程执行
│   │   │   ├── approval/        # 审批流程
│   │   │   ├── audit/           # 操作审计 / 终端审计
│   │   │   ├── aiops/           # AI 助手 / Agent CLI
│   │   │   ├── cloud/           # 云账号 / 域名 / 账单
│   │   │   ├── system/          # 用户 / 角色
│   │   │   └── agent/           # Agent 监控
│   │   ├── pages/               # 复杂域级页面（从 components 迁入）
│   │   │   ├── monitor/         # 监控中心 / 主机监控 / 中间件 / SNMP / 站点
│   │   │   ├── approval/        # 审批分类 / 流程 / 权限
│   │   │   └── audit/           # 操作审计 / 登录日志 / 终端审计回放
│   │   ├── components/          # 业务组件 + 布局
│   │   │   ├── layout/          # PageShell / Sidebar / Header / ThemePicker
│   │   │   ├── dashboard/       # 仪表盘
│   │   │   ├── server/          # 服务器管理
│   │   │   ├── k8s/             # K8s 集群管理
│   │   │   ├── monitor/         # 告警中心 / 日志中心 / 数据源
│   │   │   ├── deploy/          # CI/CD 流水线
│   │   │   ├── task/            # 定时任务 / 脚本库 / 远程执行
│   │   │   ├── aiops/           # AI 助手 / Agent CLI / 大模型设置
│   │   │   ├── cloud/           # 云资源
│   │   │   ├── approval/        # 审批组件（对话框 / 流程图）
│   │   │   ├── system/          # 系统管理
│   │   │   └── ui/              # shadcn/ui 基础组件
│   │   ├── locales/             # i18n 翻译 (zh-CN.json / en-US.json)
│   │   ├── i18n/                # i18next 初始化
│   │   ├── hooks/               # useTheme / useConfirm / usePermission 等
│   │   ├── store/               # Zustand 状态管理
│   │   ├── types/               # TypeScript 类型（按域拆分）
│   │   ├── utils/               # 主题 / 权限 / 导出 / 校验工具
│   │   └── lib/                 # 通用工具（cn 等）
│   ├── package.json
│   ├── vite.config.ts           # 代理 /api、/ws、/health、/version 到 :8080
│   └── Dockerfile               # [legacy] 独立 Nginx 镜像
│
├── backend/                     # 后端 (Go 1.24 + Gin + GORM)
│   ├── main.go                  # 应用入口（CLI + HTTP 服务）
│   ├── embed.go                 # go:embed 前端静态资源
│   ├── static/                  # 前端构建产物（embed 目录）
│   ├── config/                  # Viper 配置加载
│   ├── controller/              # HTTP 处理器（60+ 文件按领域拆分）
│   ├── middleware/              # JWT / Admin / PipelineAccess / CORS / 日志
│   ├── router/                  # 路由注册（~1000 行）
│   ├── model/                   # GORM 数据模型（86+ 表）
│   ├── dto/                     # 请求/响应 DTO
│   ├── service/                 # 业务逻辑层
│   ├── repository/              # 数据访问层
│   ├── seed/                    # 种子数据
│   ├── pkg/                     # 公共包
│   │   ├── database/            # DB 连接 + AutoMigrate
│   │   ├── kubernetesclient/    # 轻量 K8s 客户端
│   │   ├── remoteexec/          # Go-native SSH 远程执行
│   │   ├── agentcli/            # AI 运维 Agent 引擎（ReAct + Evolver）
│   │   ├── toolinstaller/       # 工具懒加载（kubectl/maven/helm 等）
│   │   ├── redis/               # Redis 连接
│   │   ├── logger/              # Zap 日志
│   │   └── wshub/               # WebSocket Hub
│   ├── config.yaml              # 默认配置
│   └── Dockerfile               # [legacy] 分离式后端镜像
│
├── agent/                       # 监控 Agent（独立 Go module）
│   ├── main.go                  # CLI 入口
│   ├── collector/               # /proc 指标采集
│   ├── task/                    # 远程任务执行
│   ├── reporter/                # HTTP 上报
│   └── deploy/                  # install.sh + systemd
│
├── docs/                        # 开发文档
│   ├── README.md                # 文档总索引
│   ├── quick-start.md           # 快速开始
│   ├── deployment.md            # 部署指南
│   ├── development-guide.md     # 开发规范
│   ├── project-structure.md     # 当前文档
│   ├── ai-agent/                # AI Agent / Agent CLI 设计文档集
│   ├── client-agent/            # 客户端 Agent 采集与任务规格
│   ├── security-bastion/        # 安全审计与堡垒机
│   ├── monitoring/              # 监控中心
│   ├── log-center/              # 日志中心
│   ├── asset-credential/        # 资产与凭证
│   ├── kubernetes/              # Kubernetes 管理
│   ├── automation-deploy/       # 自动化运维与发布
│   ├── terminal/                # 字符终端体系
│   ├── rdp/                     # Web RDP 图形桌面
│   ├── reference/               # API / 数据库参考
│   ├── platform/                # Redis/redka 等平台基础能力
│   └── frontend/                # 前端设计系统与视觉规范
├── deploy/kubernetes/           # K8s 清单 (devops 命名空间)
├── docker-compose.yml           # MySQL + Redis + AIOps embed
├── docker-compose.k8s.yml       # 单应用 + 外部 DB
├── Dockerfile             # embed 单容器镜像（推荐）
├── run.sh                       # 统一入口脚本
├── aiops                        # 独立二进制产物（gitignore）
└── 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 款配色）

部署相关文件

文件	用途
run.sh	build / docker / kubernetes / release 统一入口
Dockerfile	生产推荐：前端嵌入后端单容器
docker-compose.yml	3 容器：MySQL + Redis + AIOps
backend/static/	go:embed 目标，由 ./run.sh build 同步
./aiops	独立二进制输出路径（项目根目录）

技术栈

前端

技术	版本	用途
React	19+	前端框架
TypeScript	5+	类型安全
Vite	7+	构建工具
Tailwind CSS	3+	样式框架
shadcn/ui	-	UI 组件库
Zustand	5+	状态管理
TanStack Query	5+	数据请求
i18next	-	国际化（zh-CN / en-US）

后端

技术	版本	用途
Go	1.24+	编程语言
Gin	v1.9+	Web 框架
GORM	v1.30+	ORM
JWT	v5	认证
Viper	-	配置管理
Zap	-	结构化日志
SQLite / MySQL / Redis	-	存储

端口分配

服务	端口	说明
前端 (Vite dev)	5173	开发模式
后端 / embed 部署	8080	API + WebSocket + SPA
Docker Compose MySQL	3306	可选暴露
K8s NodePort	30080	集群外访问

版本信息注入

编译时通过 ldflags 注入 main.Version / BuildTime / GitCommit：

• ./run.sh build / ./run.sh build tag v1.5.0
• Dockerfile 构建参数 VERSION / BUILD_TIME / GIT_COMMIT
• 运行时：./aiops version、GET /version