Files

T

wandering1 49f3e2dac5 CI runner 修"双看门狗抢 .runner.lock"：-StartNow 先清残留进程再启动

实测发现（比文档问题更要紧）：runner 网页 online、-Status 说 daemon 在跑，
但 runner-watchdog.log 每 10 秒刷 "starting daemon → daemon exited, exit code 1"，
daemon 日志写 "another gitea-runner process is already using .runner" /
"runner file is already locked by another process"。

根因：Unregister-ScheduledTask 不会带走旧实例启动的进程。13:22 重跑 bootstrap 时，
12:53 起的旧看门狗成为孤儿并继续养着旧 daemon，旧 daemon 占住 .runner.lock，
新注册任务启动的看门狗永远抢不到锁。online 是旧 daemon 在硬撑——任务实际谁也没管，
日志还在以约 20 MB/天 增长。

- ci_runner_bootstrap.ps1：-StartNow 新增 Stop-StaleRunnerInstances，先停孤儿看门狗
  再停残留 daemon（顺序不能反：只杀 daemon 会被活着的看门狗 10 秒内重拉），启动后
  等 12 秒回显单实例确认；-Status 新增重复实例计数 + daemon 日志锁冲突检测
- 指南 §3.4 补注销不停进程的说明与"纯注释改动不需重启任务"；§7 排障表加
  "online 却每 10 秒重启"一行（含手工应急命令）
- §3.2 / README：deploy_runner_task.ps1 与 run_runner.cmd 状态由"仍在磁盘、建议删除"
  改为"已删除"；README 补重跑部署前的锁冲突警示

机器侧同步（不在版本库）：config.yaml 头部"常驻改用 sc.exe / New-Service"是 §3.0
已证伪的错误指引，改为看门狗口径并指向本文——改后 YAML 可解析且所有配置值逐项与
改前一致（只动注释）；删除两个废弃脚本前核实计划任务动作目标是
run_runner_watchdog.ps1，删除不影响在跑 runner；check_env.ps1 指向废弃脚本的提示
改指 bootstrap（带 BOM 文件，改后 BOM 完好、语法 0 错）。

验证：pre-commit run --all-files 17 项全 Passed；bootstrap parse 0 错、纯 ASCII、
-DryRun 正常。当前 runner 仍 online（旧 daemon 硬撑），彻底归一需管理员跑一次
-StartNow 清残留。

2026-10-12 17:37:19 +08:00

README.md

CI runner 修"双看门狗抢 .runner.lock"：-StartNow 先清残留进程再启动

2026-10-12 17:37:19 +08:00

远程CI完整指南.md

CI runner 修"双看门狗抢 .runner.lock"：-StartNow 先清残留进程再启动

2026-10-12 17:37:19 +08:00

README.md

远程 CI（Gitea Actions）—— 本目录是唯一入口

适用范围（先读这句，可以省下很多时间） 本仓库的远程 CI 只跑在本机这一台 runner 上：runner 名 win-stm32-ci，装在 D:\Docker\act_runner，连的是本机原生 Gitea http://127.0.0.1:3001。 其他机器、其他项目都不涉及，也不需要配这套东西。

日常改代码不需要读本目录：提交前的等价自查是本地门禁，runner 在不在线都照样跑——
& '.venv\Scripts\python.exe' scripts/ci_local.py     # L0 静态 + L0b 提交信息 + L0.5 主机单测
只有在这三种情况下才需要进来：① 换机/重装后要重新部署 runner；② CI 不出任务或莫名取消；③ 改 .gitea/workflows/ci.yml 本身。

索引

全部内容是一篇文档：远程CI完整指南.md（2026-10-12 由原「环境与部署」目录下的两篇指南 CI配置指南.md 与 Gitea_Runner部署指南.md 合并而来，两篇均已删除，去重后为单一来源）。

想干什么	去看
先搞清 CI 需要哪三样东西就位、本机拓扑、部署前置清单	§0 / §0.1 / §0.2
CI 不守哪些门禁（体积门禁盲区 S14、gitlint 空转）	§0.0 + §7 排障表"钩子条数对不上"行
服务端开启 Actions、`DEFAULT_ACTIONS_URL` 到底管什么	§1（含 §1.2.1，这条最容易搞反）
下载 / 注册 runner（`--instance` 用回环、labels 必须精确匹配 `runs-on`）	§2.2
`config.yaml` 各字段语义（capacity / timeout / labels / 日志目录…）	§2.3
常驻：为什么必须看门狗、不能只起 daemon、也不能做成 Windows 服务	§2.4 + §3.0
runner 装什么软件、为什么变量必须对 SYSTEM 可见、机器级 `DTU_*`	§4（§4.1.1~§4.1.3 是三个真坑）
workflow 位置 / 触发 / 内网拉不到 `actions/checkout` 的三种处置	§5（§5.3 零依赖写法）
两个 job 各自跑哪些步骤、两条 Python 探测链要同序同步	§5.5
端到端验证清单、无网页登录时直查 MySQL 核验	§6 / §6.1
出问题了按症状查表（含 `0x41301`、1053、72h 被杀、`.ps1` 无 BOM 乱码…）	§7
日常维护（改钩子集 / 改 workflow 后要不要动 runner）	§8
一键自检脚本、最小操作清单 TL;DR	§9 / §10

