The most common upgrade mistake is treating the image tag update, historical chunk training task migration, knowledge base rebuild state migration, and startup scripts as unrelated actions pushed forward in parallel. The correct order is to first confirm the image tag has been updated to the target version, then have an administrator manually trigger the two migrations—historical chunk training tasks and knowledge base rebuild state—on the version upgrade page. The two run in dependency order and do not run automatically with service startup.
Image Tag Update Is the Starting Point of the Entire Sequence
The first step of the upgrade falls on the image tag. FastGPT self-hosted deployments run through container images. During an upgrade, replace the image tag referenced in the configuration with the tag corresponding to the target version, then pull the image and rebuild the container. This step comes first because the subsequent historical chunk training task migration and knowledge base rebuild state migration are both driven by migration logic in the new version's code. That logic does not exist in the old image, so running migrations first is meaningless. Verification actions include checking whether the image field in the deployment orchestration file already points to the new tag, confirming that the pulled image digest matches the target tag, and then proceeding to container rebuild. The typical failure symptom is that the container still starts with the old code, the migration logic does not execute, historical chunk training tasks remain in the old state, and the knowledge base rebuild state is not rewritten. If the image tag is written incorrectly or the pull fails, the container may restart repeatedly, and the logs will show prompts such as the image not existing or the digest not matching. In that case, resolve the tag issue first and do not continue pushing the migration forward.
Historical Chunk Training Task Migration Depends on the New Image
Historical chunk training task migration deals with training task records that already exist in the old version but whose status fields or data structures are inconsistent with the new version. It must be read and rewritten by the migration logic after the new image starts, so in sequence it comes after the image tag update. During execution, pay attention to whether the migration script is triggered, whether the processing scope covers historical tasks, and whether the migrated task states can be read normally by the new version. Verification actions can include checking execution records for the migration on the administrator version upgrade page, confirming that the migration step has completed, and then checking whether historical chunk training tasks appear in a state that can continue to be processed in the UI or at the data layer. Failure symptoms include migration not being triggered so old tasks cannot be recognized by the new version, migration interruption leaving some tasks in an intermediate state, and repeated migration execution causing states to be rewritten repeatedly. Because migration depends on code in the new image, any manual modification of historical task states on the old image may make subsequent migration judgments inaccurate. Return to the image version check and confirm the migration prerequisites before retrying.
Knowledge Base Rebuild State Migration Comes After Training Task Migration
Knowledge base rebuild state migration deals with state records of the knowledge base during the rebuild process. It has an order dependency with historical chunk training task migration, because knowledge base rebuild state often references the progress of chunk training tasks. When training task states have not finished migrating, the rebuild state migration lacks usable prerequisite data. In sequence, historical chunk training task migration should complete first, and then knowledge base rebuild state migration should be executed. Verification actions include confirming that training task migration has ended, then observing whether the knowledge base rebuild state is correctly rewritten, and whether the rebuild process can continue from the migrated state. Failure symptoms are inconsistency between rebuild state and training task state, the knowledge base showing as rebuilding while the underlying task no longer exists, or the rebuild process repeatedly returning to the starting point. When encountering such situations, first check whether training task migration is complete, then check whether rebuild state migration was executed after it, and avoid reversing the order of the two migration steps.
Check Manual Migrations Separately from Service Readiness
The two migration tasks are manually triggered by an administrator on the version upgrade page and do not execute automatically with service startup: first stop the old instance, wait for the old training task lease to expire, then execute historical chunk training task migration and knowledge base rebuild state migration in sequence, with the second executed only after the first is complete. Manual triggering means that the service being accessible does not equal the migration being complete. The basis for judgment is the execution results and states of the two tasks, not whether the container has started. During verification, check the execution records and states of the two tasks on the version upgrade page, confirm the first is complete before checking the second, and only after both are finished verify retrieval and citation display. There are two failure symptoms: mistaking service accessibility for migration completion and prematurely using features that depend on migration results; or restarting the container before migration is complete, causing task interruption that requires retriggering. The correct approach is to wait until both tasks show as complete on the page before entering functional verification; when the image tag has not been updated, the page will not show executable migration items, so resolve the image version first.
Checklist for Each Later Step Depending on the Previous One
Stringing the above steps together, the execution order can be organized into a checklist. First confirm that the image tag has been updated and successfully pulled, and that the container starts with the new version's code; then confirm that historical chunk training task migration has been triggered and completed, and that historical task states can be read by the new version; next confirm that knowledge base rebuild state migration is executed after training task migration, and that rebuild state remains consistent with task state; throughout, remember that scripts do not block startup, and service accessibility does not mean migration is complete. Check item by item in this order, and do not skip to the next item if any item is incomplete. Failure symptoms are concentrated in reversed order, for example changing knowledge base rebuild state first and then supplementing training task migration, which causes rebuild state to reference task data that has not yet been migrated; or manually triggering migration when the image has not been updated, so the script cannot find the corresponding logic and silently skips it. Advancing according to dependencies can keep state inconsistency during upgrades within a locatable range.
Upgrade Execution and Rollback Preparation
Before upgrading, record the current App and Pro image tags, deployment configuration, data states and available backups. Update the target images and confirm that the new version's administration entry is available. Check that every old App and Pro instance in the cluster has stopped, then wait for the old training-task leases to expire. The administrator can then manually run historical chunk training task migration from the version upgrade page. Run knowledge base rebuild state migration after the first task has completed.
Preparation records should include the images, data backup, version differences and recovery steps. These records help determine a recovery path based on the changes that actually occurred. Startup logs establish service readiness, while migration task records establish completion of the two migrations. Keeping these checks separate makes service availability, conversion of historical tasks and migration of index states independently traceable.
After migration, use fixed materials and questions to check retrieval, answers and citation display. Compare the retained pre-upgrade inputs and expected sources, and record differences against the relevant rows and states. For an image pull failure, resolve image availability first. For a migration failure, inspect that task's error and processed scope, then follow the applicable recovery plan. The two failure stages need separate evidence.