# 添加 Gitea Actions Runner 人工手顺

在 Windows 机器上手工部署一台宿主机模式（host）的 act_runner，注册到
<https://gitea.docker.antior.cn/>。全程约 10 分钟。

## 0. 前置条件

- Windows 10/11 x64
- 能访问 `https://gitea.docker.antior.cn/`（浏览器打开确认）
- 一个 Gitea 账号：
  - 注册**实例级** runner 需要管理员权限
  - 只给某个仓库/组织用，仓库 Owner 也可以（在仓库 `设置 → Actions → Runners` 页面操作）
- 本手顺以安装目录 `C:\Users\<用户名>\Gitea_worker` 为例，可按需替换

## 1. 获取注册令牌（二选一）

**方式 A：Web 页面**

- 实例级：右上角头像 → 站点管理 → Actions → Runners → 创建新 Runner，复制注册令牌
- 仓库级：仓库 → 设置 → Actions → Runners，同样位置复制

**方式 B：管理员 API**

```bash
curl -X POST -H "Authorization: token <你的PAT>" \
  https://gitea.docker.antior.cn/api/v1/admin/actions/runners/registration-token
# 返回 {"token":"..."}
```

> 注册令牌一次性、有时效，注册时用掉即可，不需要保存。

## 2. 下载 act_runner

到 <https://gitea.com/gitea/runner/releases> 找最新版本，下载
`gitea-runner-<版本>-windows-amd64.exe`，放入安装目录并重命名为 `act_runner.exe`：

```bash
mkdir -p /c/Users/$USER/Gitea_worker && cd /c/Users/$USER/Gitea_worker
curl -sSL -o act_runner.exe \
  https://gitea.com/gitea/runner/releases/download/v2.1.0/gitea-runner-2.1.0-windows-amd64.exe
./act_runner.exe --version
```

## 3. 注册 runner

```bash
./act_runner.exe register --no-interactive \
  --instance https://gitea.docker.antior.cn/ \
  --token <注册令牌> \
  --name "$(hostname)-windows" \
  --labels "windows-latest:host,windows:host,windows-amd64:host"
```

- 看到 `Runner registered successfully.` 即成功，目录下会生成 `.runner` 凭证文件
- **labels 说明**：`xxx:host` 表示直接在 Windows 宿主机上执行，不经过 Docker
  - 本机没装 Docker，workflow 里 `runs-on` 只能用这几个自定义标签
  - 若之后装了 Docker Desktop，可追加 `ubuntu-latest:docker://node:22` 之类的容器标签（需重新注册）

## 4. 启动并验证

```bash
./act_runner.exe daemon
# 看到 "declare successfully" 说明已连上实例，Ctrl+C 先停掉
```

再到 Web 页面（站点管理 → Actions → Runners）确认状态为**在线**。

## 5. 配置开机自启（二选一）

**方式 A：计划任务（首选）**

```powershell
schtasks /create /tn "GiteaActRunner" /sc onlogon /f `
  /tr "wscript.exe \"C:\Users\<用户名>\Gitea_worker\run_hidden.vbs\""
```

**方式 B：启动文件夹（方式 A 提示"拒绝访问"时用）**

在安装目录新建 `run_hidden.vbs`（隐藏窗口后台运行，日志写入 runner.log）：

```vb
Dim shell
Set shell = CreateObject("WScript.Shell")
shell.CurrentDirectory = "C:\Users\<用户名>\Gitea_worker"
shell.Run "cmd /c act_runner.exe daemon >> runner.log 2>&1", 0, False
```

然后把它复制到启动文件夹（`Win+R` 输入 `shell:startup` 打开）：

```
%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\GiteaActRunner.vbs
```

立即启动一次（双击 vbs，或 `wscript run_hidden.vbs`），确认任务管理器里出现
`act_runner.exe` 进程、Web 页面上 runner 在线。

## 6. 日常使用

- **日志**：`<安装目录>\runner.log`
- **任务工作目录**：默认在安装目录下自动创建（`work/`、`.cache/`），首个任务运行后出现
- **workflow 写法**：参考本仓库根目录 README 中的 prompt 模板和
  [.gitea/workflows/build.yaml](../.gitea/workflows/build.yaml)

## 7. 卸载

1. 结束 `act_runner.exe` 进程
2. 删除自启项：计划任务 `GiteaActRunner` 或启动文件夹里的 `GiteaActRunner.vbs`
3. 删除安装目录
4. Web 页面（站点管理 → Actions → Runners）删除该 runner 记录

## 常见问题

| 现象 | 原因 / 处理 |
|---|---|
| `schtasks` 提示"拒绝访问" | 组策略限制，改用方式 B（启动文件夹） |
| workflow 一直排队不执行 | `runs-on` 标签与 runner labels 不匹配，改成 `windows-latest` |
| 任务里 `docker`/`gcc`/`make` 找不到 | host 模式没有这些工具，见 README 的工具链清单 |
| 注册时报令牌错误 | 注册令牌已过期或被用掉，重新生成一个 |
| `actions/checkout` 步骤报 `github.com ... wsarecv` 连接失败 | runner 到 github.com 的网络不稳定（偶发）。处理：① 在 Actions 页面重跑该任务，多数情况重跑即成功；② 管理员可在服务端 `app.ini` 设 `[actions] DEFAULT_ACTIONS_URL` 指向可达镜像；③ workflow 里改用 `git clone https://x-access-token:${{ secrets.GITHUB_TOKEN }}@<实例域名>/${{ github.repository }}.git` 从实例拉代码，完全不依赖 github.com |