HGhubX:Tauri 2 跨平台客户端如何解决 HLS 跨域与封面加密
我最近读了 zxsos/HGhubX 的源码,它是一个用 Tauri 2、Rust 和 React 构建的跨平台短剧客户端。这个项目的技术价值在于用自定义协议解决了浏览器 CORS 限制,用 Rust 后端处理 HLS 播放列表改写和 AES 封面解密,按 origin 隔离会话凭证避免泄露。许可证为 PolyForm Noncommercial 1.0.0,禁止商业用途。
项目不提供、不存储、不分发任何音视频内容,所有数据来自上游站点。
Tauri 自定义协议绕过跨域限制
跨平台视频客户端遇到的第一个问题是浏览器 CORS:video 标签无法直接加载第三方站点的 HLS 分片。HGhubX 注册了平台特定的自定义协议端点 /img、/hls、/seg,前端构造 LOCAL/hls?u= 地址,Tauri 在本地拦截这些请求,Rust 后端下载原始 m3u8,改写 EXT-X-KEY URI 和分片地址为 LOCAL/seg?u=,禁用 CONTENT-STEERING,播放器加载分片时再次触发下载。整个过程在本地完成,不受浏览器同源策略限制。

数据流是这样的:前端请求封面构造 LOCAL/img?u= 地址,Rust 的 load_image 下载密文,AES 解密后缓存返回。播放视频时 rewrite_playlist 改写 key 和分片地址为 LOCAL/seg?u=,禁用 CONTENT-STEERING,播放器加载分片时再次触发下载。前后端分离架构,前端 React 跑在 Tauri WebView 里,Rust 后端提供媒体代理与业务命令。
Linux 平台是个例外。WebKitGTK 的 GStreamer 播放器无法加载自定义 scheme,HGhubX 在 media.rs 中判断平台后改用 127.0.0.1:17650 的本地 HTTP 代理。macOS 的 AVFoundation 和 Windows 的 MediaFoundation 都支持自定义协议,只有 Linux 需要走 loopback HTTP。注释写「Linux 走 loopback HTTP,GStreamer 拿不到自定义 scheme」。
AES-128-CBC 封面解密与缓存策略
站点用 AES 加密封面图片防盗链,前端 img 标签拿到密文会显示裂图。load_image 函数先查缓存,未命中则下载字节流,通过文件头魔数判断是否明文图片,如果不是则用 AES-128-CBC 解密后去填充,最后缓存原图:
pub async fn load_image(url: &str) -> Result< (String, Arc< Vec< u8 >>), String> {
if let Some(hit) = IMG_CACHE.lock().unwrap().get(url).cloned() {
let kind = image_kind(&hit).unwrap_or("image/jpeg");
return Ok((kind.to_string(), hit));
}
let (_, bytes) = fetch_bytes(url).await?;
let plain = if image_kind(&bytes).is_some() {
bytes
} else {
let dec = aes_cbc_decrypt(&bytes).ok_or_else(|| "封面解密失败".to_string())?;
strip_padding(dec)
};
let kind = image_kind(&plain).unwrap_or("image/jpeg").to_string();
let arc = Arc::new(plain);
cache_put(&IMG_CACHE, url.to_string(), arc.clone(), IMG_CACHE_MAX);
Ok((kind, arc))
}
image_kind 通过文件头魔数判断是否已是 JPEG/PNG。Arc> 让缓存中的图片可以跨线程共享,避免每次滚动列表都重复解密同一张封面。封面缓存上限 240 项,播放列表 60 项,分片 36 项且总字节不超 4 MB,超出后按 FIFO 淘汰。缓存用 Mutex 实现,cache_put 函数检查容量上限。频繁切换剧集或快速滚动时,缓存命中率下降,会重复下载解密相同资源。
按 origin 隔离会话 token
不同数据源的登录凭证需要隔离避免泄露。HGhubX 把线路定义为数据源站点的完整 origin 地址,按 origin 键存储 token。切换线路时递增 generation 版本号,清空旧 token,严格模式下只有可信 origin 才发送 token。用户手动添加镜像地址后需确认可信,否则需要登录的接口返回 401。
线路切换版本号用于取消过期的探测结果。手动选线或探测开始时递增 generation,应用结果时检查版本号,不匹配则丢弃。自动探测并发检查主站与镜像可达性,全成功选延迟最低,全失败保持当前线路。启动或手动触发时调 line_auto 并发检查主站与镜像,测量 TCP 握手延迟,全成功选延迟最低,全失败保持当前。应用前检查 generation,不匹配则丢弃过期结果。
核心模块分五层:media 层处理封面 AES-128-CBC 解密、HLS 播放列表改写、分片代理,api 层提供业务命令路由、线路切换与探测、会话管理、版本检查,net 层封装 HTTP 客户端、系统代理读取、网络诊断、可信站点判断,lines 层管理固定线路清单、镜像抓取、可达性探测、自动选线逻辑,前端 API 层封装 Tauri 命令、链路异常重试、网络观察者通知、平台环境检测。
链路容错的只读重试策略
移动网络切换或代理抖动时,首页列表、搜索、播放列表请求会立即失败。HGhubX 在 src/api.ts 的 call 函数中判断命令名在 READ_ONLY 集合内,链路异常时等待 1.2 秒后重试一次:
if (networkish && READ_ONLY.has(cmd)) {
logLine(`[api] ${cmd} 链路异常,1.2s 后重试一次`);
tracePlayback("api.retry", { cmd, err: msg });
await new Promise((r) => setTimeout(r, 1200));
try {
const r = await once();
logLine(`[api] ${cmd} 重试成功`);
tracePlayback("api.retry_ok", { cmd });
notifyNet({ ok: true, cmd });
return r;
} catch (e2) {
const again = typeof e2 === "string" ? e2 : msg;
const againStatus = /^HTTP (d{3})b/.exec(again)?.[1];
logLine(`[api] ${cmd} 重试仍失败 → ${again}`);
tracePlayback("api.retry_failed", { cmd, err: again, status: againStatus ?? null });
throw new Error(failMessage(again, againStatus));
}
}
只读命令遇到网络异常时可以安全重试,不会产生副作用。1.2 秒延迟给网络恢复留缓冲。写操作(登录、收藏、历史记录)不进此分支,避免重复提交触发上游频控。所有日志行落盘到 debug.log,播放失败时调用 net_diag 命令,Rust 返回系统代理、DNS 解析、TCP 连通性快照。这是客户端容错的标准做法,读操作幂等可重试,写操作需保证恰好一次。
reqwest 系统代理配置陷阱
reqwest 关掉 default-features 会丢 system-proxy feature,导致 Windows 和 macOS 不读系统代理而直连。HGhubX 在 Cargo.toml 中显式启用 system-proxy,注释写明「关掉 default-features 会连带丢掉 system-proxy,客户端就不看系统代理而直连」。旧环境变量 HGHUB_PROXY 继续兼容。
v2.0 统一存储键和环境变量命名,从 hghub_* 改为 hghubx_*。首次启动扫描旧键逐个迁移,已有新数据优先不覆盖,写入成功后清理旧键,失败保留下次重试。v1.2.18 前吃瓜搜索永远为空,新版修复后增加栏目内就地搜索,type=post 返回 Post 类型而非 VideoCard,结构体字段不同需前端适配。
net 层提供 edge 和 fetch_bytes 函数,前者用于只读命令的自动容错。前端 API 层只读命令网络失败时等待 1.2 秒后重试一次,写操作绝不重试。api 层暴露 app_boot、line_set、line_auto 等 Tauri 命令给前端调用。
五大平台安装与诊断
从 Releases 下载对应平台安装包,Windows 为 .msi,macOS 为 .dmg,Linux 为 .AppImage 或 .deb,Android 为 .apk,iOS 为未签名 .ipa(需自行签名)。iOS ipa 需用 AltStore、Sideloadly 等工具签名安装。
首次启动会迁移旧版存储键,从 hghub_* 迁移到 hghubx_*,写入成功后清理旧键。播放失败时调用 net_diag 命令,诊断报告写入 debug.log。iOS 上用 @capacitor/clipboard 原生插件复制报告,避免 WebKit 的 NotAllowedError 安全限制。

HGhubX 适合个人学习跨平台客户端开发、Tauri 2 与 Rust WebView 集成、HLS 代理与 AES 解密实践。代码展示 reqwest 系统代理配置、GStreamer 自定义协议限制、链路容错重试、会话隔离等工程细节,Rust 和 TypeScript 类型安全,模块职责清晰。v1.1.0 起许可证改为 PolyForm Noncommercial 1.0.0,明确禁止商业用途、加入广告、付费解锁或出售。网上流传的带卡密或付费功能的改版是恶意变现。使用者需自行遵守当地版权法规。
项目地址:https://github.com/zxsos/HGhubX
本文 zblog模板 原创,转载保留链接!网址:https://www.wbaas.cn/fengrong/2522.html
1.本站遵循行业规范,任何转载的稿件都会明确标注作者和来源;2.本站的原创文章,请转载时务必注明文章作者和来源,不尊重原创的行为我们将追究责任;3.作者投稿可能会经我们编辑修改或补充。








