SingTray

SingTray 是一个用 Swift 和 AppKit 原生开发的 macOS 状态栏 sing-box 管理器。

• 导入 sing-box JSON 配置
• 导入自定义 sing-box 内核
• 通过状态栏启动和停止 TUN 模式（免密，见下文）
• 启动前自动用 sing-box check 预校验配置，失败信息直接弹窗展示
• 开机自动启动 TUN / 登录时自动打开 SingTray
• 查看 sing-box 运行日志（设置窗口内实时预览尾部 64KB）
• 一键打开 WebUI（端口从配置 experimental.clash_api.external_controller 自动解析，默认 9090）

TUN 模式需要 root 权限。SingTray 内置一个以 root 常驻的权限助手守护进程 （SingTrayHelper，LaunchDaemon com.singtray.helper），首次点击「启动」或 「启用免密权限」时弹出一次管理员授权框完成安装，之后：

• 启动 / 停止 / 重启内核全部通过本地 Unix socket 与助手通信，不再需要输入任何密码；
• 不修改系统 sudoers，不依赖 sudo，避免被系统更新或安全软件重置；
• 助手托管 sing-box 进程：优雅停止（SIGTERM → 3 秒 → SIGKILL）、PID/日志统一管理；
• 开启「开机自动启动 TUN」后，助手在开机时自动拉起 sing-box，意外退出 3 秒后自动重启。

菜单中的「撤销免密权限」会卸载助手（同时停止内核），恢复为无权限状态。

安全说明：助手只接受白名单命令（start/stop/restart/status/set-autostart）， 内核与配置路径由 root 属主的 helper-config.plist 决定，客户端无法指定， 因此不会成为"任意命令以 root 执行"的通道。代价与常见个人工具一致： 本机任何进程都能通过该 socket 启停 sing-box。

make build

make run

开发运行（swift run）时，应用会在同级构建目录查找 SingTrayHelper， 需先用 swift build 构建两个产物。

make bundle
open .build/release/SingTray.app

打包时会自动生成并嵌入应用图标，并把 SingTrayHelper 放进 Contents/Helpers/ 供一次性授权安装使用。

生成可分发的 .zip 和 .dmg：

make dist VERSION=0.1.0

产物会输出到：

dist/

本项目默认使用 ad-hoc 签名，未做 Apple Developer ID 公证。用户从 GitHub 下载后，首次打开可能需要在「系统设置」里允许运行。

推送 tag 后会自动构建并发布：

git tag v0.1.0
git push origin v0.1.0

GitHub Actions 会上传：

• SingTray-0.1.0-macos-arm64.zip
• SingTray-0.1.0-macos-arm64.dmg

1. 打开 SingTray 后，点击菜单栏里的图标。
2. 选择「导入 JSON 配置...」，选择 sing-box 配置文件。
3. 选择「导入 sing-box 内核...」，选择本机 sing-box 可执行文件。
4. 选择「启动 TUN 模式」。首次启动会弹一次管理员授权框安装免密助手，之后启动/停止/重启均无需密码。

导入后的文件保存在：

~/Library/Application Support/SingTray/

日志文件为：

~/Library/Application Support/SingTray/sing-box.log

助手相关系统文件（安装免密后）：

/Library/PrivilegedHelperTools/com.singtray/singtray-helper
/Library/PrivilegedHelperTools/com.singtray/helper-config.plist
/Library/LaunchDaemons/com.singtray.helper.plist