diff --git a/docs/development/ci-runner-setup.md b/docs/development/ci-runner-setup.md
new file mode 100644
index 0000000..3729034
--- /dev/null
+++ b/docs/development/ci-runner-setup.md
@@ -0,0 +1,79 @@
+# Gitea Actions Runner 启用手册
+
+> 目标：让 `patbond-api/.gitea/workflows/ci.yml` 在每次 push(dev)/PR 时自动执行
+> `./mvnw -B clean test`（含 Testcontainers，需 Docker）。
+> 适用：自建 Gitea（http://132.232.242.77，nginx 反代，Ubuntu）。
+> 全程在**服务器**上操作，约 10 分钟。
+
+## 第 1 步：Gitea 侧开启 Actions
+
+1. 确认版本 ≥ 1.19（建议 1.21+）：Gitea 页面右下角或 `gitea --version`。
+2. 编辑 `app.ini`（常见位置 `/etc/gitea/app.ini` 或 Gitea 安装目录 `custom/conf/app.ini`），加入/确认：
+
+   ```ini
+   [actions]
+   ENABLED = true
+   ```
+
+3. 重启 Gitea：`sudo systemctl restart gitea`（按你的部署方式调整）。
+4. 网页版验证：管理后台出现「Actions → Runners」菜单即成功。
+
+## 第 2 步：获取注册令牌
+
+- 全站级（推荐，一台 runner 服务所有仓库）：**管理后台 → Actions → Runners → 创建 Runner**，复制注册令牌（REGISTRATION TOKEN）。
+- 或仓库级：`patbond-api` 仓库 **Settings → Actions → Runners** 里获取（只服务该仓库）。
+
+## 第 3 步：启动 act_runner（Docker 方式，推荐）
+
+在装有 Docker 的机器上（与 Gitea 同机即可）：
+
+```bash
+docker run -d --name act_runner --restart unless-stopped \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v act_runner_data:/data \
+  -e GITEA_INSTANCE_URL=http://132.232.242.77 \
+  -e GITEA_RUNNER_REGISTRATION_TOKEN=<第2步的令牌> \
+  -e GITEA_RUNNER_NAME=patbond-runner \
+  -e GITEA_RUNNER_LABELS='ubuntu-latest:docker://docker.io/catthehacker/ubuntu:act-latest' \
+  docker.io/gitea/act_runner:latest
+```
+
+要点：
+
+- `-v /var/run/docker.sock`：runner 需要控制宿主 Docker 来起 job 容器。
+- 标签 `ubuntu-latest` 必须存在——工作流里 `runs-on: ubuntu-latest` 靠它匹配；
+  `catthehacker/ubuntu:act-latest` 镜像自带 node/git，能跑 `actions/checkout` 等 JS Action。
+
+### 让 job 里的 Testcontainers 拿到 Docker（关键一步）
+
+我们的门禁在 job 容器内还要再起 postgres:18 容器，所以 job 容器也要挂 docker.sock。
+生成并修改 runner 配置：
+
+```bash
+docker exec act_runner act_runner generate-config > /tmp/config.yaml
+# 编辑 /tmp/config.yaml，在 container 段加：
+#   container:
+#     options: "-v /var/run/docker.sock:/var/run/docker.sock"
+docker cp /tmp/config.yaml act_runner:/data/config.yaml
+docker restart act_runner
+# 注意：runner 以 CONFIG_FILE=/data/config.yaml 生效，若镜像未自动读取，
+# 重新以 -e CONFIG_FILE=/data/config.yaml 运行容器。
+```
+
+## 第 4 步：验证
+
+1. 管理后台 → Actions → Runners：`patbond-runner` 显示 **Idle**。
+2. `patbond-api` 仓库 **Settings → Actions** 确认已启用（默认继承全局）。
+3. 推送 `dev` 分支（或手动 re-run），仓库「Actions」页应出现运行记录，
+   `backend-test` job 全绿（首跑要拉镜像与 Maven 依赖，10 分钟内正常）。
+
+## 常见问题
+
+| 现象 | 处理 |
+| --- | --- |
+| job 卡在 `actions/checkout` 或 `setup-java` 拉不下来 | runner 访问不了 github.com。两种解法：a) `app.ini` 的 `[actions]` 加 `DEFAULT_ACTIONS_URL = https://gitea.com`（用 gitea.com 上的 Action 镜像仓）；b) 把工作流的 setup-java 步骤删掉，改用自带 JDK17 的 job 镜像（ci.yml 头部注释已写明） |
+| Testcontainers 报 `Could not find a valid Docker environment` | 第 3 步的 container.options 没生效，job 容器内没有 docker.sock |
+| runner 显示 offline | `docker logs act_runner` 看注册错误；令牌只能用一次，重新注册需删 `/data/.runner` |
+| Maven 每次全量下载依赖很慢 | 在 config.yaml 的 container.options 追加 `-v act_m2:/root/.m2` 做持久缓存 |
+
+启用完成后，把 `docs/development/feature-checklist.md` 第 6 节「CI 载体」从 🟡 改为 ✅。
diff --git a/mkdocs.yml b/mkdocs.yml
index 16b13bb..c5b0605 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -7,6 +7,7 @@ nav:
       - 开发实施计划: development/development-plan.md
       - Git 工作流规范: development/git-workflow.md
       - 功能完成清单: development/feature-checklist.md
+      - CI Runner 部署手册: development/ci-runner-setup.md
       - 第一迭代:
           - 进展看板: development/iterations/iteration-1/index.md
           - 01 任务分解: development/iterations/iteration-1/01-pm-task-breakdown.md