Gitea Runner Manager：把 act_runner 装进原生图形界面

自托管 CI 一直是件麻烦事：装一条 Runner 要找二进制、手写 config.yaml、拼凑注册 Token 、想个办法让它常驻后台、还要再去翻日志排查任务失败。act_runner 的命令行虽然称职，但全靠文档和记忆堆出来的体验，对只想跑构建的个人开发者并不友好。

Gitea Runner Manager（下称 GRM ）正是为了把这堆零碎操作压缩到「四步点击」而生的——它是一款同时提供 macOS 版（ SwiftUI 菜单栏应用）和 Windows 版（ WinUI 3 桌面应用）的图形化管理器，覆盖 act_runner 从下载安装、注册、守护进程启停到实时日志查看的全部生命周期。

官网：https://grm.duguying.net

一、为什么需要它

Gitea Actions 是目前最易自托管的 CI 方案之一，但 act_runner 的注册流程历来有点「反人类」：

注册 Token 是一次性、立刻过期的，从 Gitea 控制台复制回来再粘贴进命令行这一步容易误操作；
注册成功后 Gitea 下发的 HASHED-TOKEN 长效令牌落在 .runner 里，普通用户很难知道它存在哪、能不能改；
Runner 想常驻得用 systemd / launchd / nssm 各写一套，跨平台时每台机器重抄一次；
任务失败后想看 daemon 输出，要么开终端 tail -f，要么钻进 journalctl。

GRM 把这些路径都收编到了 UI 里：Token 怎么传、HASHED-TOKEN 落在哪、daemon 怎么启停、日志在哪看——全部图形化。

二、核心特性

1. 一站式 Runner 生命周期

下载安装：从 Gitea 官方 API 拉取 act_runner 版本列表，Windows 版对下载的二进制做 SHA256 校验；
注册：从 Gitea 管理后台复制一次性注册 Token ，原样透传给 act_runner register，应用不做任何哈希或变换；
HASHED-TOKEN 只读展示：注册成功后，Gitea 下发的长效令牌自动保存到本地 .runner 文件，Dashboard 卡片上只读展示，应用不会再次发送或重新派生；
守护进程启停：以子进程方式运行 act_runner daemon，捕获 stdout/stderr ，启动/停止/重启一键完成；
升级 / 卸载：同一个「安装」页面，回到历史版本也很轻松。

2. 固定 Host 模式，专为原生构建

GRM 默认就是 Host 模式——任务直接在本机执行，不依赖 Docker 。这是它有别于一般 Runner 管理器的关键：

在 macOS 上可以直接跑 xcodebuild、调用代码签名钥匙串、构建 iOS 应用；
在 Windows 上可以预置 Git / dotnet / MSBuild 路径，跑原生工具链；
不需要维护一个 Docker 守护进程，资源占用更可控。

配套的 Dashboard Workflow 长这样：

jobs:
  build-macos:
    runs-on: macos   # macOS 版默认 label
    steps:
      - uses: actions/checkout@v4
      - run: xcodebuild -scheme MyApp build

3. 常驻与自动拉起

macOS：菜单栏图标（NSStatusItem），状态色块随 daemon 即时切换；
Windows：系统托盘图标（H.NotifyIcon.WinUI），主窗口关闭即隐藏到托盘；
两者都支持「开机自启」+「管理器启动后自动拉起 Runner」：
- macOS 走 SMAppService 登录项；
- Windows 写 HKCU\...\Run 注册表值。

4. 实时终端风格日志

「日志」页用深色终端风格滚动展示 daemon 实时输出，排查任务失败不用再开终端 tail -f。

三、平台一图对比

