docs: 更新 CI 部署文档至 v5.3.0

同步实际部署配置变更：
- Docker Compose 使用 network_mode: host 避免 VPC 冲突
- Act Runner config 补充 options + valid_volumes 挂载配置
- 移除 systemd 不必要的 BindPaths
- CI health check 改用 bun fetch
- 新增 Docker bridge/VPC 冲突和 health check 故障排查

docs/ci-deployment-guide.md

@@ -361,6 +361,11 @@ runner:
 container:
   # 容器使用宿主机网络（解决容器无法访问 127.0.0.1:3200 Gitea 的问题）
   network: "host"
+  # 挂载宿主机目录到 job 容器（CI deploy 步骤需要读取 docker-compose.yml）
+  options: "-v /opt/duoqi-api:/opt/duoqi-api"
+  # 允许挂载的 volume 白名单
+  valid_volumes:
+    - /opt/duoqi-api
   # 不强制每次拉取镜像（国内网络下减少失败风险）
   force_pull: false
 ```
@@ -379,9 +384,6 @@ ExecStart=/usr/local/bin/act_runner daemon --config /opt/act-runner/config.yaml
 Restart=always
 Environment=HOME=/root
 
-# 关键：挂载 Docker socket，让 job 容器能访问宿主机的 Docker daemon
-BindPaths=/var/run/docker.sock:/var/run/docker.sock
-
 [Install]
 WantedBy=multi-user.target
 EOF
@@ -395,6 +397,11 @@ systemctl start act-runner
 systemctl status act-runner
 ```
 
+> **注意**：act_runner 是宿主机原生运行的二进制，不是容器。它本身已有完整的文件系统和网络访问权限。
+> - **不需要** `BindPaths` 挂载 Docker socket（宿主机进程可直接访问）
+> - **不需要** `BindPaths` 挂载 `/opt/duoqi-api`（同上）
+> - job 容器需要访问宿主机目录，通过 `config.yaml` 中的 `container.options` 和 `valid_volumes` 配置
+
 ### 环境隔离策略
 
 #### RDS 数据库隔离
@@ -472,21 +479,22 @@ LOG_LEVEL=debug
 
 **服务器 compose 文件** `/opt/duoqi-api/docker-compose.yml`：
 
+> 代码库中对应文件为 `docker-compose.prod.yml`，部署时手动重命名为 `docker-compose.yml`。
+
 ```yaml
-version: '3.8'
+# 使用 host 网络模式，避免 Docker bridge 子网与阿里云 VPC 内网 IP 段冲突
 
 services:
   # ===== 生产环境 =====
   api-prod:
     build:
-      context: /opt/gitea/data/git/repositories/admin/duoqi-api.git
+      context: .
       dockerfile: Dockerfile
     image: duoqi-api:prod
     container_name: duoqi-api-prod
     restart: unless-stopped
+    network_mode: host
     env_file: .env.prod
-    ports:
-      - "3000:3000"
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
       interval: 30s
@@ -503,17 +511,16 @@ services:
         limits:
           memory: 400M
 
-  # ===== 测试环境（按需启停） =====
+  # ===== 测试环境（Docker profiles 按需启停） =====
   api-test:
     build:
-      context: /opt/gitea/data/git/repositories/admin/duoqi-api.git
+      context: .
       dockerfile: Dockerfile
     image: duoqi-api:test
     container_name: duoqi-api-test
-    restart: "no"  # 不自动重启，手动控制
+    restart: "no"
+    network_mode: host
     env_file: .env.test
-    ports:
-      - "3001:3001"
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:3001/health"]
       interval: 30s
@@ -530,7 +537,7 @@ services:
         limits:
           memory: 300M
     profiles:
-      - test  # 使用 profiles 按需启停
+      - test
 ```
 
 **启停命令：**
@@ -621,9 +628,11 @@ git push origin main
 | 生产部署手动确认 | 防止误操作，确保人工验证后才上线 |
 | 使用 Gitea Actions | 兼容 GitHub Actions 语法，学习成本低 |
 | Runner 使用 `network: host` | 容器共享宿主机网络，解决容器无法访问 Gitea 的问题 |
