文档：按 v4.0.1 实测修正 Gitea Runner 部署指南

实测发现 act_runner 已更名为 gitea-runner，发布页迁至 gitea.com/gitea/runner，当前最新 v4.0.1，且 v4 移除了 daemon install/start/stop/status 子命令。修正内容： - §1 改为 gitea-runner v4.0.1 下载地址与文件名；新增 §1.3 命令集对照 - §3 修正 log 段（v4 无 file 键，改用 log.job.dir）+ config 子命令用法 - §4.2 常驻改用 sc.exe / New-Service（v4 无 daemon install） - 新增 §4.5 提权硬约束（IsAdmin=False 时 New-Service 拒绝访问） - 新增 §6.1 MySQL 直查核验 runner 在线状态 - 排障表补 4 条（accepts at most 0 arg / unknown config key / 拒绝访问 / WorkingDirectory） - §10 TL;DR 与配套脚本清单同步
2026-10-02 00:39:51 +08:00
parent c305a8dd20
commit c4768e98e3
1 changed files with 210 additions and 83 deletions
@@ -11,6 +11,14 @@
 > **本文只讲 Runner 端**（下载 → 注册 → 配置 → 常驻 → 验证 → 排障）。
 > Gitea 服务端开关已就绪，无需再动。CI 整体设计见 `docs/测试说明/测试开发标准流程.md` §9。

+> ⚠️ **重要版本变更（2026-10-02 实测）**：act_runner 已更名为 **`gitea-runner`**，
+> 当前最新版 **v4.0.1**（发布页 `https://gitea.com/gitea/runner/releases`，
+> 注意仓库路径已从 `gitea/act_runner` 变为 **`gitea/runner`**）。
+> **v4 移除了 `daemon install/start/stop/status` 子命令**（那些是 v0.2.x 的接口），
+> 常驻改用 **Windows 原生 `sc.exe` / `New-Service`** —— 见 §4。
+> 另：v4 的 `log` 段只有 `level` 和 `job`（**无 `file` 键**），配置用
+> `gitea-runner config init / set / get / generate` 管理。
+
 ---

 ## 0. 先理解：这台机器上的拓扑
@@ -25,7 +33,7 @@
 │      │  ① runner 注册 / 心跳 / 领任务：走 http://127.0.0.1:3001        │
 │      │     （本地回环，不经公网、不依赖 DNS/反代）                     │
 │      │                                                                │
-│  act_runner.exe ── Windows 服务（win-stm32-ci）                       │
+│  gitea-runner.exe ── Windows 服务（win-stm32-ci）                     │
 │      │                                                                │
 │      └─ ② 领到 job 后，直接在**本机**跑：                              │
 │           git fetch / pre-commit / cppcheck / cl.exe                   │
@@ -43,40 +51,59 @@
 | **用户在浏览器访问** | `https://gitea.bitnasdaq.vip` | 走反代；注册时网页上显示的示例命令用的是这个域名，**你要手动换成 127.0.0.1:3001** |

 > ⚠️ **注册时用哪个地址，决定了 runner 以后一直连哪里**。
-> 注册信息存在 `config.yaml` 里，之后改起来要重新注册，**建议一开始就用 `http://127.0.0.1:3001`**。
+> 注册信息存在 `.runner` 里，之后改起来要重新注册，**建议一开始就用 `http://127.0.0.1:3001`**。

 ---

-## 1. 下载 act_runner
+## 1. 下载 gitea-runner

 ### 1.1 选对版本

 | 项 | 值 |
 |---|---|
 | 架构 | **amd64**（`PROCESSOR_ARCHITECTURE = AMD64`，实测） |
-| 版本 | 取最新稳定版（下文以 `v0.2.11` 为例，请到 releases 页确认最新） |
-| 下载页 | https://gitea.com/gitea/act_runner/releases |
+| 版本 | **v4.0.1**（2026-10-02 实测最新稳定版） |
+| 下载页 | https://gitea.com/gitea/**runner**/releases ← 注意仓库名已从 `act_runner` 改为 `runner` |
+| 文件名 | `gitea-runner-4.0.1-windows-amd64.exe` ← 二进制名也从 `act_runner` 改为 **`gitea-runner`** |

