From 7e32c6e2b8fd382d21c9275d49fcc3020e69f8cb Mon Sep 17 00:00:00 2001 From: antior Date: Mon, 20 Jul 2026 12:16:04 +0800 Subject: [PATCH] Add agent prompt template (README) and manual runner setup guide (docs) --- README.md | 63 ++++++++++++++++++++++++ docs/add-runner.md | 118 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 181 insertions(+) create mode 100644 README.md create mode 100644 docs/add-runner.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..0e1c365 --- /dev/null +++ b/README.md @@ -0,0 +1,63 @@ +# Test_runner + +Gitea Actions 自托管 runner 的测试仓库，同时作为其他仓库编写 workflow 的参考。 + +- 实例：https://gitea.docker.antior.cn/ +- 参考 workflow：[.gitea/workflows/build.yaml](.gitea/workflows/build.yaml)（push 到 main → esbuild 编译 → 打包 → 创建 Release 并上传产物） +- runner 环境说明与人工部署手顺：[docs/add-runner.md](docs/add-runner.md) + +## 给其他电脑 Agent 的 Prompt（复制即用） + +```text +我的 Gitea 实例：https://gitea.docker.antior.cn/ +仓库已有一台在线的自托管 runner，请为本仓库编写 Gitea Actions workflow， +实现：push 到 main 分支时自动编译/构建，并创建 Release、上传构建产物。 + +【runner 环境约束 —— workflow 必须遵守】 +- runner 是 Windows 11 x64 宿主机模式（非 Docker），labels：windows-latest / windows / windows-amd64 + → runs-on 必须用 windows-latest +- 已安装工具链： + - Node.js v22 + npm 10（node/npm 直接在 PATH） + - Python 3.10 / 3.11 / 3.12 / 3.13 / 3.14，通过 py launcher 调用（py -3.12 等，py 默认为 3.14） + → workflow 里必须用 py -X.Y 显式指定版本，不要只写 python（PATH 中的 python 是 3.12，可能与预期不符） + - PowerShell 7 (pwsh)、git、curl +- 没有：gcc/make/go/rust/docker。不要引用依赖这些工具的步骤 +- workflow 文件放在 .gitea/workflows/ 目录（不是 .github/） +- 默认 shell 是 PowerShell，写 run 步骤时用 PowerShell 语法， + 或显式声明 shell: pwsh；不要写 bash 语法 +- 路径用 Windows 规则；产物打包用 Compress-Archive +- actions/checkout@v4 等 GitHub 官方 action 可用（runner 可访问 github.com 和 npm/pypi registry） + +【Release 发布方式】 +用 Gitea API 发布，token 用自动注入的 ${{ secrets.GITHUB_TOKEN }}， +API 地址用 ${{ gitea.server_url }}/api/v1。参考步骤（shell: pwsh）： + + - name: Create Gitea release with artifact + shell: pwsh + env: + GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + $repo = "${{ github.repository }}" + $tag = "v0.1.${{ github.run_number }}" + $server = "${{ gitea.server_url }}" + $headers = @{ Authorization = "token $env:GITEA_TOKEN" } + $body = @{ + tag_name = $tag; name = "Build $tag" + target_commitish = "${{ github.sha }}" + draft = $false; prerelease = $true + } | ConvertTo-Json + $release = Invoke-RestMethod -Method Post -Uri "$server/api/v1/repos/$repo/releases" ` + -Headers $headers -Body $body -ContentType "application/json" + Invoke-RestMethod -Method Post ` + -Uri "$server/api/v1/repos/$repo/releases/$($release.id)/assets?name=<产物文件名>" ` + -Headers $headers -Form @{ attachment = Get-Item "<产物文件路径>" } + +tag 命名建议带 ${{ github.run_number }} 保证唯一，避免重复 tag 导致发布失败。 +也可以直接参考本实例上 antior/Test_runner 仓库的 .gitea/workflows/build.yaml。 + +【本仓库信息】 +- 项目类型：<比如 Node / Python / 纯静态文件> +- 构建命令：<比如 npm ci && npm run build，或 py -3.12 -m PyInstaller ...> +- 产物位置：<比如 dist/ 目录> +请生成 workflow 并提交 push，然后确认 Actions 运行成功、Release 已创建。 +``` diff --git a/docs/add-runner.md b/docs/add-runner.md new file mode 100644 index 0000000..4f05138 --- /dev/null +++ b/docs/add-runner.md @@ -0,0 +1,118 @@ +# 添加 Gitea Actions Runner 人工手顺 + +在 Windows 机器上手工部署一台宿主机模式（host）的 act_runner，注册到 +。全程约 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 + +到 找最新版本，下载 +`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 的工具链清单 | +| 注册时报令牌错误 | 注册令牌已过期或被用掉，重新生成一个 |