配置历史、备份与迁移
网关上的配置往往是一点点攒出来的:几十个站点、证书、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 令牌)不记录历史。
打开侧边栏「系统 → 日志」,切到「配置历史」标签(地址
#/logs/history)。左上角下拉选择配置文件。模块配置显示为「模块名 (文件名)」,例如「Web 服务 (webservice.json)」;系统设置是
gately.json。表格按时间倒序列出版本,每一行是那个时刻被覆盖前的内容。

点某一行的「对比」,弹窗按行列出该版本与当前配置的差异:红色
-行是所选历史版本的内容,绿色+行是当前内容,没变的大段内容折叠为「省略 N 行未变更内容」。完全相同时显示「与当前配置完全一致」。
上图能看出:从那个版本到现在,Jellyfin 的后端从
.20改成了.21,并打开了网页认证。确认要退回到这个版本,点「回滚」,在确认框中点「回滚」。

界面提示「已回滚,Gately 正在重启…」,几秒后自动恢复。
回滚前的当前内容也会存成一个新的历史版本,所以回滚错了可以再回滚回来。
回滚的是整个文件
回滚把整个配置文件换成旧版本,期间对同一个文件做的其他修改也会一起退回。只想撤销其中一处时,先「对比」看清差异,再手动在界面里改回去。回滚会重启 Gately,所有转发与代理会中断几秒。
2. 手动下载一份备份
升级前、做大改动前,先手动备份一份:
打开「系统 → 设置」,切到「备份与迁移」标签。
在「备份 Gately 配置」卡片点「下载备份」,浏览器下载
gately-backup-YYYYMMDD-HHMMSS.zip。
备份包内是配置目录根部的全部 *.json:账号、各模块规则、证书与私钥、DNS 服务商密钥、令牌哈希等。手动下载的备份不加密,请当作密码一样保管。
以下内容不在备份里:运行日志 logs/、操作审计 audit.log、配置历史 history/、本地定时备份 backups/,以及子目录中的数据(例如入侵防护的封禁列表、访客审计数据、在线安装的程序 bin/、组网客户端的状态目录)。
3. 从备份恢复
在「恢复配置」卡片点「选择备份文件」,选中
.zip或加密的.zip.enc。选了加密备份时会多出「备份口令」输入框,填创建备份时设置的口令。按需勾选「保留当前管理员账号」:勾选后,当前的账号、密码、两步验证、只读账号、API 令牌和管理界面的第三方登录保持不变,备份里的这些设置被忽略,备份也可以不含
account.json。不勾选时,恢复后要用备份里的账号密码登录。点「恢复」,在确认框里输入「恢复」两个字,点「恢复并重启」。

Gately 先把现有配置复制到配置目录下的
backup-YYYYMMDD-HHMMSS文件夹,再用备份覆盖,然后自动重启。成功后提示「已恢复 N 个配置文件,原配置保存在 …」。
恢复的限制:
- 上传文件不超过 64 MB;
- 只接受 zip 根目录下、非隐藏、内容为合法 JSON 的
*.json,其他条目忽略; - 不勾选「保留当前管理员账号」时,备份里必须有
account.json; - 管理员仍在使用默认密码时拒绝恢复,先在「账号与安全」里改密码;
- 恢复账号文件后,恢复前登录的会话全部失效,需要重新登录。
恢复错了也能撤回:停止 Gately,把 backup-时间 文件夹里的文件拷回配置目录,再启动。
4. 设置定时备份并写到 NAS
手动备份容易忘。「备份与迁移」标签下方的「定时备份」卡片按计划自动打包:
打开卡片右上角的开关。
填写:
设置 示例 说明 执行计划 0 3 * * *5 段 cron 表达式,示例为每天 03:00;也可以写 @daily、@weekly保留数量 7每个目的地各保留最新的 N 份(1–365),多出的旧备份自动删除 加密口令 一段长口令 设置后备份文件为 .zip.enc,恢复时要输入同一口令;留空不加密本地目录 开启 写入配置目录下的 backups文件夹点「保存设置」。

备份和 Gately 放在同一块硬盘上,硬盘坏了会一起丢。再加一个远程目的地:
先到侧边栏「文件服务 → 存储挂载」添加 NAS 的 WebDAV 或 SMB 共享(只读或停用的挂载点不能选)。
回到「定时备份」卡片,在「远程目的地」右侧点「添加」:「名称」填
NAS 备份,「存储挂载」选刚才的挂载点,「目录」填gately-backups(留空为挂载点根目录),保持「启用」,点「保存」。
点「立即备份」执行一次。卡片的「最近一次」显示执行时间、是手动还是定时、下次执行时间,以及每个位置「成功」或「失败」和清理了几份旧备份;「本地备份文件」列出
backups/里的文件,可以直接下载。
可以添加多个目的地,所有位置使用同一个文件名。清理旧备份只处理文件名以 gately-backup- 开头、扩展名为 .zip 或 .zip.enc 的文件,目录里的其他文件不受影响。删除目的地不会删除已经写进去的备份。
记下加密口令
口令只保存在配置目录的 backup.json 里,口令丢了备份就解不开。把口令另外记在密码管理器里。backup.json 与备份放在同一台机器上时,加密的保护作用有限,所以远程目的地更重要。
备份失败时收到通知。 在 通知中心 添加订阅 backup.* 的规则:全部写入成功发出 backup.done,打包或任一位置写入失败发出 backup.failed,消息里列出每个位置的结果。配置方法见 配置告警通知。
5. 导出诊断包
遇到问题要提 issue 或在群里求助时,诊断包能省掉很多来回询问:
- 「系统 → 设置」切到「诊断」标签。
- 卡片里列出「会导出」与「绝不导出」的内容。诊断包只包含版本、系统、模块状态摘要、配置结构(字段名、数字、开关、枚举值)与脱敏后的最近日志;密码、令牌、密钥、证书、域名、真实 IP、你填写的名称与备注都不会导出。
- 「包含最近日志」默认开启,日志对定位运行时错误最有帮助,建议保留。
- 点「预览内容」查看将要导出的全部文件,确认没有敏感信息后点「下载诊断包」,再点「去提交 issue」附上。

诊断包在本机生成,不会上传到任何地方。自己填写的名称偶尔会出现在日志原文里,发布前务必预览。
6. 把配置迁到另一台机器
两种做法,按情况选:
做法一:备份与恢复(推荐,跨平台)。 适合换硬件、从 Docker 换成 OpenWrt 安装包等。
- 旧机器:「备份与迁移」→「下载备份」。
- 新机器:安装 Gately,登录后先在「账号与安全」修改默认密码。
- 新机器:「恢复配置」选择备份文件。想沿用新机器上刚设好的账号,勾选「保留当前管理员账号」;想完整沿用旧机器的账号、两步验证与 API 令牌,不要勾选。
- 恢复后 Gately 自动重启。检查以下几项:
- 在线安装的托管程序(frp、Tailscale、NetBird、EasyTier、File Browser 等)不在备份里,到对应页面重新安装;组网客户端可能需要重新登录;
- 配置里引用的本机路径(静态站点目录、证书映射目录、脚本路径、存储挂载的本地目录)在新机器上要存在,Docker 部署时把同样的宿主机目录挂载到同样的容器路径;
- 监听地址里写死的网卡 IP、DDNS 里按网卡取 IP 的设置,换机器后要改;
- 旧机器停用前,新机器上的 DDNS 会把解析改到新机器的地址,确认无误后再停旧机器,避免两边来回改解析。
做法二:整个配置目录复制。 同平台搬家、想连封禁列表与组网状态一起带走时用:
- 两台机器都停止 Gately(Docker 用
docker compose stop,系统服务用gately service stop)。 - 把旧机器的整个配置目录复制到新机器的配置目录,保持文件权限(配置文件为 0600)。
- 启动新机器上的 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 就能第一时间知道。
没有启用本地目录也没有目的地。 这种情况下备份记为失败,至少开启「本地目录」或一个远程目的地。
下一步
- 配置告警通知:备份失败、证书续期失败时推送到手机;
- API、命令行与 MCP 自动化:用脚本管理配置;
- 配置备份与定时备份、审计与配置历史:完整说明;
- 从 Lucky 迁移、从 nginx 迁移。