119 lines
4.3 KiB
Markdown
119 lines
4.3 KiB
Markdown
# 添加 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 的工具链清单 |
|
||
| 注册时报令牌错误 | 注册令牌已过期或被用掉，重新生成一个 |
|