-### 1.2 下载并解压
+### 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"
+# 下载 v4.0.1（版本号请替换为 releases 页当前最新）
+Invoke-WebRequest -Uri "https://gitea.com/gitea/runner/releases/download/v4.0.1/gitea-runner-4.0.1-windows-amd64.exe" `
+                  -OutFile "gitea-runner.exe"

 # 校验能跑
-.\act_runner.exe --version
+.\gitea-runner.exe --version
 ```

-**期望输出**：类似 `act_runner version v0.2.11`。
+**期望输出**：`gitea-runner version v4.0.1`。

-> 💡 网络受限时：该 release 也可从镜像站下载；或用 `Gitea` 自带的
-> （Gitea 1.25 已内置 act_runner 的下载入口，但独立下载更可控）。
+> 💡 **本机实测**（2026-10-02）：下载 20.6 MB，耗时约 5 秒，`gitea.com` 可直连（`HTTP 200`）。
+
+### 1.3 v4.0.1 的命令集（与 v0.2.x 的差异）
+
+```
+Available Commands:
+  bug-report      Print information useful when filing a bug report
+  cache-server    Start a cache server for the cache action
+  config          Generate, read and edit config files
+  daemon          Run as a runner daemon
+  exec            Run workflow locally.
+  help            Help about any command
+  register        Register a runner to the server
+```
+
+> ⚠️ **没有 `daemon install/start/stop/status`** —— 这些是 v0.2.x 的接口，v4 已移除。
+> 常驻必须用 Windows 原生方式（见 §4）。
+>
+> `config` 子命令很方便，建议优先用它而不是手改 YAML：
+> `config init`（生成最小配置）/ `config generate`（打印全部选项）
+> / `config set <key> <value>` / `config get <key>`。

 ---

@@ -90,18 +117,21 @@ Invoke-WebRequest -Uri "https://gitea.com/gitea/act_runner/releases/download/v$v
 4. 页面会显示一段命令，形如：

 ```
-./act_runner register --no-interactive --instance https://gitea.bitnasdaq.vip --token xxxxxxxxxxxxxxxxxxxx
+./gitea-runner register --no-interactive --instance https://gitea.bitnasdaq.vip --token xxxxxxxxxxxxxxxxxxxx
 ```

 **复制其中的 `--token` 后面那一串**（这是 Registration Token，一次性用途）。
 页面上的 `--instance` 值**不要照抄**——见下。

+> 💡 **Token 存在于 `action_runner_token` 表**（MySQL，见 `Gitea_Runner部署指南` §附录）。
+> 每仓库一个有效 token，**注册一次后即被消费**；过期（约 1 小时）或已用则需重新创建。
+
 ### 2.2 执行注册（关键：instance 用 127.0.0.1）

 ```powershell
 cd "D:\Docker\act_runner"

-.\act_runner.exe register `
+.\gitea-runner.exe register `
  --no-interactive `
  --instance "http://127.0.0.1:3001" `
  --token "粘贴刚才复制的 Registration Token" `
@@ -137,42 +167,59 @@ cd "D:\Docker\act_runner"

 ## 3. 配置 config.yaml

-首次注册后，在 `D:\Docker\act_runner\` 下会有 `config.yaml`（若无则手动建）。
-**建议改成下面这样**（含注释说明）：
+**推荐用 `config` 子命令生成/修改**（v4 新增，比手改 YAML 安全）：
+
+```powershell
+cd "D:\Docker\act_runner"
+.\gitea-runner.exe config init                    # 生成最小 config.yaml
+.\gitea-runner.exe config set runner.capacity 1   # 逐项设置
+.\gitea-runner.exe config set runner.timeout 30m
+.\gitea-runner.exe config set cache.enabled true
+.\gitea-runner.exe config set log.level info
+.\gitea-runner.exe config get runner.capacity     # 校验
+.\gitea-runner.exe config generate                # 打印全部可用选项（含注释）
+```
+
+**本机已落地的配置**（`D:\Docker\act_runner\config.yaml`）：

 ```yaml
-# act_runner 配置 —— D:\Docker\act_runner\config.yaml
-
 log:
