docs: 更新 CI 部署文档，补充国内网络适配配置

- 新增 Docker 镜像加速配置（服务器初始化） - 重写 Act Runner 安装章节：自定义镜像构建、config.yaml 关键配置、systemd --config 参数 - 补充三个国内网络问题的解决方案：Docker Hub 加速、github_mirror、--network host - 更新故障排查：新增 Action 拉取失败、checkout 失败两个排查项 - 更新目录结构：新增 act-runner/ 和 runner-image/ - 版本更新至 v5.1.0
2026-04-17 14:01:25 +08:00 · 2026-04-17 14:01:25 +08:00 · 7856d53635
commit 7856d53635
parent 02a50617e7
1 changed files with 109 additions and 11 deletions
--- a/docs/ci-deployment-guide.md
+++ b/docs/ci-deployment-guide.md
@ -111,7 +111,18 @@ dnf install -y curl git nginx certbot python3-certbot-nginx
 dnf install -y docker docker-compose-plugin
 systemctl enable --now docker

-# 4. 配置防火墙（firewalld）
+# 4. 配置 Docker 镜像加速（国内网络必须）
+tee /etc/docker/daemon.json << 'EOF'
+{
+  "registry-mirrors": [
+    "https://docker.1ms.run",
+    "https://docker.xuanyuan.me"
+  ]
+}
+EOF
+systemctl restart docker
+
+# 5. 配置防火墙（firewalld）
 #    所有服务通过 Nginx 反向代理，只需开放 22/80/443
 systemctl enable --now firewalld
 firewall-cmd --permanent --add-service=ssh
@ -119,12 +130,13 @@ firewall-cmd --permanent --add-service=http
 firewall-cmd --permanent --add-service=https
 firewall-cmd --reload

-# 5. 创建项目目录
+# 6. 创建项目目录
 mkdir -p /opt/duoqi-api
 mkdir -p /opt/gitea
 mkdir -p /opt/backups
+mkdir -p /opt/runner-image

-# 6. 验证
+# 7. 验证
 cat /etc/os-release      # 确认 Alibaba Cloud Linux
 docker --version
 nginx -v
@ -275,6 +287,31 @@ cd /opt/gitea && docker compose up -d

 #### 安装 Act Runner（CI/CD 执行器）

+> **国内网络关键配置**：Gitea Act Runner 使用 Docker 执行器，需要解决三个网络问题：
+> 1. Docker Hub 镜像拉取 → 通过 Docker 镜像加速解决（已在服务器初始化配置）
+> 2. GitHub Actions 拉取 → 通过 `github_mirror` 配置从 gitea.com 镜像解决
+> 3. 容器访问 Gitea API → 通过 `--network host` 让容器共享宿主机网络
+
+##### 1. 构建 Runner 自定义镜像
+
+> `oven/bun:latest` 不包含 git，`actions/checkout` 会回退到 REST API 下载代码，
+> 但 GitHub 风格的 REST API URL（`/tarball/{ref}`）与 Gitea（`/archive/{ref}.tar.gz`）不兼容。
+> 因此需要构建预装 git 的自定义镜像，避免每次 CI 安装。
+
+```bash
+# 创建 Dockerfile
+cat > /opt/runner-image/Dockerfile << 'EOF'
+FROM oven/bun:latest
+RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources \
+    && apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+EOF
+
+# 构建镜像（使用阿里云 Debian 镜像源加速）
+docker build -t duoqi-runner:bun-git /opt/runner-image
+```
+
+##### 2. 安装并注册 Runner
+
 ```bash
 # 下载 Act Runner
 wget -O /usr/local/bin/act_runner https://gitea.com/gitea/act_runner/releases/latest/download/act_runner-linux-amd64
@ -286,14 +323,42 @@ chmod +x /usr/local/bin/act_runner
 # 创建专用工作目录（register 和 daemon 必须在同一目录）
 mkdir -p /opt/act-runner

-# 注册 Runner
+# 注册 Runner（使用自定义镜像）
 cd /opt/act-runner && act_runner register \
  --instance http://localhost:3200 \
  --token YOUR_RUNNER_TOKEN \
  --name duoqi-runner \
-  --labels ubuntu-latest:docker://oven/bun:latest
+  --labels ubuntu-latest:docker://duoqi-runner:bun-git
+```

