把签名服务器搬进 Docker 与 Tailscale:深潜 SideRelay 的 27 枚引擎补丁、双向伴侣与跨网续签架构

把签名服务器搬进 Docker 与 Tailscale:深潜 SideRelay 的 27 枚引擎补丁、双向伴侣与跨网续签架构

过去几年,iOS 与 Apple TV 的无越狱侧载工具基本被锁死在两套叙事里:要么在桌面端常驻一个仅限局域网的签名守护进程(如 AltServer),要么在 iPhone 本地搭一条环回 VPN 隧道勉强自签(如 SideStore)。最近我在 GitHub 上发现 arkemys-consulting 开源的 SideRelay(当前分析版本为 v1.28.10 / Build 68),它直接给出了第三条工程路径——把完整的苹果签名引擎塞进 Linux Docker 容器 与 macOS 原生外壳,再通过 Tailscale 网格隧道、双端伴侣容器(LiveContainer / TVContainer)与 OrbStack 宿主机中继,把“离家后的 7 天自动续签”做成了一套生产级分布式基础设施。

当我把整份仓库拉到本地逐模块通读后,真正让我惊讶的并不是它支持多少平台,而是其背后极其克制的架构拼装术:全库仅自研核心控制面与界面层约 26,850 行代码(Swift + Python + Rust + JS),却通过 27 枚精准的 Git 补丁(20 枚作用于 jas、7 枚作用于 isideload)将上游 Rust 签名引擎改造成了支持 5 分钟可达性嗅探、AES-256-GCM 凭证库隔离、Apple TV Top Shelf App Group 自动配对以及零越狱双向伴侣接力的全栈系统。这篇文章我将以源码审计的第一视角,彻底拆解 SideRelay 的每一处工程细节。

[!NOTE] 源码审计基线与版本范围说明
本文所有文件路径、端口定义、加密参数与逻辑拆解,均基于我在 2026 年 11 月 19 日对 https://github.com/arkemys-consulting/SideRelay(最新提交 2332bde,版本 1.28.10 / Build 68,GPL-3.0 协议)的本地完整仓库静态审计。


一、为什么不从零重写签名引擎?“27 枚补丁 + 双态门户”的工程账

很多人一看到支持 macOS、Linux Docker(amd64 / arm64)、iPhone 和 Apple TV 的全平台侧载工具,第一反应是“这得写多少套底层协议栈”。但翻开 SideRelay 的目录树后,我发现作者算了一笔非常清醒的工程账:苹果私有签名与设备通信协议(Anisette、Developer Session、Misagent、CoreDevice、Remote Pairing)全部由 Rust 社区成熟组件承接,SideRelay 只在最关键的接缝处做外科手术式补丁增强。

打开 moteur/construire.sh,这套构建流水线的分层边界一目了然:

  1. 锁定上游双基座:拉取固定提交哈希的 jkcoxson/jas(cf709e4a5fb298a20cb595e0d5f1f263e4c82bef)与 nab138/isideload(065e852b2092f1386c88195ea3a6506f6b917742)。
  2. 注入 27 枚核心补丁:依次打入 20 个 jas-*.patch(负责 Wi-Fi 可达性轮询、HMAC 鉴权、Docker 凭证加密、tvOS 支持、App ID 清理与配额复用、IPA Inbox 监控、2FA 短信验证)和 7 个 isideload-*.patch(负责既有证书复用、证书周期修复、tvOS 签名与 Top Shelf 共享容器校验)。
  3. Leptos SSR 同构引擎编译:在 Docker 模式下通过 cargo leptos build --release(基于 Rust 1.95-slim-bookworm 与 cargo-leptos v0.3.11)编译出 SSR 服务端二进制 moteur/jas 以及前端 WASM 资源(jas.wasm、jas.js、jas.css),常驻监听 127.0.0.1:18784。

在这个核心引擎之上,SideRelay 并未把业务 UI 硬编码进 Leptos Rust 模板里,而是采用了一种极其巧妙的“DOM 注水后动态接管”架构:无论是 macOS 端的 Swift 原生外壳(Interface/Runtime.swift),还是 Linux 端的 Python 反向代理门户(Interface/PortailDocker.py),都在引擎原生的 SSR 页面完成 mod.hydrate() 之后,异步动态加载 9 个共享前端 ES 模块(Web.js、Guide.js、IPA.js、Jumelage.js、Comptes.js、LotsIPA.js、Store.js、Bibliotheque.js、Outils.js),将同一套交互界面无缝复用到桌面 WebKit 与浏览器门户中。

