lijianfei.com

打开 iOS 生态里大多数“网盘直链解析”或“短视频去水印”工具，套路几乎如出一辙：前端套一个轻量壳子，把链接丢给远程后端服务器解析，顺便把用户 Cookie 或行为日志一并经过第三方中转；真遇到需要转封装 m3u8 / mkv、跑 BitTorrent 磁力或者做国密/椭圆曲线签名时，又往往引入臃肿的 FFmpeg、libtorrent 或 OpenSSL 二进制静态库。直到最近我拉取并通读了 mengangs/Cloudn（v1.4.2，AGPL-3.0）的全部源码后，才发现有人在移动端走了另一条极其硬核的纯原生路线。

统计整个仓库的代码规模后，我得到了一个相当震撼的数字：全工程 59,226 行纯 Swift 代码，在 CloudnKit/Package.swift 中没有任何外部第三方包依赖（dependencies 为空）。从支持 14+ 家国内外网盘与 WebDAV、近 50 个短视频与图集平台解析，到内置 JavaScriptCore 求解 YouTube 签名、隐身 WKWebView 并发竞速与 MSE blob: 流录制，再到纯 Swift 手写的 MPEG-TS / Matroska(MKV) 流式无损转封装、BitTorrent 协议栈、secp256k1 与 ISAAC64 密码学原语，所有解析与媒体处理全部在手机本地沙盒完成，没有一台 Cloudn 服务器。这篇文章，我将结合逐文件代码审计与本地 swift test 实测结果，完整拆解这座零依赖纯 Swift 引擎的工程底座。

[!NOTE] 源码审计与实测基线说明
本文所有符号名、字节偏移、常量阈值与并发状态机分析，均基于我对 mengangs/Cloudn 仓库 v1.4.2（commit 289586c）主干源码的逐行审查；文中的单元测试数据由我在本地 macOS 15（Apple Swift 6.1.2）环境下启动 CloudnKit/Tests/Server/test_server.py 并实际运行 swift test 验证得出。

一、零外部依赖的五层技术堆栈：如何把核心拆到 Linux 上跑通单测？

在深入单个算法之前，我最先注意到的是 Cloudn 克制而清晰的工程分层。很多 iOS 工具项目写到后期会把 UIKit、WKWebView 和业务逻辑拧成一团麻花，改一行代码必须在真机或模拟器上编译半天；而 Cloudn 把 59,226 行代码严格劈成了两大边界：纯基础库层的 CloudnKit（Swift Package） 与 iOS 17+ 宿主适配层的 Cloudn / CloudnShare / CloudnWidget。

我把这个堆栈由上至下梳理为五个层次：

• L5 SwiftUI 交互壳层与系统扩展（Cloudn/、CloudnShare/、CloudnWidget/）：主界面采用 iOS 18 起可展开成 iPad 侧栏的 TabView（tabViewStyle(.sidebarAdaptable)），支持链接拖放、剪贴板自动识别、cloudn://resolve?text= 快捷指令唤起，以及锁屏和灵动岛的实时活动进度展示。
• L4 端侧沙盒适配与系统服务编排（Cloudn/Services/）：包含系统钥匙串凭证库 AccountVault（支持同平台主账号 + .extra 多账号轮换）、URLSessionConfiguration.background 后台分片接管、HeadlessWebExtractor 隐身浏览器、网页媒体录制器 MSERecorder，以及苹果相册 LivePhoto 配对合成器。
• L3 核心并发调度与解析引擎（CloudnKit Core）：整套工程的中枢神经，涵盖 DownloadEngine 任务队列、RangeTransfer 弹性分片调度、ShareResolvers（14+ 网盘分享与“我的网盘”管理）、VideoParseService（近 50 个平台路由），以及纯 Swift 实现的 TorrentSwarm 磁力客户端。
• L2 无 FFmpeg 纯 Swift 转封装与 JS 挑战求解（TSRemuxer / MKVRemuxer / YouTubeSignature）：仅用 Foundation 的 FileHandle 流式读写，就把 MPEG-TS 和 MKV/WebM 无损重打包为相册和系统播放器原生支持的 MP4；同时借助 Apple 原生的 JavaScriptCore（在 Linux 下通过 #if canImport(JavaScriptCore) 条件降级）求解 YouTube 加密参数。
• L1 零依赖密码学与二进制协议原语（Support/ & Torrent/）：由于 Apple CryptoKit 只内置 NIST 曲线、不提供 secp256k1，且标准库没有 LZ4 块解压与 ISAAC64，作者干脆全部用纯 Swift 从头实现（或按开源协议精简移植），让整个 CloudnKit 脱离 UIKit 与 Security 框架即可在 Ubuntu swift:6.1-noble 容器里直接编译运行。

