把签名服务器搬进 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,这套构建流水线的分层边界一目了然:
- 锁定上游双基座:拉取固定提交哈希的
jkcoxson/jas(cf709e4a5fb298a20cb595e0d5f1f263e4c82bef)与nab138/isideload(065e852b2092f1386c88195ea3a6506f6b917742)。 - 注入 27 枚核心补丁:依次打入
20个jas-*.patch(负责 Wi-Fi 可达性轮询、HMAC 鉴权、Docker 凭证加密、tvOS 支持、App ID 清理与配额复用、IPA Inbox 监控、2FA 短信验证)和7个isideload-*.patch(负责既有证书复用、证书周期修复、tvOS 签名与 Top Shelf 共享容器校验)。 - Leptos SSR 同构引擎编译:在 Docker 模式下通过
cargo leptos build --release(基于 Rust1.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 与浏览器门户中。
[!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 分钟内就能立即捕获在线状态并无缝切入续签。
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 主屏幕快捷方式一键直达。
下面这张跨职能泳道图完整还原了这套双向伴侣接力链路:
1. 免手工配置:通过 devicectl 沙盒缓存安全注入 .p12 凭证
用过 LiveContainer 的玩家都知道,以前要把宿主机生成的签名证书导入容器非常繁琐。SideRelay 在 Interface/LiveContainerSigning.py 与 Compagnon/SideRelayView.swift 里设计了一套极度克制的 paired-v1 自动配对协议:
- 宿主机首先校验设备已配对且伴侣宿主证书尚未过期,随后向引擎请求
export_livecontainer_cert导出当前可复用的.p12证书、随机密码与序列号(MaxCertsBehavior::Error,绝不粗暴吊销已有证书)。 - 构造一个有效期仅
120秒的 JSON 载荷(SideRelaySigning.json),通过苹果官方工具xcrun devicectl device copy to --domain-type appDataContainer直接写入伴侣 App 沙盒内的Library/Caches/目录。 - 通过
devicectl device process launch携带深层链接livecontainer://siderelay-setup(或tvcontainer://siderelay-setup)唤醒伴侣端。 - 伴侣端
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()会检查 SQLitePRAGMA 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 在“日常好用”这件事上也藏了不少务实的工程设计:
- 自带防爆仓门禁的 IPA 工坊(
Interface/ArchiveIPA.py):
支持修改应用名称、Bundle ID、最低系统版本、开启文件共享(UIFileSharingEnabled)、移除设备型号限制(UISupportedDevices等 4 个键)、剥离.appex插件扩展、替换图标及注入动态库组件。针对第三方来路不明的 IPA,解压前强制校验单文件下载上限2 GiB、展开总大小上限8 GiB、最大条目100,000个、拒绝反斜杠及..路径穿越、以及大小写折叠后的文件名碰撞检测(专门防御 ZIP 炸弹与 macOS/Linux APFS/ext4 大小写差异导致的同名覆盖漏洞)。 - 双平台内置商店与 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小时一次,同时保证本地已缓存目录仍可正常浏览与下载。 - 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] 准备自部署或二次开发前的三个实操提醒
- Apple TV 无线管理前提:Docker 本身无法直接跑 Apple CoreDevice 协议栈。如果在 Linux 服务器运行 Docker,只有纯 iPhone / iPad 功能是原生开箱即用的;需要管理 Apple TV 或导出伴侣证书时,需在 macOS 上通过 OrbStack 配合
Interface/DecouverteOrbStack.py运行宿主机辅助进程。- Docker 端口安全边界:官方
compose.yaml默认只把门户绑定在127.0.0.1:18785,请勿直接把8080裸露在公网!远程管理请严格使用ssh -N -L 18785:127.0.0.1:18785 user@docker-host隧道或 Tailscale 内网访问。- 开源协议混用边界: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 个人测试与自用应用生命周期管理”工程化到最彻底的开源方案之一。
原文链接与参考资料
- GitHub 官方仓库:arkemys-consulting/SideRelay - Keep your iPhone and iPad apps signed while you're away
- Docker 部署与 OrbStack 指南:SideRelay on Docker (docs/DOCKER.md)
- Apple TV 与 TVContainer 伴侣指南:SideRelay on Apple TV (docs/APPLE-TV.md)
- 上游核心签名与设备协议组件:jkcoxson/jas · nab138/isideload · jkcoxson/idevice · jkcoxson/idevice_pair
- 上下游容器伴侣项目:LiveContainer/LiveContainer · hubzzzgr/TVContainer