# Gitea Runner 基础设施规范

## 目标

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

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

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

---

## 正式约定

### 安装目录

统一约定 runner 安装根目录：

```text
C:\xiaoxia-ci\act_runner\
```

目录结构：

```text
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 计划任务或服务化方式** 启动，禁止依赖临时终端手工常驻。

最低要求：
- 开机自动启动
- 失败可重启
- 有固定工作目录
- 有固定日志目录

### 日志目录

```text
C:\xiaoxia-ci\act_runner\logs\
```

至少保留：
- `runner.stdout.log`
- `runner.stderr.log`
- `runner.health.log`

### 工作目录

```text
C:\xiaoxia-ci\act_runner\work\
```

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

---

## 配置要求

### config.yaml 最低要求

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

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

```yaml
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
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 到底运行在哪台机器上，并把这个事实写进文档和检查脚本。**