异常回退

本页面用于已确认当前版本影响业务、需要恢复到上一版交付状态的情况。回退前先保留证据和备份；网络抖动、配置错误等可定位问题应先按故障排查处理。首次部署请阅读系统部署，常规升级请阅读已有环境升级。

什么时候需要回退

出现以下情况且按故障排查无法在维护窗口内恢复时，可评估回退：

• 核心服务持续重启或无法完成健康检查；
• 登录、已知业务数据查询等关键功能因版本变化不可用；
• 人员同步或识别闭环在升级前正常、升级后持续失败；
• 目标版本与现场设备或终端版本存在已确认的兼容问题。

回退是版本恢复操作，不等同于恢复历史数据。是否恢复数据库和文件资源，要根据故障范围和备份时间单独决定。

回退前保留信息

1. 记录故障发生时间、当前版本、部署参数、服务状态和相关终端版本。
2. 保存升级后的服务日志、浏览器错误和一条可复现的业务记录，截图和日志先脱敏。
3. 确认上一版镜像交付包、对应配置和可读取的数据库与文件资源备份。
4. 停止继续录入、人员调整和设备配置变更，避免回退期间产生新的差异。
5. 明确回退负责人和验收人员，确认回退窗口内能够访问主机和现场终端。

执行版本回退

1. 进入上一版部署包目录，按该版本交付记录设置数据库密码、Web 端口和中心主机地址：

   cd /path/to/previous-deployment-package
   export MYSQL_ROOT_PASSWORD='请通过受控方式设置'
   export DISCOVERY_HOST='192.168.1.20'
   export DISCOVERY_HTTP_BASE_URL="http://${DISCOVERY_HOST}:${WEB_PORT:-80}"

2. 加载上一版镜像并启动服务：

   bash deploy/load-and-start.sh

   如果镜像已经加载，只需执行 bash deploy/start.sh。这些操作会重建容器，但不应删除现有数据卷。

3. 查看状态和日志：

   bash deploy/status.sh
   docker compose logs --tail=100 server web mysql

4. 按下方清单完成回退后验收。确认业务恢复前，不要恢复现场批量操作。

回退后验收

层级	检查	通过标准
服务	docker compose ps、服务日志	三个服务稳定运行，数据库健康
Web	登录管理页面	页面、账户和权限正常
数据	查询升级前已知数据	数据和文件资源与回退目标一致
节点发现	GET /api/discovery/nodes	录入端和大屏端能够被发现
人员同步	检查一名测试人员	目标设备资料和处理结果恢复正常
识别闭环	完成一次真实测试识别	接收端和大屏显示同一人员、设备和时间

是否恢复数据

• 仅镜像或运行逻辑异常时，先保留当前数据卷，只回退镜像并验收。
• 数据已经损坏、误写或与目标版本不兼容时，才评估恢复数据库或文件资源。
• 执行数据恢复前，先备份当前异常状态，确认备份时间点和恢复范围，并记录审批结果。
• 恢复数据后重新执行登录、查询、同步和识别验收；不要把未经确认的历史数据直接导入生产环境。

回退注意事项

• 严禁使用 docker compose down -v，不要手动删除 vittor_mysql_data、vittor_runtime 或 vittor_resource。
• 不要混用旧版镜像、新版 Compose 文件和新版环境参数。
• 没有匹配的上一版交付包或可读取备份时，先暂停回退并联系交付负责人。
• 回退完成后保留故障日志、版本信息、验收结果和未解决事项，便于后续修复。