SideRelay 混合控制平面与跨网签名拓扑

[!IMPORTANT] 本地控制面与引擎之间的 HMAC 边界隔离
在阅读 Interface/EngineAccess.py、Interface/Runtime.swift 与 moteur/jas-engine-access.patch 时,我注意到一个容易被忽略的安全细节:即便 moteur/jas 仅仅绑定在 127.0.0.1:18784,SideRelay 依然不允许本地任意进程直接调用引擎 API。Swift 端与 Python 端都会以 0600 权限密钥文件中的 64 位十六进制密钥作为 HMAC-SHA256 秘钥,对固定消息 "SideRelay local engine v1" 计算签名,并放入 X-SideRelay-Engine 请求头;Rust 引擎侧则引入 subtle 库进行常量时间比对,彻底堵死同机非授权进程的越权调用。


二、5 分钟可达性嗅探与 7 天自愈飞轮:为什么异地续签必须靠 Wi-Fi + Tailscale?

传统侧载工具“自动续签经常失灵”的真正元凶,其实在于调度策略与网络前提的错配:如果定时任务每 12 小时才轮询一次,恰好当时手机不在家或处于锁屏休眠,一次失败退避就会白白浪费半天窗口;而如果直接高频盲目向 Apple 服务器发起续签请求,又会在设备离线时刷爆日志并触发风控。

我在 moteur/jas-renouvellement.patch、moteur/jas-renouvellement-wifi.patch 与 signature-ios 中,看到了 SideRelay 对调度器做的精细拆分:

1. 双频调度与 PAIRING_UNREACHABLE 故障去重折算

在 signature-ios 生成的 jas.toml 运行配置中,SideRelay 将原本单一的周期拆为两条独立时间线:

  • 可达性嗅探周期:reachability_interval_minutes = 5(每 5 分钟探测一次);
  • 常规错误退避周期:interval_hours = 2(遇到 Apple 接口报错等非网络可达性问题时,冷却 2 小时重试);
  • 续签窗口期:refresh_window_days = 3(提前 3 天触发续签)。

关键在于 moteur/jas-renouvellement-wifi.patch 修改了数据库查询 apps_needing_refresh 与记录函数 record_unreachable_refresh:当调度器在预检阶段(pairing-preflight)发现设备无法连上 Apple Remote Pairing 端口时,它会写入一条带 [pairing-unreachable] 前缀的失败记录,但在同一 retry_secs 窗口内自动去重合并历史任务记录(避免数据库膨胀),同时绝不阻塞下一次 5 分钟轮询的再探测!一旦用户带着 iPhone 回到可用 Wi-Fi 环境,最快 5 分钟内就能立即捕获在线状态并无缝切入续签。

SideRelay 7 天签名自愈飞轮与 5 分钟可达性嗅探

2. RPPairing 协议预检与“纯蜂窝网络”盲区实证

SideRelay 是如何在不唤醒完整 idevice 隧道的情况下验证 iPhone 是否可达的?signature-ios 中的 diagnostic() 函数给出了最直观的协议层实现:直接向目标设备在 Tailscale 分配的 100.64.0.0/10 IPv4 地址的 TCP 49152 端口发送苹果 RPPairing 握手报文(b"RPPairing" + 2 字节大端长度 + {"originatedBy":"host","sequenceNumber":0,"message":{"plain":{"_0":{"request":{"_0":{"handshake":{"_0":{"hostOptions":{"attemptPairVerify":true},"wireProtocolVersion":19}}}}}}}}),并校验回包结构与本地出站网卡是否确实经过 Tailscale 虚拟接口。

[!WARNING] 为什么纯蜂窝数据 + Tailscale 无法触发远程续签?
很多读者会误以为“只要 iPhone 开着 5G 和 Tailscale,Docker 就能随时给手机续签”。但 SideRelay 官方文档与实测明确指出了苹果底层的限制:iOS 仅在连接至 Wi-Fi 网络时才会在 49152 端口暴露 Apple Remote Pairing 服务;在纯蜂窝移动网络下,即便 Tailscale 网格直通,该系统级配对守护进程也不会响应远程握手。因此异地续签的真实条件是:宿主机与 iPhone 同处一个 Tailnet,且 iPhone 处于任一外部 Wi-Fi(如公司、酒店、咖啡馆 Wi-Fi)下。

