From 5c5510ef0a012ec415602c7aaf8bfd7e34c3d371 Mon Sep 17 00:00:00 2001
From: titor <foolsecret@163.com>
Date: Fri, 24 Apr 2026 04:09:43 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=A4=9A=E5=B9=B3?=
 =?UTF-8?q?=E5=8F=B0=20Runner=20=E6=9E=B6=E6=9E=84=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 描述 Gitea 多平台 runner 配置方案
- 包含 macOS 和 Windows 安装脚本
- 说明跨平台编译限制
- 提供故障排查指南
---
 docs/architecture.md | 138 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 docs/architecture.md

diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..2f7f5ce
--- /dev/null
+++ 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（多平台）
\ No newline at end of file