常用命令速查

# 本地等价门禁（不依赖 runner，日常用这个）
& '.venv\Scripts\python.exe' scripts/ci_local.py

# runner 体检（四项：计划任务 / 进程 / Gitea 可达 / 机器级变量）—— 须管理员
& '.\scripts\ci_runner_bootstrap.ps1' -Status

# 干跑：只打印将要写入的启动器与任务对象，不落盘不注册（免管理员）
& '.\scripts\ci_runner_bootstrap.ps1' -DryRun

# 部署 / 修复：写机器级 DTU_* + 生成看门狗启动器 + 注册开机计划任务 + 立即启动（须管理员）
& '.\scripts\ci_runner_bootstrap.ps1' -SetEnv -StartNow

⚠️ 上面三条 ci_runner_bootstrap.ps1 是本机运维动作，会改系统计划任务与机器级环境变量；返回码 0x41301 是"任务正在运行"、next run 为空是开机触发器的正常表现，都不是故障（详见指南 §3.4）。

✅ 机器侧遗留已清理（2026-10-12）：旧方案的 deploy_runner_task.ps1 与 run_runner.cmd 已从 D:\Docker\act_runner\ 删除（它们跑单次 daemon，首次 Declare 失败就永久停摆，机理见指南 §3.2；check_env.ps1 里指向它们的提示也已改指 bootstrap）。现行部署只有 ci_runner_bootstrap.ps1 这一条路。

🔴 重跑部署前先知道这条（2026-10-12 实测）：Unregister-ScheduledTask 不会带走旧实例启动的进程。旧看门狗会作为孤儿继续养着它的 daemon，而那个 daemon 占着 .runner.lock，于是新看门狗每 10 秒失败一次（runner file is already locked by another process）—— 而 runner 在网页上照样显示 online，CI 看着正常，任务其实谁也没管。现在 -StartNow 会先清掉这些残留进程再启动（约离线几秒），-Status 也会报出重复实例。

变更记录

日期	变更
2026-10-12	🔴 修复"双看门狗抢 `.runner.lock`"缺陷：`Unregister-ScheduledTask` 不停旧实例进程 → 孤儿看门狗养着旧 daemon 占锁，新看门狗每 10 秒失败一次，而 runner 网页照样 online、`-Status` 也说"在跑"。现 `-StartNow` 先清残留进程再启动、`-Status` 报重复实例与锁冲突。同日清理机器侧：`config.yaml` 头部错误指引（"改用 sc.exe / New-Service"）改为看门狗口径，删除已废弃的 `deploy_runner_task.ps1` 与 `run_runner.cmd`，`check_env.ps1` 提示同步改指 bootstrap
2026-10-12	单一口径清理：合并稿初版对 4 处分歧"两说并存"，现统一为本机实测现状——注册口径（`gitea-runner v4.0.1` / `D:\Docker\act_runner` / `127.0.0.1:3001`，旧 `act_runner v0.2.11` + `C:\act_runner` 段删去可复制命令只留警示）、`config.yaml`（`fetch_timeout: 1m0s`、`timeout: 30m0s`）、常驻方式（只认看门狗，`deploy_runner_task.ps1` 标废弃）、验收数字（L0.5 `288/288`，历史数字标注为快照）。并补"机器侧遗留脚本勿误用"警示
2026-10-12	新建本目录：远程 CI 内容原先散在 `docs/环境与部署/`（两篇互相重叠的指南）、`docs/测试说明/测试开发标准流程.md` §9、`AGENTS.md` 提交门禁节共 4 处，约 2000 行；现合并为单一指南并把 `AGENTS.md` 压成一行指针。动因：远程 CI 只涉及本机一台 runner，与日常开发规范混在一起每次会话都被读，造成困惑

README.md Unescape Escape

远程 CI（Gitea Actions）—— 本目录是唯一入口

索引

常用命令速查

相关文档

变更记录

README.md