升级、备份与排障

升级前

1. 确认目标版本、源码提交或镜像标识，阅读其迁移和配置要求。
2. 备份当前数据库，并保留与其兼容的应用版本及配置。
3. 在隔离环境恢复备份或使用虚构数据，验证迁移与关键流程。
4. 安排作业窗口，避免在门店报货或仓库集中出入库时修改数据库结构。

执行迁移

业务仓库使用 Prisma 版本化迁移。部署已有迁移的命令是：

npm run db:deploy

该命令必须在配置正确、具备对应运行依赖的环境中执行。项目 Compose 使用专门的迁移任务；不要未经检查又在其他实例并行手工执行初始化。

不跳过迁移

不要用 prisma db push 代替已提交的迁移，也不要因为迁移失败就手工将其标记为成功。先保留错误信息，查明数据库实际状态。

升级后验证

• 进程或容器健康，应用健康检查通过。
• 管理端与移动端可以登录，角色与数据访问范围正常。
• 商品、库存和历史单据可读取。
• 在隔离测试数据中验证下单、审批、出库、收货。
• 核对包装物申请与实收、库存流水和报表。

备份与恢复

备份至少覆盖数据库，以及业务实际使用的商品图片等自管文件。配置与密钥应单独安全保管，不应被公开打包到备份说明或仓库中。

为备份设置明确的保留周期、加密和访问控制，并定期在隔离环境恢复验证。仅有“备份成功”日志不足以证明可以恢复。

回退边界

应用回退和数据库回退不是同一件事。数据库迁移后，旧应用未必兼容；直接恢复旧备份会丢失备份之后的新业务数据。

先判断迁移兼容性与新增数据范围，再选择经验证的修复、应用回退或数据恢复方案。没有可靠方案时，应暂停进一步变更，而不是反复重启。

常见部署问题

现象	首先检查
数据库连接失败	实际连接配置、服务可达性、账号权限，不要公开完整连接串
初始账号不能登录	初始化任务是否成功、账号是否已存在、密码是否被后续修改
管理端与移动端来回跳转	Host、规范域名、反向代理和 Cookie 范围
应用运行但下不了单	门店关联、报货时间、单仓可用库存及待处理订单
升级后字段缺失或查询报错	目标版本对应迁移是否真实完成

反馈时提供版本、脱敏错误和复现步骤。安全问题按项目安全策略私下报告。