专为 Yue.to 账号、AI 服务与流媒体场景打造的跨平台代理客户端

YueLink 是一个基于 Flutter + mihomo 构建的跨平台代理客户端，面向 Yue.to 账号体系做了完整集成：登录后可自动同步订阅、节点、套餐、订单、公告、签到和 Emby 媒体服务。

它既是一个日常可用的代理客户端，也是一个具备桌面增强能力的独立分发应用：支持 Android / iOS / macOS / Windows / Linux，支持 GitHub Release 自更新、桌面 TUN / Service Mode、模块运行时、启动诊断与一键修复。

• Yue.to 深度集成：账号登录、订阅同步、套餐购买、优惠券、订单历史、公告、签到、Emby 全链路接入。
• 多平台一致体验：Android / iOS 走系统 VPN 能力，桌面端默认系统代理，也支持切换 TUN。
• 独立分发优先：GitHub Releases 提供五端正式产物，应用内支持稳定版 / 预发布更新通道。
• 可开发、可扩展：Flutter UI + Go core 解耦，支持 mock mode、本地原生构建、CI 全平台发布。

• 基于 mihomo 内核，Flutter 通过 FFI 管理生命周期，通过 REST / WebSocket 获取代理、流量、日志和连接数据。
• Android 使用 VpnService + TUN (gVisor)。
• iOS 使用 NetworkExtension / PacketTunnel。
• 桌面端默认 systemProxy，可切换 TUN；必要时可安装 Service Mode 特权 helper。
• 路由模式支持 规则 / 全局 / 直连，全局模式下点击任意 group 节点会自动同步到 GLOBAL 出口；直连模式禁用所有 group 卡避免误点。

• Netflix 风格首页：Hero Banner + 横向海报行。
• 原生播放器：倍速、字幕大小、音轨切换、播放进度同步、续播提示。
• 兼容 STRM 搬运库和合集库。
• API、图片、视频、字幕都走代理链路。

YueLink 内置一套可用的 Surge 模块兼容层：.sgmodule 下载 / 解析 / 启用，规则注入到 mihomo YAML，MITM Engine 与 Root CA 生成，URL Rewrite 与 Header Rewrite，以及 http-response 响应脚本。定位是最小可用实现，不是完整 Surge Script 运行时，也不能绕过 Android 7+ 的用户 CA 信任限制和 Certificate Pinning。

详见：

• 模块能力清单
• 已知限制

• 设置页内置连接修复页面：重建 VPN、清理缓存、重同步订阅、一键修复。
• 启动失败会自动生成 startup_report.json，记录启动步骤、错误码、耗时、核心日志摘要。
• 桌面端支持托盘菜单、显示主窗口快捷键、连接模式切换、开机启动。

正式版与预发布版均通过 GitHub Releases 分发：

• Release 列表：https://github.com/onesyue/yuelink/releases
• 稳定版 tag：vX.Y.Z
• 预发布 tag：pre（覆盖式），或 vX.Y.Z-pre

每次发布附一份统一的 YueLink-<version>-SHA256SUMS 校验文件，可用 sha256sum -c YueLink-<version>-SHA256SUMS 一次性校验所有产物。

• Android：优先下载 android-universal.apk，只有明确知道设备架构时再选分 ABI 包。
• Windows：优先下载 setup.exe，需要绿色版时再用 portable.zip。
• macOS：统一下载 macos-universal.dmg，无需区分 Intel 和 Apple Silicon。
• iOS：当前为独立分发侧载包，不走 App Store 安装。详见下方安装说明。

1. 允许安装未知来源应用。
2. 安装 YueLink-<version>-android-universal.apk。
3. 首次启动时授予 VPN 权限；Android 13+ 还会请求通知权限（用于前台服务通知，建议授予）。

支持以下侧载方式：

• SideStore（推荐）：VPN 完全可用。从 GitHub Releases 下载 YueLink-<version>-ios.ipa，在 SideStore 里点 + 选 ipa 文件 → SideStore 自签 + 自装。每次发新版重新下载 ipa 导入即可。
• AltStore：VPN 完全可用，但需要电脑上跑 AltServer.app 配对（Mac 拖 ipa 给 AltStore）。
• TrollStore（巨魔）：安装永久不过期，但 VPN 几乎不工作 —— 系统会启动 PacketTunnel 进程后立刻丢弃，表现为「提示连接成功但实际无网络」。仅推荐在不需要代理的场景使用（例如只看 Emby）。

无论哪种方式，每 7 天自签会到期一次，到期前 SideStore / AltStore 会自动后台续签（前提是设备装过任一 SideStore extension 且能联网）。手动续签：重新进入 SideStore / AltStore 点击"Refresh"。

⚠️ iOS 巨魔用户重要提示 巨魔利用系统漏洞绕过签名校验，但 NetworkExtension 仍依赖 Apple 签发的 Provisioning Profile —— 巨魔安装的 IPA 拿不到这条信任链。若你需要代理上网，请改用 SideStore 或 AltStore 自签后重新安装。 App 检测到这个症状时（连接 3 秒内被系统中止）会自动弹出安装方式说明页。也可以在「设置 → 关于 → iOS 安装方式」主动查看。

1. 打开 YueLink-<version>-macos-universal.dmg
2. 将 YueLink.app 拖入 Applications
3. 若首次启动被 Gatekeeper 拦截：
   • 优先双击 DMG 内附带的 修复无法打开.command
   • 或手动执行 sudo xattr -cr /Applications/YueLink.app

• 安装版：运行 YueLink-<version>-windows-amd64-setup.exe
• 便携版：解压 YueLink-<version>-windows-amd64-portable.zip 后直接运行

