Skip to content

配置历史、备份与迁移 ​

网关上的配置往往是一点点攒出来的:几十个站点、证书、DDNS 任务、封禁规则。手滑删错一个站点、改错一个后端,或者硬盘坏了、要换一台机器,都需要能退回去。Gately 有三层保护:每次修改自动留下的配置历史,可以下载、可以定时写到别处的配置备份,以及排查问题用的诊断包。本文逐个讲怎么用,最后讲怎么把整套配置搬到另一台机器。

先看看界面

在线演示 demo.gately.cn 点「演示账号一键进入」,打开「日志 → 配置历史」与「设置 → 备份与迁移」。演示实例只读,备份下载、恢复与回滚都不可用。

适用场景与前提 ​

  • Gately 已经在运行,你用管理员账号登录(只读账号与 API 令牌不能查看配置历史,也不能下载或恢复备份);
  • 想把备份写到另一台设备时,先在「存储挂载」里添加那台设备的 WebDAV、SMB 共享或本地目录;
  • 迁移时新机器已经装好 Gately,见 从零开始。

三种手段各管什么 ​

手段保存什么保存在哪适合
配置历史每个配置文件被覆盖前的旧内容,每个最多 30 个版本配置目录 history/<名称>/刚改坏了,退回上一个版本
配置备份配置目录根部的全部 *.json,打包成 zip浏览器下载、配置目录 backups/、存储挂载机器坏了、重装、迁移
诊断包版本、系统、模块状态、脱敏后的配置结构与日志浏览器下载提交 issue、求助

Gately 的所有配置都是配置目录里的明文 JSON(Docker 部署时通常挂载为 /etc/gately),每个模块一个 <名称>.json。理解这一点,下面的操作都很直观。

步骤 ​

1. 用配置历史退回改坏的配置 ​