为了验证这套解耦架构的真实可用性，我在本地按 .github/workflows/ci.yml 的流程拉起了 CloudnKit/Tests/Server/test_server.py 模拟服务，并执行全量单元测试：

cd CloudnKit
python3 Tests/Server/test_server.py 18765 &
CLOUDN_TEST_SERVER=http://127.0.0.1:18765 swift test

实际运行输出显示：CloudnKitPackageTests.xctest 共执行 699 项测试用例（其中 25 项为 CLOUDN_LIVE 真实在线巡检用例而自动跳过），0 失败、0 异常，总耗时 109.795 秒。更妙的是，仓库的 .github/workflows/live.yml 还配了一条每天 UTC 01:37 触发的 macos-15 定时工作流，专门拿真实分享链接与海外短视频链接在线巡检解析器是否失效——这种“核心包跨平台单测 + 每日真链巡检”的工程自律，在个人开源工具项目里非常少见。

二、四路异构本地解析：竞速、JS 求解与 MSE 流拦截

面对“网页靠 JS 挑战反爬、YouTube 动态加密参数、有些网站只给 blob: 分段播放、网盘只给登录后直链”这四座大山，Cloudn 在本地沙盒内搭建了一套四路并行的异构解析管线。

1. 抖音解析的“双路并发竞速”与隐身 WKWebView 预热

抖音网页版存在 byted_acrawler JS 挑战，纯 HTTP 往往会被直接拦截；而早期的 iesdouyin 分享页有时一秒出结果，有时又会被风控挡掉。在早期版本中，Cloudn 先等隐身浏览器超时（最长 40 秒）失败后才去试分享页，体感极慢。在 v1.4.1 重构后的 DouyinParser.swift 中，作者直接设计了一个结构化并发竞速函数 DouyinParser.race：

• 通过 withThrowingTaskGroup 同时启动 webRoute（隐身 WKWebView）与 parseSSR（iesdouyin.com/share/... 抓取 window._ROUTER_DATA）；
• 只要任意一条通道率先返回非空的 medias，立即调用 group.cancelAll() 砍掉慢的那一条（同时把链接里的 playwm 替换为 play 获取无水印流）；
• 如果用户只是刚刚在输入框里粘贴了抖音、Facebook、小黑盒或快手主页链接，HeadlessWebExtractor.prewarm() 会立刻在后台拉起一个 .nonPersistent() 的空白 WKWebView 预先启动 WebContent 进程（30 秒后自动释放），省下后续点击解析时 0.5 到 1 秒的冷启动延迟。

在阅读 HeadlessWebExtractor.swift 时，我还注意到一个只有真机踩过坑才会写出的细节：隐身 WKWebView 必须真正挂载到当前 KeyWindow 的视图层级里（被套进一个 1x1 裁剪、alpha = 0.01、isUserInteractionEnabled = false 的宿主视图中），因为不在视图树里的 WKWebView 不会触发 requestAnimationFrame，会导致部分网页的初始化挑战脚本直接卡死；同时当使用 Windows 桌面 UA 时，会在 .atDocumentStart 注入 Object.defineProperty(navigator, 'platform', { get: function() { return 'Win32'; } })，防止站点检测出 UA 与 navigator.platform 不一致。

2. YouTube JavaScriptCore 本地 EJS 求解器

由于不走远程服务器，YouTube 播放地址里的 signatureCipher 加密签名 sig 与限速/防 403 的 n 参数必须完全在 iPhone 本地解开。YouTubeSignature.swift 借鉴了 yt-dlp 的 EJS 思路，将打包好的 meriyah（JS 语法解析器）和 astring（AST 生成器）内嵌在 1,796 行的 YouTubeSolverScripts.swift 中：

• 运行在专属串行队列 cloudn.youtube.jsc 上（避免同步 CPU 计算阻塞 Swift 协作线程池），复用同一个初始化好的 JSContext；
• 对每个新版本的播放器 base.js，用 meriyah 解析成 AST，剥离顶层副作用调用并定位包含 X.set("alr","yes") 的 URL 变换函数；
• 把预处理后的播放器缓存在 YouTubePlayerCache 中，同一播放器版本后续解析无需重复解析 AST，直接把挑战数组通过全局变量注入 JSContext 批量求解。

