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

docs: 同步 README 与 docs 至最新部署与版本方案

Browse Source 
- 更新三种部署方式：embed 单容器、./aiops 根目录二进制
- 补充版本管理、release、lghost/aiops 镜像推送说明
- 修正过时的 docker 4 容器、backend/aiops、run.sh start 等描述
- 更新 project-structure、deployment、quick-start 等核心文档
This commit is contained in:
Logan.Li committed 2026-06-26 16:39:00 +08:00
1 parent 9f5ce249f1
commit 286decf0b0
8 files changed
+593 -487
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+97 -114
View File
@@ -13,10 +13,11 @@
### 后端
- Go 1.24 / Gin Web Framework
- GORM (ORM) / MySQL 8.0 / Redis 7
- GORM (ORM) / MySQL 8.0 / Redis 7 / SQLite (local 模式)
- JWT 认证 / Zap 日志 / Viper 配置
- WebSocket (Gorilla) / PTY 终端 (creack/pty)
- 自研轻量 Kubernetes HTTP 客户端（channel.k8s.io WebSocket 协议）
- go:embed 嵌入前端静态资源（单二进制 / 单容器部署）
### Agent
- Go 1.24 静态编译 (CGO_ENABLED=0)
@@ -27,135 +28,113 @@
| 方式 | 命令 | 架构 | 适用场景 |
|------|------|------|----------|
| **① 独立二进制** | `./run.sh build` → `./run.sh binary` | 单文件，前后端一体 | 无 Docker/K8s 环境 |
| **② Kubernetes** | `./run.sh kubernetes deploy` | Embed 单容器 + MySQL/Redis StatefulSet | 生产集群，devops 命名空间 |
| **③ Docker Compose** | `./run.sh docker up` | 4 容器 (MySQL+Redis+Backend+Nginx) | 单机生产，开发/测试 |
| **① 独立二进制** | `./run.sh build` → `./aiops` | 单文件 embed，输出到项目根目录 | 无 Docker/K8s，边缘/本机 |
| **② Docker Compose** | `./run.sh docker up` | 3 容器 (MySQL + Redis + AIOps embed) | 单机生产、演示 |
| **③ Kubernetes** | `./run.sh kubernetes deploy` | embed 单容器 + MySQL/Redis StatefulSet | 生产集群，`devops` 命名空间 |
统一入口 `./run.sh`，详见 `./run.sh help`。
### 版本与镜像
- **发布版本**：Git tag 为权威来源（如 `v1.5.0`）
- **Docker 镜像**：`lghost/aiops:<tag>`（Docker Hub）
- **二进制版本**：`./aiops version` / `GET /version`
- **一键发版**：`./run.sh release v1.5.0`（打 tag → 编译二进制 → 构建镜像 → 推送 Docker Hub → 更新 K8s manifest）
```bash
docker login
./run.sh release v1.5.0
./aiops version # 查看二进制版本
curl http://localhost:8080/version # 查看运行版本
```
## 快速开始
### Docker Compose 部署
```bash
# 一键启动全部服务 (MySQL + Redis + 后端 + Nginx 前端)
./run.sh docker up
# 访问
# 前端: http://localhost:80
# 后端: http://localhost:8080
# 健康检查: http://localhost:8080/health
# 管理
./run.sh docker logs # 查看日志
./run.sh docker ps # 容器状态
./run.sh docker down # 停止
```
### Kubernetes 部署
```bash
# 一键部署到 devops 命名空间
./run.sh kubernetes deploy
# 访问: http://<NODE_IP>:30080
# 运维
./run.sh kubernetes status # 资源状态
./run.sh kubernetes logs # 应用日志
./run.sh kubernetes upgrade # 重新构建 + 滚动更新
./run.sh kubernetes exec # 进入容器 Shell
./run.sh kubernetes mysql # 进入 MySQL CLI
./run.sh kubernetes redis # 进入 Redis CLI
./run.sh kubernetes scale 3 # 扩缩容
./run.sh kubernetes port-forward # 端口转发到本机
./run.sh kubernetes delete # 删除所有 K8s 资源（保留 PVC）
./run.sh kubernetes build # 仅构建 embed 镜像
```
### 独立二进制部署
```bash
# 编译（前端自动嵌入）
./run.sh build
# 启动
./backend/aiops # 默认 SQLite, 端口 8080
./backend/aiops --port 9090 # 自定义端口
./backend/aiops --db-driver mysql --db-host ... # MySQL 模式
```
### 本地开发
```bash
./run.sh dev # 前端 :5173 + 后端 :8080 (热重载)
# 单独启动
cd frontend && npm run dev
cd backend && go run .
./run.sh stop # 停止
./run.sh status # 查看状态
```
### Docker Compose 部署
```bash
./run.sh docker up # 构建并启动 (MySQL + Redis + AIOps)
./run.sh docker up v1.5.0 # 指定版本构建
./run.sh docker push v1.5.0 # 构建并推送到 lghost/aiops
# 访问（前后端同一端口）
# http://localhost:8080
# http://localhost:8080/version
```
### Kubernetes 部署
```bash
./run.sh kubernetes deploy # 构建镜像 + 全量部署
./run.sh kubernetes upgrade v1.5.0 # 指定版本滚动更新
./run.sh kubernetes push v1.5.0 # 构建并推送 Docker Hub
# 访问: http://<NODE_IP>:30080
# 镜像: lghost/aiops:<tag>
```
### 独立二进制部署
```bash
./run.sh build # 编译到项目根目录 ./aiops
./run.sh build tag v1.5.0 # 指定版本编译
./aiops version # 查看版本
./aiops --mode local # 本地模式 (SQLite + redka)
./run.sh binary upgrade # 停服 → 重编译 → 后台启动
```
> Mac 上 `./run.sh build` 产出 **darwin** 二进制，仅本机可用。
> Linux 服务器请在 Linux 上构建，或使用 Docker/K8s embed 镜像（`Dockerfile.embed` 固定 `GOOS=linux GOARCH=amd64`）。
### Agent 构建
```bash
./run.sh build agent # 交叉编译 Agent (amd64+arm64)
./run.sh build agent # 交叉编译 Agent (linux-amd64 + linux-arm64)
# 验证
./agent/bin/aiops-agent-linux-amd64 version
./agent/bin/aiops-agent-linux-amd64 output -top-n 3 # Zabbix 风格指标输出
./agent/aiops-agent-linux-amd64 version
```
### 默认账号
- 用户名: `admin`
- 密码: `123456`
| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | 123456 | 超级管理员 |
| ops01 | 123456 | 运维 |
| dev01 | 123456 | 开发 |
## 项目结构
```
aiops/
├── frontend/ # 前端 (React + TypeScript)
│ ├── src/components/ # dashboard/server/kubernetes/monitor/deploy/aiops...
│ ├── src/services/ # API + HTTP 封装
│ ├── src/store/ # Zustand 状态管理
│ └── Dockerfile # nginx:alpine 镜像
│ ├── src/components/ # dashboard/server/k8s/monitor/deploy/aiops...
│ └── Dockerfile # [legacy] 独立 Nginx 镜像，Compose 已改用 embed
│
├── backend/ # 后端 (Go + Gin)
│ ├── main.go # 入口 (was cmd/main.go)
│ ├── embed.go # 前端嵌入 (was cmd/embed.go)
│ ├── config/ # 配置加载 (was internal/config)
│ ├── controller/ # HTTP 处理器 (was internal/api/handlers)
│ ├── middleware/ # JWT/日志/CORS (was internal/api/middleware)
│ ├── router/ # 路由注册 (was internal/api/routes)
│ ├── model/ # GORM 数据模型 (was internal/models)
│ ├── cloud/ # 云平台对接 (was internal/cloud)
│ ├── dto/ # 请求/响应传输对象 ★
│ ├── repository/ # 数据访问层 ★
│ ├── service/ # 业务逻辑层 ★
│ ├── utils/ # 工具函数 ★
│ ├── seed/ # 种子数据 (was cmd/seed.go)
│ ├── static/ # 前端构建产物 (was cmd/static/)
│ ├── pkg/ # 公共包 (database/kubernetesclient/remoteexec/toolinstaller)
│ └── Dockerfile # 3 阶段构建 (Go build → Agent → Alpine Runtime)
│ ├── main.go # 应用入口
│ ├── embed.go # go:embed 前端静态资源
│ ├── static/ # 前端构建产物（embed 目标目录）
│ ├── controller/ # HTTP 处理器
│ ├── router/ # 路由注册
│ ├── model/ # GORM 数据模型
│ ├── pkg/ # database/kubernetesclient/remoteexec/...
│ └── Dockerfile # [legacy] 分离式后端镜像
│
├── agent/ # 监控 Agent
│ ├── collector/ # /proc 指标采集
│ ├── task/ # 远程任务执行
│ └── reporter/ # HTTP 上报
│
├── deploy/kubernetes/ # Kubernetes 部署清单
│ ├── namespace.yaml # devops 命名空间
│ ├── secret.yaml # 密钥
│ ├── configmap.yaml # 配置
│ ├── mysql.yaml # MySQL StatefulSet
│ ├── redis.yaml # Redis StatefulSet
│ ├── deployment.yaml # AIOps Deployment + NodePort Service
│ └── ingress.yaml # Ingress 路由
│
├── docker-compose.yml # Docker Compose 4 容器编排
├── Dockerfile.embed # Embed 单容器镜像 (前端→后端→Agent→Runtime)
├── agent/ # 监控 Agent（独立 Go module）
├── deploy/kubernetes/ # K8s 部署清单 (devops 命名空间)
├── docker-compose.yml # MySQL + Redis + AIOps embed（3 容器）
├── docker-compose.k8s.yml # 单应用容器（连接外部 DB）
├── Dockerfile.embed # embed 单容器镜像（推荐）
├── run.sh # 统一入口脚本
└── Makefile # 快捷命令
└── aiops # 独立二进制产物（gitignore，项目根目录）
```
## 核心功能
@@ -164,22 +143,26 @@ aiops/
|------|------|
| 仪表盘 | 成本统计、告警聚合、Top 资源、SSL 提醒、趋势图表 |
| 资产管理 | 服务器 CRUD、批量导入、WebShell、云账号/域名/账单 |
| Kubernetes 管理 | 多集群管理、Deployment 三模式编辑器(查看/可视化编辑/YAML)、Node/Pod/Service/Ingress、kubectl 终端、事件聚合、多集群对比、Namespace 管理 |
| 应用发布 | CI/CD 流水线（GitLab CI 风格可视化）、发布配置、SSH 主机 + Kubernetes 双路径部署 |
| 监控中心 | 监控大屏、主机指标（CPU/内存/磁盘/网络/进程/端口/FD）、告警规则引擎、飞书/钉钉通知 |
| 自动化运维 | 定时任务、脚本库（Shell/Python）、远程执行（Go-native SSH）、Ansible |
| AIOps 智能 | AI 智能助手（6 种 LLM）、告警分析、容量预测 |
| Kubernetes 管理 | 多集群、Deployment 三模式编辑器、Pod 终端/文件浏览、事件聚合 |
| 应用发布 | CI/CD 流水线、发布配置、SSH + K8s 双路径部署 |
| 监控中心 | 监控大屏、主机指标、告警引擎、飞书/钉钉通知 |
| 自动化运维 | 定时任务、脚本库、远程执行（Go-native SSH） |
| AIOps 智能 | AI 助手、告警分析、容量预测 |
| 资源申请 | 云服务器/应用部署申请审批 |
| 系统管理 | 用户管理、角色权限、操作审计、终端审计、凭证配置、系统设置 |
| 系统管理 | 用户/角色、操作审计、凭证配置 |
### Kubernetes 管理亮点
## 文档
- **Deployment 三模式编辑器**: 查看模式 / 可视化编辑（5 Tab: 基本信息·容器信息·存储挂载·高级设置·服务路由）/ YAML 编辑（CodeMirror 6 语法高亮）
- **StatefulSet/DaemonSet**: 完整详情页（更新策略/选择器/PVC 模板/Init Containers）
- **Pod 交互**: 文件浏览器（上传/下载）、exec 终端（WebSocket channel.k8s.io）、日志流
- **集群运维**: 事件聚合看板、多集群对比（雷达图/柱状图）、Node 详情（资源分配率/污点/容器运行时）、Namespace CRUD（资源配额）
- **自研轻量客户端**: 不依赖 client-go，net/http + WebSocket 直连 K8s API
详细开发文档见 [docs/README.md](./docs/README.md)。
| 文档 | 说明 |
|------|------|
| [快速开始](./docs/quick-start.md) | 环境准备、本地开发 |
| [部署指南](./docs/deployment.md) | 二进制 / Docker / K8s / 版本发版 |
| [开发规范](./docs/development-guide.md) | 代码规范、Git 工作流 |
| [项目结构](./docs/project-structure.md) | 目录结构说明 |
| [CLAUDE.md](./CLAUDE.md) | AI 助手指引（完整命令参考） |
## License
MIT
MIT
docs/BACKEND_SUMMARY.md
+14 -9
View File
@@ -1,16 +1,21 @@
# AIOps 后端项目总结
> **注意**：目录结构已重构，入口为 `backend/main.go`，处理器在 `controller/`。
> 最新结构见 [project-structure.md](./project-structure.md)，部署见 [deployment.md](./deployment.md)。
## 项目概述
AIOps 后端是一个基于 Go + Gin 框架开发的专业 AIOps 智能运维平台 API 服务。
AIOps 后端是一个基于 Go + Gin 框架开发的专业 AIOps 智能运维平台 API 服务。
前端通过 `go:embed` 嵌入 `backend/static/`，支持单二进制与 embed 单容器部署。
## 项目结构
## 项目结构（历史参考，部分路径已变更）
```
backend/
├── cmd/
│ └── main.go # 应用入口
├── internal/
├── main.go # 应用入口（当前）
├── embed.go # 前端静态资源嵌入
├── controller/ # HTTP 处理器（原 handlers）
├── internal/ # [已迁移] 见下方历史结构
│ ├── api/
│ │ ├── handlers/ # HTTP 处理器
│ │ │ ├── user.go # 用户管理
@@ -265,11 +270,11 @@ docker-compose up -d mysql redis
### 4. 运行
```bash
# 开发模式
go run cmd/main.go
# 推荐：项目根目录
./run.sh dev
# 或使用 Makefile
make run
# 或仅后端
cd backend && go run .
```
### 5. 生成 Mock 数据
docs/PROJECT_SUMMARY.md
+15 -16
View File
@@ -186,11 +186,11 @@ cp config.yaml.example config.yaml
# 启动数据库
docker-compose up -d mysql redis
# 运行
go run cmd/main.go
# 运行（推荐统一入口）
./run.sh dev
# 或使用 Makefile
make run
# 或仅后端
cd backend && go run .
```
## API 文档
@@ -199,27 +199,26 @@ make run
## 部署
### Docker 部署
> 最新部署方式见 [deployment.md](./deployment.md)。
```bash
# 前端
cd app
docker build -t ezops-frontend .
docker run -p 80:80 ezops-frontend
# 独立二进制
./run.sh build tag v1.5.0 && ./aiops --mode local
# 后端
cd backend
docker build -t ezops-backend .
docker run -p 8080:8080 -v $(pwd)/config.yaml:/app/config.yaml ezops-backend
# Docker Compose（embed 单容器 + MySQL + Redis）
./run.sh docker up
# 或使用 Docker Compose
docker-compose up -d
# Kubernetes
./run.sh kubernetes deploy
# 发版推送 Docker Hub
./run.sh release v1.5.0 # → lghost/aiops:v1.5.0
```
## 默认账号
- **用户名**: admin
- **密码**: admin123
- **密码**: 123456
## 注意事项
docs/README.md
+28 -10
View File
@@ -1,17 +1,17 @@
# AIOps 开发文档
本目录包含 AIOps 智能运维平台的全部开发文档。
本目录包含 AIOps 智能运维平台的开发文档。
## 文档索引
| 文档 | 说明 |
|------|------|
| [快速开始](./quick-start.md) | 环境准备、本地开发、常见问题 |
| [部署指南](./deployment.md) | 二进制 / Docker / K8s 部署、版本发版、镜像推送 |
| [项目结构](./project-structure.md) | 前后端目录结构说明 |
| [快速开始](./quick-start.md) | 环境准备、安装、启动 |
| [开发规范](./development-guide.md) | 代码规范、Git 工作流 |
| [API 接口](./api-reference.md) | 后端 API 接口文档 |
| [数据库设计](./database-schema.md) | 数据模型和表结构 |
| [开发规范](./development-guide.md) | 代码规范、Git 工作流 |
| [部署指南](./deployment.md) | 生产环境部署 |
| [开发日志](./dev-log.md) | 详细开发日志（按日期记录） |
| [Redis 缓存策略](./redis-caching-strategy.md) | Redis 缓存使用现状与优化方案 |
@@ -25,12 +25,30 @@
## 根目录文档
以下文档位于项目根目录：
| 文档 | 说明 |
|------|------|
| [ROADMAP.md](../ROADMAP.md) | K8s 管理功能演进路线图 |
| [TDD_PLAN.md](../TDD_PLAN.md) | TDD 验证计划 |
| [PROJECT_EVALUATION.md](../PROJECT_EVALUATION.md) | K8s 管理功能评估基线 |
| [README.md](../README.md) | 项目主说明 |
| [CLAUDE.md](../CLAUDE.md) | AI 助手指引 |
| [CLAUDE.md](../CLAUDE.md) | AI 助手指引（完整命令与规范） |
| [ROADMAP.md](../ROADMAP.md) | K8s 管理功能演进路线图 |
## 部署速查
| 场景 | 命令 |
|------|------|
| 本地开发 | `./run.sh dev` |
| 编译二进制 | `./run.sh build tag v1.5.0` → `./aiops` |
| Docker Compose | `./run.sh docker up` → http://localhost:8080 |
| K8s 部署 | `./run.sh kubernetes deploy` |
| 发版推送 | `./run.sh release v1.5.0` → `lghost/aiops:v1.5.0` |
| 查看版本 | `./aiops version` / `curl /version` |
## 部署架构（当前）
```
开发: ./run.sh dev → 5173 + 8080 热重载
二进制: ./run.sh build → ./aiops (embed, 项目根目录)
Compose: ./run.sh docker up → mysql + redis + aiops (embed, :8080)
K8s: ./run.sh kubernetes → lghost/aiops:<tag> embed 单 Pod
```
> 前后端分离的 Nginx 容器已废弃，统一使用 `Dockerfile.embed` 单容器方案。
docs/deployment.md
+244 -97
View File
@@ -1,139 +1,286 @@
# 部署指南
## 开发环境
本文档描述 AIOps 的三种部署方式、版本管理和镜像发布流程。
参见 [快速开始](./quick-start.md)。
## 部署方式概览
```bash
./run.sh start
| 方式 | 命令 | 容器/产物 | 前端 | 数据库 |
|------|------|-----------|------|--------|
| 独立二进制 | `./run.sh build` | `./aiops`（项目根目录） | go:embed | 默认 SQLite + redka |
| Docker Compose | `./run.sh docker up` | 3 容器 | embed 单端口 8080 | MySQL + Redis |
| Kubernetes | `./run.sh kubernetes deploy` | embed 单 Pod | embed 单端口 8080 | 集群内 MySQL/Redis 或 local 模式 |
> **已废弃**：前后端分离的 4 容器 Compose（Backend + Nginx）已合并为 embed 单应用容器。
---
## 版本管理
### 原则
```
Git tag (v1.5.0) → 唯一发布版本
↓
┌────┴────┬──────────────┐
│ │ │
./aiops lghost/aiops K8s deployment
version :v1.5.0 image: lghost/aiops:v1.5.0
```
## 生产构建
### 版本解析优先级
### 后端编译
`run.sh` 中 `resolve_version()` 统一处理：
1. 显式参数（`./run.sh build tag v1.5.0`）
2. 环境变量 `VERSION=v1.5.0`
3. `git describe --tags --always --dirty`
4. 兜底 `dev`
### 查看版本
```bash
cd backend
CGO_ENABLED=1 go build -ldflags="-s -w" -o aiops-server cmd/main.go
./aiops version
./aiops --version
curl http://localhost:8080/version
```
### 前端构建
响应示例：
```bash
cd app
npm run build # 输出到 dist/
```
### 使用 Makefile
```bash
make build # 同时构建前后端
```
## Docker 部署
### Dockerfile
后端已有 `backend/Dockerfile`，可基于此构建镜像。
```bash
cd backend
docker build -t aiops-server .
```
### docker-compose
```bash
cd backend
docker-compose up -d
```
## Nginx 反向代理
前端构建后部署到 Nginx，后端 API 反向代理：
```nginx
server {
listen 80;
server_name aiops.example.com;
# 前端静态文件
location / {
root /usr/share/nginx/html;
try_files $uri $uri/ /index.html;
}
# 后端 API 代理
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
# WebSocket 代理
location /ws/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
```json
{
"version": "v1.5.0",
"build_time": "2026-06-26T08:26:52Z",
"git_commit": "9f5ce24",
"mode": "local",
"db_driver": "sqlite",
"redis_driver": "redka"
}
```
参考配置文件：`backend/nginx.conf`
### 一键发版
## 系统服务（systemd）
```bash
docker login
./run.sh release v1.5.0
```
创建 `/etc/systemd/system/aiops.service`：
依次执行：
1. 创建 git tag `v1.5.0`（已存在则跳过）
2. 编译独立二进制 `./aiops`（ldflags 注入版本）
3. 构建 Docker 镜像 `lghost/aiops:v1.5.0`
4. 推送到 Docker Hub
5. 更新 `deploy/kubernetes/deployment.yaml` 镜像坐标
发版后可选：
```bash
git push origin master
git push origin v1.5.0
```
---
## ① 独立二进制
### 编译
```bash
./run.sh build # 自动解析版本
./run.sh build tag v1.5.0 # 指定版本
```
产物固定输出到 **项目根目录** `./aiops`，不会在 `backend/` 下生成。
构建前会自动清理历史产物：`backend/aiops*`。
### 启动
```bash
./aiops --mode local # SQLite + redka（默认推荐）
./aiops --port 9090
./aiops --config config.yaml
# 后台守护进程
./run.sh binary upgrade
./run.sh binary status
./run.sh binary stop
```
### 平台说明
| 构建环境 | `./aiops` 格式 | 用途 |
|----------|---------------|------|
| macOS Apple Silicon | darwin/arm64 | 仅 Mac 本机 |
| macOS Intel | darwin/amd64 | 仅 Mac 本机 |
| Linux x86_64 | linux/amd64 | Linux 服务器 |
Mac 上 `./run.sh build` **不能**产出 Linux 二进制；Linux 部署请用 Docker 镜像或在 Linux 上构建。
### systemd 示例
```ini
[Unit]
Description=AIOps Server
Description=AIOps
After=network.target
[Service]
Type=simple
User=www-data
User=aiops
WorkingDirectory=/opt/aiops
ExecStart=/opt/aiops/aiops-server
ExecStart=/opt/aiops/aiops --mode local --port 8080
Restart=always
RestartSec=5
Environment=GIN_MODE=release
[Install]
WantedBy=multi-user.target
```
```bash
systemctl enable aiops
systemctl start aiops
---
## ② Docker Compose
### 架构（3 容器）
```
mysql:8.0 + redis:7-alpine + aiops (Dockerfile.embed)
↓
http://localhost:8080
(API + WebSocket + 前端 SPA)
```
## 环境变量
### 启动
| 变量 | 默认值 | 说明 |
|------|--------|------|
| PORT | 8080 | 后端端口 |
| GIN_MODE | debug | Gin 模式（release/debug） |
| GOPROXY | - | Go 模块代理 |
```bash
./run.sh docker up
./run.sh docker up v1.5.0 # 指定版本
./run.sh docker up fresh # 无缓存全量重建
```
## 生产配置建议
环境变量（可选）：
1. **数据库**: 生产环境使用 MySQL/PostgreSQL，不要用 SQLite
2. **JWT Secret**: 更换为高强度随机字符串
3. **CORS**: 生产环境配置允许的具体域名，不要用 `*`
4. **HTTPS**: 配置 TLS 证书
5. **日志**: 使用文件日志 + 日志轮转
6. **备份**: 定期备份数据库
```bash
VERSION=v1.5.0 MYSQL_PASSWORD=xxx ./run.sh docker up
```
### 推送镜像
```bash
./run.sh docker push v1.5.0
# 等价于 docker push lghost/aiops:v1.5.0
```
### 连接外部数据库
使用 `docker-compose.k8s.yml`（仅单应用容器，挂载 `backend/config.external.yaml`）：
```bash
VERSION=v1.5.0 docker compose -f docker-compose.k8s.yml up -d --build
```
### 管理命令
```bash
./run.sh docker ps
./run.sh docker logs
./run.sh docker down
./run.sh docker clean # 清理构建缓存
```
---
## ③ Kubernetes
### 镜像
- 默认镜像：`lghost/aiops:<tag>`
- 构建文件：`Dockerfile.embed`
- 命名空间：`devops`
- 访问：`http://<NODE_IP>:30080`
### 部署
```bash
./run.sh kubernetes deploy
./run.sh kubernetes deploy v1.5.0
```
### 滚动更新
```bash
./run.sh kubernetes upgrade v1.5.0
```
### 推送镜像（Mac 可构建 Linux 镜像）
```bash
./run.sh kubernetes push v1.5.0
```
`Dockerfile.embed` 内固定 `GOOS=linux GOARCH=amd64`，在 Mac 上 `docker build` 产出的是 Linux 镜像。
### 运维命令
```bash
./run.sh kubernetes status
./run.sh kubernetes logs
./run.sh kubernetes exec
./run.sh kubernetes mysql
./run.sh kubernetes redis
./run.sh kubernetes scale 3 # 多副本自动切换 release + MySQL 模式
./run.sh kubernetes port-forward
./run.sh kubernetes delete
```
### 内网部署说明
若 K8s 节点无法访问 Docker Hub：
1. **推荐**：同步到内网 Harbor，修改 `deployment.yaml` 中 `image` 为内网地址
2. **离线**：`docker save` → `scp` → 节点 `docker load`
运行节点（如 10.10.10.73/75）只需 `pull` 镜像，不需要把镜像文件直接推到服务器磁盘。
---
## Mac 构建 Linux 镜像
| 操作 | Mac 支持 | 说明 |
|------|---------|------|
| `./run.sh build` | ✅（darwin 二进制） | 仅本机运行 |
| `docker build` (Dockerfile.embed) | ✅ | 产出 linux/amd64 镜像 |
| `docker push lghost/aiops:tag` | ✅ | 需 `docker login` |
| `./run.sh release v1.x` | ✅ | 完整发版流程 |
---
## 健康检查
```bash
# 检查后端是否正常
curl http://localhost:8080/health
# {"status":"ok"}
# 检查版本
curl http://localhost:8080/version
# {"version":"dev","build_time":"...","git_commit":"..."}
curl http://localhost:8080/version # 推荐（无 DB 强依赖）
curl http://localhost:8080/health # 含 DB 检查
```
K8s 探针使用 `/version`。
---
## 生产配置建议
1. **数据库**：生产使用 MySQL + Redis（`MODE=release`），local 模式仅适合单副本
2. **JWT Secret**：更换默认密钥
3. **版本**：生产环境 pin 镜像 tag（`lghost/aiops:v1.5.0`），避免使用 `:dev`
4. **HTTPS**：Ingress 或前置 Nginx 终止 TLS
5. **备份**：定期备份 MySQL 数据和 PVC
---
## 相关文件
| 文件 | 说明 |
|------|------|
| `run.sh` | 统一入口（build/docker/kubernetes/release） |
| `Dockerfile.embed` | embed 单容器镜像（推荐） |
| `docker-compose.yml` | MySQL + Redis + AIOps |
| `deploy/kubernetes/deployment.yaml` | K8s Deployment + NodePort |
| `.gitignore` | 忽略 `aiops`、`backend/aiops*` 等编译产物 |
docs/development-guide.md
+19 -9
View File
@@ -44,14 +44,16 @@ feat: 添加服务器批量导入功能
| 目录 | 职责 |
|------|------|
| `cmd/` | 应用入口 |
| `internal/handlers/` | HTTP 请求处理（参数校验、响应） |
| `internal/models/` | 数据模型定义 |
| `internal/config/` | 配置管理 |
| `internal/middleware/` | 中间件 |
| `internal/routes/` | 路由注册 |
| `pkg/database/` | 数据库连接 |
| `main.go` / `embed.go` | 应用入口 + 前端嵌入 |
| `controller/` | HTTP 请求处理（参数校验、响应） |
| `model/` | 数据模型定义 |
| `config/` | 配置管理 (Viper) |
| `middleware/` | JWT / 日志 / CORS 中间件 |
| `router/` | 路由注册 |
| `service/` / `repository/` | 业务逻辑 / 数据访问 |
| `pkg/database/` | 数据库连接 + AutoMigrate |
| `pkg/logger/` | 日志工具 |
| `static/` | 前端 embed 静态资源 |
### 命名规范
@@ -169,8 +171,16 @@ go test -v ./...
### 前端构建测试
```bash
cd app
npm run build # TypeScript 编译 + Vite 构建
cd frontend
npm run build
npx tsc --noEmit # 类型检查（提交前零错误）
```
### 独立二进制构建
```bash
./run.sh build tag v1.5.0
./aiops version
```
## 日志
docs/project-structure.md
+79 -140
View File
@@ -4,152 +4,82 @@
```
aiops/
├── frontend/ # 前端 (React 18 + TypeScript + Vite)
├── frontend/ # 前端 (React 19 + TypeScript + Vite)
│ ├── src/
│ │ ├── components/ # 业务组件（每个 <700行，超限已模块化拆分）
│ │ ├── components/ # 业务组件（单文件 <700 行）
│ │ │ ├── agent/ # Agent 监控
│ │ │ ├── aiops/ # AI 智能运维（AIPredictiveAnalytics 含 PredictiveCapacityTab）
│ │ │ ├── approval/ # 审批流程（ApprovalFlow + Process/Template Tab）
│ │ │ ├── audit/ # SQL 审计
│ │ │ ├── automation/ # 自动化运维（CronJob/Script/Ansible）
│ │ │ ├── cloud/ # 云平台管理（CloudBilling + Helpers 子组件）
│ │ │ ├── dashboard/ # 仪表盘（Charts/Recent/Stats 子组件）
│ │ │ ├── aiops/ # AI 智能运维
│ │ │ ├── approval/ # 审批流程
│ │ │ ├── automation/ # 自动化运维
│ │ │ ├── cloud/ # 云平台管理
│ │ │ ├── dashboard/ # 仪表盘
│ │ │ ├── deploy/ # CI/CD 部署
│ │ │ ├── k8s/ # K8s 集群管理（Detail/Dialog/Topology 子组件）
│ │ │ ├── layout/ # 布局组件
│ │ │ ├── monitor/ # 监控告警（AlertManager + Events/Rules Tab + Dialog 子组件）
│ │ │ │ ├── alert-center/ # 告警中心（AlertCenter + Detail 子组件）
│ │ │ │ ├── dashboard/ # Grafana 仪表盘（GrafanaPanelContent 子组件）
│ │ │ │ ├── logs/ # 日志管理
│ │ │ │ └── trace/ # 链路追踪
│ │ │ ├── navigation/ # 导航管理
│ │ │ ├── server/ # 服务器管理（ServerManager + Form/BatchImport 子组件）
│ │ │ ├── system/ # 系统管理（SystemManager + User/Settings/Logs/Roles/LDAP Tab 子组件）
│ │ │ └── ui/ # shadcn/ui 基础组件（sidebar.tsx + sidebar-context.tsx）
│ │ │ ├── k8s/ # K8s 集群管理
│ │ │ ├── monitor/ # 监控告警
│ │ │ ├── server/ # 服务器管理
│ │ │ ├── system/ # 系统管理
│ │ │ └── ui/ # shadcn/ui 基础组件
│ │ ├── hooks/ # 自定义 Hooks
│ │ ├── lib/ # 工具库
│ │ ├── mocks/ # Mock 数据（按 domain 模块化，barrel 统一导出）
│ │ │ ├── data.ts # Barrel re-export（统一入口）
│ │ │ └── modules/ # 按业务域分组
│ │ │ ├── servers.ts # 服务器/机柜
│ │ │ ├── cloud.ts # 云平台
│ │ │ ├── k8s.ts # K8s
│ │ │ ├── alerts.ts # 告警
│ │ │ ├── dashboard.ts # 仪表盘
│ │ │ ├── cicd.ts # CI/CD
│ │ │ ├── automation.ts # 自动化
│ │ │ ├── system.ts # 系统
│ │ │ ├── approval.ts # 审批
│ │ │ ├── monitor.ts # 监控
│ │ │ └── misc.ts # SQL审计/Ansible/导航等
│ │ ├── services/ # API 封装
│ │ ├── services/ # API 封装 (api.ts / http.ts)
│ │ ├── store/ # Zustand 状态管理
│ │ ├── types/ # TypeScript 类型定义
│ │ ├── App.css # 全局样式
│ │ ├── App.tsx # 根组件
│ │ ├── index.css # 基础样式
│ │ └── main.tsx # 应用入口
│ │ └── types/ # TypeScript 类型
│ ├── package.json
│ ├── vite.config.ts # Vite 配置（含 API 代理）
│ ├── tailwind.config.js # Tailwind CSS 配置
│ └── tsconfig.json
│ ├── vite.config.ts
│ └── Dockerfile # [legacy] 独立 Nginx 镜像
│
├── backend/ # 后端 (Go + Gin + GORM)
│ ├── cmd/
│ │ └── main.go # 应用入口
│ ├── internal/
│ │ ├── api/
│ │ │ ├── handlers/ # HTTP 处理器（模块化拆分）
│ │ │ │ ├── agent.go # Agent 管理
│ │ │ │ ├── agent_task.go # Agent 任务分发
│ │ │ │ ├── alert.go # 告警管理
│ │ │ │ ├── alert_engine.go # 告警引擎
│ │ │ │ ├── ansible.go # Ansible Playbook
│ │ │ │ ├── approval.go # 审批流程
│ │ │ │ ├── audit.go # 审计日志
│ │ │ │ ├── automation.go # 自动化运维（入口）
│ │ │ │ ├── automation_cron.go # 定时任务
│ │ │ │ ├── automation_script.go # 脚本管理
│ │ │ │ ├── automation_playbook.go # Playbook
│ │ │ │ ├── billing.go # 云账单
│ │ │ │ ├── cloud_accounts.go # 云账号
│ │ │ │ ├── cloud_domain.go # 域名
│ │ │ │ ├── cloud_platform.go # 云平台
│ │ │ │ ├── cloud_region.go # 区域
│ │ │ │ ├── dashboard.go # 仪表盘
│ │ │ │ ├── k8s.go # K8s 管理
│ │ │ │ ├── ldap.go # LDAP（入口）
│ │ │ │ ├── ldap_ou.go # LDAP OU 管理
│ │ │ │ ├── ldap_users.go # LDAP 用户同步
│ │ │ │ ├── log.go # 日志管理
│ │ │ │ ├── navigation.go # 导航管理
│ │ │ │ ├── pipeline.go # CI/CD 流水线
│ │ │ │ ├── resource_model.go # 资源模型
│ │ │ │ ├── server.go # 服务器管理（入口）
│ │ │ │ ├── user.go # 用户认证
│ │ │ │ ├── user_admin.go # 用户管理（管理员）
│ │ │ │ └── webshell.go # Web 终端
│ │ │ ├── middleware/ # 中间件
│ │ │ │ └── auth.go # JWT 认证 + RBAC
│ │ │ └── routes/
│ │ │ └── routes.go # 路由注册
│ │ ├── config/
│ │ │ └── config.go # 配置加载 (Viper)
│ │ └── models/ # 数据模型
│ │ ├── alert.go # 告警模型
│ │ ├── approval.go # 审批模型
│ │ ├── audit.go # 审计日志模型
│ │ ├── automation.go # 自动化运维模型
│ │ ├── cicd.go # CI/CD 模型
│ │ ├── common.go # 通用模型 (Response/List/Page)
│ │ ├── k8s.go # K8s 模型
│ │ ├── navigation.go # 导航模型
│ │ ├── server.go # 服务器模型
│ │ └── user.go # 用户模型
│ ├── pkg/
│ │ ├── database/
│ │ │ └── database.go # 数据库连接 + AutoMigrate
│ │ └── logger/
│ │ └── logger.go # Zap 日志
│ ├── scripts/
│ │ ├── init.sql # 初始化 SQL
│ │ └── mock.go # Mock 数据生成
│ ├── config.yaml # 配置文件（SQLite 默认）
│ ├── go.mod # Go 模块定义
│ ├── Dockerfile # Docker 构建
├── backend/ # 后端 (Go 1.24 + Gin + GORM)
│ ├── main.go # 应用入口（CLI + HTTP 服务）
│ ├── embed.go # go:embed 前端静态资源
│ ├── static/ # 前端构建产物（embed 目录）
│ ├── config/ # Viper 配置加载
│ ├── controller/ # HTTP 处理器
│ ├── middleware/ # JWT / 日志 / CORS
│ ├── router/ # 路由注册
│ ├── model/ # GORM 数据模型
│ ├── dto/ # 请求/响应 DTO
│ ├── service/ # 业务逻辑层
│ ├── repository/ # 数据访问层
│ ├── seed/ # 种子数据
│ ├── pkg/ # 公共包
│ │ ├── database/ # DB 连接 + AutoMigrate
│ │ ├── kubernetesclient/ # 轻量 K8s 客户端
│ │ ├── remoteexec/ # Go-native SSH
│ │ └── toolinstaller/ # 工具懒加载
│ ├── config.yaml # 默认配置
│ └── Dockerfile # [legacy] 分离式后端镜像
│
├── agent/ # 监控 Agent (Go, 独立 module ezops/agent)
│ ├── main.go # CLI 入口 (-server/-interval/-token/-hostname)
│ ├── collector/ # CPU/mem/disk/port/system 采集器 (/proc)
│ ├── model/model.go # 上报数据结构 (Report/CPUStat/MemStat/...)
│ ├── model/model_ext.go # 扩展类型 (NetworkStat/DiskIOStat/SystemStat)
│ ├── reporter/http.go # HTTP POST 上报
│ ├── task/ # 远程任务执行 (云助手模式)
│ ├── deploy/ # systemd service + install.sh 一键安装
│ ├── Makefile # 交叉编译 amd64+arm64+darwin-arm64
│ └── bin/ # 编译产物 (gitignore)
├── agent/ # 监控 Agent（独立 Go module）
│ ├── main.go # CLI 入口
│ ├── collector/ # /proc 指标采集
│ ├── task/ # 远程任务执行
│ ├── reporter/ # HTTP 上报
│ └── deploy/ # install.sh + systemd
│
├── docs/ # 开发文档
│ ├── README.md # 文档索引
│ ├── dev-log.md # 开发日志
│ ├── project-structure.md # 本文件
│ ├── quick-start.md # 快速开始
│ ├── api-reference.md # API 接口
│ ├── database-schema.md # 数据库设计
│ ├── development-guide.md # 开发规范
│ ├── deployment.md # 部署指南
│ ├── ROADMAP.md # 项目路线图
│ ├── PDD_PLAN.md # 产品开发计划
│ ├── PROJECT_SUMMARY.md # 项目概述
│ └── BACKEND_SUMMARY.md # 后端摘要
├── deploy/kubernetes/ # K8s 清单 (devops 命名空间)
│ ├── namespace.yaml
│ ├── deployment.yaml # embed 单容器, lghost/aiops:<tag>
│ ├── mysql.yaml / redis.yaml
│ └── ...
│
├── run.sh # 一键启动脚本
├── Makefile # 快捷命令
├── .env.example # 环境变量模板
├── .gitignore
├── docs/ # 开发文档（本目录）
├── docker-compose.yml # MySQL + Redis + AIOps embed
├── docker-compose.k8s.yml # 单应用 + 外部 DB
├── Dockerfile.embed # embed 单容器镜像（推荐）
├── run.sh # 统一入口脚本
├── aiops # 独立二进制产物（gitignore）
└── README.md
```
## 部署相关文件
| 文件 | 用途 |
|------|------|
| `run.sh` | build / docker / kubernetes / release 统一入口 |
| `Dockerfile.embed` | 生产推荐：前端嵌入后端单容器 |
| `docker-compose.yml` | 3 容器：MySQL + Redis + AIOps |
| `backend/static/` | `go:embed` 目标，由 `./run.sh build` 同步 |
| `./aiops` | 独立二进制输出路径（项目根目录） |
## 技术栈
### 前端
@@ -168,18 +98,27 @@ aiops/
| 技术 | 版本 | 用途 |
|------|------|------|
| Go | 1.21+ | 编程语言 |
| Go | 1.24+ | 编程语言 |
| Gin | v1.10+ | Web 框架 |
| GORM | v1.25+ | ORM 框架 |
| JWT | v5 (golang-jwt) | 认证 |
| GORM | v1.25+ | ORM |
| JWT | v5 | 认证 |
| Viper | - | 配置管理 |
| Zap | - | 结构化日志 |
| SQLite/MySQL/PostgreSQL | - | 数据库 |
| SQLite / MySQL / Redis | - | 存储 |
## 端口分配
| 服务 | 端口 | 说明 |
|------|------|------|
| 前端 (Vite dev) | 5173 | http://localhost:5173 |
| 后端 (Gin) | 8080 | http://localhost:8080 |
| 健康检查 | 8080 | http://localhost:8080/health |
| 前端 (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.embed` 构建参数 `VERSION` / `BUILD_TIME` / `GIT_COMMIT`
- 运行时：`./aiops version`、`GET /version`
docs/quick-start.md
+97 -92
View File
@@ -4,17 +4,18 @@
| 工具 | 最低版本 | 说明 |
|------|---------|------|
| Go | 1.21+ | 后端编译运行（需 CGO 支持 SQLite） |
| Go | 1.24+ | 后端编译（SQLite 需 CGO_ENABLED=1） |
| Node.js | 18+ | 前端构建 |
| npm | 9+ | 包管理 |
| gcc/clang | - | CGO 编译 SQLite 需要 |
| gcc/clang | - | CGO 编译 SQLite |
| Docker | 20+ | 可选，Compose/K8s 部署 |
### 检查环境
```bash
go version # >= 1.21
node -v # >= 18
gcc --version # macOS 自带 clang
go version
node -v
./run.sh help
```
## 安装
@@ -30,134 +31,138 @@ cd aiops
```bash
make install
# 或手动安装
# 或
cd backend && go mod download && cd ..
cd frontend cd app &&cd app && npm install && cd ..
cd frontend && npm install && cd ..
```
### 3. 配置（可选）
默认使用 SQLite，无需任何额外配置即可启动。
如需使用 MySQL 等其他数据库，编辑 `backend/config.yaml`：
```yaml
database:
driver: mysql # 改为 mysql / postgres
host: localhost
port: 3306
user: root
password: your_password
dbname: aiops
```
## 启动
### 方式一：一键启动（推荐）
## 本地开发（推荐）
```bash
chmod +x run.sh
./run.sh start
./run.sh dev
```
输出示例：
```
[INFO] ========== AIOps 启动脚本 ==========
[INFO] 正在启动后端服务...
[INFO] 编译 Go 程序...
[SUCCESS] 后端服务已启动 (PID: 12345, 端口: 8080)
[INFO] 正在启动前端服务...
[SUCCESS] 前端服务已启动 (PID: 12346, 端口: 5173)
[SUCCESS] ========== 所有服务已启动 ==========
[INFO] 前端地址: http://localhost:5173
[INFO] 后端地址: http://localhost:8080
[INFO] 健康检查: http://localhost:8080/health
[OK] 后端已启动 (PID: ..., 端口: 8080)
[OK] 前端已启动 (PID: ..., 端口: 5173)
```
### 方式二：分别启动
```bash
# 仅后端
./run.sh backend
# 仅前端
./run.sh frontend
```
### 方式三：使用 Makefile
```bash
make dev # 启动
make status # 查看状态
make stop # 停止
```
## 访问
| 地址 | 说明 |
|------|------|
| http://localhost:5173 | 前端界面 |
| http://localhost:8080/health | 后端健康检查 |
| http://localhost:5173 | 前端界面（Vite 热重载） |
| http://localhost:8080 | 后端 API |
| http://localhost:8080/version | 版本信息 |
| http://localhost:8080/api/v1/auth/login | 登录接口 |
| http://localhost:8080/health | 健康检查 |
### 默认账号
- 用户名：`admin`
- 密码：`123456`
## 常用命令
```bash
./run.sh status # 查看服务状态
./run.sh stop # 停止所有服务
./run.sh restart # 重启所有服务
./run.sh help # 查看帮助
make logs # 查看实时日志
make build # 构建生产包
make clean # 清理构建产物
./run.sh dev # 启动开发环境
./run.sh stop # 停止
./run.sh restart # 重启
./run.sh status # 查看状态
./run.sh logs # 实时日志
./run.sh help # 完整帮助
```
## 独立二进制（本机试用）
```bash
./run.sh build tag v1.0.0 # 编译到 ./aiops
./aiops version
./aiops --mode local # SQLite + redka，零外部依赖
```
数据文件与二进制同级：`./sqlite3.db`、`./redka.db`。
## Docker Compose（单机演示）
```bash
./run.sh docker up
# 访问 http://localhost:8080
```
## 发版（构建 + 推送镜像）
```bash
docker login
./run.sh release v1.5.0
```
镜像：`lghost/aiops:v1.5.0`
## 日志位置
| 服务 | 日志文件 |
|------|---------|
| 后端 | `backend/logs/server.log` |
| 前端 | `frontend/logs/dev.log` |
| 数据库 | `backend/data/aiops.db`（SQLite 文件） |
| 场景 | 日志 |
|------|------|
| 本地开发后端 | `backend/logs/server.log` |
| 本地开发前端 | `frontend/logs/dev.log` |
| 独立二进制 | `logs/aiops.log` |
| Docker | `./run.sh docker logs` |
## 数据库
默认使用 SQLite，数据库文件位于 `backend/data/aiops.db`，首次启动时自动创建表结构（AutoMigrate）。
### 开发模式
### 重置数据库
默认 SQLite，数据库由后端自动迁移（AutoMigrate）。
### local 二进制模式
```bash
./run.sh stop
rm -f backend/data/aiops.db
./run.sh start
./aiops --mode local
# sqlite3.db / redka.db 在项目根目录
```
### 重置 local 数据
```bash
./run.sh binary stop
rm -f sqlite3.db redka.db
./run.sh binary upgrade
```
## 常见问题
### Q: CGO 编译失败？
SQLite 需要 CGO 支持。确保环境变量 `CGO_ENABLED=1`：
### CGO 编译失败
```bash
export CGO_ENABLED=1
```
### Q: Go 模块下载慢？
设置国内代理：
```bash
export GOPROXY=https://goproxy.cn,direct
```
### Q: 端口被占用？
### Go 模块下载慢
```bash
./run.sh stop # 先停止
./run.sh start # 再启动
# 或强制释放端口
export GOPROXY=https://goproxy.cn,direct
export GOTOOLCHAIN=local
```
### 端口被占用
```bash
./run.sh stop
# 或
lsof -ti:8080 | xargs kill -9
lsof -ti:5173 | xargs kill -9
```
### Mac 编译的二进制无法在 Linux 运行
`./run.sh build` 在 Mac 上产出 darwin 二进制。Linux 部署请使用：
- `./run.sh release v1.x`（Docker 镜像）
- 或在 Linux 服务器上执行 `./run.sh build`
## 下一步
- [部署指南](./deployment.md) — 生产环境、版本管理、K8s
- [开发规范](./development-guide.md) — 代码规范
- [API 接口](./api-reference.md) — 后端 API