维度	macOS 版	Windows 版
UI 框架	SwiftUI	WinUI 3 （.NET 8 ）
常驻形态	`NSStatusItem` 菜单栏	`H.NotifyIcon.WinUI` 托盘
登录自启	`SMAppService`	`HKCU\...\Run`
结束 daemon	`kill -SIGTERM/SIGKILL`	`taskkill /F /T /PID`
Shell 集成	`zsh -i -l -c /usr/bin/env`	预置 Git / dotnet / MSBuild 路径
数据目录	`~/Library/Application Support/GiteaRunnerManager/`	`%LOCALAPPDATA%\GiteaRunnerManager\`

界面设计、注册流程、Host 模式配置和打包方式两个版本 1:1 镜像，差异只在于各平台的原生系统集成。

四、四步走完接入

安装 —— 打开「安装」页 → 刷新版本列表 → 选择版本 → 安装；
注册 ——「配置」页填 Gitea 实例 URL + 一次性 Token + Runner 名称 + Labels → 点击「注册 Runner 」；
启动 —— 回到「状态」页点击「启动」，daemon 开始从 Gitea 拉取任务；
看日志 ——「日志」页滚动展示 daemon 输出，失败原因一眼可见。

整个过程不需要碰任何配置文件。

五、数据目录里有什么

应用不往系统其他位置写文件，所有运行时数据收敛在一个目录里，卸载时直接删掉就彻底清干净：

~/Library/Application Support/GiteaRunnerManager/   (macOS)
%LOCALAPPDATA%\GiteaRunnerManager\                    (Windows)
├── bin/act_runner(.exe)        # 下载安装的 Runner 二进制
├── config.yaml                 # act_runner 配置，自动应用 Host 模式补丁
├── .runner                     # 注册信息，含 Gitea 下发的 HASHED-TOKEN
├── config.json                 # 界面中填写的注册配置（明文 JSON ，仅 Windows ）
├── version.json                # 已安装版本记录
└── logs/act_runner.log         # daemon 日志

六、几个值得展开的小细节

关于 Token 的安全姿态

一次性注册 Token：原样透传给 act_runner register --token <verbatim>，无任何哈希或变换——这避免了「加盐后再解」的歧义，也避免实现层引入安全漏洞；
HASHED-TOKEN：注册成功后 Gitea 下发的长效令牌由 act_runner 自身保存到 .runner，GRM 把它只读展示在 Dashboard 「认证信息」卡片上，不会再次发送或重新派生；
整个应用既不联网收集配置，也不上传任何 Token 到第三方。

Windows 版的 PowerShell 7 依赖

act_runner 在 Windows 的 Host 模式下默认用 pwsh 执行 workflow 步骤，缺失时会报 Cannot find: pwsh in PATH。安装器会检测并在需要时通过 winget 自动安装 PowerShell 7 ；若系统没有 winget，则需要手动安装。

macOS 版为什么不上 Mac App Store

应用需要下载并执行 act_runner 二进制并管理子进程，与 App Store 的沙盒要求不兼容。因此采用 Developer ID 签名 + Apple 公证的 DMG 直装分发——这也是各类开发/CI 工具的通行做法。完整链路（ Xcode 工程 → fastlane mac dmg → Gitea Actions macOS Runner 上出 DMG → 公证 → 上传 Release ）已在仓库内配齐，开 vX.Y.Z tag 即触发。

单 Runner 设计

一个管理器对应一个 act_runner 实例，配置、注册信息和日志都绑定这一个实例。如果需要多实例，多启几个管理器即可——它们各自的数据目录互相隔离。

七、推荐给谁

个人开发者 / 小团队：想给 macOS 自建机或 Windows 工作机挂一个 Runner ，又不想折腾服务注册和 Token 流程；
iOS / macOS 原生项目：要在本机跑 xcodebuild、需要用到钥匙串签名的；
Windows 原生工具链项目：要在 CI 里跑 MSBuild 、dotnet 、Visual Studio 相关步骤的；
任何不想维护 Docker daemon 的场景：Host 模式更轻、更直接。

八、写在最后

GRM 不是要把 act_runner 包成另一个黑盒，而是把命令行时代那些容易出错、容易遗忘的细节固定成一个对开发者更友好的 UI 。它尊重平台的原生习惯（ macOS 菜单栏 / Windows 托盘），尊重 Token 的安全协议（不哈希、不外发），也尊重用户的卸载权（删一个目录即清空）。

如果你正在为 Gitea 自建一套 CI ，强烈推荐先装上 GRM——比起读一长串文档去手动串起 register、daemon、systemd / launchd / nssm，它能让你在十分钟内从零跑到第一条任务。

项目以 MIT 协议开源，欢迎提 Issue / PR ，也欢迎直接到 https://grm.duguying.net 下载最新版本：

macOS：DMG · 已公证 · 拖入 Applications 即可
Windows：EXE 安装包 · 安装即可

小提示：Windows 版的迭代次数更多，版本号通常领先 macOS 版；两个版本互不依赖，按平台各取最新即可。