跳转到内容
BangNiCMS 文档

模型包升级与版本

模型包发布新版本时，可能新增字段、修改字段类型、删除字段——直接影响已录入的数据。本节讲安全升级流程。

版本号机制

Section titled “版本号机制”

模型包用 semver（X.Y.Z）：

数字含义例子
X（主版本）重大变更（删字段、改类型）1.x → 2.x
Y（次版本）新增字段、增功能1.5 → 1.6
Z（补丁版本）修 bug、调默认值1.5.1 → 1.5.2

规律：

  • Z 升级 → 几乎无风险
  • Y 升级 → 低风险（新增不破坏现有）
  • X 升级 → 必须谨慎，可能破坏数据

升级前必做的 3 件事

Section titled “升级前必做的 3 件事”

  1. 看新版的 changelog / release notes

    开发者应该清晰列出：

    • 新增了哪些字段
    • 修改了哪些字段（类型变更等）
    • 删除了哪些字段
    • 是否需要数据迁移
    • 兼容性说明

  2. 数据库完整备份

    让运维做一份完整备份。详见 备份与升级（建设中）。

  3. 测试环境先跑一次

    • 把新版包先装到测试环境
    • 抽测 5-10 条已录入的内容看升级后是否正确
    • 测试通过再上生产

升级流程

Section titled “升级流程”

  1. 进「扩展市场 → 模型包」 → 点 上传模型包

  2. 上传新版 .zip（同 extensionKey）

  3. 系统检测到旧版本 → 弹窗显示变更预览：

    即将升级：工业设备字段 v1.2 → v2.0
    

    ✓ 新增字段（3 个）：
      - cad_drawings    (CAD 图纸 多文件上传)
      - iso_certifications (ISO 认证 多选标签)
      - safety_video    (安全视频 视频上传)
    

    ⚠️ 修改字段（1 个）：
      - specifications  (规格表)
        类型变更：短文本 → 富文本
        现有数据：自动包装为 <p>...</p>
        受影响内容数：247
    

    ✗ 删除字段（1 个）：
      - legacy_serial_no (旧版序列号)
        受影响内容数：127
        数据将丢失！
    

        □ 我已确认 "legacy_serial_no" 数据可丢弃

  4. 认真审核每条变更

  5. 如果有”删除字段” → 必须勾选确认框才能继续

  6. 点 确认升级

  7. 系统执行：

    • 新字段：在数据库追加（默认值为空 / null）
    • 修改字段：按 manifest 的迁移规则转换
    • 删除字段：定义和数据永久删除

  8. 升级完成 → 状态保持原样（active 仍是 active）

待补充截图 弹窗清晰显示新增 / 修改 / 删除字段，且删除项需要勾选确认
模型包升级的变更预览弹窗

升级后立刻验证

Section titled “升级后立刻验证”

升级成功后，立刻抽样检查：

检查怎么看
新字段在编辑页出现进任一产品的编辑页
现有数据完整抽 5-10 条产品，对比升级前后字段值
类型变更的数据详细查看（富文本 / 数字 / 日期）
前台没崩溃打开产品详情页确认
API 返回正常开发工具 F12 看 API 响应没报错

回滚

Section titled “回滚”

如果升级后发现严重 bug，怎么回滚：

方式 A：装回旧版包

Section titled “方式 A：装回旧版包”

最简单。前提：你有旧版 zip 包备份。

  1. 卸载当前新版（选归档卸载保留数据）

  2. 上传旧版 zip 包

  3. 旧版字段恢复，已录入的数据部分恢复：

    • 旧版本里有的字段：数据可能恢复（如果归档了）
    • 新版本独有的字段：数据丢失

问题：

  • 升级时新字段已经在产品里录了一些 → 卸载新版 = 这些数据丢
  • 升级时类型变更已经把旧数据转换 → 卸载新版后旧数据还是新格式

总结：装回旧版只能在升级后很短时间内做（几小时内、运营还没大规模录新字段）。

方式 B：从数据库备份恢复

Section titled “方式 B：从数据库备份恢复”

如果升级后已经录了大量新字段数据，回滚 = 数据库整表恢复。

  1. 让运维从升级前的备份恢复数据库

  2. 站点回到升级前状态

  3. 升级期间录入的所有新内容全部丢失

  4. 重新评估升级方案

升级时机

Section titled “升级时机”
时机适合不适合
业务低峰期（晚上 / 周末）✅高峰时段
运维 / 开发者在岗✅节假日无人值守
数据库有最新备份（< 24h）✅备份过老
已在测试环境验证过✅直接生产升级

跨多个版本升级

Section titled “跨多个版本升级”

如果你的版本很旧（如 1.0），新版是 3.5——跨大版本升级：

两种思路：

方式 A：直接升到最新

Section titled “方式 A：直接升到最新”
  • 优势：只跑一次升级
  • 风险：如果中间某个版本有数据迁移脚本，可能跳过

方式 B：逐版本升级

Section titled “方式 B：逐版本升级”
  • 1.0 → 1.5 → 2.0 → 3.0 → 3.5
  • 每步都跑迁移
  • 优势：稳妥，每一步可回滚
  • 劣势：耗时长

推荐：

  • 从 X.Y 跨到 X.(Y+多)：直接升
  • 跨主版本 X：建议逐主版本升级

具体让开发者评估。

升级失败了怎么办

Section titled “升级失败了怎么办”
现象怎么办
升级中断看 server 日志报错 → 修复后重试
数据迁移失败让运维从备份恢复 → 等开发者修复迁移脚本
字段冲突升级失败前已停止 → 解决冲突再重试
前台报错立即停用该模型包 → 联系开发者

常见问题

Section titled “常见问题”

升级会不会让前台短暂崩溃？

Section titled “升级会不会让前台短暂崩溃？”

升级期间（通常几秒）：

  • 数据库 schema 变更瞬间完成
  • 现有用户已经渲染的页面不受影响（用浏览器缓存）
  • 升级完成瞬间之后，新加载的页面用新版字段

实际感受：访客几乎察觉不到。但如果升级失败导致部分字段 / 数据异常，可能让前台部分内容显示异常。

模型包能”跳过升级”吗（一直用旧版）？

Section titled “模型包能”跳过升级”吗（一直用旧版）？”

可以——只要旧版仍在服务器上 + 状态是 active。不强制升级。

但长期不升级的代价：

  • 错过新字段 / 新功能
  • 错过 bug 修复
  • 安全风险（罕见但存在）

建议每季度评估一次是否升级。

我能在升级前看到数据迁移的具体 SQL 吗？

Section titled “我能在升级前看到数据迁移的具体 SQL 吗？”

当前后台不暴露 SQL——但开发者会在 manifest 里写迁移规则。让开发者给你 changelog + 迁移说明。

升级模型包会影响其他模型包吗？

Section titled “升级模型包会影响其他模型包吗？”

通常不会——每个模型包的字段独立。但如果新版字段名字撞车了别的包的字段名，会被校验拦下。

同时启用了多个模型包，能批量升级吗？

Section titled “同时启用了多个模型包，能批量升级吗？”

当前不支持批量 —— 必须一个一个升级。逐个升级也更安全（一个失败不影响其他）。

接下来

Section titled “接下来”