# 备份、迁移与恢复

**当前版本的在线“面板迁移”已停用。** 不通过收藏地址、旧 `.zfpkg`教程或源码中留存的表单执行在线导入。本篇使用当前可用的安装脚本打包／恢复；它与停用的在线迁移流程独立。

## 先确认数据库和迁移范围

安装脚本的一键打包目前只支持 **内置 PostgreSQL**。外部 PostgreSQL 需要自行安排数据库备份、恢复和连接配置，不能把脚本拒绝外部库当作“没有数据需要备份”。

| 材料 | 为什么需要 |
| --- | --- |
| 原安装目录与当前 `install.sh` | `.env`、Compose 与实例配置都与部署相关 |
| 数据库和锁定版本 | 恢复要匹配对应 release，不能直接用当天 latest 配旧数据库 |
| 自定义配置及外部服务清单 | 反向代理、域名、外部数据库、时序存储等要单独核对 |
| 授权、DNS 和节点管理地址 | 数据迁移不会替你完成授权与域名切换 |

迁移包包含密钥、用户和业务数据。限制文件权限，使用受控渠道传输。

## 在源机器打包

在原安装目录运行现有脚本，选择 **6. 一键打包迁移文件**，或使用当前支持的命令：

```bash
cd /root/zfc
bash install.sh --pack
```

路径按实际部署替换。确认脚本报告打包成功，记录生成的 `zfc_migration_*.tar.gz`文件名、大小、时间、锁定版本及数据库导出结果。不要把“命令启动了”当作迁移包有效。

默认会跳过以下表的**行数据**，仍保留对应结构：诊断记录、服务器状态快照、审计日志、Peer 统计和 forwarder 任务队列。需要完整保留这些数据库记录时，在打包前显式使用：

```bash
ZFC_BACKUP_FULL=1 bash install.sh --pack
```

这会增加包体和耗时，也不等于自动包含所有外部系统的历史。先核对磁盘空间与所需数据范围。

对选定的实际包计算校验和，传输到目标机器后再次比较：

```bash
shasum -a 256 zfc_migration_实际时间.tar.gz
tar -tzf zfc_migration_实际时间.tar.gz
```

列出归档和校验和只是基础完整性检查，真正验证备份还需要一次成功的恢复与业务验收。

## 在目标机器恢复

1. 准备兼容的系统、Docker / Compose、足够磁盘，以及需要的域名和网络访问。
2. 把迁移包与当前脚本放在计划的安装目录，确认传输校验一致。
3. 如目标已有部署，先另存其备份；恢复会替换目标数据，不能直接覆盖唯一副本。
4. 在脚本选择 **7. 一键恢复迁移文件**，按提示选择 `.tar.gz`迁移包。
5. 核对版本与恢复结果，不在恢复之前先执行一次全新安装去覆盖目标目录。
6. 协调停机和域名切换，避免新旧面板同时使用同一授权、管理同一批节点。

当前脚本支持显式指定恢复包，适合已经准备好恢复条件的自动化流程：

```bash
ZFC_RESTORE_PACKAGE=/安全路径/zfc_migration_实际时间.tar.gz \
  bash install.sh --restore
```

读取不到迁移包的 release 身份、版本不兼容或恢复报错时，保留日志并按提示处理，不绕过版本／schema 门禁强行启动。

## 恢复后的验收与回退

依次验证：登录与角色、用户套餐和余额、服务器／端点在线、端口与共同规则同步、真实 TCP / UDP 业务、订阅链接、共享资源、证书、DNS、通知和支付回调地址。

特别核对新主机的面板 URL、控制器 WebSocket 地址、反向代理与证书。数据库有原记录，不表示外部节点已经连到新控制面。

确认新环境可用前，保留源安装目录、迁移包和关键配置。需要回退时先停止新控制面，避免两个实例并行操作资源，再恢复源环境与域名。已发生的新订单、DNS 写入或业务变更还需单独核对，不能认为回滚数据库会自动撤回全部外部动作。

日常保数据升级使用 `bash install.sh --update`；`--force`与`--clean-install`不是迁移修复选项。安装与更新的详细入口见[安装面板](/docs/quickstart/)。