ZeroTierAPI (Flutter)

基于 Flutter 的 ZeroTier 设备状态查看应用。支持桌面端与移动端打包。

当前策略

• 桌面端：Windows / macOS / Linux 可一键打包。
• 移动端：Android 支持直接产出 APK；iOS 支持产出未签名包用于后续自签。
• Web 仍可用，但 Web 模式通常需要本地代理处理 CORS。
• 内置双字体：Noto Sans（英文主字体，约 608KB）+ Droid Sans Fallback（中文兜底，约 3.9MB），避免中英文任一方块乱码。

前置要求

• Flutter SDK（建议 3.41+）
• Dart SDK（随 Flutter 提供）
• ZeroTier API Token

开发运行（桌面调试）

flutter pub get
flutter run -d linux

在 Windows / macOS 上分别使用 -d windows 或 -d macos。

一键打包（桌面）

Linux（在 Linux 机器上执行）

./scripts/package_desktop.sh

产物：dist/zerotierapi-linux-<arch>.tar.gz
解压后双击 zerotierapi 即可运行。

Windows（在 Windows 机器上执行）

scripts\package_desktop.bat

产物：dist\zerotierapi-windows-<arch>.zip（支持 x86 / x64 / arm / arm64）
解压后双击 zerotierapi.exe 即可运行。

macOS（在 macOS 机器上执行）

./scripts/package_desktop_macos.sh

产物：dist/zerotierapi-macos.zip
解压后双击 zerotierapi.app 即可运行。

GitHub Actions 自动打包（Win/macOS/Linux）

仓库已提供工作流：.github/workflows/desktop-build.yml

• 触发方式：
  • push 到 main
  • 手动触发（Actions -> Build Desktop Packages -> Run workflow）
• 构建平台：Windows / macOS / Linux
• 产物：在每次工作流运行的 Artifacts 中下载
  • zerotierapi-windows
  • zerotierapi-macos
  • zerotierapi-linux
• 自动发布：工作流成功后会自动创建 GitHub Release，并附带上述产物

GitHub Actions 自动打包（Android/iOS）

仓库已提供工作流：.github/workflows/mobile-build.yml

• 触发方式：
  • push 到 main
  • 手动触发（Actions -> Build Mobile Packages -> Run workflow）
• Android 产物：
  • Artifact 名称：zerotierapi-android-apk
  • 文件：build/app/outputs/flutter-apk/app-release.apk
• iOS 产物（未签名）：
  • Artifact 名称：zerotierapi-ios-unsigned-ipa
  • 文件：dist/zerotierapi-ios-unsigned.ipa

iOS 构建先用 flutter build ios --release --no-codesign 产出 Runner.app，再在 CI 中打包为未签名 .ipa，需你后续在本地进行自签后再安装运行。

Web 运行（可选）

推荐使用一键脚本：

./scripts/run_web_with_proxy.sh

行为说明：

• 默认启动 proxy（127.0.0.1:3000）+ Flutter web-server（127.0.0.1:8080）。
• 若 proxy 端口或 web 端口已被占用，会自动跳过对应服务，不会中断脚本。
• 默认使用 release 模式；可用 --debug 启动 debug 模式。

可选环境变量：

PROXY_PORT=3001 WEB_PORT=8081 ./scripts/run_web_with_proxy.sh

前端说明：

• Web 默认请求 http://<当前页面主机>:3000/api，因此在局域网用 IP 打开页面时也可正常访问代理。
• 如需自定义代理地址，可在启动时传入：--dart-define=ZT_PROXY_URL=http://127.0.0.1:3000/api。

配置

首次启动后，在配置页面填写 ZeroTier API Token 与 Network ID，应用会加密保存在本地并在下次启动自动回填。

macOS 桌面 Widget（在线 / 离线 / 全部）

已提供 WidgetKit 源码（目录：macos/ZeroTierWidgets），包含 3 个 widget：

• 在线设备
• 离线设备
• 全部设备

工程接入状态

Widget Extension target 已经直接接入工程（macos/Runner.xcodeproj/project.pbxproj），包含：

• ZeroTierWidgets target
• Embed App Extensions（Runner 自动内嵌 ZeroTierWidgets.appex）
• Widget 的 Info.plist / Entitlements / Build Settings
• Runner 与 Widget 共享 App Group：group.com.example.zerotierapi.widgets

你只需要在 macOS 打开 macos/Runner.xcworkspace 后确认签名（Signing）与 Team 配置即可。

数据更新机制

• App 每次刷新设备列表后，会通过原生通道同步设备快照到 UserDefaults(App Group)
• 同步成功后自动触发 WidgetCenter.reloadAllTimelines() 刷新桌面 widget

如果你修改了 PRODUCT_BUNDLE_IDENTIFIER，请同步更新 App Group 命名和相关常量。