多端同步Multi-device Sync
Shellby 不自建账号、不强制上云。同步全部 opt-in：你可以一直只用本机；需要时再开 iCloud（Apple 设备之间）或第三方存储（跨 Android / Windows / Linux / 鸿蒙）。
两种方式，怎么选
| 方式 | 适合 | 入口 |
|---|---|---|
| iCloud 同步 | iPhone / iPad / Mac 之间，零配置 | 设置 ▸ 通用 ▸ iCloud 同步（Pro） |
| 第三方同步 | 跨生态，或自带 WebDAV / S3 账号 | 设置 ▸ 通用 ▸ 第三方同步（全平台） |
两条通道可以并存，但更推荐按场景二选一当主写路径，避免两边同时改同一批主机时互相覆盖。
A · iCloud 同步（Apple 设备）
登录同一 iCloud 账号的设备之间同步。打开开关后：
- 主机配置（含 CloudKit 容器）在重启 App 后生效；
- AI 配置（Provider、脱敏、步数、命令规则）可热同步，不必为这项单独重启；
- 需系统开启 iCloud 钥匙串，凭证才能跟到新设备。
数据怎么分轨
| 轨道 | 内容 | 通道 | 谁能读 |
|---|---|---|---|
| 配置 | 主机、分组、密钥元数据、转发规则、命令片段、AI 对话历史 | CloudKit 私有库 | 仅你的 iCloud 账号（Apple 持传输/静态密钥） |
| 凭证 | 主机密码、私钥、私钥口令、AI API Key | iCloud 钥匙串 | 端到端加密，Apple 不可读 |
| AI 设置 | Provider 列表、活动模型、脱敏开关、最大步数、命令白/黑名单 | iCloud 键值存储（KVS） | 随 iCloud 账号；不含 API Key |
CloudKit 记录里只有引用键和公钥，绝无密码/私钥明文。引用键与钥匙串项同名对齐后，新设备即可免重输连接。
会同步
| 类别 | 具体内容 |
|---|---|
| 主机 | 名称、地址、端口、用户、认证方式、标签、分组、跳板、排序、已信任主机指纹等 |
| 分组 | 名称、嵌套关系、排序 |
| 密钥身份 | 名称、类型、公钥、存储方式标记（私钥本体走钥匙串） |
| 端口转发规则 | 本地 / 远程 / 动态 SOCKS、绑定与目标、是否自动启动 |
| 命令片段 | 名称、命令正文、排序 |
| AI 对话 | 会话标题与历史消息（落库前已脱敏） |
| 凭证 | 密码、普通钥匙串私钥及口令、AI API Key（E2E 钥匙串） |
| AI 配置 | Provider（endpoint / 模型）、脱敏、最大步数、命令白名单 / 黑名单 |
不会同步
- 终端与 App 外观偏好——主题、字号、回滚行数、App 锁、语言、外观等（本机设置）。
- 运行时状态——当前打开的终端会话、滚动缓冲、分屏布局、正在跑的隧道、SFTP 传输队列。
- Pro 内购状态——由 App Store / StoreKit 按 Apple ID 校验。
- 第三方同步自己的账号口令——WebDAV / S3 / 档案口令只存在本机。
B · 第三方同步（WebDAV / S3）
面向跨生态：例如 iPhone ↔ Android，或全家桶不想走 iCloud。你自带存储账号（BYOS），Shellby 把配置打成端到端加密档案上传；存储方只看到密文。
- WebDAV：坚果云、Nextcloud 等（URL + 用户名 + 应用密码）
- S3 兼容：Cloudflare R2、阿里云 OSS、腾讯云 COS、AWS S3 等
同步时用条件写（If-Match）做比较并交换，多设备并发靠本地按记录后写覆盖（LWW） + 删除墓碑收敛，无需自建服务器。
档案里有什么
| 集合 | 说明 |
|---|---|
| hosts / groups / identities / forwardRules | 与 App 内主机世界一致的配置（含公钥元数据） |
| snippets | 命令片段库 |
| secrets（可选） | 密码、私钥、AI API Key；可用「仅配置」关掉，各端手输凭证 |
| aiConfig | 完整 AI 设置（含脱敏 / 步数 / 命令规则） |
| aiChats | AI 对话快照 |
| tombstones | 删除记录，防止已删项被旧设备「复活」 |
与 iCloud 的差异（摘要）
| iCloud | 第三方 | |
|---|---|---|
| 平台 | 仅 Apple | 六端统一协议 |
| 凭证 | iCloud 钥匙串 E2E | 与配置同档 passphrase E2E |
| AI 护栏设置 | 经 KVS 整包同步 | 经 aiConfig 同步 |
| 合并 | CloudKit 镜像 + KVS LWW | 记录级 LWW + 墓碑 |
常见问题
新设备有主机却连不上？
多半是配置已到、凭证未到：请确认两台设备都登录了同一 iCloud，并开启了iCloud 钥匙串；或等待片刻后再试，或在本机重新输入该主机密码 / 导入私钥。
主机指纹会同步吗？
会。设备 A 已信任的指纹会随主机配置到设备 B，可减少重复确认；若服务器密钥轮换，仍以本机校验为准。
终端主题、分屏布局会同步吗？
不会。同步面向「主机世界与凭证」，不面向本机 UI 偏好与会话运行态。
Shellby has no account of its own and never forces the cloud. Sync is fully opt-in: stay local forever, or turn on iCloud (Apple devices) or third-party storage (Android / Windows / Linux / HarmonyOS).
Two options — how to choose
| Option | Best for | Where |
|---|---|---|
| iCloud Sync | iPhone / iPad / Mac, zero setup | Settings ▸ General ▸ iCloud Sync (Pro) |
| Third-party Sync | Cross-ecosystem, or your own WebDAV / S3 | Settings ▸ General ▸ Third-party Sync |
Both can run side by side, but pick one primary write path so concurrent edits don’t fight each other.
A · iCloud Sync (Apple)
Syncs across devices signed into the same iCloud account. After you enable it:
- Host configuration (CloudKit container) applies after an app restart;
- AI settings (providers, redaction, step limits, command rules) sync live — no restart just for those;
- iCloud Keychain must be on so credentials arrive on new devices.
Separate tracks
| Track | What | Channel | Who can read |
|---|---|---|---|
| Config | Hosts, groups, key metadata, forward rules, snippets, AI chat history | CloudKit private database | Your iCloud account only (Apple holds transport/at-rest keys) |
| Secrets | Host passwords, private keys, key passphrases, AI API keys | iCloud Keychain | End-to-end encrypted — unreadable by Apple |
| AI settings | Provider list, active model, redaction, max steps, command allow/deny lists | iCloud Key-Value Store (KVS) | Follows your iCloud account; no API keys |
CloudKit records hold reference keys and public keys only — never password or private-key plaintext. Matching Keychain items let a new device connect without re-entering secrets.
What syncs
| Category | Details |
|---|---|
| Hosts | Name, address, port, user, auth method, tags, group, jump host, sort order, trusted host fingerprint, … |
| Groups | Name, nesting, sort order |
| Identities | Name, type, public key, storage flag (private key body stays in Keychain) |
| Port-forward rules | Local / remote / dynamic SOCKS, bind & destination, auto-start |
| Snippets | Name, command text, order |
| AI chats | Titles and message history (redacted before persistence) |
| Secrets | Passwords, normal Keychain private keys & passphrases, AI API keys (E2E Keychain) |
| AI settings | Providers (endpoint / model), redaction, max steps, command allow / deny lists |
What does not sync
- Terminal & app UI prefs — theme, font size, scrollback, app lock, language, appearance (device-local).
- Runtime state — open sessions, scrollback buffer, split layout, live tunnels, SFTP transfer queues.
- Pro purchase state — App Store / StoreKit entitlement for your Apple ID.
- Third-party sync credentials — WebDAV / S3 / archive passphrase stay on-device.
B · Third-party Sync (WebDAV / S3)
Built for cross-ecosystem use (e.g. iPhone ↔ Android) or when you prefer your own storage. You bring the account (BYOS). Shellby uploads an end-to-end encrypted archive; the storage provider only sees ciphertext.
- WebDAV — Nutstore, Nextcloud, … (URL + username + app password)
- S3-compatible — Cloudflare R2, Aliyun OSS, Tencent COS, AWS S3, …
Sync uses conditional writes (If-Match) as compare-and-swap. Multi-device merges are record-level last-writer-wins (LWW) plus delete tombstones — no custom server.
What’s in the archive
| Collection | Notes |
|---|---|
| hosts / groups / identities / forwardRules | Same host world as the app (including public-key metadata) |
| snippets | Command snippet library |
| secrets (optional) | Passwords, private keys, AI API keys; “config only” mode skips these |
| aiConfig | Full AI settings (including redaction / steps / command rules) |
| aiChats | AI conversation snapshots |
| tombstones | Deletes, so old devices don’t resurrect removed items |
vs iCloud (summary)
| iCloud | Third-party | |
|---|---|---|
| Platforms | Apple only | One protocol across six platforms |
| Secrets | iCloud Keychain E2E | Same archive, passphrase E2E |
| AI guardrails | Full config via KVS | Full config via aiConfig |
| Merge | CloudKit mirror + KVS LWW | Record LWW + tombstones |
FAQ
New device shows hosts but can’t connect?
Usually config arrived, secrets didn’t. Confirm both devices use the same iCloud account with iCloud Keychain on; wait a bit, or re-enter the password / re-import the key on this device.
Do host fingerprints sync?
Yes. A fingerprint trusted on device A rides with the host record to device B. After a server key rotation, verification still happens on each device.
Do themes and split layouts sync?
No. Sync covers the host world and credentials, not per-device UI prefs or live session state.