3. 网页嗅探双保险：PageMediaScanner 源码预扫与 MSERecorder

对于不在近 50 个适配列表里的任意网页，Cloudn 提供了内置浏览器嗅探。有意思的是它分了两层推进：

1. 首屏不等播放的源码扫描（PageMediaScanner.swift）：打开网页的同时发起一次普通请求，先对 HTML 源码做 \/、\u002F、\u0026 反转义，随后同时扫描 og:video / twitter:player:stream 等元标签、<video> / <audio> / <source> 标签、JSON-LD 的 contentUrl 以及脚本里裸露的 .m3u8 / .mp4 直链（同时过滤 image/ 类型的 <source>），让用户在视频还没点播放前就看到候选项。
2. 专治 blob: 加密分片的 MSE 录制器（MSERecorder.swift + MSESegments.swift）：很多视频网站只走 MediaSource（地址是 blob:https://...），根本抓不到完整直链。Cloudn 在网页注入钩子截获页面每次喂给 SourceBuffer.appendBuffer() 的二进制切片，按轨道写入独立的串行队列（总录制上限 2GB）。更精巧的是 MSESegments.swift 对初始化段的识别：
   • 对 fMP4，解析盒子大小直至确认出现 ftyp + moov；
   • 对 WebM，直接按变长 EBML ID 和 VINT 大小扫描到第一个 Cluster（0x1F43B675）之前的字节流；
   • 遇到网页中途切换清晰度追加了新的初始化段时，自动关闭当前 run 并另起一段，停止录制时每条轨道只保留字节数最长的那一段；而对某些每次切片前都重复塞入同一份初始化段的播放器，则直接剥除重复头；最后调用 AVFoundation 无损合流输出标准 MP4。

4. 网盘“临时转存—取链—即删”与隐私克制

针对百度网盘、迅雷、115（大文件）等禁止免登录直接拿下载地址的平台，Cloudn 采取了“借壳取链、用完即毁”的策略。以 BaiduResolver（Baidu.swift）为例：调用 locatedownload 之前必须先转存到用户自己的网盘临时目录（Cloudn临时转存），拿到带签名的明文直链后，通过 Task.detached 在 do/catch 的成功与失败分支上同时挂载清理逻辑——哪怕用户在取链瞬间取消了下载任务，Task.detached 也会脱离当前任务取消态把云端临时目录删除干净，绝不白白占用用户网盘空间。

[!IMPORTANT] 全应用唯一的一处第三方中转与最小化授权
通读 PRIVACY.md 与 QuarkKouling.swift 后我确认，全应用确实只有夸克 / UC 中文口令这一处会联系第三方服务器（名为“星海”的解析接口 starsea-api.qwq.pics）。因为这类纯中文口令只能由官方 App 还原，Cloudn 不仅在首次调用前强制弹窗征得同意、支持在设置里彻底关闭，而且请求体里死守 step=parse 底线——只发送不超过 120 字符的口令原文去换取 pwdId，绝对不索取 stoken、绝对不附带任何账号凭据；拿到 pwdId 拼出标准分享链接后，后续验证、列目录与取链全数回归本地直连。

三、混合下载引擎与无 FFmpeg 纯 Swift 无损转封装

拿到直链只是开始，在弱网、移动端切后台、多账号限速以及不兼容相册的流媒体封装面前，下载引擎才是真正见工程功力的地方。

1. 弹性分片窃取、2 秒慢连接看门狗与多账号轮换

在 RangeTransfer.swift 中，一个文件下载要经历以下精密的状态调度：

