跳到主要内容

云同步

Cloud Sync V3 预览​

设置中的 Cloud Sync V3 提供独立的 V4 同步空间，首批支持 WebDAV、S3 和本地目录后端。选择 V3 后先保存设置，再生成同步预览。确认时会重新检查本地数据和已可见的远端发布；预览过期时须重新生成。

连接、分组、代理、隧道、快捷命令、笔记、自定义图标和主题按稳定 ID 合并。不同字段可自动合并，同字段冲突保留候选和本机当前值；可以在预览中选择候选，也可以先同步无冲突部分。删除和并发编辑会保留存在性冲突。外观偏好可单独开启，仅同步主题、终端字体、光标和对比度白名单。快捷键是独立的可选范围，按操作合并；关闭后保留已有配置。

首次确认会在配置目录创建并回读验证加密的 cloud-sync-v3-safety-<id>.nya 备份。旧云端数据保留，检测到旧客户端后续写入时暂停自动同步；可手动生成导入预览，确认后保留双方资源和冲突候选。V4 的合并结果先原子应用到本机，再发布；上传失败显示“等待发布”，重试会复用已保留的精确密文。已完成回读验证的状态会单独显示。

AI 非敏感配置是独立的可选范围，包含供应商配置、手动添加的模型、自定义操作及默认模式。API 密钥和请求头由独立的敏感数据范围控制；代理、执行权限、外部工具路径和自动发现的模型保留在本机。未开启敏感数据同步时，涉及本机密钥的地址变更和删除会暂缓，需先在本机编辑确认。无效引用、循环和不完整配置也会暂缓相关原子组；预览列出暂缓字段，其他有效修改继续应用，完整候选保留在副本中。

密码、私钥、凭据、OTP、连接／代理密码及 AI 密钥可在独立的敏感数据范围中开启，默认关闭。因果副本只保存版本引用，值使用独立加密对象；接收后用本机密钥重新加密。SSH／VNC 信任范围也默认关闭，每项收到的身份新增、变更和删除都须在本机预览中单独确认；自动同步不会授予信任。关闭范围保留已有数据，重新开启会重新合并。其他 Provider 的 V4 写入尚未开放。引用缺失凭据的认证组会暂缓，待接收设备补齐本机凭据后重新应用。原有 Provider 的旧协议入口保留；选择 V3 后不会因失败而自动写回旧协议。自动双向同步要求首次迁移已确认、自动推送和拉取均开启，并且没有活动会话或未保存设置。

完成 V3 迁移后，在安全设置修改主密码会先发布并回读验证新的 rotation-<id> 子空间，再原子切换密码、远程命名空间和本地副本。失败或上传期间有新的本地编辑时，原密码和原空间继续有效；重试复用已保存的密文。旧空间保留，其他设备须使用新的命名空间和密码接入。云账户／范围变更须与改密分开保存。已有 V4 副本时不能直接关闭主密码。

下面介绍的是保留用于兼容的旧快照协议与 Provider 设置。.nya 始终是独立备份，不携带 V4 Writer 身份、发布历史或同步副本。

NyaTerm 的 云同步 能力，解决的不是“远程文件传输”，而是把应用里的可移植配置数据同步到一份加密的远端核心快照。

远端使用不可变快照和每台设备独立的提交记录：

  • sync/snapshots/<revision>.redb.enc 保存加密快照，是当前协议的正常数据路径
  • sync/heads/ 保存每台设备的提交记录及上传中的临时标记，用于识别并保留并发修改
  • sync/latest.redb 保存供兼容读取使用的最新 revision、设备、时间和 hash 元数据
  • sync/current.redb.enc 是尽力更新的兼容／恢复副本，不是唯一权威数据源

两台设备同时推送时，各自的提交都会保留；下一次检查发现并发分支后，会要求明确选择本地或云端。远端存储若存在可见性延迟，冲突可能在后续检查才出现。判断先后关系使用因果记录，不依赖设备时钟。

.nya 本地导出 / 导入仍然是配置备份和迁移入口。云端旧快照会按保留策略清理；设备正在引用、尚未解决的并发分支及上传中的快照受到保护。云同步不会自动删除用户云端已有的旧 backups/ 数据，保留的快照也不替代独立备份。

