fix: cicd-调整4

docs/ci-cd.md

@@ -2,63 +2,41 @@
 
 ## 概览
 
-- 依赖 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` 默认支持）。
+- **构建方式**：采用 Docker Multi-stage 构建。第一阶段使用 Maven 镜像编译代码，第二阶段使用 JRE 镜像运行，产出极简镜像。
+- **流程文件**：`.gitea/workflows/ci-deploy.yml`。
+- **依赖**：依赖 `actions/checkout` (Gitea 内置或兼容) 以及 Docker 环境。
 
 ## 前置准备
 
-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 本身有访问权限可不配。
+### 1. Runner 环境
+在部署目标服务器上安装 `gitea-runner` 并注册。
+- **Labels**: 确保 Runner 包含标签 `xw-runner` (或修改 workflow 文件中的 `runs-on` 字段)。
+- **Docker**: 宿主机需安装 Docker，且 Runner 用户有权限执行 `docker` 命令。
 
-> 你提到“仓库/Runner/部署都在同一台服务器”时，本仓库的 workflow 默认采用**本机直接部署**（不走 SSH），因此不需要 `DEPLOY_*` 相关 Secrets。
+### 2. Secrets 配置 (Gitea 仓库设置 -> Secrets)
+请配置以下 Secrets 以支持镜像推送：
 
-## 工作流 `.gitea/workflows/ci-deploy.yml`
+| 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`) |
 
-```6:30:.gitea/workflows/ci-deploy.yml
-name: JT808 CI/CD
+> 注意：如果使用的是 HTTP 的私有仓库，请确保 Runner 的 `/etc/docker/daemon.json` 中配置了 `insecure-registries`。
 
-on:
-  push:
-    branches:
-      - main
-```
+## 工作流详解
 
-> Gitea Actions 使用 `uses: https://github.com/...` 语法来引用 GitHub 上已有的 Action，因此 workflow 中的 Action 即使不是 Gitea 官方的也能被 Runner 下载与执行。
+1. **Check out**: 拉取最新代码。
+2. **Login**: 登录 Docker Registry。
+3. **Build & Push**: 
+   - 执行 `docker build`，自动在容器内完成 `mvn package` 和镜像打包。
+   - 执行 `docker push` 推送到配置的仓库。
+4. **Deploy**:
+   - 停止旧容器 `jt808-server`。
+   - 启动新容器，映射端口 `8080` (Web) 和 `20048` (TCP)。
 
-> 如果你希望 **完全不依赖外部 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
+## 常见问题
 
+- **actions/checkout 失败**: 如果 Runner 无法访问外网 GitHub，请确保 Gitea 实例已配置 Action 镜像，或手动修改 workflow 使用 git 命令。
+- **Maven 构建慢**: Docker 构建缓存会加速后续构建。首次构建需要下载 Maven 依赖，耗时较长。