升级最容易错在把镜像tag更新、历史分块训练任务迁移、知识库重建状态迁移和启动脚本当成互不相干的动作并行推进。正确判断顺序是先确认镜像tag已更新到目标版本，再由管理员在版本升级页手动触发历史分块训练任务与知识库重建状态两项迁移，两项按依赖顺序执行，不随服务启动自动运行。
镜像tag更新是整条顺序的起点
升级动作的第一步落在镜像tag上。FastGPT自托管部署通过容器镜像运行，升级时需要把配置中引用的镜像tag替换为目标版本对应的tag，再拉取镜像并重建容器。这一步之所以排在前面，是因为后续的历史分块训练任务迁移、知识库重建状态迁移都由新版本代码中的迁移逻辑驱动，旧镜像里不存在这些逻辑，先跑迁移没有意义。核对动作包括查看部署编排文件中镜像字段是否已经指向新tag，确认拉取到的镜像摘要与目标tag一致，再进入容器重建。失败表现通常是容器仍以旧代码启动，迁移逻辑不执行，历史分块训练任务停留在旧状态，知识库重建状态也不会被改写。若镜像tag写错或拉取失败，容器可能反复重启，日志里出现镜像不存在或摘要不匹配的提示，此时应先解决tag问题，不要继续往下推进迁移。
历史分块训练任务迁移依赖新镜像
历史分块训练任务迁移处理的是旧版本中已经存在、但状态字段或数据结构与新版本不一致的训练任务记录。它必须在新镜像启动后由迁移逻辑读取并改写，因此顺序上排在镜像tag更新之后。执行时需要关注迁移脚本是否被触发、处理范围是否覆盖历史任务、以及迁移后任务状态是否可被新版本正常读取。核对动作可以查看管理员版本升级页中该迁移任务的执行记录，确认迁移步骤已经执行完成，再检查历史分块训练任务在界面或数据层是否呈现为可继续处理的状态。失败表现包括迁移未触发导致旧任务无法被新版本识别，迁移中断导致部分任务停留在中间状态，以及重复执行迁移造成状态被反复改写。由于迁移依赖新镜像中的代码，任何在旧镜像上手动改动历史任务状态的做法都可能让后续迁移判断失准，应先回退到镜像更新这一步重新对齐。
知识库重建状态迁移排在训练任务之后
知识库重建状态迁移处理的是知识库在重建流程中的状态记录。它与历史分块训练任务迁移之间存在先后依赖，因为知识库重建状态往往引用分块训练任务的进度，训练任务状态未迁移完成时，重建状态迁移缺少可用的前置数据。顺序上应让历史分块训练任务迁移先完成，再执行知识库重建状态迁移。核对动作包括确认训练任务迁移已结束、再观察知识库重建状态是否被正确改写、以及重建流程能否从迁移后的状态继续推进。失败表现是重建状态与训练任务状态不一致，知识库显示为重建中但底层任务已不存在，或者重建流程反复回到起点。遇到这类情况应先检查训练任务迁移是否完整，再检查重建状态迁移是否在其后执行，避免把两个迁移步骤的顺序颠倒。
手动迁移与服务启动分别核对
两项迁移任务由管理员在版本升级页手动触发，不随服务启动自动执行：先停旧实例，等旧训练任务租约过期，再依次执行历史分块训练任务迁移与知识库重建状态迁移，第一项完成后再执行第二项。手动触发意味着服务能访问不等于迁移已经完成，判断依据是两项任务的执行结果与状态，不是容器是否启动。核对时查看版本升级页里两项任务的执行记录与状态，确认第一项完成后再检查第二项，并在两项都结束后再验证检索与引用展示。失败表现有两种：把服务可访问误当成迁移结束，提前使用依赖迁移结果的功能；或在迁移未完成时重启容器，导致任务中断需要重新触发。正确做法是等两项任务都在页面上显示完成，再进入功能验证；镜像tag未更新时页面不会出现可执行的迁移项，先解决镜像版本。
后一个依赖前一个的核对清单
把上述环节串起来，执行顺序可以整理成一份核对清单。先确认镜像tag已经更新并成功拉取，容器以新版本代码启动；再确认历史分块训练任务迁移被触发并完成，历史任务状态可被新版本读取；接着确认知识库重建状态迁移在训练任务迁移之后执行，重建状态与任务状态保持一致；全程记住脚本不阻塞启动，服务可访问不代表迁移结束。核对时按这个顺序逐项检查，任何一项未完成都不要跳到下一项。失败表现集中在顺序颠倒上，例如先改知识库重建状态再补训练任务迁移，会让重建状态引用到尚未迁移的任务数据；或者在镜像未更新时手动触发迁移，脚本找不到对应逻辑而静默跳过。按依赖关系推进，可以把升级中的状态不一致控制在可定位的范围内。进一步阅读：https://fastgpt.cn/deploy/fastgpt-aiproxy-replace-oneapi
升级执行与回退准备
升级前记录当前App与Pro镜像tag、部署配置、数据状态及可恢复的备份。更新目标镜像并确认新版本管理入口就绪后，先核对集群中全部旧版App与Pro实例均已停止，再等待旧训练任务租约过期。管理员随后在“版本升级”页手动执行历史分块训练任务迁移，确认完成后再执行知识库重建状态迁移。
准备阶段记录镜像、数据备份、版本差异和恢复步骤，便于出现问题时按实际变更范围判断恢复路径。启动日志用于确认服务就绪，迁移任务记录用于确认两项迁移完成。两个检查对象分别记录，能够把服务可访问、历史任务已转换、索引状态已迁移这几件事逐一对上。
迁移结束后，用固定的资料和问题回归检索、问答与引用展示；对照升级前保留的输入与预期出处，记录差异对应的数据行与状态。镜像拉取失败时先解决镜像可用性；迁移任务失败时查看对应任务错误和已处理范围，再按实际恢复安排操作，避免混淆两个阶段的故障。