docs: 添加多平台 Runner 架构文档

- 描述 Gitea 多平台 runner 配置方案 - 包含 macOS 和 Windows 安装脚本 - 说明跨平台编译限制 - 提供故障排查指南
2026-04-24 04:09:43 +08:00
parent 3e8fe16e07
commit 5c5510ef0a
1 changed files with 138 additions and 0 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,138 @@
+# 架构文档 - 多平台 Runner 构建方案
+
+## 概述
+
+本项目使用 Gitea Actions 实现 CI/CD，通过在不同操作系统上运行 runner 来构建对应平台的二进制文件。
+
+## 平台与 Runner 对应关系
+
+| 平台 | Runner 名称 | 构建目标 | 状态 |
+|------|-----------|---------|------|
+| NAS (Linux) | ubuntu24.04 | linux-amd64, linux-arm64 | ✅ 已配置 |
+| macOS | macos | darwin-amd64, darwin-arm64 | ⏳ 待配置 |
+| Windows | windows | windows-amd64 | ⏳ 待配置 |
+
+## Gitea Runner 安装
+
+### macOS (Apple Silicon / Intel)
+
+```bash
+# 安装 act_runner
+curl -sL https://gitea.com/trossr32/gitea-act/releases/download/v0.2.47/gitea-act_Darwin_arm64 -o /usr/local/bin/act
+chmod +x /usr/local/bin/act
+
+# 或 Intel 版本
+curl -sL https://gitea.com/trossr32/gitea-act/releases/download/v0.2.47/gitea-act_Darwin_x86_64 -o /usr/local/bin/act
+chmod +x /usr/local/bin/act
+
+# 注册 runner（在 Gitea 仓库获取 token 后执行）
+act runner register \
+  --url https://hub.gaomia.site \
+  --token <RUNNER_TOKEN> \
+  --name macos-runner \
+  --labels macos
+
+# 启动 runner
+act runner start --name macos-runner
+```
+
+### Windows
+
+```powershell
+# 下载 act_runner
+curl -sL https://gitea.com/trossr32/gitea-act/releases/download/v0.2.47/gitea-act_Windows_x86_64.exe -o act.exe
+
+# 注册 runner
+.\act.exe runner register --url "https://hub.gaomia.site" --token "<RUNNER_TOKEN>" --name windows-runner --labels windows
+
+# 启动 runner
+.\act.exe runner start --name windows-runner
+```
+
+### 获取 Runner Token
+
+1. 登录 Gitea
+2. 进入仓库 → Settings → Actions → Runners
+3. 点击 "Add Runner"
+4. 复制注册命令（含 token）
+
+## Workflow 配置
+
+### 当前支持的构建目标
+
+```yaml
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu24.04
+            target: linux-amd64
+          - os: ubuntu24.04
+            target: linux-arm64
+          - os: macos
+            target: darwin-amd64
+          - os: macos
+            target: darwin-arm64
+          - os: windows
+            target: windows-amd64
+```
+
+注意：Gitea Actions 的 `runs-on` 需要与注册的 runner labels 匹配。
+
+## 跨平台编译限制
+
+| 源平台 | 目标平台 | 是否支持 |
+|--------|---------|---------|
+| Linux (x86_64) | linux-amd64 | ✅ 原生支持 |
+| Linux (x86_64) | linux-arm64 | ✅ 交叉编译 |
+| Linux (x86_64) | darwin-amd64 | ❌ 需要 macOS |
+| Linux (x86_64) | darwin-arm64 | ❌ 需要 macOS |
+| Linux (x86_64) | windows-amd64 | ❌ 需要 Windows 或 MinGW |
+
+因此必须在对应平台上运行 runner 才能构建对应平台的二进制。
+
+## 依赖管理
+
+### Rust 交叉编译目标
+
+```bash
+# 安装所有需要的 target
+rustup target add aarch64-unknown-linux-gnu
+rustup target add x86_64-apple-darwin
+rustup target add aarch64-apple-darwin
+rustup target add x86_64-pc-windows-gnu
+```
+
+### cargo 镜像源
+
+构建时使用国内镜像加速：
+
+```toml
+# ~/.cargo/config.toml
+[source.crates-io]
+replace-with = "ustc"
+
+[source.ustc]
+registry = "sparse+https://mirrors.ustc.edu.cn/crates.io/index/"
+```
+
+## 故障排查
+
+### Runner 不在线
+- 检查 act_runner 进程是否运行
+- 查看日志：`act runner run --debug`
+
+### 构建失败
+- 检查对应 runner 是否注册并在线
+- 确认 labels 与 workflow 中的 `runs-on` 匹配
+
+### Token 过期
+- 重新生成 runner token
+- 更新注册命令
+
+## 相关文件
+
+- `.gitea/workflows/release.yml` - Gitea Actions workflow
+- `.github/workflows/release.yml` - GitHub Actions workflow（多平台）