chmod +x YueLink-<version>-linux-amd64.AppImage
./YueLink-<version>-linux-amd64.AppImage

• 移动端始终使用系统 VPN 能力，不提供系统代理模式切换。
• 桌面端默认连接模式为 systemProxy，适合大多数场景。
• 桌面 TUN 适合更完整的系统级接管需求；如需稳定的特权辅助，可安装 Service Mode。

YueLink 在独立分发版中内置自更新逻辑：

• 默认检查稳定版 update.json
• 可在设置中切换到预发布通道 update-pre.json
• manifest 支持多镜像拉取，适配 GitHub API 不稳定或受限网络环境
• 下载后会校验 SHA-256

iOS 用户每次发布新版本时，从 GitHub Releases 重新下载 .ipa 用 SideStore / AltStore 导入即可。

注意：

• 独立分发版：支持应用内检查更新和下载更新
• 商店模式构建：通过 --dart-define=STANDALONE=false 编译，自更新入口会被关闭

不需要 Go core，也能跑完整 UI：

git clone --recursive https://github.com/onesyue/yuelink.git
cd yuelink
flutter pub get
flutter run

当本地没有原生内核时，YueLink 会自动进入 mock mode，用模拟的代理组、节点、流量和连接数据驱动界面。

core/mihomo/ 是 git 子模块，首次克隆必须带 --recursive，或者在已有仓库中执行：

git submodule update --init --recursive

仓库 fork 自 MetaCubeX/mihomo（Meta 稳定通道），在主线之上叠加三个非破坏性补丁（非致命的 buildAndroidRules / 非致命的 MMDB+iptables 加载 / Shutdown 时清理监听器）。CI 与本地构建会自动应用同一份补丁集，应用是幂等的，重复执行不会失败。

git clone --recursive https://github.com/onesyue/yuelink.git
cd yuelink
flutter pub get

# 首次构建桌面端时启用对应平台
flutter config --enable-macos-desktop
flutter config --enable-windows-desktop
flutter config --enable-linux-desktop

# Android：构建全部 ABI
dart setup.dart build -p android
dart setup.dart install -p android
flutter build apk

# iOS：构建 arm64 静态库
dart setup.dart build -p ios
dart setup.dart install -p ios
flutter build ios

# Windows / Linux：建议显式指定 amd64
dart setup.dart build -p windows -a amd64
dart setup.dart install -p windows
flutter build windows

dart setup.dart build -p linux -a amd64
dart setup.dart install -p linux
flutter build linux

# macOS 见下方 universal 示例
flutter build macos

macOS 需要分别构建两个架构，再由 install 合并：

dart setup.dart build -p macos -a arm64
dart setup.dart build -p macos -a x86_64
dart setup.dart install -p macos
flutter build macos --release

仓库提供了一个 Linux AppImage 打包脚本：

bash scripts/build_linux.sh <version>

如需构建不带自更新能力的商店版本（自更新检查 + 应用内"检查更新"入口都会被禁用）：

flutter build appbundle --dart-define=STANDALONE=false

flutter analyze --no-fatal-infos --no-fatal-warnings
bash scripts/check_imports.sh    # 架构边界检查（modules 不能 import datasources）
flutter test

当前仓库共 109 个 Dart 测试文件，覆盖核心 lifecycle / FFI、mihomo REST 客户端、流断路 / 重连、Riverpod 状态机、XBoard 容错、PII 脱敏等。CI 全平台 build 之外，还会跑 architecture import guard。

CI 只在推送 tag 或手动 workflow_dispatch 时触发：

• pre：构建全平台预发布，覆盖上一个 pre-release，并刷新 update-pre.json manifest
• vX.Y.Z：构建全平台正式版，创建 GitHub Release，并刷新 update.json manifest
• vX.Y.Z-pre 同样视为 pre-release（prerelease: true）

dev / master 分支的 push 不会触发 build.yml，仅触发 ci.yml（analyze + test + import guard）。

1. 所有代码先合入 dev，触发 ci.yml

2. 需要预发布时移动 pre tag：

   git tag -d pre && git push origin :refs/tags/pre
   git tag pre && git push origin pre

3. 正式版：dev → master 合入后再打 vX.Y.Z 并推送

4. CI 执行：应用 core/patches/*.patch → 构建 Go 核心 → dart setup.dart install → Flutter 打包 → 签名 / 归档 → 上传产物 → 创建 Release + manifest

发布矩阵覆盖 Android / iOS / macOS / Windows / Linux。产物由 CI 自动命名、统一汇总到一份 YueLink-<version>-SHA256SUMS、刷新 release notes 与 updater manifest。

GitHub Release body 取自 docs/releases/<tag>.md（稳定版）或 docs/releases/pre.md（fallback），保持版本说明三处同源（in-repo CHANGELOG / docs/releases / GitHub Release）。

使用 DMG 内附带的 修复无法打开.command，或执行：

sudo xattr -cr /Applications/YueLink.app

Android 的 VpnService 只能在主用户空间可靠工作。Samsung Secure Folder 等二级用户环境无法建立有效 TUN（establish() 始终返回 null）。

几乎只在 TrollStore 安装的包上发生。NetworkExtension 信任链依赖 Apple 签发的 Provisioning Profile，巨魔的签名绕过覆盖不了这一条 —— 改用 SideStore 或 AltStore 自签即可。App 检测到这个症状时会自动弹出安装方式说明页。

这是 Android 用户 CA 信任限制和证书固定带来的已知边界，不是 YueLink 单独能绕过的问题。详见 模块已知限制。

这是商店模式构建的预期行为。STANDALONE=false 时，自更新逻辑会被关闭，以满足商店分发约束。

MIT