From 7856d5363588f16700b6c409dbd681d9158a2fb6 Mon Sep 17 00:00:00 2001 From: Wang Zhuoxuan Date: Fri, 17 Apr 2026 14:01:25 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20CI=20=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E6=96=87=E6=A1=A3=EF=BC=8C=E8=A1=A5=E5=85=85=E5=9B=BD?= =?UTF-8?q?=E5=86=85=E7=BD=91=E7=BB=9C=E9=80=82=E9=85=8D=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 Docker 镜像加速配置（服务器初始化） - 重写 Act Runner 安装章节：自定义镜像构建、config.yaml 关键配置、systemd --config 参数 - 补充三个国内网络问题的解决方案：Docker Hub 加速、github_mirror、--network host - 更新故障排查：新增 Action 拉取失败、checkout 失败两个排查项 - 更新目录结构：新增 act-runner/ 和 runner-image/ - 版本更新至 v5.1.0 --- docs/ci-deployment-guide.md | 120 ++++++++++++++++++++++++++++++++---- 1 file changed, 109 insertions(+), 11 deletions(-) diff --git a/docs/ci-deployment-guide.md b/docs/ci-deployment-guide.md index 6ed90fb..547d5ba 100644 --- 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