3. 5 天最小有效期强门禁与旧版描述文件防御

在 moteur/jas-renouvellement.patch 中,我还发现了一个非常务实的防坑逻辑:无论是在首次安装签名的 validate_signed_profile,还是在无线续签 refresh_provisioning_profile 拿到 Apple 返回的新描述文件之后,Rust 引擎都会调用 apple-codesign-quick 解析 embedded.mobileprovision 中的 ExpirationDate,并强制断言:

// 要求剩余有效期必须 >= 5 天,否则直接拒收并报错
remaining >= std::time::Duration::from_secs(5 * 24 * 60 * 60)

这直接防止了 Apple 开发者接口偶尔返回缓存旧描述文件、导致“表面显示续签成功,实际两天后依然闪退”的幽灵故障;同时引擎把精确的 profile_expires_at 时间戳落盘到 SQLite 的 apps 表中,替代了上游粗暴的 installed_at + 7天 估算逻辑。


三、零越狱双向伴侣接力:LiveContainer(iPhone)与 TVContainer(Apple TV)

免费个人开发者账号(Personal Team)最大的枷锁在于“最多 3 个激活应用 + 7 天有效期”。SideRelay 并没有停留在传统的逐个应用侧载上,而是直接在 Compagnon/ 目录下内置了对 LiveContainer(iPhone/iPad 应用容器,AGPL-3.0)与 TVContainer(Apple TV 移植版,AGPL-3.0)的深度集成——而且做到了免手动导出证书、5 分钟限时二维码直传、以及 Safari 主屏幕快捷方式一键直达。

下面这张跨职能泳道图完整还原了这套双向伴侣接力链路:

SideRelay 伴侣应用证书配对与 Guest IPA 双向接力泳道

1. 免手工配置:通过 devicectl 沙盒缓存安全注入 .p12 凭证

用过 LiveContainer 的玩家都知道,以前要把宿主机生成的签名证书导入容器非常繁琐。SideRelay 在 Interface/LiveContainerSigning.py 与 Compagnon/SideRelayView.swift 里设计了一套极度克制的 paired-v1 自动配对协议:

  1. 宿主机首先校验设备已配对且伴侣宿主证书尚未过期,随后向引擎请求 export_livecontainer_cert 导出当前可复用的 .p12 证书、随机密码与序列号(MaxCertsBehavior::Error,绝不粗暴吊销已有证书)。
  2. 构造一个有效期仅 120 秒的 JSON 载荷(SideRelaySigning.json),通过苹果官方工具 xcrun devicectl device copy to --domain-type appDataContainer 直接写入伴侣 App 沙盒内的 Library/Caches/ 目录。
  3. 通过 devicectl device process launch 携带深层链接 livecontainer://siderelay-setup(或 tvcontainer://siderelay-setup)唤醒伴侣端。
  4. 伴侣端 SideRelaySigning.finalizeSetup() 读取后,严格比对 Info.plist 中的 SideRelayConnection.revision、TeamIdentifier 与 SecCertificateCopySerialNumberData 序列号,确认无误才写入 App Group,并在缓存目录写回 SideRelaySigningReady.json 回执(开启 .completeFileProtectionUntilFirstUserAuthentication 文件保护)。宿主机轮询到回执后即宣告就绪。

2. 300 秒一次性 Tailscale Serve 传输与双因子来源校验

当你在 Mac 端或 Docker 门户点击 Import into LiveContainer 时,SideRelay 不会让 IPA 走公网图床,而是在 Interface/TransfertCompagnon.py(Docker)或 Interface/ImportLiveContainer.py(macOS)中动态生成一段 32 字节 URL-Safe 随机令牌,有效期严格锁定为 300 秒(5 分钟),并利用 qrencode 生成二维码或通过 devicectl 直接唤起 livecontainer://install?url=...。

