Kang
b434a7f90c
- Added new features including RDP session support, SSH Agent authentication, cloud sync enhancements, and terminal output improvements. - Changed settings for better draft-state handling and layout consistency. - Fixed issues related to cursor handling in RDP and command injection timeouts in SSH. - Improved performance during large output bursts in the terminal. - Updated documentation with new community engagement badges and detailed export/import functionalities for quick commands.
309 lines
9.1 KiB
Markdown
309 lines
9.1 KiB
Markdown
---
|
||
sidebar_position: 8
|
||
---
|
||
|
||
# 云同步
|
||
|
||
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 会自动拉取并应用当前云端快照。
|
||
|
||
这项能力只会处理没有本地未同步变更的情况。只要本地和云端都变了，NyaTerm 仍会进入冲突状态，而不是自动选择一边覆盖另一边。
|
||
|
||
### 本地变更后的自动推送
|
||
|
||
开启后，当受支持的本地配置数据发生变化并保存完成时，NyaTerm 会在一个防抖窗口后自动推送快照。
|
||
|
||
你可以设置：
|
||
|
||
- **同步防抖秒数**
|
||
|
||
这意味着它更接近“保存后延迟推送”，而不是实时双向同步。
|
||
|
||
## 手动操作
|
||
|
||
### 测试连接
|
||
|
||
先验证 provider 配置与远端布局是否可用。
|
||
|
||
### 立即推送
|
||
|
||
把当前设备的可移植配置快照上传到云端。
|
||
|
||
适合：
|
||
|
||
- 你刚完成一组设置调整
|
||
- 想明确控制何时写入云端
|
||
|
||
### 立即拉取
|
||
|
||
把云端当前最新同步快照拉回本地并应用。
|
||
|
||
适合：
|
||
|
||
- 另一台设备已经推送过更新
|
||
- 当前设备需要显式对齐到最新云端状态
|
||
|
||
## 冲突是怎么出现的？
|
||
|
||
如果**本地状态**和**云端状态**自上次同步后都发生了变化，就会进入冲突状态。
|
||
|
||
典型场景：
|
||
|
||
- A 设备改了设置但还没拉取 B 的更新
|
||
- B 设备已经把新的同步快照推到了云端
|
||
- A 再尝试推送或启动检查时发现双方都变了
|
||
|
||
这时你会看到冲突预览，例如：
|
||
|
||
- 本地快照哈希
|
||
- 远程 revision
|
||
- 远程设备信息
|
||
- 当前云端快照时间与 hash
|
||
- 冲突提示信息
|
||
|
||
## 冲突怎么处理？
|
||
|
||
当前实现提供两种处理方式：
|
||
|
||
### 下载远程版本
|
||
|
||
把远端快照拉回当前设备并应用。
|
||
|
||
适合：
|
||
|
||
- 你确认云端版本才是应该保留的版本
|
||
- 当前设备上的本地变更不需要保留
|
||
|
||
### 上传本地版本
|
||
|
||
强制用当前设备的本地快照覆盖远端最新状态。
|
||
|
||
适合：
|
||
|
||
- 你确认当前设备才是最新正确版本
|
||
- 你希望别的设备后续以这份状态为准
|
||
|
||
这里要特别注意：
|
||
|
||
- 当前不是字段级 merge
|
||
- 也不是多人协作式冲突解决
|
||
- 本质上是“本地快照”和“远程快照”二选一
|
||
|
||
NyaTerm 会保留当前云端快照的元数据，用来辅助判断应该下载远端版本还是上传本地版本。旧版 `sync/snapshots/` 对象只作为兼容读取和清理来源，不再作为常规多版本备份入口。
|
||
|
||
## 会同步哪些内容？
|
||
|
||
当前实现基于 **portable snapshot**，覆盖的是 NyaTerm 的可移植配置数据，例如：
|
||
|
||
- 已保存连接 / 分组
|
||
- 密钥、密码、OTP 配置
|
||
- 代理与隧道
|
||
- 快捷命令
|
||
- 大部分应用设置
|
||
- known_hosts 与主密钥 token
|
||
|
||
命令历史不会进入云同步核心快照；如需离线留档或迁移，使用本地 `.nya` 导出 / 导入。
|
||
|
||
当前实现会保留一部分设备本地 UI 状态，例如：
|
||
|
||
- 当前打开的标签页
|
||
- 面板开合与尺寸等运行态布局
|
||
|
||
所以它更适合被理解为：
|
||
|
||
- **同步可移植配置**
|
||
- **让多台设备共享当前核心配置状态**
|
||
|
||
而不是完整桌面会话镜像。
|
||
|
||
## 建议的首次配置顺序
|
||
|
||
如果你是第一次启用，建议按这个顺序：
|
||
|
||
1. 在 **设置 → 安全** 中设置主密码
|
||
2. 打开 **设置 → 云同步**
|
||
3. 先选 provider，再填写 endpoint / bucket / root / 凭据
|
||
4. 设置设备名称与远程命名空间
|
||
5. 先执行 **测试连接**
|
||
6. 再决定是否启用：
|
||
- 启动时检查
|
||
- 自动拉取远端变更
|
||
- 自动推送
|
||
7. 最后手动执行一次 **立即推送**，确认整条链路可用
|
||
|
||
## 排障建议
|
||
|
||
如果你发现按钮不可用或操作被拦住，优先检查：
|
||
|
||
- 是否已经设置主密码
|
||
- 当前设置是否已经保存（未应用的草稿会阻止某些手动操作）
|
||
- provider 必填项是否已经补齐
|
||
- 远端命名空间、provider root、endpoint 是否填写正确
|
||
|
||
如果你主要想查看最近发生了什么，优先看工作区里的 **云同步** 面板；如果你主要想改配置，回到设置页更直接。
|
||
|
||
:::tip 使用建议
|
||
- 首次接入新 provider 时，先“测试连接”，再启用自动策略。
|
||
- 做较大范围的连接、OTP、快捷命令调整前，如果需要可回退点，请先使用本地 `.nya` 导出。
|
||
- 如果你经常在多台设备之间切换，建议统一远程命名空间规则，并给每台设备设置清晰的设备名称。
|
||
:::
|