# 备份与恢复

Source: https://onexray.com/zh/docs/backup/
Description: 使用 iCloud、Android 系统文件选择器或 OneDrive 文件夹保存一份可覆盖的连接配置备份，恢复无需等待 GeoData 下载。


打开**设置 → 数据 → 备份与恢复**。连接和服务器页面的空状态也提供“从备份恢复”入口，详情页仍在当前 Tab 内打开。

OneXray 只保存一份 `OneXray-backup.json`，每次成功备份都会覆盖旧内容。它不是历史版本管理、数据合并或设备间双向自动同步。

## 选择保存位置

| 平台 | 保存位置 |
| --- | --- |
| iPhone、iPad、macOS、macOS System Extension | OneXray 的 iCloud 文档容器。请为 App 开启 iCloud Drive，需要访问同一文件的设备使用同一 Apple 账号。 |
| Android | 通过系统文件选择器创建或选择一份文件；Google Drive 的文档提供程序出现在选择器中时，可以将文件保存在其中。OneXray 保留该文件的读取和覆盖权限，不单独提供 Google 登录。 |
| Windows EXE、ZIP、MSIX | 选择已经由 OneDrive 同步的文件夹。OneXray 写入普通文件，账号登录和云端同步由 OneDrive 负责。 |

Linux 不提供此功能。写入成功只代表存储提供程序已接收文件，不代表文件已上传到云端。依赖备份前，请确认另一台设备可以读取它；提供程序或网络故障可能中断写入，不能假定所有提供程序都支持原子覆盖。

选择或读取保存位置**不等于同意覆盖**。首次备份前需要阅读敏感信息提示并确认；可以先恢复已有文件，再决定是否允许覆盖。解除绑定或清理 App 数据不会删除外部备份文件。

## 敏感信息

**备份文件未加密。** 文件可能包含节点凭据、订阅 URL、Age 私钥和订阅 HWID。配置文本的 Base64 编码不是加密。请限制保存位置的访问权限，不要公开分享备份，也不要将其粘贴给 AI。云端存储适用相应服务商的安全与隐私政策；文件不会上传至 OneXray 服务器。

## 备份范围

| 包含 | 不包含 |
| --- | --- |
| 手动添加的节点、完整 Raw JSON 原文 | 订阅节点缓存、对缓存节点的本地修改、测速结果、位置和收藏状态 |
| 订阅名称、URL、Age 密钥、HWID 及其开关 | 下载文件、GeoData 内容和索引、日志、证书或外部密钥文件 |
| 常规和高级自定义路由的名称、类型及配置原文 | 当前节点／路由／Raw 选择、专家模式状态、App 的最终出口选择 |
| 智能路由选项 | VPN 隧道设置、设备权限、平台策略和 App 偏好 |
| 自定义 GeoData 的文件名、类型及 HTTPS 来源，包括待下载记录 | 默认 GeoData 文件及其来源记录 |

Raw JSON 自身的出站定义会保留。不备份 App 的最终出口选择，不等于删除完整 Raw 配置内的节点。配置引用的外部文件需要在目标设备上单独准备。

## 自动备份与手动备份

自动备份默认开启，但只有确认保存位置后才会写入。开启时，首次确认会立即创建备份；也可以关闭自动备份，仅手动执行。

备份周期**与 GeoData 独立保存**：可选 **1、3、7 天**，默认为 **3 天**。App 在启动、回到前台以及运行期间的定时检查中判断是否到期。这不是 App 挂起或退出后仍保证准时执行的系统后台任务，也不要求 VPN 已连接。

自动备份失败会显示在备份页面，不影响 VPN 状态；可以手动重试。关闭自动备份只停止后续自动写入，不会删除已有文件。

## 恢复流程

1. 选择保存位置并读取备份。仅存在云端的文件可能需要存储提供程序先下载。
2. 查看预览并确认替换。恢复会替换 App 管理的连接配置，不做合并；应用前先停止 VPN，停止失败时不改动原有配置。
3. 返回 App。当前选择重置为常规模式、自动选择和智能路由，不会自动启动 VPN；保留目标设备的隧道设置和偏好。
4. 更新恢复后的订阅以获取节点。手动节点和 Raw JSON 已包含在备份中；恢复不会自动更新订阅，也不等待测速。

只要备份文件已经可以读取，恢复配置记录本身不需要联网，但**不保证所有恢复的配置立即可连接**。

### GeoData 无法下载时

文件名、类型、来源 URL 相同且有效的本地自定义数据会复用；其他自定义来源恢复为**待下载**，不阻塞恢复或进入首页。同名但来源冲突的项目会在替换前展示。默认路由数据使用设备上已有的有效文件或 App 内置文件。

需要缺失文件的配置会明确报告依赖，不会丢弃规则、静默改为直连，也不会在 VPN 启动时下载兜底。必要时先使用其他可用配置，再到 [GeoData](https://onexray.com/zh/docs/advanced/geodata/) 下载缺失数据。GeoData 自动更新仍要求 VPN 已连接；待下载数据在下载并建立索引前不提供自动补全类别。

## 备份格式与独立分享

备份为版本 1 的 JSON 文档，使用 `format: "onexray-backup"` 标识，不是旧版 ZIP 备份。恢复支持最大 64 MiB 的文件，请使用“备份与恢复”入口，不要从节点、自定义路由或 Raw JSON 导入入口读取。

单独迁移配置请使用[分享与导入](https://onexray.com/zh/docs/sharing/)。与订阅分享不同，备份会保留 Age 私钥和 HWID 以便恢复。让 AI 生成配置时，应使用文档中的[配置格式](https://onexray.com/zh/docs/configuration/)，不要让 AI 构造备份文件。