# CI/CD 部署文档

本文档描述 LiveForum 论坛社区项目的 CI/CD 流水线配置，基于 Drone CI + Docker + Harbor 私有镜像仓库。

## 一、整体架构

```
代码推送 (master) → Drone CI 触发 → 构建 Docker 镜像 → 推送 Harbor → SSH 部署到服务器
```

| 组件 | 说明 |
|------|------|
| CI 平台 | Drone CI (`192.168.195.25:13080`) |
| 镜像仓库 | Harbor (`192.168.195.25:19900`，HTTP） |
| 部署方式 | Docker Compose |
| 部署服务器 | `192.168.195.15` |
| 触发条件 | `master` 分支 push 事件 |

## 二、构建的镜像

| 镜像 | 说明 | Dockerfile | 构建上下文 |
|------|------|-----------|-----------|
| `live-forum/webapi` | 小程序 API（.NET 8） | `server/webapi/LiveForum/LiveForum.WebApi/Dockerfile` | `server/webapi/LiveForum` |
| `live-forum/admin-api` | 后台管理 API（.NET 8） | `server/admin/ZrAdminNetCore/ZR.Admin.WebApi/Dockerfile` | `server/admin/ZrAdminNetCore` |
| `live-forum/admin-web` | 后台管理前端（Vue 3 + Nginx） | `server/admin/ZrAdminNetCore/ZR.Vue/Dockerfile` | `server/admin/ZrAdminNetCore/ZR.Vue` |

每个镜像打两个标签：`latest` 和 commit SHA 前 8 位（用于回滚）。

## 三、流水线步骤

`.drone.yml` 定义了 4 个步骤：

1. `build-webapi` — 构建小程序 API 镜像
2. `build-admin-api` — 构建后台管理 API 镜像
3. `build-admin-web` — 构建后台管理前端镜像
4. `deploy` — SSH 部署（等待前三步完成）

> 三个构建步骤默认并行执行，deploy 步骤通过 `depends_on` 等待全部完成后执行。

## 四、基础镜像（内网 Harbor）

所有 Dockerfile 的基础镜像已切换到内网 Harbor，避免依赖外网：

| 基础镜像 | 内网地址 | 用途 |
|---------|---------|------|
| `dotnet/aspnet:8.0` | `192.168.195.25:19900/library/dotnet/aspnet:8.0` | .NET 运行时 |
| `dotnet/sdk:8.0` | `192.168.195.25:19900/library/dotnet/sdk:8.0` | .NET 构建 |
| `node:18-alpine` | `192.168.195.25:19900/library/node:18-alpine` | Vue 前端构建 |
| `nginx:alpine` | `192.168.195.25:19900/library/nginx:alpine` | 前端运行 |

如需更新基础镜像，在能访问外网的机器上拉取、tag、push：

```bash
docker pull mcr.microsoft.com/dotnet/aspnet:8.0
docker tag mcr.microsoft.com/dotnet/aspnet:8.0 192.168.195.25:19900/library/dotnet/aspnet:8.0
docker push 192.168.195.25:19900/library/dotnet/aspnet:8.0
docker tag caddy:alpine 192.168.195.25:19900/library/caddy:alpine
 
```

## 五、前置条件

### 5.1 Drone CI Secrets

在 Drone 仓库设置 → Secrets 中配置：

| Secret 名称 | 说明 |
|-------------|------|
| `harbor_username` | Harbor 仓库用户名 |
| `harbor_password` | Harbor 仓库密码 |
| `ssh_username` | 部署服务器 SSH 用户名 |
| `ssh_password` | 部署服务器 SSH 密码 |

### 5.2 Harbor 镜像仓库

1. 在 Harbor 中创建项目 `live-forum` 和 `library`
2. `library` 为公开项目，存放基础镜像（pull 不需要登录）
3. `live-forum` 存放业务镜像，推送需要认证
4. 当前使用 HTTP（`insecure: true`）

### 5.3 部署服务器（192.168.195.15）

1. 安装 Docker 和 Docker Compose
2. 配置 Docker 信任 Harbor（HTTP）：

```bash
# /etc/docker/daemon.json
{
  "insecure-registries": ["192.168.195.25:19900"]
}

# 重启 Docker
systemctl restart docker
```

3. 登录 Harbor：

```bash
docker login 192.168.195.25:19900
```

4. 部署目录：`/disk/docker-compose/live-forum-new`

## 六、常见问题

### Q: 构建时拉取基础镜像失败？

基础镜像需要提前推送到内网 Harbor。Drone CI 的 Docker daemon 也需要配置 `insecure-registries`（在 `.drone.yml` 中通过 `insecure: true` 处理推送，但 Dockerfile 中的 FROM 拉取需要 runner 层面配置）。

### Q: Harbor 认证失败（unauthorized）？

检查 Drone Secrets 中的 `harbor_username` / `harbor_password` 是否正确且未过期。

### Q: 部署后服务没更新？

1. 检查 `docker compose pull` 是否拉到了新镜像
2. 确认服务器 Docker 已配置 `insecure-registries`
3. 检查容器状态：`docker compose ps` / `docker compose logs`

### Q: 如何回滚？

使用 commit SHA 标签：

```bash
# 在服务器上修改 docker-compose.yml 中的镜像标签
# 例如将 :latest 改为 :a1b2c3d4
docker compose up -d
```

### Q: admin-web 构建报 COPY failed: stat app/dist？

`vite.config.js` 中 `outDir` 配置了服务器绝对路径，Dockerfile 中已通过 `npx vite build --mode production --outDir dist` 覆盖输出到 `dist` 目录。

### Q: 如何手动触发构建？

在 Drone 界面找到对应仓库，点击 "New Build"，选择分支即可。