已有环境升级

本页面只介绍已经运行的 Vittor 环境如何升级。升级使用新的镜像交付包，并保留现有业务数据和文件资源；首次部署请阅读系统部署，发生异常需要恢复时请阅读异常回退。

升级前确认

1. 确认目标版本、交付包来源和校验值，安排维护窗口并通知现场使用人员。
2. 查看当前服务状态，记录当前版本、镜像摘要、部署参数、终端版本和最近一次成功识别时间。
3. 备份数据库、人员照片和其他文件资源，实际读取备份内容，确认能够按计划恢复。
4. 确认目标版本的端口、环境参数和终端兼容范围；复用现有数据时，数据库密码必须与当前环境一致。
5. 暂停升级期间的批量录入、人员调整和设备配置变更，避免新旧版本同时写入业务数据。

不要通过删除数据卷来“清理”升级问题。升级前的备份和当前服务记录是回退判断的依据。

执行升级

1. 将目标版本部署包复制到主机，进入部署包目录。不要覆盖或删除现有数据卷。

2. 按当前环境设置参数，至少确认数据库密码、Web 端口和中心主机地址：

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

3. 加载新镜像并启动服务：

   bash deploy/load-and-start.sh

   如果镜像已经单独加载，只需执行 bash deploy/start.sh。脚本会重新创建容器，但保留业务数据和文件资源。

4. 查看服务状态和日志，确认数据库健康、服务没有持续重启：

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

5. 升级完成后，再恢复录入、人员调整和设备配置等日常操作。

升级后验收

层级	检查	通过标准
服务	docker compose ps、服务日志	三个服务稳定运行，数据库健康
Web	登录管理页面	页面可访问，账户和权限正常
数据	查询已知组织、空间和人员	数据、照片和文件资源可读取
节点发现	GET /api/discovery/nodes	录入端和大屏端地址可达
终端配置	检查系统配置和终端设置	中心地址未丢失，终端能够重新连接
人员同步	修改一名测试人员	中心记录、目标设备和处理结果一致
识别闭环	完成一次真实测试识别	接收端和大屏显示同一人员、设备和时间

升级期间若发现异常，先保留日志和当前状态，不要连续重复加载不同版本。确认问题属于版本变更后，按异常回退处理。

升级注意事项

• 升级只替换镜像和容器，不会让已有数据卷重新执行初始化。
• 不要使用 docker compose down -v，也不要手动删除 vittor_mysql_data、vittor_runtime 或 vittor_resource。
• 不要混用旧版镜像、新版 Compose 文件和不匹配的环境参数。
• 升级记录、备份和日志应纳入现场交付档案，截图和问题单必须脱敏。