# 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 需要具备：
   - Java 17 + Maven（用于构建）。
   - Docker CLI + `docker buildx` （用于构建、推送镜像）。
   - Git 和网络访问（拉取仓库、推送镜像、SSH 连接目标服务器）。
2. **Secrets 配置**：在 Gitea 仓库的 “Settings → Secrets” 下新增：
   - `REGISTRY_URL`：镜像仓库域名，例如 `registry.example.com`。
   - `REGISTRY_USERNAME` / `REGISTRY_PASSWORD`：镜像仓库凭据；若 Registry 允许匿名访问，可留空，本 workflow 会自动跳过登录步骤。
   - `IMAGE_NAME`：镜像名称，默认为 `jt808-server`。
   - `DEPLOY_HOST` / `DEPLOY_PORT`：SSH 目标主机地址与端口（22）。
   - `DEPLOY_USER`：SSH 用户名。
   - `DEPLOY_PRIVATE_KEY`：SSH 私钥，目标主机需部署对应的公钥。

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

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

on:
  push:
    branches:
      - main
```

- **构建阶段**：
  - `actions/checkout@v4` 拉取代码。
  - `actions/setup-java@v4` 配置 Temurin JDK 17。
  - 使用 `mvn -B clean package -DskipTests` 生成可执行 Jar。
- **镜像阶段**：
  - `docker/setup-buildx-action@v3` 准备多平台构建环境。
  - `docker/login-action@v3` 登陆私有仓库。
  - `docker/build-push-action@v5` 构建 Docker 镜像并推送：标签格式 `${REGISTRY_URL}/${IMAGE_NAME}:${short-commit}`，通过 `git rev-parse --short HEAD` 动态生成。
- **部署阶段**：
  - `appleboy/ssh-action@v0.1.5` 登录目标主机，执行 `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