From c305a8dd201db55e3393df1df15e15de4e82f745 Mon Sep 17 00:00:00 2001
From: Wanderingss <1624155937@qq.com>
Date: Fri, 2 Oct 2026 00:29:45 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E6=96=B0=E5=A2=9E?=
 =?UTF-8?q?=20Gitea=20Runner=20=E9=83=A8=E7=BD=B2=E6=8C=87=E5=8D=97?=
 =?UTF-8?q?=EF=BC=88=E6=9C=AC=E6=9C=BA=E5=8E=9F=E7=94=9F=E7=8E=AF=E5=A2=83?=
 =?UTF-8?q?=E5=AE=9A=E5=88=B6=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

针对实测环境定制：Gitea 1.25.4 为 Windows 原生 gitea.exe（非 Docker）、
以服务运行、监听 0.0.0.0:3001、[actions] ENABLED=true 已开启。

覆盖 Runner 端全流程：下载 act_runner / register（--instance 用 127.0.0.1:3001 回环、
--labels "windows:host" 必须精确匹配 runs-on）/ config.yaml / daemon install 常驻 /
软件与 PATH 服务账号坑 / MSVC 标准路径约束 / 内网 action 零依赖改法 / 排障表。

附 check_env.ps1 一键环境自检脚本（落位 D:/Docker/act_runner/）。
关联更新：项目部署环境要求 §七 + 变更记录、测试开发标准流程 §9.4 + 关联文档表。

验证：check_doc_links --all 107 文档通过；本机工具链 Python/cppcheck/pre-commit/MSVC 四项全齐。
---
 docs/测试说明/测试开发标准流程.md       |   6 +-
 docs/环境与部署/Gitea_Runner部署指南.md | 471 ++++++++++++++++++++++++
 docs/环境与部署/项目部署环境要求.md     |   3 +-
 3 files changed, 477 insertions(+), 3 deletions(-)
 create mode 100644 docs/环境与部署/Gitea_Runner部署指南.md

diff --git a/docs/测试说明/测试开发标准流程.md b/docs/测试说明/测试开发标准流程.md
index 14219e07..47fa4723 100644
--- a/docs/测试说明/测试开发标准流程.md
+++ b/docs/测试说明/测试开发标准流程.md
@@ -14,7 +14,8 @@
 | `docs/UI设计/UI_自动化测试流程.md` | UI 模拟器回归（ui-verify）细节 |
 | `docs/代码规范/pre-commit使用说明.md` | pre-commit 门禁配置与范围 |
 | `docs/环境与部署/项目部署环境要求.md` | 构建 / 测试工具链环境 |
-| `docs/环境与部署/CI配置指南.md` | **CI（Gitea Actions）配置全流程与排障** |
+| `docs/环境与部署/CI配置指南.md` | **CI（Gitea Actions）服务端 + workflow 配置全流程与排障** |
+| `docs/环境与部署/Gitea_Runner部署指南.md` | **Runner 端部署全流程**（下载/注册/常驻/排障） |
 | `docs/测试说明/<模块>_Test_Guide.md` | 各模块测试规范（CH395F / GD5F / SD2506 / FTP） |
 
 ---
@@ -499,7 +500,8 @@ CI 只在 push / PR 时跑，且需 runner 就绪。**提交前自查、或 runn
 
 > 📖 **配置步骤 / 排障**（服务端开关、runner 注册命令、PATH 与 MSVC 路径要求、
 > 内网拉不到 action 的处置、故障排查表）见
-> [`../环境与部署/CI配置指南.md`](../环境与部署/CI配置指南.md)。
+> [`../环境与部署/CI配置指南.md`](../环境与部署/CI配置指南.md)
+> 与 [`../环境与部署/Gitea_Runner部署指南.md`](../环境与部署/Gitea_Runner部署指南.md)。
 
 ---
 
