备份、升级与多实例

升级不仅是替换 JAR 或镜像。数据库、文件、密钥和配置共同决定能否恢复；应用版本回退不等于数据库回滚。

需要备份哪些内容

内容	为什么要保留
MySQL 数据与 Flyway 历史	账号、业务、文件元信息、迁移版本
本地上传卷 / 云存储对象	图片、附件等实际文件内容，数据库中仅有定位信息
config/application-prod.yml	连接配置、业务参数、通知和支付密钥
deploy/compose.prod.yml	Docker 资源、端口与 MySQL 管理员凭据
持久化 RSA 私钥	保持部署密钥一致，尤其多实例场景
对应应用版本	恢复时需要与数据结构兼容的程序

这些内容应按同一次备份记录关联起来。只有数据库没有文件，会出现“列表记录存在，但附件打不开”；只有数据库没有支付加密密钥，则不能正常解密已有商户凭据。

升级前准备

记录应用构建版本、Flyway 版本、配置版本及备份时间。在隔离的脱敏副本验证迁移与关键业务，再安排实际维护窗口。

备份至少覆盖 MySQL、文件内容或对象版本清单、两份客户实际 YAML、持久化 RSA 私钥、通知签名密钥和支付凭据加密密钥。密钥通过受控加密备份保存，不写进普通备份清单或日志。

确认停写后再做一致备份

站点 maintenanceMode 只提供维护公告，不阻止 API、已有会话、回调或后台任务。关闭 app.mall.scheduler.enabled 也只关闭商城调度，不能作为全站停写证明。

1. 在网关阻断业务写入口，考虑上传、长连接、回调及绕过网关的入口。
2. 排空请求与外部调用，停止全部应用实例、任务进程和外部写入脚本。
3. 确认数据库无应用写事务、存储无上传或删除后，在同一停写窗口完成数据库与文件/对象备份。
4. 校验备份与清单，保持停写，启动一个新版本实例迁移与验收。
5. 成功后启动其他同版本实例，恢复入口并核对停机期间的支付、退款与任务积压。

mysqldump --single-transaction 仅提供数据库事务快照，不自动让随后复制的文件一致，也不覆盖并发 DDL。对象存储开启版本化不等于已有可恢复且与数据库对应的备份。

程序升级

随包 Docker 保留实际 YAML，更新已验证源码后执行 sh scripts/deploy.sh update。仅配置变更使用 config。JAR 使用独立发布目录，不 clean 或覆盖正在运行实例依赖的文件。

保留已发布 Flyway 文件，新结构使用更高版本迁移；不删历史表、不自动扩大自定义角色授权。迁移异常保留现场，再评估新增修复迁移或经过演练的整库恢复。

停写流程中需要停止随包生产服务时，在后端根目录执行：

docker compose --env-file /dev/null -p art-design-pro-x-java -f docker-compose.yml -f deploy/compose.prod.yml stop

这保留数据卷；恢复服务仍走 sh scripts/deploy.sh update（代码升级）或 config（已有镜像配置更新）。不要执行 down -v，它会删除数据卷；也不要在客户更新中重新初始化数据库或用模板覆盖配置。

数据库备份应由客户选定的备份工具或 DBA 在上述停写方案下完成。使用外置对象存储时同步记录桶、版本与备份位置，不在备份命令中明文展开密码。

恢复演练

在隔离数据库、文件桶/目录与 Redis 中恢复备份对应的应用版本、配置和密钥。演练实例不能连接生产存储、支付或通知服务；关闭商城任务仍不足以隔离所有后台写入，必须用独立依赖与网络限制。

验证登录、菜单、文件引用、商品/SKU、分仓库存、订单、售后及支付流水，检查库存非负与聚合一致，记录恢复时间和数据恢复点。只生成文件而未验证恢复，不算完成恢复能力验收。

多实例共同服务

启用 app.deployment.multi-instance=true 前准备：

状态	同一部署各实例的要求
MySQL	同一业务数据库与兼容迁移版本
Redis	同一实例/逻辑库与 art.cache.key-prefix
RSA	挂载相同持久化私钥，通过 app.crypto.private-key-path 指定
通知	相同且至少 32 字节的 stream-token-secret，同一通知频道
支付	相同 credential-key 与对应数据库凭据
云存储	相同对象定位、桶与授权配置
本地文件	所有节点挂载同一共享卷，并声明 shared-local-storage=true

相同本机路径不代表共享目录，配置开关也不会创建共享卷。历史 LOCAL 对象同样需要共享或先迁移。

通知 Pub/Sub 不提供离线重放，断线通过持久化收件箱补齐。任务跨节点仍需有界与幂等；FORBID 固定租约不支持任意长运行。

滚动发布

只有验证新旧代码、数据库迁移与状态协议兼容后才使用滚动发布。尤其库存、支付与文件恢复协议变化时，不能让旧实例继续按旧规则写同一数据。

容量、故障恢复和备份策略需在实际客户环境验证，随包文档 mall-operations.md、identity-storage.md 提供进一步操作依据。