-  level: info          # 排障时临时改 debug
+  # trace/debug/info/warn/error/fatal/panic；排障时临时改 debug
+  level: info
+  # 每个 job 的任务日志另存一份到本地（防上报 Gitea 失败时日志丢失）
+  job:
+    dir: "D:\\Docker\\act_runner\\log\\job"
+    retention: 168h
+    max_size: 100MB

 runner:
-  # 文件路径（默认即如此，可省）
-  file: .runner        # 注册凭据
-  capacity: 1          # 并行 job 数；单机建议 1（cppcheck 吃 CPU，1 更稳）
-  timeout: 30m         # 单 job 超时；本仓库 L0+L0.5 合计约 1~3 分钟，30m 很宽裕
-  # 🔴 标签必须与注册时一致，且与 runs-on 对应
+  file: .runner           # 注册凭据（由 register 生成，勿手改）
+  capacity: 1             # 并行 job 数；单机建议 1（cppcheck 吃 CPU）
+  timeout: 30m0s          # 单 job 超时；L0+L0.5 约 1~3 分钟
+  fetch_timeout: 5m0s
+  fetch_interval: 2s
+  # 🔴 标签：windows 必须与 workflow 的 runs-on: windows 逐字一致
  labels:
    - "windows:host"
-  # 是否允许 runner 执行未在本实例的动作等（默认 false 即可）
-  fetch_timeout: 5m
-  fetch_interval: 2s

 cache:
-  enabled: true        # 开缓存，pre-commit 首次下载的钩子环境可复用，后续快很多
+  enabled: true
  dir: "D:\\Docker\\act_runner\\cache"

 container:
-  # host 模式下用不到；保留默认即可
  network: ""
  privileged: false
-  options:
+  options: ""
  valid_volumes: []
  docker_host: ""
  force_pull: false
 ```

-> ⚠️ **改了 `runner.labels` 必须重启 runner 服务才生效**
+> ⚠️ **v4 的 `log` 段只有 `level` 和 `job` 两个键** —— **没有 `file` 键**
+> （`config set log.file ...` 会报 `unknown config key`）。
+> 想要本地日志用 `log.job.dir`（按 job 落文件），或把服务输出重定向到文件。
+>
+> ⚠️ **改了 `runner.labels` 必须重启 runner 才生效**
 > （Gitea 官方 FAQ：*"A runner declares its labels every time it starts ... so change them there and restart the runner."*）

 ---
@@ -181,69 +228,102 @@ container:

 ### 4.1 前台先试跑（强烈建议）

-**先别急着装服务**——用前台模式确认能连上、能领任务：
+**先别急着装服务**——用前台模式确认能连上：

 ```powershell
 cd "D:\Docker\act_runner"
-.\act_runner.exe daemon
+.\gitea-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"
+level=info msg="runner: win-stm32-ci, with version: v4.0.1, with labels: [windows], declare successfully"
 ```

-**让这个窗口开着**，去 Gitea 页面确认 runner 是 Idle，然后再按 Ctrl+C 停掉、装服务。
+**让这个窗口开着**，去 Gitea 页面确认 runner 是 Idle，然后再 Ctrl+C 停掉、装服务。

-### 4.2 注册为 Windows 服务
+### 4.2 ⚠️ v4 没有 `daemon install` —— 用 `sc.exe` 注册服务
+
+**这是与旧版文档最大的差异。** v4.0.1 的 `daemon` 只接受 `--labels` / `--once` 两个 flag，
+`daemon install` 会报 `Error: accepts at most 0 arg(s)`。
+
+**正确做法**——在**管理员** PowerShell 中执行（脚本已备好：
+`D:\Docker\act_runner\install_service.ps1`）：

 ```powershell
-cd "D:\Docker\act_runner"
+# ① 创建服务（路径含空格必须加引号；--config 用绝对路径）
+sc.exe create gitea-runner `
+  binPath= '"D:\Docker\act_runner\gitea-runner.exe" daemon --config "D:\Docker\act_runner\config.yaml"' `
+  start= auto `
+  DisplayName= "Gitea Actions Runner"

-# 安装服务（需管理员权限的 PowerShell）
-.\act_runner.exe daemon install
+# ② 描述
+sc.exe description gitea-runner "Gitea Actions Runner for STM32F4-Base CI (windows:host)"

-# 启动
-.\act_runner.exe daemon start
+# ③ 失败自动重启（5 秒后重试，最多 3 次；86400 秒后重置计数）
+sc.exe failure gitea-runner reset= 86400 actions= restart/5000/restart/5000/restart/5000

-# 查看状态
-.\act_runner.exe daemon status
+# ④ 启动
+sc.exe start gitea-runner
 ```

