备份与恢复
打开设置 → 数据 → 备份与恢复。连接和服务器页面的空状态也提供“从备份恢复”入口，详情页仍在当前 Tab 内打开。
OneXray 只绑定一份备份文件，新建文件默认命名为 OneXray-backup.json，后续成功备份覆盖同一文件。不提供历史版本、配置合并或设备间双向自动同步。
选择保存位置
| 平台 | 保存位置 |
|---|---|
| iPhone、iPad、macOS、macOS System Extension | 首选 iCloud Drive，使用 OneXray 文档容器；也可通过系统选择器选择已有文件或创建文件。两种位置共用恢复与自动备份设置。 |
| Android | 通过系统文件选择器创建或选择一份文件；Google Drive 的文档提供程序出现在选择器中时，可以将文件保存在其中。OneXray 保留该文件的读取和覆盖权限，不单独提供 Google 登录。 |
| Windows EXE、ZIP、MSIX | 选择已经由 OneDrive 同步的文件夹。OneXray 写入普通文件，账号登录和云端同步由 OneDrive 负责。 |
Linux 不提供此功能。写入成功只代表存储提供程序已接收文件，不代表文件已上传到云端。依赖备份前，请确认另一台设备可以读取它；提供程序或网络故障可能中断写入，不能假定所有提供程序都支持原子覆盖。
选择保存位置时，App 先检查文件是否已有内容。空文件立即写入首份备份，即使自动备份已关闭；文件有内容时选择恢复或覆盖备份，取消则保留原绑定和文件。恢复会验证文件并展示替换预览；覆盖不要求旧内容是有效备份。读取失败会报错，不会把文件当作空文件覆盖。
Apple 可通过“切换到本地备份”选择或创建文件，通过“切换到云端备份”使用 iCloud Drive。iOS 创建文件时选择保存目录。请选择 OneXray 数据目录以外的位置，避免文件随 App 删除；重新安装后可重新选择原文件。取消切换保留原位置，解除绑定或清理 App 数据不会删除外部文件。
敏感信息
备份文件未加密。 文件可能包含节点凭据、订阅 URL、Age 私钥和订阅 HWID。配置文本的 Base64 编码不是加密。请限制保存位置的访问权限，不要公开分享备份，也不要将其粘贴给 AI。云端存储适用相应服务商的安全与隐私政策；文件不会上传至 OneXray 服务器。
备份范围
| 包含 | 不包含 |
|---|---|
| 手动添加的节点、完整 Raw JSON 原文 | 订阅节点缓存、对缓存节点的本地修改、测速结果和收藏状态 |
| 订阅名称、URL、显式 User-Agent、Age 密钥、HWID 及其开关 | 下载文件、GeoData 内容和索引、日志、证书或外部密钥文件 |
| 常规和高级自定义路由的名称、类型及配置原文 | 当前节点／路由／Raw 选择、专家模式状态、App 的最终出口选择 |
| 智能路由选项及匹配平台的 VPN 设置 | 物理出口网卡名称、设备权限、API／自动化授权和 App 偏好 |
| 自定义 GeoData 的文件名、类型及 HTTPS 来源，包括待下载记录 | 默认 GeoData 文件及其来源记录 |
Raw JSON 自身的出站定义会保留。不备份 App 的最终出口选择，不等于删除完整 Raw 配置内的节点。配置引用的外部文件需要在目标设备上单独准备。
自动备份与手动备份
自动备份默认开启。绑定空文件或确认覆盖时，无论开关状态都会写入首份备份；选择恢复则保留源文件，从本次绑定时间计算后续周期，“本机上次成功写入”仅在实际写入后更新。开关控制后续自动写入，关闭后仍可手动备份。
备份周期与 GeoData 独立保存：可选 1、3、7 天，默认为 3 天。App 在启动、回到前台以及运行期间的定时检查中判断是否到期。这不是 App 挂起或退出后仍保证准时执行的系统后台任务，也不要求 VPN 已连接。
自动备份失败会显示在备份页面，不影响 VPN 状态；可以手动重试。关闭自动备份只停止后续自动写入，不会删除已有文件。
恢复流程
- 选择保存位置并读取备份。仅存在云端的文件可能需要存储提供程序先下载。
- 查看预览并确认替换。恢复会替换 App 管理的连接配置，不做合并；应用前先停止 VPN，停止失败时不改动原有配置。
- 返回 App。当前选择重置为常规模式、自动选择和智能路由，不会自动启动 VPN；存在匹配平台分区时恢复其设置，否则保留本机值，App 偏好保留。
- 更新恢复后的订阅以获取节点。手动节点和 Raw JSON 已包含在备份中；恢复不会自动更新订阅，也不等待测速。
只要备份文件已经可以读取，恢复配置记录本身不需要联网，但不保证所有恢复的配置立即可连接。
GeoData 无法下载时
文件名、类型、来源 URL 相同且有效的本地自定义数据会复用；其他自定义来源恢复为待下载，不阻塞恢复或进入首页。同名但来源冲突的项目会在替换前展示。默认路由数据使用设备上已有的有效文件或 App 内置文件。
需要缺失文件的配置会明确报告依赖，不会丢弃规则、静默改为直连，也不会在 VPN 启动时下载兜底。必要时先使用其他可用配置，再到 GeoData 下载缺失数据。GeoData 自动更新仍要求 VPN 已连接；待下载数据在下载并建立索引前不提供自动补全类别。
备份格式与独立分享
备份为版本 1 的 JSON 文档，使用 format: "onexray-backup" 标识，不是旧版 ZIP 备份。恢复支持最大 64 MiB 的文件，请使用“备份与恢复”入口，不要从节点、自定义路由或 Raw JSON 导入入口读取。
单独迁移配置请使用分享与导入。与订阅分享不同，备份会保留 Age 私钥和 HWID 以便恢复。让 AI 生成配置时，应使用文档中的配置格式，不要让 AI 构造备份文件。
备份字段与兼容性
协议仍为 v1，新增保存订阅 panel／mode 和支持的智能 DNS／嗅探／选路参数。旧备份缺少这些字段时使用通用／App 管理来源及原路由默认值。不备份提供方完整配置或派生节点缓存，恢复后需刷新；个人 Raw 副本按普通资产备份。未知字段忽略且不重新导出，但格式、版本、必要分区、已知类型和显式枚举仍须有效。不保存运行探测或退休地区数据；旧内部普通 DNS 超时／缓存覆盖／过滤／过期缓存／并发及嗅探排除已退休，外部普通 JSON 导入仍严格检查字段。
协议 v1 保存每个订阅显式设置的 User-Agent；缺少该字段时使用恢复设备的兼容默认值。服务器显示排序仍属于本机偏好；服务器拨号随匹配的平台分区保存和恢复。
协议 v1 还保存命名手动分组（包括空组）、分组顺序、节点归属和组内位置。旧备份没有这些可选字段时，手动节点按原顺序恢复到未分组。手动组用于资产组织，不是连接选择；恢复不会创建按组自动连接。
平台专属 VPN 设置
协议 v1 可包含 platformSettings，按 ios、macos、android、windows、linux 分区。备份仅写当前平台可迁移的 VPN 设置，恢复仅读取并校验匹配的键。iOS 与 macOS 不互相匹配；OneXraySE 使用 macos，各 Windows 分发使用 windows。这不增加 Linux 的备份页面。
匹配分区包含 IPv6、隧道 DNS、服务器拨号、局域网共享、日志偏好及本平台 VPN 策略。Android 同时保存访问模式、包含与排除两份应用包名列表，保留尚未安装的包名。其它平台分区不改变本机设置；缺少分区或某项设置时保留接收设备当前值，匹配分区格式错误在确认替换前报告。
物理出口网卡名称、系统权限、API／自动化授权、外观偏好和备份位置仍保留在本机。确认恢复后，同平台设置与连接资产一同恢复，并先停止 VPN；完成后不自动重连。