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/](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 长这样：
```yaml
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 镜像**，差异只在于各平台的原生系统集成。
## 四、四步走完接入
1. **安装** —— 打开「安装」页 → 刷新版本列表 → 选择版本 → 安装；
2. **注册** ——「配置」页填 Gitea 实例 URL + 一次性 Token + Runner 名称 + Labels → 点击「注册 Runner 」；
3. **启动** —— 回到「状态」页点击「启动」，daemon 开始从 Gitea 拉取任务；
4. **看日志** ——「日志」页滚动展示 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/](https://grm.duguying.net/) 下载最新版本：
- **macOS**：DMG · 已公证 · 拖入 Applications 即可
- **Windows**：EXE 安装包 · 安装即可
> 小提示：Windows 版的迭代次数更多，版本号通常领先 macOS 版；两个版本互不依赖，按平台各取最新即可。
---
原文链接：[点击查看](https://www.v2ex.com/t/1230838)
**Gitea Runner Manager**（下称 GRM ）正是为了把这堆零碎操作压缩到「四步点击」而生的——它是一款同时提供 macOS 版（ SwiftUI 菜单栏应用）和 Windows 版（ WinUI 3 桌面应用）的图形化管理器，覆盖 `act_runner` 从下载安装、注册、守护进程启停到实时日志查看的全部生命周期。
> 官网：[https://grm.duguying.net/](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 长这样：
```yaml
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 镜像**，差异只在于各平台的原生系统集成。
## 四、四步走完接入
1. **安装** —— 打开「安装」页 → 刷新版本列表 → 选择版本 → 安装；
2. **注册** ——「配置」页填 Gitea 实例 URL + 一次性 Token + Runner 名称 + Labels → 点击「注册 Runner 」；
3. **启动** —— 回到「状态」页点击「启动」，daemon 开始从 Gitea 拉取任务；
4. **看日志** ——「日志」页滚动展示 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/](https://grm.duguying.net/) 下载最新版本：
- **macOS**：DMG · 已公证 · 拖入 Applications 即可
- **Windows**：EXE 安装包 · 安装即可
> 小提示：Windows 版的迭代次数更多，版本号通常领先 macOS 版；两个版本互不依赖，按平台各取最新即可。
---
原文链接：[点击查看](https://www.v2ex.com/t/1230838)
评论
暂无评论。