• 严谨的 Range: bytes=0-0 探测：只信任 HTTP 206 且 Content-Range 严格匹配 bytes 0-0/<总长> 的响应；凡是返回 text/html（防盗链或过期页）或像光鸭云盘那样无视 Range 直接吐 HTTP 200 的服务器，一律视为不可信，转而发起不带 Range 的常规探测获取真实总长，防止把 1 字节响应误判为文件总大小。
• 弹性工作窃取（Work-Stealing）：初始按最小分片 2MB 切分并发任务；当某个线程率先下完手头分片变成空闲连接时，ChunkScheduler.claim() 会去寻找当前剩余字节最多的活跃分片，只要剩余量大于等于 2 * minStealPiece（2MB），就当场对半劈开把后半段切走接手，彻底消灭“其他连接干等着一条慢连接磨尾巴”的长尾瓶颈；而被切短的旧连接在下一次写入时通过 self.progress.chunk(index).end 动态感知新终点，写满即抛出 ChunkScheduler.Reached() 优雅断开。
• 2 秒采样慢连接抢占：独立看门狗协程每 2 秒采样一次各连接速率。正常阶段跑满 15 秒且剩余 >= 128KB、或者收尾阶段（endgame，已有连接领不到活退出）跑满 3 秒且剩余 >= 16KB 时，只要单连接速度同时低于 12KB/s 绝对下限和“当前均速的一半”，立刻标记 stop = true 强制断开并换源重连（每分片最多抢占 3 次），已写入的字节无缝保留。
• 针对 YouTube 的 10MB 切片上限与多账号镜像源：RangeTransfer.requestCap(for:) 专门识别 googlevideo.com 域名，强制把单次 HTTP 拉取控制在 10MB 以内，规避 YouTube 对单次长连接拉流的限速；同时，当用户在某网盘登录了多个账号时，DownloadRequest.mirrors 会携带其余账号各自取到的直链，不同分片按 (index + attempt) % count 轮换节点请求，某条被拒立刻换下一条。
• 直链过期自动续命：百度、阿里、YouTube 等直链往往几十分钟就过期。一旦后台或前台返回 HTTP 403 / 404 / 410 / 412，AppModel.didFail 会自动触发一次 downloads.refreshLink(item) 重新解析新直链，随后 RangeTransfer.verifyPlan() 校验新旧文件总长一致后，直接从已有进度继续写入；只有总长对不上才重新规划，避免几 GB 文件从头白下。

2. 切后台交接：为什么坚决不用 URLSession 的 resumeData？

当用户锁屏或切出 App 时，DownloadEngine 切换到 backgroundMode，由 BackgroundTransfers.swift 把单文件任务剩余的未完成区间按 每段不超过 32MB 切成若干 BackgroundChunkJob 塞进系统级 URLSessionConfiguration.background 会话中继续跑（注意：因为后台下载需要重新构造 URLRequest，在 willPerformHTTPRedirection 里若发现 302 跳转跨了域名，会主动剥离 Authorization 头，防止 GitHub 私有附件重定向到对象存储时带 Token 被拒）。

我在源码注释里读到一段非常清醒的架构决策——为什么某段在后台失败时不用苹果自带的 downloadTask(withResumeData:) 断点续传，而是宁愿从该 32MB 段的起点重下（最多重试 2 次）？ 因为 Cloudn 的请求自带了精确的 Range 头，而系统 resumeData 内部如何改写自定义 Range 并没有官方行为保证，一旦拼接错位就会悄无声息地把整份大文件写坏。把段上限压到 32MB，既能在锁屏后一段一段安全写回主文件，又把单段重传的极端代价锁死在可控范围内。

3. 零 FFmpeg：手写 3,121 行纯 Swift TSRemuxer 与 MKVRemuxer

iOS 系统相册和“文件”App 原生播不了 HLS 拼接出来的 .ts，也不认识 .mkv。常规做法是静态链接庞大的 FFmpeg（动辄给 IPA 增重十几二十 MB），但 Cloudn 的全量未签名 IPA 只有 约 9 MB（v1.4.2 实测 9,034,290 字节），秘密全在于 TSRemuxer.swift（1,459 行）和 MKVRemuxer.swift（1,662 行）这两座纯 Swift 二进制解析引擎：