-# 创建 systemd 服务
+##### 3. 生成并配置 Runner 配置文件
+
+```bash
+# 生成默认配置
+cd /opt/act-runner && act_runner generate-config > config.yaml
+```
+
+编辑 `/opt/act-runner/config.yaml`，修改以下关键配置：
+
+```yaml
+runner:
+  # 移除默认的测试环境变量
+  envs: {}
+  # 从 gitea.com 镜像拉取 GitHub Actions（解决国内无法访问 GitHub 的问题）
+  github_mirror: 'https://gitea.com'
+  labels:
+    - "ubuntu-latest:docker://duoqi-runner:bun-git"
+
+container:
+  # 容器使用宿主机网络（解决容器无法访问 127.0.0.1:3200 Gitea 的问题）
+  network: "host"
+  # 不强制每次拉取镜像（国内网络下减少失败风险）
+  force_pull: false
+```
+
+##### 4. 创建 systemd 服务并启动
+
+```bash
 cat > /etc/systemd/system/act-runner.service << 'EOF'
 [Unit]
 Description=Gitea Act Runner
@ -301,7 +366,7 @@ After=docker.service

 [Service]
 WorkingDirectory=/opt/act-runner
-ExecStart=/usr/local/bin/act_runner daemon
+ExecStart=/usr/local/bin/act_runner daemon --config /opt/act-runner/config.yaml
 Restart=always
 Environment=HOME=/root

@ -482,7 +547,7 @@ develop 分支（开发测试）              main 分支（生产发布）
    │                                    │
    ▼                                    ▼
 ┌───────────┐                      ┌───────────┐
-│  quality  │ ← Lint + 类型检查     │  quality  │ ← Lint + 类型检查
+│  quality  │ ← 类型检查            │  quality  │ ← 类型检查
 └─────┬─────┘                      └─────┬─────┘
      ▼                                  ▼
 ┌───────────┐                      ┌───────────┐
@ -543,6 +608,9 @@ git push origin main
 | 测试环境使用 Docker profiles | 按需启停，节省内存 |
 | 生产部署手动确认 | 防止误操作，确保人工验证后才上线 |
 | 使用 Gitea Actions | 兼容 GitHub Actions 语法，学习成本低 |
+| Runner 使用 `--network host` | 容器共享宿主机网络，解决容器无法访问 Gitea 的问题 |
+| Runner 使用 `github_mirror` | 从 gitea.com 镜像拉取 Actions，解决国内无法访问 GitHub 的问题 |
+| 自定义 Runner 镜像（bun + git） | 避免 checkout REST API 与 Gitea 不兼容的问题，跳过每次安装 |

 ### 部署操作

@ -919,7 +987,32 @@ systemctl restart act-runner
 journalctl -u act-runner -f
 ```

-#### 4. 数据库连接失败
+#### 4. CI Action 拉取失败（国内网络）
+
+```bash
+# 检查 github_mirror 配置
+grep github_mirror /opt/act-runner/config.yaml
+# 应输出：github_mirror: 'https://gitea.com'
+
+# 清除缓存的 action（修复损坏的缓存）
+rm -rf /root/.cache/act/
+
+# 重启 Runner
+systemctl restart act-runner
+```
+
+#### 5. CI checkout 失败（ECONNREFUSED 或 404）
+
+```bash
+# 检查容器网络配置
+grep -A2 "network:" /opt/act-runner/config.yaml
+# 应包含：network: "host"
+
+# 确认 Gitea API 可达
+curl http://localhost:3200/api/v1/repos/search?q=duoqi-api
+```
+
+#### 6. 数据库连接失败

 ```bash
 # 从服务器测试 RDS 连通性
@ -953,6 +1046,11 @@ docker compose up -d api-prod
 ├── gitea/                        # Gitea 代码托管
 │   ├── docker-compose.yml
 │   └── data/                     # Gitea 数据（仓库、配置）
+├── act-runner/                   # Act Runner CI/CD 执行器
+│   ├── config.yaml               # Runner 配置（网络、镜像源等）
+│   └── .runner                   # 注册数据
+├── runner-image/                 # Runner 自定义镜像
+│   └── Dockerfile                # 基于 oven/bun + git
 ├── duoqi-api/                    # 应用部署
 │   ├── docker-compose.yml        # 包含 prod + test 配置
 │   ├── .env.prod                 # 生产环境变量
@ -1001,6 +1099,6 @@ docker compose up -d api-prod

 ---

-**文档版本**: v5.0.0 (双分支工作流)
-**最后更新**: 2026-04-16
+**文档版本**: v5.1.0 (双分支工作流 + 国内网络适配)
+**最后更新**: 2026-04-17
 **维护者**: Duoqi Team