-**期望**：`Status: Running`（或 `started`）。
+> ⚠️ `sc.exe` 的 `key= value` 语法：**等号后必须有空格，等号前不能有空格**，否则报参数错误。
+> 这是 `sc` 的历史怪癖，不是笔误。

-> 💡 `daemon install` 在 Windows 上会把 runner 注册成名为 `act_runner` 的 Windows 服务，
-> 开机自启、随系统常驻——**和你的 `gitea.exe` 服务是同一种存在形式**。
-
-### 4.3 备用方案：改用 `sc.exe` 手动建服务
-
-若 `daemon install` 不工作（版本差异），用系统命令：
+**或用 PowerShell 原生 `New-Service`**（注意 Windows PowerShell 5.1 **没有 `-WorkingDirectory` 参数**，
+所以要靠 `--config` 绝对路径兜住工作目录）：

 ```powershell
-# 管理员 PowerShell
-New-Service -Name "act_runner" `
-            -BinaryPathName "D:\Docker\act_runner\act_runner.exe daemon --config D:\Docker\act_runner\config.yaml" `
+New-Service -Name "gitea-runner" `
+  -BinaryPathName '"D:\Docker\act_runner\gitea-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"
+Start-Service -Name "gitea-runner"
 ```

-> ⚠️ 用 `New-Service` 时，工作目录不是 runner 目录，**必须用 `--config` 显式指定配置路径**，
-> 否则会找不到 `.runner` 注册文件。
+**期望**：`Get-Service gitea-runner` → `Status: Running`。
+
+### 4.3 一键脚本（推荐）
+
+仓库内已提供两个脚本（**都需管理员 PowerShell**）：
+
+| 脚本 | 用途 |
+|---|---|
+| `D:\Docker\act_runner\deploy_runner.ps1` | **一键全流程**：环境自检 → 检查注册 → 装服务 → 启动 → 验证 |
+| `D:\Docker\act_runner\install_service.ps1` | 只做「装服务」（注册已完成时用） |
+| `D:\Docker\act_runner\check_env.ps1` | 只做「环境自检」（Gitea 可达 / 工具链 / MSVC / 服务状态） |
+
+```powershell
+# 管理员 PowerShell
+powershell -ExecutionPolicy Bypass -File "D:\Docker\act_runner\deploy_runner.ps1"
+```

 ### 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  # 卸载服务
+Get-Service gitea-runner                  # 状态
+Stop-Service gitea-runner                 # 停止
+Start-Service gitea-runner                # 启动
+Restart-Service gitea-runner              # 重启（改完 config.yaml 后必须）
+sc.exe delete gitea-runner                # 删除服务（卸载）
 ```

+### 4.5 ⚠️ 权限要求（本机实测的硬约束）
+
+**安装 Windows 服务必须用「提权的管理员」Shell**。本机实测：
+
+| 检查项 | 结果 |
+|---|---|
+| 当前用户 | `DESKTOP-KM0OG7Q\Administrator` |
+| 是否提权（`IsInRole(Administrator)`） | **False** |
+| 尝试 `New-Service` | ❌ `拒绝访问`（CreateService 需要 elevated token） |
+
+> **"是 Administrator 用户" ≠ "有管理员权限"** —— Windows 的 UAC 会把普通登录会话降权。
+> 必须**右键 PowerShell → 以管理员身份运行**，标题栏会显示「管理员」字样。
+
 ---

 ## 5. Runner 必须装齐的软件
@@ -278,7 +358,7 @@ MSVC      : VS2019 BuildTools 14.29.30133 (Hostx64\x64\cl.exe)  ✅
 - **装完任何新软件 / 改过 PATH 后，必须重启 runner 服务**：

 ```powershell
-.\act_runner.exe daemon restart
+Restart-Service gitea-runner
 ```

 ### 5.2 ⚠️ 关键坑：MSVC 的路径必须"标准"
