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

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

## 概览

- 依赖 Gitea Actions 与自建 Runner：推送到 `main` 时自动完成 Maven 打包、Docker 镜像构建/推送并通过 SSH 在目标主机拉取镜像、重启 `jt808-server` 容器。
- CI 流程文件位于 `.gitea/workflows/ci-deploy.yml`，使用 `actions/checkout`、`actions/setup-java`、`docker/build-push-action` 等常见 Actions，因此 Runner 也要兼容这些 Github Action 的语义（最新版本的 `gitea-runner` 默认支持）。

## 前置准备

1. **Runner 环境**：在可访问源码的 CI 节点安装 `gitea-runner`，为本仓库注册一个带标签 `self-hosted` 的 Runner。Runner 需要具备：
   - Docker（用于 Maven 容器构建 Jar、以及构建/推送应用镜像）。本 workflow 通过 `maven:3.9.9-eclipse-temurin-17` 容器执行 Maven，因此 **Runner 主机无需预装 Java/Maven**。
   - Docker CLI + `docker buildx` （用于构建、推送镜像）。
   - Git 和网络访问（拉取仓库、推送镜像、SSH 连接目标服务器）。
2. **Secrets 配置**：在 Gitea 仓库的 “Settings → Secrets” 下新增（若希望整个组织复用，可在组织层级配置，仓库内可以覆盖同名 Key）：
   - `REGISTRY_URL`：镜像仓库域名，例如 `registry.example.com`。
   - `REGISTRY_USERNAME` / `REGISTRY_PASSWORD`：镜像仓库凭据；若 Registry 允许匿名访问，可留空，本 workflow 会自动跳过登录步骤。
   - `IMAGE_NAME`：镜像名称，默认为 `jt808-server`。
   - `CLONE_TOKEN`：可选；**私有仓库**用来 `git clone` 的访问令牌（推荐使用一个只读 Token）。若仓库公开或 Runner 本身有访问权限可不配。

> 你提到“仓库/Runner/部署都在同一台服务器”时，本仓库的 workflow 默认采用**本机直接部署**（不走 SSH），因此不需要 `DEPLOY_*` 相关 Secrets。

## 工作流 `.gitea/workflows/ci-deploy.yml`

```6:30:.gitea/workflows/ci-deploy.yml
name: JT808 CI/CD

on:
  push:
    branches:
      - main
```

> Gitea Actions 使用 `uses: https://github.com/...` 语法来引用 GitHub 上已有的 Action，因此 workflow 中的 Action 即使不是 Gitea 官方的也能被 Runner 下载与执行。

> 如果你希望 **完全不依赖外部 Action**，可以像本仓库当前 workflow 一样：用 `run:` + `git clone` + `docker` 命令完成全部流程（不再使用 `checkout`）。

- **构建阶段**：
  - 使用 `git clone` 拉取代码（可选 `CLONE_TOKEN` 访问私有仓库）。
  - 使用 `maven:3.9.9-eclipse-temurin-17` 容器在 CI 中执行 `mvn -B clean package -DskipTests` 生成可执行 Jar。
- **镜像阶段**：
  - 直接使用 `docker build` / `docker push` 构建并推送镜像：标签格式 `${REGISTRY_URL}/${IMAGE_NAME}:${short-commit}`，通过 `git rev-parse --short HEAD` 动态生成。
- **部署阶段**：
  - 同机部署：在 Runner 所在服务器直接执行 `docker pull`、`docker stop`、`docker rm`、`docker run`，始终以 `jt808-server` 名称运行容器并暴露 `8080`/`20048`。

## 目标服务器要求

1. 安装并运行 Docker，允许 Runner 通过 SSH 执行命令。
2. 在目标服务器中预先创建 `.ssh/authorized_keys` 并部署 `DEPLOY_PRIVATE_KEY` 对应的公钥。
3. 目标主机需能访问 `${REGISTRY_URL}`（如存在防火墙或需登录）。

## 验证流程

1. Runner 全部就绪并注册为 `self-hosted`，Secrets 配置完成。
2. 推送或合并代码到 `main` 分支，Gitea Actions 自动触发。
3. 在 Gitea Actions 界面观察 Job，每一步日志分别输出 Maven 构建、Docker 镜像以及 SSH 部署的执行状态。
4. 登录目标主机执行 `docker ps`，确认 `jt808-server` 正在运行并使用最新镜像。
5. 访问 `http://目标主机:8080` / TCP 20048 确认服务可用。

## 参考

- Gitea Actions 文档：https://docs.gitea.io/en-us/actions/
- Gitea Runner：https://docs.gitea.io/en-us/runner/
- `appleboy/ssh-action` 详解：https://github.com/appleboy/ssh-action