wandering1
8b35769a5c
合并稿初版对 4 处分歧采取"两说并存 + 衔接注"，长期看是隐患（读者可能照抄失效方案）。 本次先实测取现状，再统一口径：gitea-runner v4.0.1 / D:\Docker\act_runner / --instance http://127.0.0.1:3001 / labels windows:host / config.yaml 实际值。 - 注册口径：删掉 act_runner v0.2.11 + C:\act_runner + 公网域名的可复制命令块，只留 "勿照抄"警示——核实 C:\act_runner 至今不存在，且 v0.2.x 与 v4 命令集不兼容， 照抄会装出连不上 Gitea 的 runner - config.yaml：示例 fetch_timeout 由 5m0s 改为磁盘实际值 1m0s（超 RPC timeout 1m 会被 截断并刷告警）、timeout 统一 30m0s，两处示例块对齐真实文件 - 常驻口径：§3.2 deploy_runner_task.ps1 标为已废弃并写清失效机理（单次 daemon 是 "正常退出"，计划任务失败重启永不触发）；§3.3 手动等价命令重写为看门狗版任务对象 （旧版会教人手搓出坏配置）；§10 TL;DR 第 4 步改指 ci_runner_bootstrap.ps1 - 数字口径：L0.5 期望值更新为 288/288（2026-10-12 实测），run#8 的 39/39 与 278/278 标注为历史快照——判定只看 fail=0 与 A==B，不拿历史数字当基准 顺带同步到现状：健康三查与排障表改用现行日志名（runner-daemon.log / runner-watchdog.log；runner-stdout.log 标为遗留并说明其 ASCII+UTF-16LE 混编码）； BOM 示例对象换成 check_env.ps1 并注明看门狗是纯 ASCII 无需 BOM；配套脚本表补 run_runner_watchdog.ps1，并警示磁盘上仍存的 deploy_runner_task.ps1 / run_runner.cmd 误执行会把看门狗任务覆盖回单次任务；补"Next Run Time 为空属开机触发器正常表现"。 保留不动：机器级 DTU_* 为正式通道、全局 site-packages 为兜底——这是设计的降级链， 不是文档分歧。 验证：check_doc_links.py --all 125 篇 0 问题；pre-commit run --all-files 17 项全 Passed。
远程 CI（Gitea Actions）—— 本目录是唯一入口
适用范围（先读这句，可以省下很多时间） 本仓库的远程 CI 只跑在本机这一台 runner 上：runner 名
win-stm32-ci，装在D:\Docker\act_runner，连的是本机原生 Giteahttp://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）。
🗑 机器侧遗留，别误用：
D:\Docker\act_runner\下还留着旧方案的deploy_runner_task.ps1与run_runner.cmd。它们跑的是单次 daemon——首次 Declare 失败就永久停摆（机理见指南 §3.2），而且执行它会把看门狗任务覆盖回单次任务。现行部署只有ci_runner_bootstrap.ps1这一条路；那两个文件建议改名加.deprecated后缀或直接删除。
相关文档
- 测试分层与门禁决策（L0~L3 各层由谁把关）：
../测试说明/测试开发标准流程.md - workflow 本体：
../../.gitea/workflows/ci.yml - 本地等价脚本：
../../scripts/ci_local.py - runner 机器的工具链环境要求：
../环境与部署/项目部署环境要求.md DTU_*工具路径变量机制：../环境与部署/本地工具路径环境变量方案.md
变更记录
| 日期 | 变更 |
|---|---|
| 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，与日常开发规范混在一起每次会话都被读，造成困惑 |