Xiaoxia AI
165 lines
3.5 KiB
Markdown
165 lines
3.5 KiB
Markdown
# 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 到底运行在哪台机器上，并把这个事实写进文档和检查脚本。**
|