当前支持这些远程存储提供方：

  • WebDAV
  • S3 兼容存储
  • Gitee 代码片段（Gitee Snippet）
  • GitHub Gist
  • Google Drive
  • OneDrive
  • AliyunDrive

先决条件：先设置主密码​

在使用 设置 → 云同步 前，你必须先到 设置 → 安全 设置 主密码。

这是硬性前置条件。没有主密码时：

  • 不能启用云同步
  • 不能执行测试连接、推送、拉取等手动操作

上传到云端的是加密后的可移植快照。新快照使用随机盐的 Argon2id 派生密钥，再通过 AES-256-GCM 加密和认证；版本头、参数、盐和 nonce 也参与认证。

旧 NyaTerm 和 Dragonfly 快照仍可读取。下次实际上传或显式覆盖会写成新格式；仅检查到内容相同不会重写旧密文。新格式需要所有参与同步的设备升级到支持它的版本，旧客户端无法解密新快照，也不具备新的并发保护。升级前建议保留本地 .nya 备份。

升级后第一次检查，如果旧同步基线无法证明完整数据未变，可能需要手动确认冲突；这是为了保护此前未计入变更 hash 的 VNC 信任记录和扩展数据。

从哪里进入​

这项功能主要有两个入口：

1. 设置 → 云同步​

这里是主要配置页，负责：

  • 选择 provider
  • 配置远程命名空间与 provider 根路径
  • 设置自动同步策略
  • 运行测试连接、立即推送、立即拉取
  • 在冲突发生时执行处理

2. 工作区中的 Cloud Sync / 云同步面板​

主工作区侧栏里的 云同步 面板用于查看：

  • 当前状态
  • 最近的同步活动
  • 最近一次检查、同步时间
  • 冲突状态与快速处理入口

改配置去设置页，看运行状态看工作区面板。

Provider 配置​

通用项​

无论使用哪种 provider，都需要先确认这几项：

  • 启用云同步
  • 存储提供方配置
  • 设备名称
  • 远程命名空间

其中：

  • 设备名称 会写入快照元数据，方便你识别是哪台设备上传的内容
  • 远程命名空间 是 NyaTerm 在远端保存云同步快照时使用的顶层路径前缀

WebDAV​

如果 provider 选的是 WebDAV，通常需要填写：

  • WebDAV Endpoint
  • Provider Root（可选）
  • 用户名
  • 密码

WebDAV 认证同时支持 Basic 和 Digest 两种方式。当服务端要求 Digest 时，NyaTerm 会自动改用 Digest，以提升对 NAS / 网关的兼容性。

S3 兼容存储​

如果 provider 选的是 S3 兼容，通常需要填写：

  • S3 Endpoint
  • Bucket
  • Region
  • Provider Root（可选）
  • Access Key ID
  • Secret Access Key
  • Session Token（可选）
  • Virtual Host Style（按 provider 要求决定是否开启）

Gitee 代码片段（Snippet）​

如果 provider 选的是 Gitee 代码片段，NyaTerm 会把加密后的云同步对象保存到一个 Gitee 代码片段中。

Gitee 的文件数量限制也适用于快照、设备提交及临时标记。设备较多或保留了多个冲突分支时，可能需要使用新的代码片段或更换存储提供方；不会为了腾出位置删除未解决的分支。

通常需要填写：

  • Gitee 个人访问令牌（Personal Access Token）
  • 代码片段 ID

GitHub Gist​

如果 provider 选的是 GitHub Gist，NyaTerm 会通过 GitHub device flow 授权，并把加密后的云同步对象保存到一个私有 Gist 中。

通常需要：

  • 点击 连接 GitHub
  • 在浏览器打开的 GitHub 授权页面输入设备码
  • 授权 gist scope

在 GitHub device-flow 授权流程中，如果没有填写 Gist ID，NyaTerm 会在授权成功后自动创建并回填一个私有 Gist；已有 Gist ID 时，会先验证并复用该 Gist。

Google Drive / OneDrive / AliyunDrive​

如果 provider 选的是 Google Drive、OneDrive 或 AliyunDrive，NyaTerm 会通过桌面端原生 HTTP adapter 访问对应网盘服务。

当前需要手动填写 OAuth 信息：

  • Refresh Token
  • Client ID
  • Client Secret
  • Access Token（可选，长期同步建议依赖 Refresh Token）
  • Provider Root（可选）

