From db4abe357ed88443e517f159769c84ff3042f2f1 Mon Sep 17 00:00:00 2001
From: lzh <sickone075@gmail.com>
Date: Fri, 12 Dec 2025 14:36:33 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20cicd-=E6=B5=81=E7=A8=8B=E6=9E=84?=
 =?UTF-8?q?=E5=BB=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitea/workflows/ci-deploy.yml | 64 ++++++++++++++++++++++++++++++++++
 README.md                      |  4 +++
 docs/ci-cd.md                  | 63 +++++++++++++++++++++++++++++++++
 3 files changed, 131 insertions(+)
 create mode 100644 .gitea/workflows/ci-deploy.yml
 create mode 100644 docs/ci-cd.md

diff --git a/.gitea/workflows/ci-deploy.yml b/.gitea/workflows/ci-deploy.yml
new file mode 100644
index 0000000..8f76500
--- /dev/null
+++ b/.gitea/workflows/ci-deploy.yml
@@ -0,0 +1,64 @@
+name: JT808 CI/CD
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    runs-on: 1panel-docker
+    env:
+      REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
+      IMAGE_NAME: ${{ secrets.IMAGE_NAME }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Build Jar
+        run: mvn -B clean package -DskipTests
+
+      - name: Determine image tag
+        id: vars
+        run: |
+          SHA=$(git rev-parse --short HEAD)
+          echo "IMAGE_TAG=${REGISTRY_URL}/${IMAGE_NAME}:${SHA}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to registry
+        if: ${{ secrets.REGISTRY_USERNAME && secrets.REGISTRY_PASSWORD }}
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ secrets.REGISTRY_URL }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          file: Dockerfile
+          tags: ${{ steps.vars.outputs.IMAGE_TAG }}
+
+      - name: Deploy to target host
+        uses: appleboy/ssh-action@v0.1.5
+        with:
+          host: ${{ secrets.DEPLOY_HOST }}
+          port: ${{ secrets.DEPLOY_PORT }}
+          username: ${{ secrets.DEPLOY_USER }}
+          key: ${{ secrets.DEPLOY_PRIVATE_KEY }}
+          script: |
+            docker pull ${{ steps.vars.outputs.IMAGE_TAG }}
+            docker stop jt808-server || true
+            docker rm jt808-server || true
+            docker run -d --name jt808-server -p 8080:8080 -p 20048:20048 ${{ steps.vars.outputs.IMAGE_TAG }}
+
diff --git a/README.md b/README.md
index 0e0515f..9f8f88a 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,10 @@ docker build -t jt808-server .
 docker run -d -p 8080:8080 -p 20048:20048 --name jt808 jt808-server
 ```
 
+## CI/CD
+
+参考 [`docs/ci-cd.md`](docs/ci-cd.md) 了解如何通过 Gitea Actions + Runner 构建容器、推送镜像并在目标主机上自动部署 `jt808-server`。
+
 ## API Usage
 
 **Report Location (HTTP):**
diff --git a/docs/ci-cd.md b/docs/ci-cd.md
new file mode 100644
index 0000000..2d916dd
--- /dev/null
+++ b/docs/ci-cd.md
@@ -0,0 +1,63 @@
+# 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
+