升级与迁移

适用读者：生产环境运维人员

升级前

1. 阅读目标版本 Release Notes 和兼容矩阵。
2. 记录当前 Halo、插件、Lucene 和模型配置。
3. 备份 Halo 数据目录、数据库、AI 智能套件 ConfigMap、AI Foundation 配置和自定义 Extension。
4. 导出或截图关键配置与索引统计。
5. 保留上一版本插件 JAR。

升级流程

1. 在测试环境安装新版本。
2. 确认插件状态为 STARTED。
3. 验证 AI 智能套件 ConfigMap 与 AI Foundation 模型配置已正确读取。
4. 检查意图路由、评测集和历史记录仍存在。
5. 按版本说明决定是否重建索引。
6. 执行后台调试、匿名聊天、搜索和写作验收。
7. 再升级生产环境。

配置资源

AI 智能套件当前只保存业务配置：

• ConfigMap：ai-suite-configmap
• 用量历史：ai-suite-usage-YYYY-MM-DD（按日期保存，默认恢复/查询窗口为最近 30 天）

模型供应商、Base URL、API Key 和默认模型由 Halo AI Foundation 管理。旧 ai-suite-api-keys Secret 不再读取。

升级到 0.3.2

• Halo 必须为 2.25.0 或更高版本，并已安装 AI Foundation。
• 旧版插件内 Base URL、API Key 和供应商配置不再生效，应先在 AI Foundation 中重建模型资源。
• shortcutQuestions 可以继续读取，保存后会逐步转换为结构化 shortcutItems。
• 旧 reasoningMode=enabled 会兼容为“默认开启深度思考”。建议在“对话与外观”重新确认访客权限与默认值。
• 插件热更新后若旧聊天路由仍被 Halo 缓存，可临时使用 v1alpha2；生产升级建议完整重启 Halo。
• Embedding 模型或维度发生变化时必须全量重建索引。

升级到 0.3.4

• 最低运行版本仍为 Halo 2.25.0；当前按 AI Foundation 1.0.0-beta.4 的公开 API 编译并完成验证。Halo 2.25 暂不支持在插件依赖表达式中锁定预发布版本，因此升级 AI Foundation 后需重新执行兼容验证。
• 模型接入已改为 AI Foundation 公开类型化 SDK，不再反射调用 API，也不再读取 AI Foundation 内部 ConfigMap。
• Java 实现包名迁移到 cn.rainwu.halo.ai.suite；插件 ID、API Group、ConfigMap 和业务 Extension GVK 保持不变，不需要迁移现有业务数据。
• 脑图渲染依赖改为插件内本地构建，不再从 jsDelivr 或 unpkg 加载脚本、样式。
• 若同时更换 Embedding 模型或向量维度，升级后必须执行全量索引重建；仅从 0.3.3 升级且模型与维度未变化时无需重建。

升级到 0.3.6

• 修复插件启动时对已有完整索引执行冗余全量重建的问题。升级后会继续复用可读且完整的既有索引。
• 修复固定维度 Embedding 模型因不支持 dimensions 请求参数而连接失败的问题，已验证硅基流动 BAAI/bge-m3 可返回 1024 维向量。
• 本次版本不改变索引结构。Embedding 模型和向量维度保持不变时无需重建索引；若切换模型或维度，仍须全量重建。

升级到 0.4.0

• 升级前先将 Halo 更新到 2.26.0 或更高版本，并安装、启用 Halo AI Foundation 1.1.1 或更高版本。0.4.0 不支持继续运行在 Halo 2.25 上。
• 先备份数据库、Halo 数据目录、AI Foundation 配置、AI 智能套件配置及上一版本插件 JAR，再在测试环境升级。现有宠物与模型配置应在升级后复核；图片模型需要支持参考图生成，生成结果须逐张检查。
• 本版与 Halo 2.26 运行时对齐 Lucene 10.5.0。升级后检查旧索引是否可读并验证搜索与问答；如出现 Codec 错误或索引不一致，执行全量重建。不要在未备份旧数据的情况下让旧 Halo 版本读取升级后的数据目录。
• 验证插件达到 STARTED，再检查访客问答、搜索、编辑器写作和交互宠物。新版本本身不会自动调用生图模型；生成宠物时才会使用已配置的图片模型。

何时重建索引

必须重建：Embedding 模型、向量维度或索引结构变化。建议重建：切片规则大幅调整、Lucene 版本变化或统计不一致。仅 Chat 模型、Prompt、UI 主题变化不需要重建。

回滚

1. 禁用新插件。
2. 恢复上一版本 JAR。
3. 恢复升级前 AI 智能套件 ConfigMap、需要保留的用量 ConfigMap、AI Foundation 配置和业务 Extension。
4. 必要时恢复 Halo 数据目录中的索引。
5. 启用旧插件并验证状态、配置和公开 API。

不同 Lucene 版本生成的索引不一定能互相读取；最安全的回滚方式是恢复对应数据快照，或在旧版本下重新建立索引。