跳到主要内容

云同步

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

远端始终以当前快照为准：

  • sync/current.redb.enc 保存加密后的当前核心数据
  • sync/latest.redb 保存当前快照的 revision、设备、时间和 hash 元数据
  • 旧版 sync/snapshots/ 只用于兼容读取和清理

.nya 本地导出 / 导入仍然是配置备份和迁移入口；云同步不再创建远端多版本备份，也不会自动删除用户云端已有的旧 backups/ 数据。

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

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

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

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

这是当前实现的前置条件，而不是可选建议。没有主密码时：

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

原因很直接：上传到云端的是加密后的可移植快照，而不是明文配置文件。

从哪里进入​

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

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 个人访问令牌（Personal Access Token）
  • 代码片段 ID

GitHub Gist​

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

通常需要：

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

如果没有填写 Gist ID，NyaTerm 会在授权成功后自动创建一个私有 Gist。已有 Gist ID 时，会复用该 Gist。

Google Drive / OneDrive / AliyunDrive​

如果 provider 选的是 Google Drive、OneDrive 或 AliyunDrive，NyaTerm 会通过 OpenDAL 使用对应网盘服务。

当前需要手动填写 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
  • Google Drive / OneDrive / AliyunDrive 需要填写 Refresh Token、Client ID、Client Secret

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

自动同步策略​

启动时检查​

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

常见结果包括：

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

这不是实时云端监听，而是启动时检查当前状态。

本地变更后的自动推送​

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

你可以设置：

  • 同步防抖秒数

这意味着它更接近“保存后延迟推送”，而不是实时双向同步。

手动操作​

测试连接​

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

立即推送​

把当前设备的可移植配置快照上传到云端。

适合：

  • 你刚完成一组设置调整
  • 想明确控制何时写入云端

立即拉取​

把云端当前最新同步快照拉回本地并应用。

适合：

  • 另一台设备已经推送过更新
  • 当前设备需要显式对齐到最新云端状态

冲突是怎么出现的？​

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

典型场景：

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

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

  • 本地快照哈希
  • 远程 revision
  • 远程设备信息
  • 冲突提示信息

冲突怎么处理？​

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

下载远程版本​

把远端快照拉回当前设备并应用。

适合：

  • 你确认云端版本才是应该保留的版本
  • 当前设备上的本地变更不需要保留

上传本地版本​

强制用当前设备的本地快照覆盖远端最新状态。

适合：

  • 你确认当前设备才是最新正确版本
  • 你希望别的设备后续以这份状态为准

这里要特别注意：

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

会同步哪些内容？​

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

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

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

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

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

所以它更适合被理解为：

  • 同步可移植配置
  • 让多台设备共享当前核心配置状态

而不是完整桌面会话镜像。

建议的首次配置顺序​

如果你是第一次启用，建议按这个顺序：

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

排障建议​

如果你发现按钮不可用或操作被拦住，优先检查：

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

如果你主要想查看最近发生了什么，优先看工作区里的 云同步 面板；如果你主要想改配置，回到设置页更直接。

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