296 lines
7.1 KiB
Markdown
296 lines
7.1 KiB
Markdown
# 部署指南
|
||
|
||
本文档描述 AIOps 的三种部署方式、版本管理和镜像发布流程。
|
||
|
||
## 部署方式概览
|
||
|
||
| 方式 | 命令 | 容器/产物 | 前端 | 数据库 |
|
||
|------|------|-----------|------|--------|
|
||
| 独立二进制 | `./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
|
||
./aiops version
|
||
./aiops --version
|
||
curl http://localhost:8080/version
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"version": "v1.5.0",
|
||
"build_time": "2026-06-26T08:26:52Z",
|
||
"git_commit": "9f5ce24",
|
||
"mode": "local",
|
||
"db_driver": "sqlite",
|
||
"redis_driver": "redka"
|
||
}
|
||
```
|
||
|
||
### 一键发版
|
||
|
||
```bash
|
||
docker login
|
||
./run.sh release v1.5.0
|
||
```
|
||
|
||
依次执行：
|
||
|
||
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
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=aiops
|
||
WorkingDirectory=/opt/aiops
|
||
ExecStart=/opt/aiops/aiops --mode local --port 8080
|
||
Restart=always
|
||
RestartSec=5
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
---
|
||
|
||
## ② Docker Compose
|
||
|
||
### 架构（3 容器）
|
||
|
||
```
|
||
mysql:8.0 + redis:7-alpine + aiops (Dockerfile)
|
||
↓
|
||
http://localhost:8080
|
||
(API + WebSocket + 前端 SPA)
|
||
```
|
||
|
||
### 启动
|
||
|
||
```bash
|
||
./run.sh docker up
|
||
./run.sh docker up v1.5.0 # 指定版本
|
||
./run.sh docker up fresh # 无缓存全量重建
|
||
```
|
||
|
||
环境变量（可选）：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
chmod 600 .env
|
||
# 填写 MYSQL_ROOT_PASSWORD、MYSQL_PASSWORD、JWT_SECRET 后再启动
|
||
VERSION=v1.5.0 ./run.sh docker up
|
||
```
|
||
|
||
Compose 不再为密码或 JWT 提供不安全默认值；缺少任一必要值会拒绝启动。MySQL/Redis 端口仅绑定本机回环地址，Docker Socket 不会挂载给 AIOps 容器。
|
||
|
||
### 推送镜像
|
||
|
||
```bash
|
||
./run.sh docker push v1.5.0
|
||
# 等价于 docker push lghost/aiops:v1.5.0
|
||
```
|
||
|
||
### 连接外部数据库
|
||
|
||
使用 `docker-compose.k8s.yml`（仅单应用容器，连接外部 MySQL/Redis）：
|
||
|
||
```bash
|
||
VERSION=v1.5.0 docker compose -f docker-compose.k8s.yml up -d --build
|
||
```
|
||
|
||
该方式要求在 `.env`（权限 `600`）提供 `DATABASE_HOST`、`DATABASE_USER`、`DATABASE_PASSWORD`、`REDIS_HOST` 和 `JWT_SECRET`；uploads 使用命名卷持久化。
|
||
|
||
### 管理命令
|
||
|
||
```bash
|
||
./run.sh docker ps
|
||
./run.sh docker logs
|
||
./run.sh docker down
|
||
./run.sh docker clean # 清理构建缓存
|
||
```
|
||
|
||
---
|
||
|
||
## ③ Kubernetes
|
||
|
||
### 镜像
|
||
|
||
- 默认镜像：`lghost/aiops:<tag>`
|
||
- 构建文件：`Dockerfile`
|
||
- 命名空间：`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` 内固定 `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) | ✅ | 产出 linux/amd64 镜像 |
|
||
| `docker push lghost/aiops:tag` | ✅ | 需 `docker login` |
|
||
| `./run.sh release v1.x` | ✅ | 完整发版流程 |
|
||
|
||
---
|
||
|
||
## 健康检查
|
||
|
||
```bash
|
||
curl http://localhost:8080/version # 推荐（无 DB 强依赖）
|
||
curl http://localhost:8080/health # 含 DB 检查
|
||
```
|
||
|
||
K8s 探针使用 `/version`。
|
||
|
||
---
|
||
|
||
## 生产配置建议
|
||
|
||
1. **数据库**：生产使用 MySQL + Redis（`MODE=release`），local 模式仅适合单副本
|
||
2. **Secret**：通过 Secret 管理系统或权限为 `600` 的 `.env` 注入数据库密码和至少 32 字节 JWT；不得提交真实值
|
||
3. **运行身份**：镜像默认以非 root UID `10001` 运行；不得恢复 Docker Socket 或 `hostNetwork` 挂载
|
||
4. **持久化**：备份 MySQL 数据、SQLite/redka PVC 和 uploads PVC，并定期验证恢复
|
||
5. **网络**：K8s 的 `deployment.yaml` 内置 MySQL/Redis NetworkPolicy；在收集 Ingress/Agent 出口 CIDR 后继续收紧 AIOps 入站规则
|
||
6. **版本**：生产环境 pin 镜像 tag（`lghost/aiops:v1.5.0`），避免使用 `:dev`
|
||
7. **HTTPS**：Ingress 或前置 Nginx 终止 TLS
|
||
|
||
---
|
||
|
||
## 相关文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `run.sh` | 统一入口（build/docker/kubernetes/release） |
|
||
| `Dockerfile` | embed 单容器镜像（推荐） |
|
||
| `docker-compose.yml` | MySQL + Redis + AIOps |
|
||
| `deploy/kubernetes/deployment.yaml` | K8s Deployment + NodePort |
|
||
| `.gitignore` | 忽略 `aiops`、`backend/aiops*` 等编译产物 |
|