feat(system-info): surface DB migration errors with troubleshooting links

When a startup database migration fails (e.g. issue #1319: pg_trgm not
available so 000041 cannot build its trigram index), the application
intentionally keeps booting so operators can reach the UI to diagnose.
However, before this change the system info page silently dropped the
"DB Version" row because the value was empty:

  - migration.go only cached the version after a successful m.Up(); the
    error path returned early and left migrationVersionSet=false.
  - system.go used CachedMigrationVersion's ok=false to skip emitting
    db_version, and the JSON tag was already omitempty.
  - SystemInfo.vue gated the entire row on v-if="systemInfo?.db_version".

The end result was the most useful diagnostic surface vanishing in the
exact failure mode that needs it most — Wiki ingest and KG features
would silently produce nothing with no UI hint.

Changes:

  - migration.go: replace sync.Once-based setter with an RWMutex-guarded
    state struct holding {version, dirty, err}. Every failure path now
    calls captureMigrationFailure(m, err), which best-effort reads
    m.Version() so the cached value still reflects the partial state.
  - system.go (handler): always emit db_version (falling back to
    "unknown" when no version could be read), append " (failed)" when an
    error is recorded, and add db_migration_error to the response.
  - swagger / client SDK: keep the API contract in sync with the new
    response field.
  - SystemInfo.vue: render the DB version row whenever either field is
    present, show a "Migration failed" danger tag, and add a full-width
    alert below the row carrying the error message plus two links:
      1. View troubleshooting guide -> new docs/migration-troubleshooting.md
      2. Report an issue -> github.com/Tencent/WeKnora/issues/new,
         prefilled with the captured error and environment metadata.
  - docs/migration-troubleshooting.md: new self-service guide covering
    the common failure modes (missing extension, dirty state, privileges,
    out of disk, schema drift) with concrete psql / make commands.
  - i18n: add the new keys to zh-CN, en-US, ko-KR, ru-RU.