当手机访问该 https://<hostname>.ts.net:19445/...(macOS 临时导入通道使用 :19444)链接时,服务端 CompagnonService.py 会执行三重零信任校验:

  • HTTP 请求头 Tailscale-User-Login 必须与宿主机当前 Tailnet 拥有者完全一致;
  • X-Forwarded-For 中的来访 IP 必须精准匹配目标设备在 signature.db 中注册的 Tailscale IP;
  • 路径中的 43 位字符令牌通过 secrets.compare_digest 常量时间比对,同时响应头强制附加 Cache-Control: no-store、Referrer-Policy: no-referrer 与 Content-Security-Policy: default-src 'none'。

3. 主屏幕孤立快捷方式:Service Worker 离线自举的 Web Clip

在 LiveContainer 里装好应用后,如何像原生 App 一样从桌面直接启动?Interface/CompagnonEcranAccueil.py 与 Interface/CompagnonService.py 给出了一套非常聪明的“在线生成 .mobileconfig + 离线 Service Worker 自举”方案:

  • SideRelay 动态打包一份 com.apple.webClip.managed 描述文件(单次最多支持 256 个应用快捷方式,单个图标限定 400×400 尺寸以内 PNG),将每个图标指向托管在 Tailscale Serve 上的受保护启动页;
  • 用户将其添加到 iPhone 主屏幕后,启动页内的 LAUNCH_SCRIPT 与 WORKER_SCRIPT 会把 icon.png 和 launcher.js 缓存进浏览器的 Cache Storage。此后哪怕彻底断开 Tailscale、在纯离线飞行模式下,点击桌面图标也能直接通过 Service Worker 本地瞬时唤醒 livecontainer://livecontainer-launch?bundle-name=... 跳转到对应 Guest 应用!

4. Apple TV 专项突破:Top Shelf 共享容器与 App ID 节流复用

相比 iOS,tvOS 侧载在社区里一直是工程荒漠,主要卡在两件事上:一是免费账号 App ID 配额极易被扩展(Extension)耗尽;二是苹果要求 tvOS 主应用与其 Top Shelf 扩展(com.apple.tv-top-shelf)必须共享同一个 App Group,否则系统直接拒签。

我在 moteur/isideload-tvos-app-id-reuse.patch 和 moteur/isideload-tvos-top-shelf.patch 中看到了 SideRelay 的针对性解法:

  • Top Shelf App Group 自动链路:当检测到 Info.plist 开启了 TopShelfSharedContainer = true 且存在 .topshelf 扩展时,引擎自动调用开发者接口 ensure_app_group 创建 group.<main_app_id_str>,为两个 App ID 开启 Group Feature 并完成绑定,最后在下载描述文件后执行 validate_top_shelf_group 强校验,确保两边 com.apple.security.application-groups 完全一致。
  • App ID 满额复用机制:当旧版已安装应用不依赖 Top Shelf 扩展,或账号 App ID 配额耗尽时,SideRelay 支持传入 app_id_override 与 require_existing_app_id = true,直接复用尚未过期的既有主 App ID 完成签名更新,把原本的“死局”变成了一键升级。
  • TVContainer 控制反转:由于 Apple TV 没有文件管理器,SideRelay 支持通过 iPhone 伴侣端(Apps → Apple TV)或 Mac / Docker 门户直接把 tvOS IPA 通过 devicectl 推送至 TVContainer 的 Library/Caches/SideRelayImport-<uuid>.ipa,再通过 tvcontainer://siderelay-import/<uuid> 触发安装并轮询 result.json 回执。

四、把 Docker 容器武装到牙齿:密钥隔离、OrbStack 宿主机穿透与跨端加密备份

在很多开源项目里,“Docker 版”往往只是把桌面代码粗暴塞进容器里跑个 root。但审计完 Dockerfile、compose.yaml、Interface/SecuriteDocker.py 与 Interface/CoreDeviceDocker.py 后,我必须承认 SideRelay 的容器安全工程达到了相当少见的高水准。

1. 容器纵深加固与 AES-256-GCM 数据库双卷分离

