升级、回滚与备份

升级只替换镜像和部署文件。.env、state/machine-id 和 gateway_state 卷保留，许可的主机指纹不变，升级后不需要重新激活。

升级必须在原安装目录进行。compose 的项目名取自目录名，卷名为 <目录名>_gateway_state，换一个目录就会用上一个新的空卷。

用安装命令升级

适用于用 install.sh 安装、安装目录为 /opt/rst-ai-copilot-for-zabbix 的部署。2.0.2 之前的安装目录是 /opt/rst-zabbix-ai-copilot，脚本发现它里面有 .env 时会沿用这个目录原地升级。

步骤

1. 再次执行安装时的命令。安装指定版本时加 --version <x.y.z>：

   curl -fsSL https://github.com/Reallysec/RST-AI-Copilot-for-Zabbix/releases/latest/download/install.sh | sudo bash

2. deploy.sh 询问是否保留现有 .env 时，输入 y。

3. 询问是否重建并启动时，选择是。

脚本校验签名后删除目录中旧版本的镜像包，解压新交付包，加载新镜像并重启容器。

从 2.0.1 及更早升级到 2.0.2

2.0.2 起安装包、镜像和容器随产品改名：安装包 RST-AI-Copilot-for-Zabbix-<版本>.tar.gz，网关镜像 rst-ai-copilot-for-zabbix-gateway，容器 rst-ai-copilot-for-zabbix-gateway、rst-ai-copilot-for-zabbix-caddy。2.0.1 及更早的网关找不到改名后的安装包，在线更新到 2.0.2 会失败，需要手动升级一次，任选一种：

• 用安装命令升级。脚本会沿用老目录 /opt/rst-zabbix-ai-copilot。
• 用交付包升级：解压到原安装目录，运行 ./deploy.sh 并保留 .env。

数据卷和许可绑定不变：卷名由安装目录名决定，state/machine-id 也在安装目录里，所以一定要在原目录升级。旧容器会被替换为新名字的容器。之后照常在线更新。

从 2.0.0 升级

2.0.1 起不再使用 Caddy 的 Basic Auth，改用网关自带的登录页，账号在用户页管理。原来的 Basic Auth 账号不再使用，.env 中的 CADDY_BASIC_AUTH_USER、CADDY_BASIC_AUTH_HASH 可以删除。

2.0.0 的 .env 中没有 RST_ADMIN_PASSWORD_HASH，这时管理员 admin 只有出厂密码，只能从网关主机本机登录，浏览器登录返回 403。deploy.sh 和 rst-update.sh 结束时都会提示。升级后在安装目录执行：

docker exec rst-ai-copilot-for-zabbix-gateway python -m backend.session_auth '<密码>'

把输出写入 .env 的 RST_ADMIN_PASSWORD_HASH=（每个 $ 写成 $$），再执行 docker compose -f docker-compose.prod.yml up -d，然后以 admin 和这个密码登录。

用交付包升级

步骤

1. 删除原安装目录中旧版本的镜像包，再把新交付包解压到原安装目录：

   rm <安装目录>/RST-AI-Copilot-for-Zabbix-images-*.tar
   tar xzf RST-AI-Copilot-for-Zabbix-<新版本>.tar.gz --strip-components=1 -C <安装目录>
   cd <安装目录>
   sudo ./deploy.sh

2. 询问是否保留现有 .env 时，输入 y。询问是否重建并启动时，选择是。

deploy.sh 只加载目录中找到的第一个镜像包，所以先删除旧镜像包。

社区版升级

所有版本使用同一个交付包。管理员在 设置 > 产品激活 中导入专业版或企业版许可即可，不需要重装，数据与主机指纹保留。见产品激活。

在线更新

前提条件

• 网关主机可以访问 github.com 及其下载域名的 443 端口。版本清单和交付包从 GitHub Releases 读取。离线激活的主机不检查更新。

步骤

1. 在设置的 版本与更新 中查看 在线更新。网关每天自动检查一次，也可以选择 立即检查。