Refs #1319.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
wizardchen
2026-05-14 16:25:01 +08:00
committed by lyingbug
parent 8f4e5a459f
commit 6f95c75ed2
13 changed files with 411 additions and 22 deletions
+69 -19
View File
@@ -16,24 +16,66 @@ import (
)
var (
migrationStateMu sync.RWMutex
currentMigrationVersion uint
currentMigrationDirty bool
migrationVersionOnce sync.Once
migrationVersionSet bool
currentMigrationError string
)
// CachedMigrationVersion returns the migration version captured at startup.
// Returns (version, dirty, ok). ok is false if the version was never captured.
//
// Note: when migrations fail mid-way, the cache may still be populated via a
// best-effort m.Version() call inside RunMigrationsWithOptions so the system
// info endpoint can surface the partial state. Check CachedMigrationError() to
// distinguish a clean version reading from a recorded-after-failure one.
func CachedMigrationVersion() (uint, bool, bool) {
migrationStateMu.RLock()
defer migrationStateMu.RUnlock()
return currentMigrationVersion, currentMigrationDirty, migrationVersionSet
}
func setMigrationVersion(version uint, dirty bool) {
migrationVersionOnce.Do(func() {
// CachedMigrationError returns the error message captured when the most recent
// migration attempt failed at startup. Empty string means migrations either
// succeeded or were never run.
func CachedMigrationError() string {
migrationStateMu.RLock()
defer migrationStateMu.RUnlock()
return currentMigrationError
}
// setMigrationState records the latest known migration state. Unlike the old
// sync.Once-based setter, this is intentionally idempotent-overwrite so the
// failure path (which runs after Up() errored) can replace the pre-migration
// snapshot taken from the initial m.Version() call.
func setMigrationState(version uint, dirty bool, errMsg string, versionKnown bool) {
migrationStateMu.Lock()
defer migrationStateMu.Unlock()
if versionKnown {
currentMigrationVersion = version
currentMigrationDirty = dirty
migrationVersionSet = true
})
}
currentMigrationError = errMsg
}
// captureMigrationFailure best-effort queries m for the current version so the
// system info endpoint can show "N (failed)" instead of vanishing the row, and
// stores the human-readable error message. Always returns the original error.
func captureMigrationFailure(m *migrate.Migrate, err error) error {
versionKnown := false
var ver uint
var dirty bool
if m != nil {
v, d, vErr := m.Version()
if vErr == nil {
versionKnown = true
ver, dirty = v, d
}
}
setMigrationState(ver, dirty, err.Error(), versionKnown)
return err
}
// RunMigrations executes all pending database migrations
@@ -71,25 +113,33 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
sqlDB, err := sql.Open("sqlite3", opts.SQLiteDBPath)
if err != nil {
logger.Errorf(ctx, "Failed to open sqlite db for migration: %v", err)
return fmt.Errorf("failed to open sqlite db for migration: %w", err)
wrapped := fmt.Errorf("failed to open sqlite db for migration: %w", err)
setMigrationState(0, false, wrapped.Error(), false)
return wrapped
}
driver, err := sqlite3migrate.WithInstance(sqlDB, &sqlite3migrate.Config{})
if err != nil {
sqlDB.Close()
logger.Errorf(ctx, "Failed to create sqlite3 migrate driver: %v", err)
return fmt.Errorf("failed to create sqlite3 migrate driver: %w", err)
wrapped := fmt.Errorf("failed to create sqlite3 migrate driver: %w", err)
setMigrationState(0, false, wrapped.Error(), false)
return wrapped
}
m, err = migrate.NewWithDatabaseInstance(migrationsPath, "sqlite3", driver)
if err != nil {
logger.Errorf(ctx, "Failed to create migrate instance: %v", err)
return fmt.Errorf("failed to create migrate instance: %w", err)
wrapped := fmt.Errorf("failed to create migrate instance: %w", err)
setMigrationState(0, false, wrapped.Error(), false)
return wrapped
}
} else {
var err error
m, err = migrate.New(migrationsPath, dsn)
if err != nil {
logger.Errorf(ctx, "Failed to create migrate instance: %v", err)
return fmt.Errorf("failed to create migrate instance: %w", err)
wrapped := fmt.Errorf("failed to create migrate instance: %w", err)
setMigrationState(0, false, wrapped.Error(), false)
return wrapped
}
}
defer m.Close()
@@ -98,7 +148,7 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
oldVersion, oldDirty, versionErr := m.Version()
if versionErr != nil && versionErr != migrate.ErrNilVersion {
logger.Errorf(ctx, "Failed to get migration version: %v", versionErr)
return fmt.Errorf("failed to get migration version: %w", versionErr)
return captureMigrationFailure(m, fmt.Errorf("failed to get migration version: %w", versionErr))
}
if versionErr == migrate.ErrNilVersion {
@@ -113,7 +163,7 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
if opts.AutoRecoverDirty {
logger.Infof(ctx, "AutoRecoverDirty is enabled, attempting recovery...")
if err := recoverFromDirtyState(ctx, m, oldVersion); err != nil {
return err
return captureMigrationFailure(m, err)
}
// Update oldVersion after recovery
oldVersion, _, _ = m.Version()
@@ -123,7 +173,7 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
if oldVersion == 0 || forceVersion < 0 {
forceVersion = 0
}
return fmt.Errorf(
return captureMigrationFailure(m, fmt.Errorf(
"database is in dirty state at version %d. This usually means a migration failed partway through. "+
"To fix this:\n"+
"1. Check if the migration partially applied changes and manually fix if needed\n"+
@@ -136,7 +186,7 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
forceVersion,
forceVersion,
forceVersion,
)
))
}
}
@@ -152,13 +202,13 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
logger.Infof(ctx, "Attempting to recover from dirty state...")
// Try to recover and retry
if recoverErr := recoverFromDirtyState(ctx, m, currentVersion); recoverErr != nil {
return recoverErr
return captureMigrationFailure(m, recoverErr)
}
// Retry migration after recovery
logger.Infof(ctx, "Retrying migration after recovery...")
if retryErr := m.Up(); retryErr != nil && retryErr != migrate.ErrNoChange {
logger.Errorf(ctx, "Migration failed after recovery attempt: %v", retryErr)
return fmt.Errorf("migration failed after recovery attempt: %w", retryErr)
return captureMigrationFailure(m, fmt.Errorf("migration failed after recovery attempt: %w", retryErr))
}
} else {
// Calculate the version to force to (usually the previous version)
@@ -166,7 +216,7 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
if currentVersion == 0 {
forceVersion = 0
}
return fmt.Errorf(
return captureMigrationFailure(m, fmt.Errorf(
"migration failed and database is now in dirty state at version %d. "+
"To fix this:\n"+
"1. Check if the migration partially applied changes and manually fix if needed\n"+
@@ -179,20 +229,20 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
forceVersion,
forceVersion,
forceVersion,
)
))
}
} else {
return fmt.Errorf("failed to run migrations: %w", err)
return captureMigrationFailure(m, fmt.Errorf("failed to run migrations: %w", err))
}
}
// Get current version after migration
version, dirty, err := m.Version()
if err != nil && err != migrate.ErrNilVersion {
return fmt.Errorf("failed to get migration version: %w", err)
return captureMigrationFailure(m, fmt.Errorf("failed to get migration version: %w", err))
}
setMigrationVersion(version, dirty)
setMigrationState(version, dirty, "", true)
if oldVersion != version {
logger.Infof(ctx, "Database migrated from version %d to %d", oldVersion, version)