为 iTerm2 Buddy 自托管中继服务器，加速手机连接 Mac 终端速度
内容提要
iTerm2 Buddy 是 iTerm2 的 iPhone 应用，可远程连接 Mac 终端，但默认公共中继服务器速度很慢。作者用 AI 在群晖 NAS 上自托管开源中继服务器，通过 Docker Compose 部署，配置域名、TLS 证书和端口转发，并修改 Mac 端设置重新配对，连接速度大幅提升。
延伸解读
自托管中继的适用场景与前提
文章指出，自托管中继适合希望减少公共中继绕行、提升连接速度的用户。但需要具备公网IP、Linux服务器（如群晖NAS）权限、域名以及受信任的TLS证书。若没有公网IP或无法配置端口转发，则无法实现外部访问。此外，自建中继不会增加iTerm2 Buddy的新功能，仅改善连接路径。
部署中的关键配置与验证
部署时需注意RELAY_ORIGIN必须与Mac和手机实际连接的地址完全一致，包括协议、域名和端口。证书必须覆盖该域名且受iOS/macOS信任。验证时，根路径返回HTTP 400不一定是异常，但WebSocket升级应返回101。公网测试建议从外部网络进行，避免NAT回环影响。
配对与恢复的注意事项
修改Mac端设置后需完全退出iTerm2并重新配对，已有配对会记住原中继，因此必须建立新配对。若想恢复默认中继，需删除自定义键并重新配对。升级或备份时，注意配对数据库位于relay-data卷中，避免执行docker compose down -v导致数据丢失。
性能提升与限制
文章作者实测自托管后连接速度大幅提升，但实际效果因网络环境而异。自建中继仅优化连接路径，不改变客户端功能。此外，方案仅在x86_64群晖上验证，其他NAS架构可能需调整。官方源码和协议可能变化，复现时建议使用文中固定的版本。
Q&A
iTerm2 Buddy 默认使用公共中继服务器有什么问题？
默认使用 iTerm2 的公共中继服务器（relay1.iterm2.com 和 relay2.iterm2.com），速度很慢。例如通过 5G 连接时，从打开应用到打开终端至少需要 5 秒。
自托管 iTerm2 Buddy 中继服务器需要哪些前提条件？
需要公网 IP、一台 Linux 服务器（如群晖 NAS）的权限、一个域名（用于创建 TLS 证书），以及 Mac 上安装支持 Companion 的 iTerm2 和手机安装 iTerm2 Buddy。
自托管中继服务器的工作原理是什么？
Mac 和手机分别主动建立 WebSocket 连接，中继将两条连接接起来并转发加密数据，中继服务器看不到内容。连接时使用 Ed25519 签名验证配对身份，用 Apple App Attest 验证手机应用，配对记录保存在 SQLite 数据库中。
如何在群晖 NAS 上部署 iTerm2 Buddy 中继服务器？
使用 Docker Compose 部署。主要步骤包括：建立目录并下载官方源码、创建 Dockerfile 和 compose.yaml 等部署文件、准备 TLS 证书、配置 DNS 和端口转发、构建并启动容器。
自托管中继服务器后，Mac 端需要如何修改设置？
完全退出 iTerm2，在终端执行命令写入新的中继地址：defaults write com.googlecode.iterm2 CompanionRelayOrigin -string 'https://relay.example.com:18443'，并将 CompanionResolverURL 设为空。然后重新打开 iTerm2，在 Companion Device Settings 中生成新二维码，用 Buddy 扫描并重新配对。
自托管中继服务器后，连接速度能提升多少？
文章中的对比测试显示，自托管后从家中连回家中，速度提升非常明显，与使用公共中继相比“完全没有可比性”。但实际速度提升需在自己的网络环境下比较。
自托管中继服务器有哪些限制或注意事项？
该方案仅在 x86_64 群晖上验证过，其他 NAS 架构尚未验证；自建 Relay 不会增加新建 iTerm2 标签页等客户端功能；升级或备份时需注意配对数据库在 relay-data 卷中，不要执行 docker compose down -v 以免丢失数据。