2. 显示「发现新版本」时，选择 下载并暂存。网关校验签名清单和 SHA-256 后，把交付包暂存到安装目录的 ./release/。

3. 在网关主机的安装目录执行：

   sudo ./deploy/rst-update.sh

rst-update.sh 不信任网关下载的内容，在主机上用内置公钥重新校验签名清单和交付包，然后加载镜像，用新版本的 compose 文件和 Caddyfile 替换现有文件（旧文件保留为 .bak），切换 .env 中的 GATEWAY_IMAGE_TAG 并重启网关。120 秒内容器健康检查连续 3 次成功视为升级成功，否则自动回滚到上一版本。.env 和 ./certs 不会被改动。

内容包

内容包是签名的提示词与模板，独立于版本发布，不需要重启网关。网关每天自动检查更新，管理员也可以选择 立即检查，检查时同时检查 GitHub 上是否有比当前更新的内容包，验签通过后直接启用。

要由管理员手动启用时，在 .env 中设置 RST_CONTENT_AUTO_APPLY=0，重建网关容器，见配置项参考。这时新内容包只下载、校验并保存在本机，管理员在 设置 > 内容包 中找到该版本，选择 回滚到此版本 启用。

离线环境在同一张卡片的 导入内容包 中粘贴内容包令牌，选择 验签并导入。签名不通过或版本比当前旧时拒绝导入。要回到本机保存过的旧版本，同样选择该版本的 回滚到此版本。

手动切换镜像版本

步骤

1. 加载新镜像并修改 .env：

   docker load -i RST-AI-Copilot-for-Zabbix-images-<新版本>.tar
   sed -i 's/^GATEWAY_IMAGE_TAG=.*/GATEWAY_IMAGE_TAG=<新版本>/' .env

   .env 中没有 GATEWAY_IMAGE_TAG 时，在末尾加一行 GATEWAY_IMAGE_TAG=<新版本>。

2. 执行 docker compose -f docker-compose.prod.yml up -d。

回滚时用同样的方法把 GATEWAY_IMAGE_TAG 改回上一版本。本产品不修改 Zabbix 中的数据，回滚不影响 Zabbix。

备份对象

Zabbix 中的主机、问题、触发器和历史数据不由本产品备份。网关中的告警是副本，丢失后从 Zabbix 重新拉取，只丢失 AI 摘要。

备份网关状态

备份和恢复脚本用网关镜像读写卷，不需要额外镜像，在安装目录中执行即可。

步骤

1. 在安装目录执行：

   bash scripts/backup.sh /backup/rst-copilot

2. 把备份目录权限设为 700：chmod 700 /backup/rst-copilot。

脚本把 gateway_state 卷打包为 gateway-state-<时间>.tar.gz，把 state/machine-id 复制为 machine-id-<时间>，并删除该目录中超过 30 天的备份（由 RETENTION_DAYS 调整）。不指定目录时写入 ./backups。SSO 部署加 COMPOSE_FILE=docker-compose.sso.yml。每日执行可以加入 cron：

0 2 * * * cd /opt/rst-ai-copilot-for-zabbix && bash scripts/backup.sh /backup/rst-copilot >> /var/log/rst-backup.log 2>&1

恢复网关状态

步骤

1. 在安装目录执行恢复脚本：

   bash scripts/restore.sh /backup/rst-copilot/gateway-state-<时间>.tar.gz

   脚本停止容器（不删除卷），恢复同一时间的 machine-id-<时间>，清空并重新写入卷，然后启动容器。machine-id 文件也可以作为第二个参数指定。

2. 打开产品激活，确认许可状态为有效。

machine-id 必须与激活许可时的一致，否则许可报绑定的是另一台机器。恢复到另一台主机时，许可可能需要重新激活。在线激活的许可先在旧主机的 撤销激活 中选择 撤销当前 license。

保留期

gateway_state 卷中的这些数据按上表自动清理。修改保留期时在 .env 中设置对应配置项，重建网关容器。