3.5 KiB
3.5 KiB
架构文档 - 多平台 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)
# 安装 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
# 下载 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
- 登录 Gitea
- 进入仓库 → Settings → Actions → Runners
- 点击 "Add Runner"
- 复制注册命令（含 token）
Workflow 配置
当前支持的构建目标
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 交叉编译目标
# 安装所有需要的 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 镜像源
构建时使用国内镜像加速：
# ~/.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（多平台）