AliyunDrive 还需要填写 Drive Type，通常为 resource。

配置校验​

当前实现会先做最基本的 provider 校验：

  • WebDAV 至少需要填写 endpoint
  • S3 至少需要填写 endpoint 与 bucket
  • Access Key ID 和 Secret Access Key 需要成对出现
  • GitHub Gist 需要完成 GitHub 授权；Gist ID 可以在授权流程中自动创建并回填，也可以使用已有 ID
  • Google Drive / OneDrive / AliyunDrive 需要填写 Refresh Token、Client ID、Client Secret

建议在真正启用自动策略前，先执行一次 测试连接。

自动同步策略​

启动时检查​

开启后，NyaTerm 会在启动时检查远端是否已经有新的同步快照。

常见结果包括：

  • 本地与云端一致
  • 远端有更新，可以拉取
  • 本地有尚未同步的变化
  • 本地和云端都变了，进入冲突状态

所有 Provider（包括 GitHub Gist）还会每 15 分钟检查一次；窗口重新聚焦时也会检查，聚焦检查至少间隔 120 秒。关闭“启动时检查”只跳过启动检查。失败时会退避重试，限流时遵守服务端有效的 Retry-After；认证失效会暂停，修改设置后恢复。

自动拉取远端变更​

开启 自动拉取远端变更 后，如果启动检查或同步检查发现“只有远端发生变化”，NyaTerm 会自动拉取并应用当前云端快照。

它只处理本地没有未同步变更的情况；存在活动会话或未保存设置草稿时，会等到安全后再拉取。本地和云端都变了时仍然进入冲突状态，不会自动选一边覆盖另一边。

本地变更后的自动推送​

开启后，当受支持的本地配置数据发生变化并保存完成时，NyaTerm 会在一个防抖窗口后自动推送快照。

你可以设置：

  • 同步防抖秒数

它是「保存后延迟推送」，不是实时双向同步。

手动操作​

测试连接​

先验证 provider 配置与远端布局是否可用。

立即推送​

把当前设备的可移植配置快照上传到云端。用于刚完成一组设置调整后，或需要明确控制何时写入云端时。

立即拉取​

把云端当前最新同步快照拉回本地并应用。用于另一台设备已经推送过更新，需要让当前设备显式对齐时。

冲突是怎么出现的？​

如果本地状态和云端状态自上次同步后都发生了变化，就会进入冲突状态。

典型场景：

  • A 设备改了设置但还没拉取 B 的更新
  • B 设备已经把新的同步快照推到了云端
  • A 再尝试推送或启动检查时发现双方都变了

这时你会看到冲突预览，例如：

  • 本地快照哈希
  • 远程 revision
  • 远程设备信息
  • 当前云端快照时间与 hash
  • 冲突提示信息

冲突怎么处理？​

当前实现提供两种处理方式：

下载远程版本​

分支列表显示每个并发 revision、设备名称（旧快照显示缩短的 UUID）、时间、可读状态及差异数量。仅有一个可读分支时自动选中；有多个可读分支时必须先选择。差异摘要仅展示已知集合新增、删除、修改数量、设置分类以及未知实体是否变化，不显示凭据、OTP、笔记或命令正文。

把选定的远端快照拉回当前设备并应用。当前设备上未同步的本地变更会丢失，选它之前先确认云端版本是要保留的那份。

上传本地版本​

用当前设备的本地快照解决当前预览中已观察到的分支。确认时会重新校验本地内容、所选快照和分支集合；发生变化会刷新预览，要求再次确认。远端那份变更会被覆盖，其他设备后续会以这份状态为准。

这里要特别注意：

  • 当前不是字段级 merge
  • 也不是多人协作式冲突解决
  • 本质上是“本地快照”和“远程快照”二选一

NyaTerm 保留独立的设备提交和因果记录。明确选择本地或云端会生成覆盖已观察到分支的新提交；选择云端时会固定使用预览中明确选定的 revision。若其他设备随后提交新的并发修改，仍会再次提示冲突。sync/snapshots/ 是现行协议的数据路径，不要手动清空。

会同步哪些内容？​

当前实现基于 portable snapshot，覆盖的是 NyaTerm 的可移植配置数据，例如：

  • 已保存连接 / 分组
  • 密钥、密码、OTP 配置
  • 代理与隧道
  • 快捷命令
  • 大部分应用设置
  • known_hosts 与主密钥 token