+| API 容器使用 `network_mode: host` | 避免 Docker bridge 默认子网（172.x.0.0/16）与阿里云 VPC 内网 IP 段冲突 |
 | Runner 使用 `github_mirror` | 从 gitea.com 镜像拉取 Actions，解决国内无法访问 GitHub 的问题 |
 | 自定义 Runner 镜像（bun + git + docker CLI） | 避免 checkout REST API 不兼容，支持 CI 中执行 docker 命令 |
-| Runner 挂载 Docker socket | Job 容器通过 socket 访问宿主机 Docker daemon，执行构建操作 |
+| Runner config 的 `options` + `valid_volumes` | 让 job 容器能挂载宿主机的 `/opt/duoqi-api` 目录，读取 docker-compose.yml |
+| CI health check 使用 `bun -e "fetch(...)"` | runner 镜像未安装 curl，用 bun 内置 fetch API 做 HTTP 健康检查 |
 | 固定 Bun 版本（1.3） | 确保 CI 环境可复现，避免 latest 版本变化导致意外失败 |
 
 ### 部署操作
@@ -840,11 +849,10 @@ services:
 # Phase 2: 多实例 docker-compose.yml
 # API 服务器上的配置
 
-version: '3.8'
-
 services:
   api:
     image: your-registry/duoqi-api:latest
+    network_mode: host
     deploy:
       replicas: 2       # 运行 2 个实例
       resources:
@@ -1036,6 +1044,48 @@ mysql -h your-rds-endpoint -u duoqi_prod -p -e "SELECT 1;"
 # 阿里云 RDS 控制台 → 数据安全性 → 白名单设置
 ```
 
+#### 7. Docker bridge 网络与 VPC 内网冲突
+
+> **症状**：服务器无法连接 RDS（或 VPC 内其他服务），ping 显示源 IP 为 `172.x.0.1`（Docker 网桥 IP）而非宿主机内网 IP。
+
+```bash
+# 查看路由表，检查是否有 Docker 网桥路由劫持了 VPC 流量
+route -n
+# 如果看到类似以下行，说明 Docker bridge 子网与 RDS IP 段冲突：
+# 172.23.0.0   0.0.0.0   255.255.0.0   U   0   0   0 br-xxxxxx
+
+# 查看哪个 Docker 网络创建了冲突子网
+docker network ls
+docker network inspect <network-name>
+
+# 解决方案 1：使用 network_mode: host（推荐，已在本方案中采用）
+# 在 docker-compose.yml 中为服务添加 network_mode: host
+# 这样不会创建 Docker bridge 网络，从根本上避免 IP 段冲突
+
+# 解决方案 2：指定不冲突的子网
+# docker network create --subnet=192.168.200.0/24 my-network
+```
+
+#### 8. CI health check 失败
+
+```bash
+# 检查 health 路径是否正确（health 路由注册时无 /v1 前缀）
+# 正确：/health    错误：/v1/health
+
+# 检查容器是否在运行
+docker ps -a --filter name=duoqi-api-prod
+
+# 检查端口是否在监听（host 网络模式下直接看宿主机端口）
+ss -tlnp | grep 3000
+
+# 查看容器日志
+docker logs duoqi-api-prod --tail 50
+
+# 注意：CI health check 使用 bun -e "fetch(...)" 而非 curl
+# 如果 bun 的 promise 处理有问题，使用 top-level await：
+# bun -e "try{const r=await fetch('http://localhost:3000/health');process.exit(r.ok?0:1)}catch{process.exit(1)}"
+```
+
 ### 回滚操作
 
 ```bash
@@ -1113,6 +1163,6 @@ docker compose up -d api-prod
 
 ---
 
-**文档版本**: v5.2.0 (双分支工作流 + 国内网络适配 + Docker 执行器完善)
+**文档版本**: v5.3.0 (host 网络模式 + Act Runner 挂载配置 + 故障排查更新)
-**最后更新**: 2026-04-17
+**最后更新**: 2026-04-18
 **维护者**: Duoqi Team