@@ -316,7 +396,7 @@ C:\Program Files\Microsoft Visual Studio\2026\{BuildTools,Community}

 | # | 动作 | 期望 |
 |---|---|---|
-| 1 | `.\act_runner.exe daemon` 前台启动 | 打印 `win-stm32-ci` + `labels: [windows]` |
+| 1 | `.\gitea-runner.exe daemon` 前台启动 | 打印 `win-stm32-ci` + `labels: [windows]` + `declare successfully` |
 | 2 | 浏览器 Settings → Actions → Runners | 🟢 Idle |
 | 3 | 确认 workflow 已推到远程（**见下方注意**） | 远程分支有 `.gitea/workflows/ci.yml` |
 | 4 | Push 一次（或页面 **Run workflow**） | Actions 页出现运行中任务 |
@@ -325,35 +405,71 @@ C:\Program Files\Microsoft Visual Studio\2026\{BuildTools,Community}
 | 7 | 提交记录旁 | ✅ 绿灯 |

 > ⚠️ **第 3 步是当前的最大阻塞**：本仓库的 `.gitea/workflows/ci.yml` 还在本地
-> （提交 `e904865` / `1e01950` / `52e6dcb` 均未 push）。**workflow 不上远程，CI 永远不会跑**，
+> （提交 `e904865` / `1e01950` / `52e6dcb` / `c305a8d` 均未 push）。**workflow 不上远程，CI 永远不会跑**，
 > 哪怕 runner 配得再完美。

+### 6.1 无网页登录时的状态核验（MySQL 直查）
+
+runner 是否在线，可以直接查 Gitea 数据库确认（本机 MySQL 凭据见
+`D:\Docker\Gitea\custom\conf\app.ini` 的 `[database]` 段）：
+
+```bash
+MYSQL="/c/Program Files/MySQL/MySQL Server 8.4/bin/mysql.exe"
+"$MYSQL" -h 127.0.0.1 -P 3306 -u wandering -p<pwd> -D gitea -e \
+  "SELECT id,name,version,last_online,agent_labels FROM action_runner;"
+```
+
+| 字段 | 判读 |
+|---|---|
+| `name` / `version` | 注册名与版本（应为 `win-stm32-ci` / `v4.0.1`） |
+| `agent_labels` | 应为 `["windows"]` ← **不含 windows 就是标签配错了** |
+| `last_online` | Unix 秒；**与当前时间相差 < 30 秒即在正常心跳** |
+
+```bash
+date +%s   # 对比 last_online
+```
+
+相关表：`action_runner`（已注册 runner）、`action_runner_token`（注册令牌，
+字段 `repo_id` 对应 `repository.id`）。
+
 ---

 ## 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` |
+| runner 一直 **Idle**，push 后任务**排队不跑** | `--labels` 不是 `windows`（最常见） | 改 `config.yaml` 的 `runner.labels: ["windows:host"]` → `Restart-Service gitea-runner` |
+| `daemon` 启动报 **connection refused / dial tcp** | `--instance` 填了不可达地址 | 删 `.runner` → 重新 `register`，`--instance http://127.0.0.1:3001` |
 | 启动报 **token** 相关错误 | Registration Token 过期（约 1 小时）或已用过 | 回网页重新创建 runner 拿新 token，重新 `register` |
-| 任务跑到一半报 `python: 不是内部或外部命令` | 服务 PATH 没有 Python | 确认 Python 在**系统** PATH → `daemon restart` |
+| 任务跑到一半报 `python: 不是内部或外部命令` | 服务 PATH 没有 Python | 确认 Python 在**系统** PATH → `Restart-Service gitea-runner` |
 | `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` |
+| `daemon install` 报 `accepts at most 0 arg(s)` | **v4 已移除该子命令** | 用 `sc.exe create` / `New-Service`（§4.2） |
+| `config set log.file ...` 报 `unknown config key` | **v4 的 log 段无 `file` 键** | 用 `log.job.dir` 或输出重定向（§3） |
+| `New-Service` 报 **拒绝访问** | Shell 未提权（`IsAdmin=False`） | 右键 PowerShell → **以管理员身份运行**（§4.5） |
+| `New-Service` 报 `找不到与参数名称"WorkingDirectory"匹配的参数` | WinPS 5.1 的 `New-Service` 无此参数 | 去掉它，靠 `--config` 绝对路径 |

