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

> **适用范围（先读这句，可以省下很多时间）**
> 本仓库的远程 CI **只跑在本机这一台 runner 上**：runner 名 `win-stm32-ci`，装在
> `D:\Docker\act_runner`，连的是本机原生 Gitea `http://127.0.0.1:3001`。
> **其他机器、其他项目都不涉及，也不需要配这套东西。**
>
> 日常改代码**不需要读本目录**：提交前的等价自查是本地门禁，runner 在不在线都照样跑——
>
> ```powershell
> & '.venv\Scripts\python.exe' scripts/ci_local.py     # 静态门禁 + 提交信息门禁 + 主机侧纯逻辑单测
> ```
>
> 只有在这三种情况下才需要进来：**① 换机/重装后要重新部署 runner；② CI 不出任务或莫名
> 取消；③ 改 `.gitea/workflows/ci.yml` 本身。**

## 索引

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

| 想干什么 | 去看 |
|---|---|
| 先搞清 CI 需要哪三样东西就位、本机拓扑、部署前置清单 | §0 / §0.1 / §0.2 |
| **CI 体积门禁现在怎么守**（同码凭证强制，「只声明不执行」那处盲区已关闭；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 |

## 常用命令速查

```powershell
# 本地等价门禁（不依赖 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 已实测收敛**：清掉 3 个残留后 `daemon up: pid … (single instance)`，
> 监管链 `svchost(任务) → 看门狗 → daemon` 恢复，runner 回 online。

## 相关文档

- 测试分层与门禁决策（静态门禁~人工目检各层由谁把关）：[`../测试说明/流程与规范/测试开发标准流程.md`](../测试说明/流程与规范/测试开发标准流程.md)
- workflow 本体：[`../../.gitea/workflows/ci.yml`](../../.gitea/workflows/ci.yml)
- 本地等价脚本：[`../../scripts/ci_local.py`](../../scripts/ci_local.py)
- runner 机器的工具链环境要求：[`../环境与部署/项目部署环境要求.md`](../环境与部署/项目部署环境要求.md)
- `DTU_*` 工具路径变量机制：[`../环境与部署/本地工具路径环境变量方案.md`](../环境与部署/本地工具路径环境变量方案.md)