diff --git a/docs/环境与部署/Gitea_Runner部署指南.md b/docs/环境与部署/Gitea_Runner部署指南.md
new file mode 100644
index 00000000..ed3bb502
--- /dev/null
+++ b/docs/环境与部署/Gitea_Runner部署指南.md
@@ -0,0 +1,471 @@
+# Gitea Actions Runner 部署指南（本机 Windows 原生版）
+
+> **适用环境（2026-10-02 实测确认）**：
+> - Gitea **1.25.4**，**Windows 原生二进制**（`D:\Docker\Gitea\gitea.exe`，**不是 Docker**），
+>   以 **Windows 服务**运行（`tasklist` 显示 Session = `Services`），监听 `0.0.0.0:3001`
+> - 配置 `D:\Docker\Gitea\custom\conf\app.ini`，`[actions] ENABLED = true` **已开启** ✅
+> - 数据库 MySQL（`127.0.0.1:3306`），仓库根 `D:\Docker\Gitea\data\gitea-repositories`
+> - 对外域名 `http://gitea.bitnasdaq.vip/`（经反代），本地直连 `http://127.0.0.1:3001` ✅
+> - Docker Desktop **已装但 daemon 未运行** → **本指南不使用容器，全程原生**
+>
+> **本文只讲 Runner 端**（下载 → 注册 → 配置 → 常驻 → 验证 → 排障）。
+> Gitea 服务端开关已就绪，无需再动。CI 整体设计见 `docs/测试说明/测试开发标准流程.md` §9。
+
+---
+
+## 0. 先理解：这台机器上的拓扑
+
+**Gitea 和 Runner 在同一条机器上** —— 这是本部署最关键的事实：
+
+```
+┌─────────────────────────── 本机 (Windows) ────────────────────────────┐
+│                                                                       │
+│  gitea.exe  ── Windows 服务 ── 监听 0.0.0.0:3001                      │
+│      ▲                                                                │
+│      │  ① runner 注册 / 心跳 / 领任务：走 http://127.0.0.1:3001        │
+│      │     （本地回环，不经公网、不依赖 DNS/反代）                     │
+│      │                                                                │
+│  act_runner.exe ── Windows 服务（win-stm32-ci）                       │
+│      │                                                                │
+│      └─ ② 领到 job 后，直接在**本机**跑：                              │
+│           git fetch / pre-commit / cppcheck / cl.exe                   │
+│         （标签 windows:host = 用宿主环境，非容器）                     │
+│                                                                       │
+│  外部用户 → https://gitea.bitnasdaq.vip → 反代 → 127.0.0.1:3001        │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+**两个地址要分清**（最容易搞错的地方）：
+
+| 用途 | 地址 | 说明 |
+|---|---|---|
+| **Runner 连接 Gitea** | `http://127.0.0.1:3001` | 本机回环，**最稳**。用 `gitea.bitnasdaq.vip` 也行，但会多绕一圈 DNS + 反代，且若反代没配对内网 IP 会失败 |
+| **用户在浏览器访问** | `https://gitea.bitnasdaq.vip` | 走反代；注册时网页上显示的示例命令用的是这个域名，**你要手动换成 127.0.0.1:3001** |
+
+> ⚠️ **注册时用哪个地址，决定了 runner 以后一直连哪里**。
+> 注册信息存在 `config.yaml` 里，之后改起来要重新注册，**建议一开始就用 `http://127.0.0.1:3001`**。
+
+---
+
+## 1. 下载 act_runner
+
+### 1.1 选对版本
+
+| 项 | 值 |
+|---|---|
+| 架构 | **amd64**（`PROCESSOR_ARCHITECTURE = AMD64`，实测） |
+| 版本 | 取最新稳定版（下文以 `v0.2.11` 为例，请到 releases 页确认最新） |
+| 下载页 | https://gitea.com/gitea/act_runner/releases |
+
+### 1.2 下载并解压
+
+```powershell
+# 建目录（与 Gitea 同级，便于管理）
+New-Item -ItemType Directory -Force -Path "D:\Docker\act_runner" | Out-Null
+cd "D:\Docker\act_runner"
+
+# 下载（版本号请替换为 releases 页当前最新）
+$ver = "0.2.11"
+Invoke-WebRequest -Uri "https://gitea.com/gitea/act_runner/releases/download/v$ver/act_runner-$ver-windows-amd64.exe" `
+                  -OutFile "act_runner.exe"
+
+# 校验能跑
+.\act_runner.exe --version
+```
+
+**期望输出**：类似 `act_runner version v0.2.11`。
+
+> 💡 网络受限时：该 release 也可从镜像站下载；或用 `Gitea` 自带的
+> （Gitea 1.25 已内置 act_runner 的下载入口，但独立下载更可控）。
+
+---
+
+## 2. 注册 Runner
+
+### 2.1 先拿 Registration Token
+
+1. 浏览器登录 `https://gitea.bitnasdaq.vip`
+2. 进仓库 **`wandering1/STM32F4-Base`**
+3. **Settings（设置）→ Actions → Runners → 创建 Runner / Create new Runner**
+4. 页面会显示一段命令，形如：
+
+```
+./act_runner register --no-interactive --instance https://gitea.bitnasdaq.vip --token xxxxxxxxxxxxxxxxxxxx
+```
+
+**复制其中的 `--token` 后面那一串**（这是 Registration Token，一次性用途）。
+页面上的 `--instance` 值**不要照抄**——见下。
+
+### 2.2 执行注册（关键：instance 用 127.0.0.1）
+
+```powershell
+cd "D:\Docker\act_runner"
+
+.\act_runner.exe register `
+  --no-interactive `
+  --instance "http://127.0.0.1:3001" `
+  --token "粘贴刚才复制的 Registration Token" `
+  --name "win-stm32-ci" `
+  --labels "windows:host"
+```
+
+**四个参数逐一说明**：
+
+| 参数 | 值 | 为什么 |
+|---|---|---|
+| `--instance` | `http://127.0.0.1:3001` | **本机回环**。因为 Gitea 就在这台机器上，回环最稳、最快、不受反代/DNS 影响 |
+| `--token` | 网页复制的那串 | 绑定到具体仓库（仓库级 runner） |
+| `--name` | `win-stm32-ci` | runner 显示名，随意但建议有辨识度 |
+| `--labels` | **`windows:host`** | 🔴 **最容易踩的坑**：`windows` 必须与 workflow 的 `runs-on: windows` **逐字一致**；`:host` 表示用**宿主环境**直接跑（非容器）——本场景**必须 host**，容器里拿不到 MSVC/cppcheck |
+
+> ⚠️ **`--labels` 写错的后果**：runner 会注册成功、显示绿色，但**任务永远排队不执行**
+> （没有任何 runner 匹配 `runs-on: windows`）。这是最隐蔽的失败模式。
+
+**期望输出**：`Runner registered successfully`，并在 `D:\Docker\act_runner\` 生成 `.runner` 文件（记录注册凭据）。
+
+### 2.3 验证注册
+
+浏览器刷新 **Settings → Actions → Runners**，应看到：
+
+| 列 | 期望值 |
+|---|---|
+| Name | `win-stm32-ci` |
+| Labels | `windows`（`:host` 是执行方式，UI 可能只显示 `windows`） |
+| Status | 🟢 **Idle** |
+
+---
+
+## 3. 配置 config.yaml
+
+首次注册后，在 `D:\Docker\act_runner\` 下会有 `config.yaml`（若无则手动建）。
+**建议改成下面这样**（含注释说明）：
+
+```yaml
+# act_runner 配置 —— D:\Docker\act_runner\config.yaml
+
+log:
+  level: info          # 排障时临时改 debug
+
+runner:
+  # 文件路径（默认即如此，可省）
+  file: .runner        # 注册凭据
+  capacity: 1          # 并行 job 数；单机建议 1（cppcheck 吃 CPU，1 更稳）
+  timeout: 30m         # 单 job 超时；本仓库 L0+L0.5 合计约 1~3 分钟，30m 很宽裕
+  # 🔴 标签必须与注册时一致，且与 runs-on 对应
+  labels:
+    - "windows:host"
+  # 是否允许 runner 执行未在本实例的动作等（默认 false 即可）
+  fetch_timeout: 5m
+  fetch_interval: 2s
+
+cache:
+  enabled: true        # 开缓存，pre-commit 首次下载的钩子环境可复用，后续快很多
+  dir: "D:\\Docker\\act_runner\\cache"
+
+container:
+  # host 模式下用不到；保留默认即可
+  network: ""
+  privileged: false
+  options:
+  valid_volumes: []
+  docker_host: ""
+  force_pull: false
+```
+
+> ⚠️ **改了 `runner.labels` 必须重启 runner 服务才生效**
+> （Gitea 官方 FAQ：*"A runner declares its labels every time it starts ... so change them there and restart the runner."*）
+
+---
+
+## 4. 让 Runner 常驻（Windows 服务）
+
+### 4.1 前台先试跑（强烈建议）
+
+**先别急着装服务**——用前台模式确认能连上、能领任务：
+
+```powershell
+cd "D:\Docker\act_runner"
+.\act_runner.exe daemon
+```
+
+看到类似输出即成功：
+
+```
+level=info msg="Starting runner daemon"
+level=info msg="runner: win-stm32-ci, with labels: [windows]"
+level=info msg="Runner registered successfully"   # 或 "polling for tasks"
+```
+
+**让这个窗口开着**，去 Gitea 页面确认 runner 是 Idle，然后再按 Ctrl+C 停掉、装服务。
+
+### 4.2 注册为 Windows 服务
+
+```powershell
+cd "D:\Docker\act_runner"
+
+# 安装服务（需管理员权限的 PowerShell）
+.\act_runner.exe daemon install
+
+# 启动
+.\act_runner.exe daemon start
+
+# 查看状态
+.\act_runner.exe daemon status
+```
+
+**期望**：`Status: Running`（或 `started`）。
+
+> 💡 `daemon install` 在 Windows 上会把 runner 注册成名为 `act_runner` 的 Windows 服务，
+> 开机自启、随系统常驻——**和你的 `gitea.exe` 服务是同一种存在形式**。
+
+### 4.3 备用方案：改用 `sc.exe` 手动建服务
+
+若 `daemon install` 不工作（版本差异），用系统命令：
+
+```powershell
+# 管理员 PowerShell
+New-Service -Name "act_runner" `
+            -BinaryPathName "D:\Docker\act_runner\act_runner.exe daemon --config D:\Docker\act_runner\config.yaml" `
+            -DisplayName "Gitea Actions Runner" `
+            -Description "Gitea Actions Runner for STM32F4-Base CI" `
+            -StartupType Automatic
+Start-Service -Name "act_runner"
+```
+
+> ⚠️ 用 `New-Service` 时，工作目录不是 runner 目录，**必须用 `--config` 显式指定配置路径**，
+> 否则会找不到 `.runner` 注册文件。
+
+### 4.4 服务管理速查
+
+```powershell
+.\act_runner.exe daemon status     # 状态
+.\act_runner.exe daemon stop       # 停止
+.\act_runner.exe daemon restart    # 重启（改完 config.yaml / 重装软件后用）
+.\act_runner.exe daemon uninstall  # 卸载服务
+```
+
+---
+
+## 5. Runner 必须装齐的软件
+
+Runner 会**直接在本机跑** CI 步骤，所以本机必须有一套工具链。
+（**你本机是开发机，大概率已经全有** —— 逐条核对下表。）
+
+| 项 | 检查命令 | 期望 | 缺了怎么办 |
+|---|---|---|---|
+| **Python 3.x** | `python --version` | `Python 3.x` | `winget install Python.Python.3.12` |
+| **cppcheck** | `cppcheck --version` | `Cppcheck 2.21.0` | `winget install Cppcheck.Cppcheck` |
+| **pre-commit** | `python -m pre_commit --version` | `pre-commit 4.x` | `pip install pre-commit` |
+| **MSVC** | 见下 | `cl.exe` 存在 | `winget install Microsoft.VisualStudio.2022.BuildTools`（勾"使用 C++ 的桌面开发"） |
+| Git | `git --version` | 任意 | 你已在用 |
+
+**本机实测状态（2026-10-02）**：
+
+```
+Python    : C:\ProgramData\anaconda3\python.exe → 3.12.4        ✅
+cppcheck  : C:\Program Files\Cppcheck\cppcheck.exe → 2.21.0     ✅
+pre-commit: 4.6.0 (anaconda3)                                   ✅
+MSVC      : VS2019 BuildTools 14.29.30133 (Hostx64\x64\cl.exe)  ✅
+```
+
+**→ 四项全齐，无需额外安装。**
+
+### 5.1 ⚠️ 关键坑：PATH 与服务账号
+
+**问题的本质**：`act_runner` 作为 Windows 服务运行时，继承的是**安装服务那个时刻的系统 PATH**。
+
+- 你在某个终端里能用 `python`，**不代表 runner 服务里也能用**；
+- **装完任何新软件 / 改过 PATH 后，必须重启 runner 服务**：
+
+```powershell
+.\act_runner.exe daemon restart
+```
+
+### 5.2 ⚠️ 关键坑：MSVC 的路径必须"标准"
+
+CI 的 MSVC 探测（`l05` job）会去这几个**固定根目录**找
+`VC\Tools\MSVC\*\bin\Hostx64\x64\cl.exe`：
+
+```
+C:\Program Files (x86)\Microsoft Visual Studio\2019\{BuildTools,Community,Professional}
+C:\Program Files\Microsoft Visual Studio\2022\{BuildTools,Community,Professional,Enterprise}
+C:\Program Files\Microsoft Visual Studio\2026\{BuildTools,Community}
+```
+
+**你本机实测命中第 1 条**：
+`C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Tools\MSVC\14.29.30133\bin\Hostx64\x64\cl.exe` ✅
+
+> ⚠️ 若将来 MSVC 装到 **D 盘或非上述路径** → 探测不到 → **L0.5 被静默跳过**（只告警）。
+> 修法要**同步改两处**（否则本地能跑、CI 跳过）：
+> - `test/host/common/unit_test_harness.py` 的 `VS_ROOTS`
+> - `.gitea/workflows/ci.yml` 里 `探测 MSVC` 步骤的 `$roots`
+
+### 5.3 验证运行器能找到工具链（注册前先跑一遍）
+
+```powershell
+& '.venv\Scripts\python.exe' scripts/ci_local.py
+```
+
+这条命令跑的就是 CI 的同一套判定。**本地能过，runner 上基本就能过**（前提是 PATH 一致）。
+
+---
+
+## 6. 端到端验证
+
+按顺序做，任一步不过就停在那里查：
+
+| # | 动作 | 期望 |
+|---|---|---|
+| 1 | `.\act_runner.exe daemon` 前台启动 | 打印 `win-stm32-ci` + `labels: [windows]` |
+| 2 | 浏览器 Settings → Actions → Runners | 🟢 Idle |
+| 3 | 确认 workflow 已推到远程（**见下方注意**） | 远程分支有 `.gitea/workflows/ci.yml` |
+| 4 | Push 一次（或页面 **Run workflow**） | Actions 页出现运行中任务 |
+| 5 | 看 `l0-gates` 日志 | `pre-commit ... Passed`；`mem-numbers` 显示 `Skipped`（无 Keil `.map`，正常） |
+| 6 | 看 `l05-host-unit-tests` 日志 | `=== Task Watchdog Tests: 39/39 PASSED (failed=0) ===` |
+| 7 | 提交记录旁 | ✅ 绿灯 |
+
+> ⚠️ **第 3 步是当前的最大阻塞**：本仓库的 `.gitea/workflows/ci.yml` 还在本地
+> （提交 `e904865` / `1e01950` / `52e6dcb` 均未 push）。**workflow 不上远程，CI 永远不会跑**，
+> 哪怕 runner 配得再完美。
+
+---
+
+## 7. 排障对照表
+
+| 现象 | 根因 | 处置 |
+|---|---|---|
+| runner 一直 **Idle**，push 后任务**排队不跑** | `--labels` 不是 `windows`（最常见） | 改 `config.yaml` 的 `runner.labels: ["windows:host"]` → `daemon restart` |
+| `daemon` 启动报 **connection refused / dial tcp** | `--instance` 填了不可达地址 | 重新 `register`，`--instance http://127.0.0.1:3001` |
+| 启动报 **token** 相关错误 | Registration Token 过期（约 1 小时）或已用过 | 回网页重新创建 runner 拿新 token，重新 `register` |
+| 任务跑到一半报 `python: 不是内部或外部命令` | 服务 PATH 没有 Python | 确认 Python 在**系统** PATH → `daemon restart` |
+| `l0-gates` 报 `::error::runner 缺少：Python, cppcheck` | 同上，PATH 未生效 | 装齐 + 重启服务（§5.1） |
+| `checkout` 步骤卡住 / 拉不到 action | Gitea 默认从 **github.com** 拉 action，本机不通外网 | 见 §8 |
+| `l05` 日志 `::warning::runner 未安装 MSVC` | MSVC 不在标准路径 | 见 §5.2 |
+| `l05` 报 `fatal error C1083: 无法打开 "stdio.h"` | 缺 Windows SDK | 装 VS 时勾"使用 C++ 的桌面开发" + SDK |
+| 日志里 `pre-commit` 第一次特别慢 | 首次下载各钩子环境 | 正常，`cache.enabled: true` 后第二次快 |
+| **改了 `.runner` / 换机器** | 注册信息失效 | 删 `.runner` → 重新 `register` |
+
+**看日志**（服务模式）：act_runner 的日志默认输出到 Windows 事件日志或标准输出。
+建议在 `config.yaml` 里显式开文件日志方便排障：
+
+```yaml
+log:
+  level: info
+  file: "D:\\Docker\\act_runner\\log\\runner.log"    # 加这行
+```
+
+---
+
+## 8. ⚠️ 内网 action 拉取问题（你的环境很可能命中）
+
+workflow 里用了 `actions/checkout@v4`。Gitea **默认从 `https://github.com` 拉取这个 action**
+（不是从你自己的实例，也不是从 gitea.com —— 这点很反直觉，见
+`CI配置指南.md` §1.2.1）。
+
+**你的环境判断**：Gitea 装了 `OFFLINE_MODE = true`，说明这台机器的外网访问**可能受限**。
+如果 runner 拉不到 github.com，checkout 步骤会卡住。
+
+### 处置：改用零依赖写法（内网首选）
+
+把 `.gitea/workflows/ci.yml` 里的 `actions/checkout@v4` 两步替换为纯 git 命令：
+
+```yaml
+      - name: Checkout
+        shell: pwsh
+        run: |
+          git init .
+          git remote add origin $env:GITHUB_SERVER_URL/$env:GITHUB_REPOSITORY.git
+          git fetch --depth 1 origin $env:GITHUB_SHA
+          git checkout $env:GITHUB_SHA
+```
+
+**优点**：不依赖任何外部 action、不需要配 `DEFAULT_ACTIONS_URL`、不需要镜像 action。
+**代价**：失去 checkout 的缓存优化（对本仓库影响很小）。
+
+> 另两种方案（`DEFAULT_ACTIONS_URL = self` + 镜像 action 进实例 / 指向可达镜像站）见
+> `docs/环境与部署/CI配置指南.md` §4.3。**注意 `self` 是关键字，不是写你的域名。**
+
+**建议**：**先按原样试一次**。若 checkout 步骤报网络错误，再换成上面的零依赖写法。
+
+---
+
+## 9. 一键检查脚本（可选）
+
+存为 `D:\Docker\act_runner\check_env.ps1`，注册前跑一遍：
+
+```powershell
+Write-Host "=== Gitea 可达性 ===" -ForegroundColor Cyan
+try {
+    $v = (Invoke-RestMethod -Uri "http://127.0.0.1:3001/api/v1/version" -TimeoutSec 8).version
+    Write-Host "  OK  Gitea $v (127.0.0.1:3001)" -ForegroundColor Green
+} catch { Write-Host "  FAIL 连不上 Gitea: $_" -ForegroundColor Red }
+
+Write-Host "=== 工具链 ===" -ForegroundColor Cyan
+foreach ($c in @("python", "cppcheck", "git")) {
+    $p = Get-Command $c -ErrorAction SilentlyContinue
+    if ($p) { Write-Host "  OK  $c -> $($p.Source)" -ForegroundColor Green }
+    else    { Write-Host "  FAIL 缺 $c" -ForegroundColor Red }
+}
+$pc = (python -m pre_commit --version 2>&1)
+if ($LASTEXITCODE -eq 0) { Write-Host "  OK  $pc" -ForegroundColor Green }
+else { Write-Host "  FAIL 缺 pre-commit" -ForegroundColor Red }
+
+Write-Host "=== MSVC cl.exe ===" -ForegroundColor Cyan
+$roots = @(
+  'C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools',
+  'C:\Program Files (x86)\Microsoft Visual Studio\2019\Community',
+  'C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional',
+  'C:\Program Files\Microsoft Visual Studio\2022\BuildTools',
+  'C:\Program Files\Microsoft Visual Studio\2022\Community',
+  'C:\Program Files\Microsoft Visual Studio\2022\Professional',
+  'C:\Program Files\Microsoft Visual Studio\2022\Enterprise',
+  'C:\Program Files\Microsoft Visual Studio\2026\BuildTools',
+  'C:\Program Files\Microsoft Visual Studio\2026\Community'
+)
+$hit = $null
+foreach ($r in $roots) {
+    if (Test-Path $r) {
+        $hit = Get-ChildItem -Path $r -Recurse -Filter 'cl.exe' -ErrorAction SilentlyContinue |
+               Where-Object { $_.FullName -like '*Hostx64\x64*' } | Select-Object -First 1
+        if ($hit) { break }
+    }
+}
+if ($hit) { Write-Host "  OK  $($hit.FullName)" -ForegroundColor Green }
+else { Write-Host "  FAIL 未找到 MSVC (Hostx64\x64\cl.exe)" -ForegroundColor Red }
+```
+
+---
+
+## 10. 最小操作清单（TL;DR）
+
+```powershell
+# 1) 下载
+New-Item -ItemType Directory -Force -Path "D:\Docker\act_runner" | Out-Null
+cd "D:\Docker\act_runner"
+Invoke-WebRequest -Uri "https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-windows-amd64.exe" -OutFile "act_runner.exe"
+
+# 2) 注册（token 从网页 Settings→Actions→Runners 拿）
+.\act_runner.exe register --no-interactive `
+  --instance "http://127.0.0.1:3001" `
+  --token "<粘贴 token>" `
+  --name "win-stm32-ci" `
+  --labels "windows:host"
+
+# 3) 前台试跑，确认能连上
+.\act_runner.exe daemon          # 看到 labels: [windows] 即成功，Ctrl+C 停
+
+# 4) 常驻（管理员 PowerShell）
+.\act_runner.exe daemon install
+.\act_runner.exe daemon start
+.\act_runner.exe daemon status
+
+# 5) 回网页确认 runner 为 Idle → 然后（经你同意后）push 代码触发第一次 CI
+```
+
+---
+
+## 变更记录
+
+| 日期 | 变更 |
+|---|---|
+| 2026-10-02 | 初版：针对**本机 Gitea 原生部署**（`D:\Docker\Gitea\gitea.exe` + Windows 服务 + `127.0.0.1:3001`）定制 Runner 端部署全流程。核心要点：`--instance` 用回环地址、`--labels "windows:host"` 必须精确匹配 `runs-on`、PATH 与服务账号坑、MSVC 路径约束、内网 action 拉取的零依赖改法 |
diff --git a/docs/环境与部署/项目部署环境要求.md b/docs/环境与部署/项目部署环境要求.md
index 9fa6e89b..9d96971c 100644
--- a/docs/环境与部署/项目部署环境要求.md
+++ b/docs/环境与部署/项目部署环境要求.md
@@ -561,7 +561,7 @@ workflow 见 `.gitea/workflows/ci.yml`；覆盖边界与判定细节见 [`../测
 | LVGL 模拟器部署 | `docs/UI设计/LVGL模拟器部署与使用说明.md`、`simulator/README.md` |
 | 串口调试 / 自动化测试 | `docs/测试说明/串口助手使用指南.md`、`docs/测试说明/串口助手设计说明.md`、`docs/测试说明/自动化测试流程.md` |
 | **测试分层 / L0.5 主机侧单测** | `docs/测试说明/测试开发标准流程.md`（分层与门禁）· `docs/测试说明/看门狗单元测试说明.md`（L0.5 范式：MSVC 离线编译 + 平台桩） |
-| **CI（Gitea Actions）** | `docs/环境与部署/CI配置指南.md`（**服务端开关 / runner 注册 / 软件环境 / 排障全流程**）· `docs/测试说明/测试开发标准流程.md` §9（覆盖边界） |
+| **CI（Gitea Actions）** | `docs/环境与部署/Gitea_Runner部署指南.md`（**Runner 端部署全流程：下载 / 注册 / 常驻 / 排障**，针对本机原生 Gitea 定制）· `docs/环境与部署/CI配置指南.md`（服务端 + workflow 全流程）· `docs/测试说明/测试开发标准流程.md` §9（覆盖边界） |
 | pre-commit / cppcheck | `docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md` |
 | 引用关系图（文件引用） | `docs/架构设计/引用关系图说明.md`（生成工具 `tools/refgraph`；渲染依赖 Graphviz，§2.8） |
 | 各模块测试指南 | `docs/测试说明/CH395F_Test_Guide.md`、`GD5F2GQ5UE_Test_Guide.md`、`SD2506_Test_Guide.md`、`FTP_Test_Guide.md` |
@@ -573,6 +573,7 @@ workflow 见 `.gitea/workflows/ci.yml`；覆盖边界与判定细节见 [`../测
 
 | 日期 | 变更 |
 |---|---|
+| 2026-10-02 | 新增 **`Gitea_Runner部署指南.md`**：针对**本机 Gitea 原生部署**（`D:\Docker\Gitea\gitea.exe` + Windows 服务 + `127.0.0.1:3001`）定制的 Runner 端全流程——下载 / `register`（**`--instance` 用回环、`--labels "windows:host"` 必须精确匹配 `runs-on`**）/ `config.yaml` / `daemon install` 常驻 / 软件与 PATH 坑 / MSVC 路径约束 / 内网 action 零依赖改法 / 排障表 / `check_env.ps1` 自检脚本；§七相关文档登记 |
 | 2026-10-01 | 新增 **`CI配置指南.md`**（Gitea Actions 配置全流程：服务端 `[actions] ENABLED` / Windows runner 注册（`--labels "windows:host"`）/ runner 软件环境与 PATH / workflow 位置与触发 / 内网拉不到 `actions/checkout` 的三种处置 / 端到端验证清单 / 故障排查表 / 日常维护）；§七相关文档登记 |
 | 2026-10-01 | **新增 §2.11 CI runner 环境（Gitea Actions，T-6）**：Gitea ≥1.21（实测 1.25.4）+ `[actions] ENABLED` + Windows runner（装 Python/cppcheck/pre-commit/MSVC）；**不需要 Keil**（刻意不跑 `@build`，无 `.map` 时 `mem-numbers` 自动跳过）；补"CI 不能替代本地门禁"与 `scripts/ci_local.py` 过渡命令 |
 | 2026-10-01 | **补主机侧单元测试（L0.5）环境要求**：§2.3 由"PC 模拟器环境"扩为"PC 侧编译环境（模拟器 + 主机侧单元测试）"——明确**同一套 VS 的 `cl.exe` 同时服务模拟器与单测**，MSVC 从"仅模拟器需要"升级为"提交门禁需要"；§2.7 pre-commit 表补 `watchdog-unit-test` 钩子及"未装 VS 会被拦截"；第 3 步 / 第 10 步冒烟 / 搭建清单 / §2.10 下载表（补 VS2022/2026 行）/ 速查表（补 `cl.exe` 缺失与 `C1083 stdio.h` 两条）/ 相关文档同步；总览拓扑图加 `MSVC cl.exe` 节点 |