版本升级

升级组成

版本升级依次处理数据库、后端服务和前端产物：数据库按版本区间执行增量脚本，后端替换为目标版本产物，AI 前端以目标版本目录发布联邦产物并切换宿主注册表。

一、升级前准备

1. 确认当前版本与目标版本。后端以运行中的产物版本为准，AI 前端以线上注册表中 ai 条目的 version 为准。
2. 阅读目标版本的版本日志，以及 doc/sql/upgrade/ 下对应升级脚本内的说明。
3. 完整备份数据库，同时备份原始资料与作品文件、关键环境配置和线上注册表，备份范围见 日志、备份与监控。
4. 保留当前版本的后端产物（JAR 或镜像）与 AI 版本目录，供回滚使用。

先行演练

在与生产结构一致的测试环境中，用生产库的备份按本页顺序演练一次，确认脚本执行、服务启动与业务核验都通过后再升级生产环境。

二、执行数据库升级脚本

升级脚本位于 doc/sql/upgrade/，命名为 bladex.mysql.ai.upgrade.<起始版本>-<目标版本>.sql。每份脚本只适用于文件名标明的版本区间，在起始版本的库上执行；新装的库直接执行全量脚本，无需执行升级脚本。

1. 跨 BladeX 基座版本时，先执行基座系统表的升级脚本；已执行过 BladeX 官方同版本升级脚本的库跳过此步。
2. 按版本顺序，逐个执行当前版本至目标版本之间的产品升级脚本。跨越多个版本时，依次执行每个相邻区间的脚本，不跳过中间区间。
3. 执行前阅读脚本内的说明。标注为可选的语句默认注释，按说明决定是否执行；删列、删表、改类型等破坏性语句与数据回填单独分组并注明影响。

mysql -h <数据库地址> -u <账号> -p bladex_aigc \
  < doc/sql/upgrade/bladex.mysql.ai.upgrade.<起始版本>-<目标版本>.sql

未提供升级脚本的版本区间不支持原地升级。容器部署的 MySQL 只在数据目录为空的首次启动时执行 init.sql，已有数据的库同样按上述步骤执行升级脚本。

升级脚本只包含正向变更，执行后的库结构与目标版本全量脚本新装的库一致。需要核对时，在测试环境用目标版本的全量脚本新装一个库作对照。脚本约定见 数据模型与初始化。

三、升级后端

1. 准备目标版本的后端产物：JAR 运行与镜像构建见 后端与基础服务部署。
2. 对照目标版本的 配置加载与环境管理，补齐新增或调整的配置项。
3. 数据库脚本执行完成后，停止旧服务，以原有 profile 与外部配置启动目标版本。后端按目标版本的表结构编写，需在数据库升级完成后启动。
4. 容器部署时，更新 docker-compose.yaml 中的镜像标签，再执行 docker compose up -d。

启动后检查服务日志，确认数据库、Redis、文件存储与向量库连接正常。升级脚本新增菜单或按钮时，按需为业务角色授权。

四、升级前端

后端核验通过后发布前端。AI 前端按版本目录发布，宿主无需因 AI 升级重新构建；在 Saber 仓库根目录执行：

deploy/saber.sh remote ai ../Saber-AI
deploy/saber.sh check ai <目标版本>
deploy/saber.sh switch ai <目标版本>
deploy/saber.sh registry

remote 将目标版本写入独立的版本目录并执行影子工程的 verify，check 核对 manifest、版本与出口，switch 与 registry 切换并下发注册表。分享入口随注册表指向的版本切换。命令说明见 宿主与 AI 业务部署 与 版本发布与回滚。

Saber 宿主同时升级时，先发布宿主，再发布 AI 版本；两者的契约版本与共享依赖通过宿主兼容矩阵核对。

五、升级后核验

1. 登录宿主，打开 AI 菜单、资源列表与详情，刷新深链接。
2. 运行一个代表性应用，检查流式输出、运行记录与用量。
3. 在知识库执行命中测试，确认向量连接与召回正常；创作按已配置用途检查模型与媒体能力。
4. 打开分享入口与嵌入页面，确认访问控制与资源加载正常。
5. 记录目标环境、升级时间、前后端版本、buildId、执行的升级脚本与注册表变更。

六、回滚

范围	方式
AI 前端	将注册表切回保留的上一版本并下发，见 版本发布与回滚
后端	重新部署保留的上一版本产物
数据库	升级脚本不包含回滚语句，恢复升级前的备份；数据库与文件存储恢复到同一时间点

后端回滚到上一版本时，同时将数据库恢复到升级前的备份，使代码与表结构保持一致。升级后新写入的业务数据需在回滚前评估导出与补录方式。