先看 compose.yaml 与 Dockerfile 给出的默认运行约束:

  • 最小权限运行面:容器内以非特权 UID/GID 10001:10001 运行,开启 read_only: true 只读根文件系统、cap_drop: [ALL]、no-new-privileges: true 与 core: 0(禁用 core dump 防止内存密钥转储),仅挂载 /tmp 内存临时盘与两个持久化卷 siderelay_data、siderelay_secrets。
  • 双卷隔离与零残留迁移:Interface/SecuriteDocker.py 强制要求秘密目录(/var/lib/siderelay-secrets)权限严格为 0700、不得为符号链接且不得位于数据目录内部。启动时 migrate_apple_sessions() 会检查 SQLite PRAGMA user_version(目标版本 0x53520002):
    • 若发现历史明文记录,立即启用 PRAGMA secure_delete = ON;
    • 对 apple_accounts.apple_id 与 ipa_batches.account_name 使用 AES-256-GCM 加密,并用 HMAC-SHA256("SideRelay Apple Account lookup\0" + name) 派生盲索引前缀;
    • 重写 sideload_storage 中的所有会话与 Xcode Token 键值对为 enc: 密文格式,最后执行 VACUUM 与 PRAGMA wal_checkpoint(TRUNCATE) 彻底擦除旧页残余明文。
  • 内存零清与门户防爆破:在 moteur/jas-docker-credentials.patch 中,Rust 端引入 zeroize::Zeroizing 托管用户输入的 Apple 密码,登录完成即刻 drop 清零;Web 门户登录口则配备了 10次/60秒 滑动窗口限流、43 位 URL-Safe 访问密钥、HttpOnly; SameSite=Strict 会话 Cookie(12 小时过期 / 最多 64 个活跃会话),以及严格校验 Host(仅限环回地址)、Origin 与 Sec-Fetch-Site 的 CSRF 防护。

2. OrbStack 宿主机穿透:无卷共享下的 CoreDevice 与代码验签中继

由于 Linux Docker 容器内部无法直接运行 macOS 专属的 xcrun devicectl(Apple TV 无线管理依赖)与 /usr/bin/codesign(深度签名验证),SideRelay 设计了一套极其干净的 host.docker.internal:18786 Bearer 令牌中继架构(Interface/DecouverteOrbStack.py、Interface/CoreDeviceDocker.py、Interface/SignatureOrbStack.py):

  • 流式定长二进制封装:当需要在 OrbStack 容器内使用 Mac 验签或导入 .p12 证书签名时,SignatureOrbStack.py 构造自定义 MIME 类型 application/x-siderelay-signing(4 字节长度头 + JSON 清单 + 流式文件体),直接通过环回网络流式发送给 Mac 宿主机辅助进程;宿主机在临时私密目录建临时钥匙串完成操作后立即销毁,全程不共享任何宿主机数据卷。
  • 受限白名单 tar 管道:对于 Apple TV 安装,CoreDeviceDocker.py 会先严格校验 xcrun devicectl 参数模板(仅允许预定义的超时档位 8 / 12 / 30 / 300 与固定指令形态),将 .app 打包为流式 x-tar 推送至 Mac 辅助进程;Mac 端 receive_app() 强制限制包体上限 1 GiB、文件条目上限 50,000 个,拒绝一切路径穿越与符号链接条目,检验 CFBundleSupportedPlatforms 包含 AppleTVOS 且存在 embedded.mobileprovision 后才交付 devicectl install app。

3. 跨平台分块 AEAD 加密备份格式(SideRelayBackup1)

为了方便用户在 macOS 原生版与 Linux Docker 版之间无损迁移 IPA 仓库、商店源与自动续签偏好,Interface/BackupCrypto.py(对应 macOS 端的 Interface/PortableBackup.swift)定义了一套简洁可靠的流式分帧加密格式:

字段 / 参数 规范与取值 安全设计意图
魔数头(Header) b"SideRelayBackup1" + 16 字节随机 Salt 识别文件格式并隔离不同备份的密钥派生
密钥派生(KDF) PBKDF2-HMAC-SHA256(600,000 次迭代,dklen=32) 抵抗离线字典爆破,兼顾跨语言(Swift CryptoKit / Python Cryptography)互通
分帧加密(AEAD) 每 4 MiB 一帧,AES-256-GCM(12 字节随机 Nonce + 密文) 避免大体积 IPA 库(数 GB)导出/导入时爆内存
关联数据(AAD)与防截断 AAD = header + struct.pack(">Q", frame_index);末尾写入空块帧 防止攻击者调换帧顺序、重放或截断尾部数据;明确剥离 Apple 会话密钥与配对文件

