aiops/docs/deployment.md

部署指南

本文档描述 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

查看版本

./aiops version
./aiops --version
curl http://localhost:8080/version

响应示例：

{
  "version": "v1.5.0",
  "build_time": "2026-06-26T08:26:52Z",
  "git_commit": "9f5ce24",
  "mode": "local",
  "db_driver": "sqlite",
  "redis_driver": "redka"
}

一键发版

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 镜像坐标

发版后可选：

git push origin master
git push origin v1.5.0

---

① 独立二进制

编译

./run.sh build                  # 自动解析版本
./run.sh build tag v1.5.0       # 指定版本

产物固定输出到 项目根目录 ./aiops，不会在 backend/ 下生成。

构建前会自动清理历史产物：backend/aiops*。

启动

./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 示例

[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)

启动

./run.sh docker up
./run.sh docker up v1.5.0       # 指定版本
./run.sh docker up fresh        # 无缓存全量重建

环境变量（可选）：

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 容器。

推送镜像

./run.sh docker push v1.5.0
# 等价于 docker push lghost/aiops:v1.5.0

连接外部数据库

使用 docker-compose.k8s.yml（仅单应用容器，连接外部 MySQL/Redis）：

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 使用命名卷持久化。

管理命令

./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

部署

./run.sh kubernetes deploy
./run.sh kubernetes deploy v1.5.0

滚动更新

./run.sh kubernetes upgrade v1.5.0

推送镜像（Mac 可构建 Linux 镜像）

./run.sh kubernetes push v1.5.0

Dockerfile 内固定 GOOS=linux GOARCH=amd64，在 Mac 上 docker build 产出的是 Linux 镜像。

运维命令

./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	✅	完整发版流程

---

健康检查

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* 等编译产物