138 lines
3.5 KiB
Markdown
138 lines
3.5 KiB
Markdown
# 架构文档 - 多平台 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（多平台） |