# 部署指南

本文档描述 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*` 等编译产物 |