五、IPA 工坊、商店生态与源码中的细节克制

除了核心的签名与网络调度,SideRelay 在“日常好用”这件事上也藏了不少务实的工程设计:

  1. 自带防爆仓门禁的 IPA 工坊(Interface/ArchiveIPA.py):
    支持修改应用名称、Bundle ID、最低系统版本、开启文件共享(UIFileSharingEnabled)、移除设备型号限制(UISupportedDevices 等 4 个键)、剥离 .appex 插件扩展、替换图标及注入动态库组件。针对第三方来路不明的 IPA,解压前强制校验单文件下载上限 2 GiB、展开总大小上限 8 GiB、最大条目 100,000 个、拒绝反斜杠及 .. 路径穿越、以及大小写折叠后的文件名碰撞检测(专门防御 ZIP 炸弹与 macOS/Linux APFS/ext4 大小写差异导致的同名覆盖漏洞)。
  2. 双平台内置商店与 GitHub 限流降级(Interface/Store2026.json / StoreTV.json):
    截至 v1.28.10,仓库内置的 2026 精选 iOS 目录共收录 236 款应用,Apple TV 目录收录 56 款 tvOS 应用,并在 StoreSources.json 中分类预置了 64 个出版商与社区源。自 v1.28.8 起,一旦检测到 GitHub API 触发速率限制,SideRelay 会自动暂停 GitHub 源抓取并展示恢复时间,将自动检查拉长到每 4 小时一次,同时保证本地已缓存目录仍可正常浏览与下载。
  3. Rust 原生跨平台配对工具(Interface/Jumelage/src/main.rs):
    只有短短 140 行 Rust 代码,却同时打通了三种配对路径:usb-simple(直接连接新版 RemotePairingLockdownService)、usb(降级走 CoreDeviceProxy -> 软件隧道 -> RsdHandshake -> com.apple.internal.dt.coredevice.untrusted.tunnelservice 双阶段授权)以及 wifi(通过 mdns-sd 广播 PAIRABLE_HOST_SERVICE_TYPE 服务并用 PairableHost 打印 6 位无线配对码)。

[!TIP] 准备自部署或二次开发前的三个实操提醒

  1. Apple TV 无线管理前提:Docker 本身无法直接跑 Apple CoreDevice 协议栈。如果在 Linux 服务器运行 Docker,只有纯 iPhone / iPad 功能是原生开箱即用的;需要管理 Apple TV 或导出伴侣证书时,需在 macOS 上通过 OrbStack 配合 Interface/DecouverteOrbStack.py 运行宿主机辅助进程。
  2. Docker 端口安全边界:官方 compose.yaml 默认只把门户绑定在 127.0.0.1:18785,请勿直接把 8080 裸露在公网!远程管理请严格使用 ssh -N -L 18785:127.0.0.1:18785 user@docker-host 隧道或 Tailscale 内网访问。
  3. 开源协议混用边界:SideRelay 自研代码采用 GPL-3.0,iPhone/tvOS 伴侣基于 AGPL-3.0 的 LiveContainer/TVContainer,isideload 为 MIT,而核心底层库 jkcoxson/jas 的作者在许可证中明确要求商业用途需取得书面授权,企业内部或二次打包前务必核清授权边界。

六、总结:从“个人脚本”到“基础设施级侧载”的演进样本

审视完 arkemys-consulting/SideRelay 的全部 27 枚引擎补丁与双模控制面代码后,我认为它最大的参考价值在于架构克制:它没有重复发明轮子去手写一遍苹果私有无线协议,而是以 jas 和 isideload 为内核,用 Swift、Python 与少数关键 Rust 胶水代码补齐了侧载工作流里最缺失的四块拼图——可远控的 Docker 容器安全隔离、基于 5 分钟可达性嗅探的跨 Wi-Fi 自愈调度、零配置沙盒注入的双向伴侣接力、以及对 Apple TV Top Shelf 生态的完整支持。

对于已经拥有 NAS/Linux 服务器与 Tailscale 组网习惯的开发者来说,SideRelay 几乎是目前把“iOS / tvOS 个人测试与自用应用生命周期管理”工程化到最彻底的开源方案之一。


原文链接与参考资料