• TSRemuxer（MPEG-TS → MP4）：按 0x47 同步字流式读取 188 字节 TS 包，解析 PAT / PMT 并按 PID 重组 PES；通过 TSClock 处理 33 位 90kHz PTS/DTS 回绕（以整个转封装首个时间戳作锚点，保证独立音轨 TS 与视频 TS 跨回绕后依然严丝合缝）；提取视频 Annex-B 起始码切分 NAL，剥离 AUD 与冗余参数集后改写成 4 字节长度前缀样本并生成 avcC / hvcC；剥离音频 ADTS 头合成 2 字节 AudioSpecificConfig；若存在 B 帧导致首帧 PTS != DTS，通过 elst 编辑列表的 media_time 精确校准首帧跳过偏移。
• 4GB 大文件平滑升级头（MP4SampleSink）：顺序写出 ftyp（32 字节）→ free（8 字节占位）→ mdat（8 字节头，共 48 字节），样本边解析边带 1MB 缓冲直写磁盘，内存中只留样本表（多 GB 视频也不会爆 iPhone 内存）；若最终 mdat 超过 4GB，直接把开头的 free(8) + mdat(8) 原地改写成 16 字节的 64 位 largesize mdat 头，最后把 moov 写到文件尾部。
• MKVRemuxer（Matroska / WebM → MP4）：内置 1MB 滑动缓冲 EBMLStream，支持直播录制产生的未知大小 Segment/Cluster 与破损 Cluster 跳过恢复；支持 Xiph、固定大小与 EBML 三种 lacing 打包；如果遇到 ContentCompAlgo == 3（头部剥离压缩），自动把剥离的公共前缀补回每一帧前面；视频方面更是针对 MKV “只记 PTS、块顺序即 DTS”的特性，把全轨 PTS 排序并整体前移构造 DTS <= PTS 序列从而算出 ctts；甚至还能把内嵌的 S_TEXT/UTF8、WEBVTT 与带样式标签的 ASS/SSA 字幕顺手剥离清洗成标准 .srt 外挂字幕！

四、藏在角落里的硬核细节：BitTorrent、纯 Swift 密码学与实况照片

除了主链路之外，我在翻阅 Torrent/、Support/ 与 Share/Upload/ 目录时，还挖出了几块含金量极高的独立模块：

尤其值得一提的是 DownloadEngine.swift 对本地持久化异常的防御设计：每次写任务表 downloads.json 前都会留存一份 downloads.json.bak；启动读取时使用自定义的 LossyItem 逐条解码——绝不因为某一条 JSON 字段损坏而把用户几十个历史任务全盘清空；如果主文件彻底写坏，就把它保存为 downloads.damaged.json 供排查并立即从 .bak 恢复，同时避免把坏文件覆盖成下一次的备份。

五、架构权衡与实机边界：这套设计并非没有代价

在赞叹这 59,000 行纯 Swift 代码的高完成度之余，我也从源码注释与实际限制中看到了它为“零服务器 + 零外部依赖 + 免越狱沙盒”所付出的几项明确权衡：

1. 前台保活边界：虽然普通文件与多段 Range 任务可以无缝交接给系统 URLSession 后台会话（≤32MB 切片），但 m3u8 切片流合并转封装、BitTorrent PeerWire 组网以及网页 MSE 录制受限于 iOS 沙盒保活机制，依然要求 App 留在前台完成（切后台时 AppModel 会提前挂起对应任务，回到前台自动恢复）。
2. 格式覆盖的刻意取舍：TSRemuxer 与 MKVRemuxer 为了保持轻量和零转码，明确不接入软解编码器——遇到 MKV 封装里包含 VP9 或 AV1 等 iOS 原生 MP4 不兼容的视频编码时，会直接抛出明确报错而非静默输出无画面的音频文件；遇到有 DRM 版权加密的长视频平台（如优酷、爱奇艺、腾讯视频）以及直播流同样直接跳过。
3. 无独立中继意味着更直接的风控面对面：由于没有云端代理池做 IP 清洗，像 Instagram 这类对机房节点极其敏感的平台，若用户自身代理被返回 429 空白页，App 只能诚实提示“当前网络被站点拒绝”；好在 v1.4.2 刚修复了 sessionid 提取 ds_user_id 与实时合并 document.cookie 的登录拦截问题，并新增了原生 SideStore / AltStore 订阅源（altstore.json），把后续侧载更新的摩擦降到了最低。

把 mengangs/Cloudn 从 SwiftUI 界面一路读到底层字节流操作，我最深的感受是：好的工具软件之所以克制，往往是因为作者有能力把复杂度全部吞进本地代码里，而不是转嫁给云端服务器、用户隐私或一长串第三方库清单。 对正在学习 Swift 并发架构、流媒体容器格式解析、或者想摆脱重型 C/C++ 依赖链的 iOS 开发者而言，这份 59,000 行的代码库堪称一座极佳的实战标本。

原文链接与参考资料

• GitHub 官方开源仓库：mengangs/Cloudn
• Cloudn v1.4.2 发布说明与源码档案：Cloudn v1.4.2 Release Notes
• SideStore / AltStore 侧载软件源清单：altstore.json
• Cloudn 隐私声明与权限边界文档：PRIVACY.md
• 部分协议与下载器架构溯源参考：CYQawa/YunX · OpenListTeam/OpenList · yt-dlp/yt-dlp · SheltonZhu/115driver