xiaoxia-saas/docs/RUNNER-INFRASTRUCTURE.md

Gitea Runner 基础设施规范

目标

把 CI runner 从“文档里假定存在”收敛为“可安装、可启动、可验证、可排障”的正式基础设施。

当前已确认的问题不是单个 workflow 命令，而是 runner 基础设施缺少可观测、可管理、可验证的落地形态，导致：

• workflow 可以触发
• run 可以入队
• job 长时间停留在 Waiting to run
• 无法快速确认 runner 是否在线、注册、可消费队列

---

正式约定

安装目录

统一约定 runner 安装根目录：

C:\xiaoxia-ci\act_runner\

目录结构：

C:\xiaoxia-ci\act_runner\
├── act_runner.exe
├── config.yaml
├── .runner
├── data\
├── work\
├── logs\
└── scripts\
    ├── install-runner.ps1
    ├── start-runner.ps1
    ├── stop-runner.ps1
    └── check-runner.ps1

启动方式

统一使用 Windows 计划任务或服务化方式 启动，禁止依赖临时终端手工常驻。

最低要求：

• 开机自动启动
• 失败可重启
• 有固定工作目录
• 有固定日志目录

日志目录

C:\xiaoxia-ci\act_runner\logs\

至少保留：

• runner.stdout.log
• runner.stderr.log
• runner.health.log

工作目录

C:\xiaoxia-ci\act_runner\work\

不得把 runner 工作目录放在随机用户临时目录。

---

配置要求

config.yaml 最低要求

应明确：

• Gitea 实例地址
• runner 名称
• labels
• workdir
• 日志输出位置
• 容器 / shell 执行策略

示例字段（示意，不代表最终 token）：

instance:
  url: https://api.xiaoxiajianji.com/git
  token: CHANGE_ME

runner:
  name: xiaoxia-windows-runner
  labels:
    - windows
    - local
    - xiaoxia-ci
  workdir: C:\xiaoxia-ci\act_runner\work

---

健康检查标准

必须能通过固定命令验证以下事实：

1. runner 进程存在
2. runner 配置文件存在
3. runner 工作目录存在
4. runner 最近日志有心跳/拉取任务痕迹
5. Gitea 新 run 不再长期停留在 Waiting to run

推荐检查命令：

powershell -ExecutionPolicy Bypass -File C:\xiaoxia-ci\act_runner\scripts\check-runner.ps1

---

与仓库文档的关系

以下历史说法在 runner 正式落地前，不能再当作既成事实：

• docs/CI-CD.md 中“act_runner 已注册并持续运行”
• docs/PHASE7-PROGRESS.md 中“Gitea Runner 已运行”

以后必须改成：

• 已验证 runner 基础设施状态
• 已验证 runner 当前在线
• 已验证 runner 可消费指定 run

也就是： 状态必须来自检查，不来自假设。

---

验收标准

runner 基础设施完成的标准：

• act_runner.exe 有固定安装目录
• config.yaml 有固定路径
• 有固定启动脚本
• 有固定停止脚本
• 有固定健康检查脚本
• 开机自动启动机制已配置
• 日志目录固定
• 新 run 可以被稳定消费
• 文档中的 runner 状态表述与现实一致

---

当前结论

本专项当前真正缺的不是另一条 workflow patch， 而是 runner 作为基础设施的正式纳管。

并且根据现有仓库中的路径约定（如 xiaoxia-server:/var/lib/xiaoxia-ci/xiaoxia-saas.git）， runner / Gitea 的真实宿主很可能在服务器侧而非当前本机。

因此正式治理必须先回答一个基础问题： runner 到底运行在哪台机器上，并把这个事实写进文档和检查脚本。