haibao-tts-cli/docs/architecture.md

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

1. 登录 Gitea
2. 进入仓库 → Settings → Actions → Runners
3. 点击 "Add Runner"
4. 复制注册命令（含 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（多平台）