# 架构文档 - 多平台 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（多平台）