命令历史不会进入云同步核心快照；如需离线留档或迁移，使用本地 .nya 导出 / 导入。

当前实现会保留一部分设备本地 UI 状态，例如：

  • 当前打开的标签页
  • 面板开合与尺寸等运行态布局

所以它同步的是可移植配置，让多台设备共享当前核心配置状态，不是完整的桌面会话镜像。

建议的首次配置顺序​

首次启用按这个顺序：

  1. 在 设置 → 安全 中设置主密码
  2. 打开 设置 → 云同步
  3. 先选 provider，再填写 endpoint / bucket / root / 凭据
  4. 设置设备名称与远程命名空间
  5. 先执行 测试连接
  6. 再决定是否启用：
    • 启动时检查
    • 自动拉取远端变更
    • 自动推送
  7. 最后手动执行一次 立即推送，确认整条链路可用

凭据、设备名称与活动历史​

三个网盘刷新令牌后，会先加密保存新的 Access Token 和服务端返回的 Refresh Token，再继续认证请求；未返回 Refresh Token 时保留原值。保存失败会停止操作，后续同步失败或取消不会撤销已完成的令牌保存。未编辑的设置令牌字段会跟随轮换更新，显式编辑的凭据仍需通过保存冲突检查。

设备名称保存在加密快照中；UUID 仍是设备身份。名称修改在下一次实际发布时生效，不会仅为改名重新上传。

自动上传、下载、冲突、失败和恢复成功会由进程统一写入活动历史，多窗口共享一条记录。无变化、忙碌、防抖或禁用检查不会刷屏；相同错误分类、触发原因和 revision 在 15 分钟内去重。错误只包含受控分类、Provider、操作和 HTTP 状态，不包含请求 URL、签名地址或响应正文；历史写入故障不会改变已经成功的同步结果。

后台检查与流量​

自动检查先检查指针和全部设备提交，已验证且未变化的快照最多每 24 小时完整下载校验一次。轻量检查不会延长这个期限。S3 支持 ETag 条件请求时，未变化的指针返回 304，设备提交可以复用本次列表确认的缓存；服务不支持时退回普通 GET。

其他 Provider 仍需传输各自的指针和目录 API 响应；Gist/Snippet 的容器响应还可能包含文件内容。因此每日校验限制针对显式快照读取和验证，不能保证每个 Provider 的网络正文都只包含元数据。

缓存由同一进程的窗口共享，关闭应用后丢弃。首次启动、切换远端配置或账号、轮换凭据、修改主密码、缓存淘汰及分支变化都可能增加完整读取。实际推送、拉取、恢复和冲突确认仍验证快照；每日历史清理、上传回读及兼容副本也会产生流量。

本地变更通知没有改变实际同步内容时，可以跳过联网。持续编辑不会推迟定时远端检查，但上传仍等待防抖结束。最近成功的手动或自动检查会推迟下一次定时检查，并在 120 秒内抑制聚焦重复检查；测试连接不算完整检查。关闭“启动时检查”不会关闭 15 分钟定时检查。

日志提供受控的操作汇总：请求数、上传和下载正文的字节、304、缓存命中及完整校验次数。所有 Provider 均在 HTTP 边界统计，包含认证重试和已读取的错误正文；上传字节为每次尝试提交的正文大小，下载字节为应用实际读取量，不包含 HTTP 头和 TLS 开销，不能直接视为云厂商账单。日志不包含地址、对象路径、ETag、凭据或同步正文。实际流量取决于在线时长、设备数、快照大小、变更、重试和存储服务能力。

排障建议​

按钮不可用或操作被拦住时，依次检查：

  • 是否已经设置主密码
  • 当前设置是否已经保存（未应用的草稿会阻止某些手动操作）
  • provider 必填项是否已经补齐
  • 远端命名空间、provider root、endpoint 是否填写正确

查看最近发生了什么看工作区的 云同步 面板，改配置回设置页。

使用建议
  • 首次接入新 provider 时，先“测试连接”，再启用自动策略。
  • 做较大范围的连接、OTP、快捷命令调整前，如果需要可回退点，请先使用本地 .nya 导出。
  • 在多台设备之间切换时，统一远程命名空间规则，并给每台设备设置可区分的设备名称。