每次保存修改,Gately 在覆盖配置文件之前把旧内容存成一个历史版本。内容没有变化时不存。account.json(账号)与 tokens.json(API 令牌)不记录历史。

  1. 打开侧边栏「系统 → 日志」,切到「配置历史」标签(地址 #/logs/history)。

  2. 左上角下拉选择配置文件。模块配置显示为「模块名 (文件名)」,例如「Web 服务 (webservice.json)」;系统设置是 gately.json。

  3. 表格按时间倒序列出版本,每一行是那个时刻被覆盖前的内容。

    配置历史:Web 服务的历史版本

  4. 点某一行的「对比」,弹窗按行列出该版本与当前配置的差异:红色 - 行是所选历史版本的内容,绿色 + 行是当前内容,没变的大段内容折叠为「省略 N 行未变更内容」。完全相同时显示「与当前配置完全一致」。

    对比历史版本与当前配置

    上图能看出:从那个版本到现在,Jellyfin 的后端从 .20 改成了 .21,并打开了网页认证。

  5. 确认要退回到这个版本,点「回滚」,在确认框中点「回滚」。

    回滚确认

  6. 界面提示「已回滚,Gately 正在重启…」,几秒后自动恢复。

回滚前的当前内容也会存成一个新的历史版本,所以回滚错了可以再回滚回来。

回滚的是整个文件

回滚把整个配置文件换成旧版本,期间对同一个文件做的其他修改也会一起退回。只想撤销其中一处时,先「对比」看清差异,再手动在界面里改回去。回滚会重启 Gately,所有转发与代理会中断几秒。

2. 手动下载一份备份 ​

升级前、做大改动前,先手动备份一份:

  1. 打开「系统 → 设置」,切到「备份与迁移」标签。

  2. 在「备份 Gately 配置」卡片点「下载备份」,浏览器下载 gately-backup-YYYYMMDD-HHMMSS.zip。

    下载备份与恢复配置

备份包内是配置目录根部的全部 *.json:账号、各模块规则、证书与私钥、DNS 服务商密钥、令牌哈希等。手动下载的备份不加密,请当作密码一样保管。

以下内容不在备份里:运行日志 logs/、操作审计 audit.log、配置历史 history/、本地定时备份 backups/,以及子目录中的数据(例如入侵防护的封禁列表、访客审计数据、在线安装的程序 bin/、组网客户端的状态目录)。

3. 从备份恢复 ​

  1. 在「恢复配置」卡片点「选择备份文件」,选中 .zip 或加密的 .zip.enc。选了加密备份时会多出「备份口令」输入框,填创建备份时设置的口令。

  2. 按需勾选「保留当前管理员账号」:勾选后,当前的账号、密码、两步验证、只读账号、API 令牌和管理界面的第三方登录保持不变,备份里的这些设置被忽略,备份也可以不含 account.json。不勾选时,恢复后要用备份里的账号密码登录。

  3. 点「恢复」,在确认框里输入「恢复」两个字,点「恢复并重启」。

    恢复前的确认

  4. Gately 先把现有配置复制到配置目录下的 backup-YYYYMMDD-HHMMSS 文件夹,再用备份覆盖,然后自动重启。成功后提示「已恢复 N 个配置文件,原配置保存在 …」。

恢复的限制:

  • 上传文件不超过 64 MB;
  • 只接受 zip 根目录下、非隐藏、内容为合法 JSON 的 *.json,其他条目忽略;
  • 不勾选「保留当前管理员账号」时,备份里必须有 account.json;
  • 管理员仍在使用默认密码时拒绝恢复,先在「账号与安全」里改密码;
  • 恢复账号文件后,恢复前登录的会话全部失效,需要重新登录。

恢复错了也能撤回:停止 Gately,把 backup-时间 文件夹里的文件拷回配置目录,再启动。

4. 设置定时备份并写到 NAS ​

手动备份容易忘。「备份与迁移」标签下方的「定时备份」卡片按计划自动打包:

  1. 打开卡片右上角的开关。

  2. 填写:

    设置示例说明
    执行计划0 3 * * *5 段 cron 表达式,示例为每天 03:00;也可以写 @daily、@weekly
    保留数量7每个目的地各保留最新的 N 份(1–365),多出的旧备份自动删除
    加密口令一段长口令设置后备份文件为 .zip.enc,恢复时要输入同一口令;留空不加密
    本地目录开启写入配置目录下的 backups 文件夹
  3. 点「保存设置」。

    定时备份卡片

备份和 Gately 放在同一块硬盘上,硬盘坏了会一起丢。再加一个远程目的地:

  1. 先到侧边栏「文件服务 → 存储挂载」添加 NAS 的 WebDAV 或 SMB 共享(只读或停用的挂载点不能选)。

  2. 回到「定时备份」卡片,在「远程目的地」右侧点「添加」:「名称」填 NAS 备份,「存储挂载」选刚才的挂载点,「目录」填 gately-backups(留空为挂载点根目录),保持「启用」,点「保存」。

    添加远程目的地

  3. 点「立即备份」执行一次。卡片的「最近一次」显示执行时间、是手动还是定时、下次执行时间,以及每个位置「成功」或「失败」和清理了几份旧备份;「本地备份文件」列出 backups/ 里的文件,可以直接下载。

可以添加多个目的地,所有位置使用同一个文件名。清理旧备份只处理文件名以 gately-backup- 开头、扩展名为 .zip 或 .zip.enc 的文件,目录里的其他文件不受影响。删除目的地不会删除已经写进去的备份。

记下加密口令

口令只保存在配置目录的 backup.json 里,口令丢了备份就解不开。把口令另外记在密码管理器里。backup.json 与备份放在同一台机器上时,加密的保护作用有限,所以远程目的地更重要。

备份失败时收到通知。 在 通知中心 添加订阅 backup.* 的规则:全部写入成功发出 backup.done,打包或任一位置写入失败发出 backup.failed,消息里列出每个位置的结果。配置方法见 配置告警通知。

5. 导出诊断包 ​

遇到问题要提 issue 或在群里求助时,诊断包能省掉很多来回询问:

  1. 「系统 → 设置」切到「诊断」标签。
  2. 卡片里列出「会导出」与「绝不导出」的内容。诊断包只包含版本、系统、模块状态摘要、配置结构(字段名、数字、开关、枚举值)与脱敏后的最近日志;密码、令牌、密钥、证书、域名、真实 IP、你填写的名称与备注都不会导出。
  3. 「包含最近日志」默认开启,日志对定位运行时错误最有帮助,建议保留。
  4. 点「预览内容」查看将要导出的全部文件,确认没有敏感信息后点「下载诊断包」,再点「去提交 issue」附上。

导出诊断包

诊断包在本机生成,不会上传到任何地方。自己填写的名称偶尔会出现在日志原文里,发布前务必预览。

6. 把配置迁到另一台机器 ​

两种做法,按情况选:

做法一:备份与恢复(推荐,跨平台)。 适合换硬件、从 Docker 换成 OpenWrt 安装包等。

  1. 旧机器:「备份与迁移」→「下载备份」。
  2. 新机器:安装 Gately,登录后先在「账号与安全」修改默认密码。
  3. 新机器:「恢复配置」选择备份文件。想沿用新机器上刚设好的账号,勾选「保留当前管理员账号」;想完整沿用旧机器的账号、两步验证与 API 令牌,不要勾选。
  4. 恢复后 Gately 自动重启。检查以下几项:
    • 在线安装的托管程序(frp、Tailscale、NetBird、EasyTier、File Browser 等)不在备份里,到对应页面重新安装;组网客户端可能需要重新登录;
    • 配置里引用的本机路径(静态站点目录、证书映射目录、脚本路径、存储挂载的本地目录)在新机器上要存在,Docker 部署时把同样的宿主机目录挂载到同样的容器路径;
    • 监听地址里写死的网卡 IP、DDNS 里按网卡取 IP 的设置,换机器后要改;
    • 旧机器停用前,新机器上的 DDNS 会把解析改到新机器的地址,确认无误后再停旧机器,避免两边来回改解析。

做法二:整个配置目录复制。 同平台搬家、想连封禁列表与组网状态一起带走时用:

  1. 两台机器都停止 Gately(Docker 用 docker compose stop,系统服务用 gately service stop)。
  2. 把旧机器的整个配置目录复制到新机器的配置目录,保持文件权限(配置文件为 0600)。
  3. 启动新机器上的 Gately。

配置目录是纯 JSON,也可以纳入 git 管理,或用启动参数 -apply <目录> 每次启动时把指定目录里的配置覆盖进来,适合批量部署,见 配置文件。

7. 从 Lucky 或 nginx 导入 ​

从其他工具迁过来不需要手动重建:

  • Lucky:「备份与迁移」标签顶部的「从 Lucky 导入」卡片,拖入 Lucky 配置目录里的 *.lkcf 文件(可多选)或 Lucky 导出的整站备份 .zip,先「预览」再「确认导入」。导入的规则默认是停用状态,同名条目跳过。完整对照表与切换顺序见 从 Lucky 迁移。
  • nginx 与 Nginx Proxy Manager:在「Web 服务」页的「导入 nginx」中粘贴 nginx -T 的输出,预览后导入,见 从 nginx 迁移。

导入前先下载一份备份,导入结果不满意时可以直接恢复。

验证 ​

  • 在任意页面改一项设置并保存,「配置历史」里对应文件多出一个版本,「对比」能看到这处修改;
  • 「立即备份」后,「最近一次」各位置显示「成功」;到 NAS 的 gately-backups 目录能看到 gately-backup-….zip.enc;
  • 在一台测试机或测试容器里用这份备份恢复一次,确认口令正确、能登录、站点与证书都在。没恢复过的备份不算可靠的备份;
  • 「日志 → 操作审计」里能看到下载备份、恢复、回滚的记录。

常见问题 ​

配置历史里没有某个文件。 那个文件还没有被修改过,或者它是 account.json、tokens.json,这两个文件不记录历史。

恢复时提示需要先修改密码。 新装的 Gately 仍在用默认密码时拒绝恢复,先在「账号与安全」改密码。

恢复后登录不上。 没有勾选「保留当前管理员账号」时,账号密码与两步验证都换成了备份里的。用旧机器的账号登录;彻底忘记时在服务器上执行 gately reset-password,见 重置密码与两步验证。

加密备份恢复失败。 口令错误或文件损坏。确认用的是创建这份备份时的口令;中途改过口令的话,旧备份仍要用旧口令。

定时备份某个目的地失败。 「最近一次」里该位置显示错误原因,常见是挂载点离线、目录不可写或空间不足。去「存储挂载」检查连通性;在通知中心订阅 backup.failed 就能第一时间知道。

没有启用本地目录也没有目的地。 这种情况下备份记为失败,至少开启「本地目录」或一个远程目的地。

下一步 ​

以 Apache-2.0 许可证开源发布。