From 3060597e57c080adf83a232a3ffd58661786d017 Mon Sep 17 00:00:00 2001 From: antior Date: Tue, 21 Jul 2026 10:08:14 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E5=A2=9E=E5=8A=A0=20WSL2=20Li?= =?UTF-8?q?nux=20(Docker)=20runner=20=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 runner 对照表：Windows host 与 WSL2 Docker 两种模式 - 补充 ubuntu-latest 标签的 workflow 编写约束 - prompt 模板更新为双 runner 版本 --- README.md | 91 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 64 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index bf75ea3..192f3d1 100644 --- a/README.md +++ b/README.md @@ -4,22 +4,36 @@ Gitea Actions 自托管 runner 的测试仓库，同时作为其他仓库编写 - 实例：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) +- Windows runner 人工部署手顺：[docs/add-runner.md](docs/add-runner.md) -## 编写 workflow 注意点 +## 现有 runner -这台 runner 是一台 Windows 宿主机（host 模式），不是云端标准环境，写 workflow 时务必注意： +同一台物理机上跑着两台 runner，写 workflow 先按需求选标签： -1. **标签匹配**：`runs-on: windows-latest`（或 `windows` / `windows-amd64`）。写成 `ubuntu-latest` 等未注册标签，任务会永远排队。 -2. **不依赖 github.com**：runner 到 github.com 网络不稳定，禁止使用 `actions/checkout@v4` 等托管在 github.com 的 action。拉代码用实例克隆： - ```powershell - git clone https://x-access-token:${{ secrets.GITHUB_TOKEN }}@gitea.docker.antior.cn/${{ github.repository }}.git . - git checkout ${{ github.sha }} - ``` - npm / pypi registry 目前可正常访问。 -3. **Windows 宿主机写法**：workflow 放 `.gitea/workflows/`（不是 `.github/`）；shell 是 PowerShell（建议显式 `shell: pwsh`），不要写 bash 语法；打包用 `Compress-Archive`。 -4. **工具链边界**：有 Node 22 / npm、Python 3.10–3.14（用 `py -X.Y` 显式指定版本，勿裸写 `python`）、pwsh、git、curl；没有 gcc / make / go / rust / docker。 -5. **发布方式**：用 Gitea API，token 用自动注入的 `${{ secrets.GITHUB_TOKEN }}`，地址用 `${{ gitea.server_url }}/api/v1`；tag 带 `${{ github.run_number }}` 保证唯一。 +| 名称 | 模式 | labels | shell | 适用场景 | +|---|---|---|---|---| +| Lees-Desktop-windows | Windows 11 宿主机（host） | `windows-latest` / `windows` / `windows-amd64` | PowerShell | 需要 Windows 工具链、直接访问宿主机文件 | +| Lees-Desktop | WSL2 Ubuntu 22.04 + Docker（容器模式） | `ubuntu-latest` / `ubuntu-24.04` / `ubuntu-22.04` | bash（容器内） | 常规 Linux 构建，需要 root / apt / 干净一次性环境 | + +## 编写 workflow 注意点（两台通用） + +1. **标签匹配**：`runs-on` 必须是上表中的标签，写成未注册标签任务会永远排队。 +2. **不依赖 github.com**：两台 runner 到 github.com 的网络都不稳定，禁止使用 `actions/checkout@v4` 等托管在 github.com 的 action。拉代码用实例克隆（见下文模板），npm / pypi registry 目前可正常访问。 +3. **workflow 位置**：放 `.gitea/workflows/`（不是 `.github/`）。 +4. **发布方式**：用 Gitea API，token 用自动注入的 `${{ secrets.GITHUB_TOKEN }}`，地址用 `${{ gitea.server_url }}/api/v1`；tag 带 `${{ github.run_number }}` 保证唯一。 + +### Windows runner（runs-on: windows-latest） + +- shell 是 PowerShell（建议显式 `shell: pwsh`），不要写 bash 语法；路径用 Windows 规则；打包用 `Compress-Archive`。 +- 工具链：Node 22 + npm 10、Python 3.10–3.14（用 `py -X.Y` 显式指定版本，勿裸写 `python`）、pwsh、git、curl。 +- 没有 gcc / make / go / rust / docker。 + +### Linux runner（runs-on: ubuntu-latest） + +- 作业运行在一次性 Docker 容器里（镜像 `docker.gitea.com/runner-images:ubuntu-*`，首次运行需拉取约 1GB+ 镜像），容器内是 root，可用 `apt` 安装依赖。 +- 默认 shell 是 bash，写 Linux 语法即可。 +- 镜像预装常用工具链（Node、Python、git 等），但**环境是一次性的**：不要在多个 job 之间依赖容器内的文件状态，产物传递用 Gitea Release 或上传 artifact。 +- 容器里有 docker CLI 不可用（未挂载宿主机 docker.sock），不要在 job 里构建镜像。 完整约束见下面的 prompt 模板，可直接发给其他电脑的 agent 使用。 @@ -27,26 +41,42 @@ Gitea Actions 自托管 runner 的测试仓库，同时作为其他仓库编写 ```text 我的 Gitea 实例：https://gitea.docker.antior.cn/ -仓库已有一台在线的自托管 runner，请为本仓库编写 Gitea Actions workflow， -实现：push 到 main 分支时自动编译/构建，并创建 Release、上传构建产物。 +仓库有在线的自托管 runner（同一台机器上的两台，按需求二选一）， +请为本仓库编写 Gitea Actions workflow，实现：push 到 main 分支时 +自动编译/构建，并创建 Release、上传构建产物。 -【runner 环境约束 —— workflow 必须遵守】 -- runner 是 Windows 11 x64 宿主机模式（非 Docker），labels：windows-latest / windows / windows-amd64 - → runs-on 必须用 windows-latest +【runner 选择（runs-on 二选一）】 +A. windows-latest：Windows 11 x64 宿主机模式（非 Docker）， + labels：windows-latest / windows / windows-amd64 +B. ubuntu-latest：WSL2 + Docker 容器模式， + labels：ubuntu-latest / ubuntu-24.04 / ubuntu-22.04， + 作业镜像 docker.gitea.com/runner-images:ubuntu-* + +【共同约束 —— workflow 必须遵守】 +- workflow 文件放在 .gitea/workflows/ 目录（不是 .github/） +- runner 到 github.com 的网络不稳定，【禁止使用 actions/checkout@v4 等 + 托管在 github.com 的 action】，拉代码必须用下文实例克隆步骤 + （npm/pypi registry 可正常访问） +- 标签必须与所选 runner 匹配，否则任务永远排队 + +【A. Windows runner 环境约束】 - 已安装工具链： - 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，可能与预期不符） + - Python 3.10 / 3.11 / 3.12 / 3.13 / 3.14，通过 py launcher 调用 + （py -3.12 等）→ 必须用 py -X.Y 显式指定版本，不要只写 python - PowerShell 7 (pwsh)、git、curl - 没有：gcc/make/go/rust/docker。不要引用依赖这些工具的步骤 -- workflow 文件放在 .gitea/workflows/ 目录（不是 .github/） -- 默认 shell 是 PowerShell，写 run 步骤时用 PowerShell 语法， - 或显式声明 shell: pwsh；不要写 bash 语法 -- 路径用 Windows 规则；产物打包用 Compress-Archive -- runner 到 github.com 的网络不稳定，【禁止使用 actions/checkout@v4 等托管在 github.com 的 action】， - 拉代码必须用下面的实例克隆步骤（npm/pypi registry 可正常访问） +- 默认 shell 是 PowerShell，run 步骤用 PowerShell 语法或显式 shell: pwsh， + 不要写 bash 语法；路径用 Windows 规则；产物打包用 Compress-Archive -【拉取代码（代替 actions/checkout，shell: pwsh）】 +【B. Linux runner 环境约束】 +- 作业在一次性 Docker 容器中运行，容器内为 root，可 apt 安装依赖 +- 默认 shell 是 bash；镜像预装 Node/Python/git 等常用工具 +- 环境一次性：不要在 job 之间依赖容器内文件状态 +- 容器内不能构建 docker 镜像（无 docker.sock） + +【拉取代码（代替 actions/checkout）】 +Windows（shell: pwsh）： - name: Checkout shell: pwsh @@ -57,6 +87,13 @@ Gitea Actions 自托管 runner 的测试仓库，同时作为其他仓库编写 git clone $url . git checkout ${{ github.sha }} +Linux（bash）： + + - name: Checkout + run: | + git clone https://x-access-token:${{ secrets.GITHUB_TOKEN }}@gitea.docker.antior.cn/${{ github.repository }}.git . + git checkout ${{ github.sha }} + 【Release 发布方式】 用 Gitea API 发布，token 用自动注入的 ${{ secrets.GITHUB_TOKEN }}， API 地址用 ${{ gitea.server_url }}/api/v1。参考步骤（shell: pwsh）：