-**看日志**（服务模式）：act_runner 的日志默认输出到 Windows 事件日志或标准输出。
-建议在 `config.yaml` 里显式开文件日志方便排障：
+**看日志**：v4 的 `log` 段**没有 `file` 键**，两种落盘方式：

 ```yaml
+# 方式 A：按 job 落文件（推荐，防上报失败丢日志）
 log:
  level: info
-  file: "D:\\Docker\\act_runner\\log\\runner.log"    # 加这行
+  job:
+    dir: "D:\\Docker\\act_runner\\log\\job"
 ```

+```powershell
+# 方式 B：前台运行时直接重定向
+.\gitea-runner.exe daemon > "D:\Docker\act_runner\log\runner.log" 2>&1
+```
+
+服务模式（sc.exe 创建的）可在**事件查看器 → Windows 日志 → 应用程序**里找来源 `gitea-runner`。
+
 ---

 ## 8. ⚠️ 内网 action 拉取问题（你的环境很可能命中）
@@ -439,33 +555,44 @@ else { Write-Host "  FAIL 未找到 MSVC (Hostx64\x64\cl.exe)" -ForegroundColor
 ## 10. 最小操作清单（TL;DR）

 ```powershell
-# 1) 下载
+# 1) 下载（v4.0.1；注意仓库名是 gitea/runner，二进制名是 gitea-runner）
 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"
+Invoke-WebRequest -Uri "https://gitea.com/gitea/runner/releases/download/v4.0.1/gitea-runner-4.0.1-windows-amd64.exe" -OutFile "gitea-runner.exe"

-# 2) 注册（token 从网页 Settings→Actions→Runners 拿）
-.\act_runner.exe register --no-interactive `
+# 2) 注册（token 从网页 Settings→Actions→Runners 拿；instance 用回环）
+.\gitea-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 停
+.\gitea-runner.exe daemon       # 看到 "labels: [windows] ... declare successfully" 即成功，Ctrl+C 停

-# 4) 常驻（管理员 PowerShell）
-.\act_runner.exe daemon install
-.\act_runner.exe daemon start
-.\act_runner.exe daemon status
+# 4) 常驻 —— ⚠️ v4 无 daemon install，用 sc.exe（管理员 PowerShell）
+sc.exe create gitea-runner binPath= '"D:\Docker\act_runner\gitea-runner.exe" daemon --config "D:\Docker\act_runner\config.yaml"' start= auto
+sc.exe start gitea-runner
+
+#   或直接跑一键脚本（管理员 PowerShell）：
+#   powershell -ExecutionPolicy Bypass -File "D:\Docker\act_runner\deploy_runner.ps1"

 # 5) 回网页确认 runner 为 Idle → 然后（经你同意后）push 代码触发第一次 CI
 ```

+**配套脚本**（均在 `D:\Docker\act_runner\`）：
+
+| 脚本 | 用途 | 需要管理员 |
+|---|---|---|
+| `check_env.ps1` | 环境自检（Gitea 可达 / 工具链 / MSVC / 服务） | 否 |
+| `deploy_runner.ps1` | 一键部署（自检 + 装服务 + 启动 + 验证） | **是** |
+| `install_service.ps1` | 只装服务 | **是** |
+
 ---

 ## 变更记录

 | 日期 | 变更 |
 |---|---|
+| 2026-10-02 | **按实测修正为 v4.0.1**：act_runner 已更名 **`gitea-runner`**，发布页迁至 `gitea.com/gitea/runner`。**v4 移除 `daemon install/start/stop/status`**（§4.2 改用 `sc.exe` / `New-Service`）；**v4 `log` 段无 `file` 键**（§3 改用 `log.job.dir`）；补 §1.3 命令集对照、§4.5 提权硬约束（`IsAdmin=False` → `New-Service` 拒绝访问）、§6.1 MySQL 直查核验、排障表 +4 条（`accepts at most 0 arg(s)` / `unknown config key log.file` / `拒绝访问` / `WorkingDirectory` 参数） |
 | 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 拉取的零依赖改法 |