iot-test-platform/docs/ci-cd.md

# CI/CD 通过 Gitea Actions + Runner 容器化部署

## 概览

- **构建方式**：采用 Docker Multi-stage 构建。第一阶段使用 Maven 镜像编译代码，第二阶段使用 JRE 镜像运行，产出极简镜像。
- **流程文件**：`.gitea/workflows/ci-deploy.yml`。
- **依赖**：依赖 `actions/checkout` (Gitea 内置或兼容) 以及 Docker 环境。

## 前置准备

### 1. Runner 环境
在部署目标服务器上安装 `gitea-runner` 并注册。
- **Labels**: 确保 Runner 包含标签 `xw-runner` (或修改 workflow 文件中的 `runs-on` 字段)。
- **Docker**: 宿主机需安装 Docker，且 Runner 用户有权限执行 `docker` 命令。

### 2. Secrets 配置 (Gitea 仓库设置 -> Secrets)
请配置以下 Secrets 以支持镜像推送：

| Secret Key | 说明 | 示例 |
| :--- | :--- | :--- |
| `REGISTRY_URL` | **(必填)** 镜像仓库地址 | `192.168.1.10:5000` 或 `docker.io` |
| `REGISTRY_USERNAME` | (可选) 镜像仓库用户名 | `admin` |
| `REGISTRY_PASSWORD` | (可选) 镜像仓库密码 | `my-secret-password` |
| `IMAGE_NAME` | (可选) 镜像名称空间/名 | `hua/jt808-server` (默认为 `jt808-server`) |

> 注意：如果使用的是 HTTP 的私有仓库，请确保 Runner 的 `/etc/docker/daemon.json` 中配置了 `insecure-registries`。

## 工作流详解

1. **Check out**: 拉取最新代码。
2. **Login**: 登录 Docker Registry。
3. **Build & Push**: 
   - 执行 `docker build`，自动在容器内完成 `mvn package` 和镜像打包。
   - 执行 `docker push` 推送到配置的仓库。
4. **Deploy**:
   - 停止旧容器 `jt808-server`。
   - 启动新容器，映射端口 `8080` (Web) 和 `20048` (TCP)。

## 常见问题

- **actions/checkout 失败**: 如果 Runner 无法访问外网 GitHub，请确保 Gitea 实例已配置 Action 镜像，或手动修改 workflow 使用 git 命令。
- **Maven 构建慢**: Docker 构建缓存会加速后续构建。首次构建需要下载 Maven 依赖，耗时较长。