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:
@@ -88,16 +88,50 @@
|
||||
</div>
|
||||
|
||||
<!-- DB Version -->
|
||||
<div v-if="systemInfo?.db_version" class="setting-row">
|
||||
<div v-if="systemInfo?.db_version || systemInfo?.db_migration_error" class="setting-row">
|
||||
<div class="setting-info">
|
||||
<label>{{ $t('system.dbVersionLabel') }}</label>
|
||||
<p class="desc">{{ $t('system.dbVersionDescription') }}</p>
|
||||
</div>
|
||||
<div class="setting-control">
|
||||
<span class="info-value">{{ systemInfo.db_version }}</span>
|
||||
<span class="info-value">
|
||||
{{ systemInfo?.db_version || $t('system.unknown') }}
|
||||
<t-tag
|
||||
v-if="systemInfo?.db_migration_error"
|
||||
theme="danger"
|
||||
variant="light"
|
||||
size="small"
|
||||
style="margin-left: 8px;"
|
||||
>{{ $t('system.dbMigrationFailedTag') }}</t-tag>
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- DB migration error: full-width banner under the row -->
|
||||
<div v-if="systemInfo?.db_migration_error" class="setting-row migration-error-row">
|
||||
<t-alert theme="error" :title="$t('system.dbMigrationFailedTitle')" style="width: 100%;">
|
||||
<template #default>
|
||||
<p class="migration-error-desc">{{ $t('system.dbMigrationFailedDesc') }}</p>
|
||||
<pre class="migration-error-detail">{{ systemInfo.db_migration_error }}</pre>
|
||||
<div class="migration-error-actions">
|
||||
<t-link
|
||||
theme="primary"
|
||||
:href="troubleshootingDocsURL"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
>{{ $t('system.dbMigrationViewDocs') }}</t-link>
|
||||
<span class="migration-error-actions-sep">·</span>
|
||||
<t-link
|
||||
theme="primary"
|
||||
:href="reportIssueURL"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
>{{ $t('system.dbMigrationReportIssue') }}</t-link>
|
||||
</div>
|
||||
</template>
|
||||
</t-alert>
|
||||
</div>
|
||||
|
||||
<!-- Keyword Index Engine -->
|
||||
<div class="setting-row">
|
||||
<div class="setting-info">
|
||||
@@ -136,7 +170,7 @@
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import { ref, onMounted } from 'vue'
|
||||
import { ref, computed, onMounted } from 'vue'
|
||||
import { getSystemInfo, type SystemInfo } from '@/api/system'
|
||||
import { useI18n } from 'vue-i18n'
|
||||
|
||||
@@ -148,6 +182,37 @@ const loading = ref(true)
|
||||
const error = ref('')
|
||||
const frontendVersion = __FRONTEND_VERSION__
|
||||
|
||||
const troubleshootingDocsURL =
|
||||
'https://github.com/Tencent/WeKnora/blob/main/docs/migration-troubleshooting.md'
|
||||
|
||||
// Pre-fills a new issue with the current migration error so users don't have to
|
||||
// paste it manually. Body is intentionally minimal — the bug template will fill
|
||||
// in the rest. Encode aggressively to survive newlines / quotes.
|
||||
const reportIssueURL = computed(() => {
|
||||
const base = 'https://github.com/Tencent/WeKnora/issues/new'
|
||||
const params = new URLSearchParams({
|
||||
template: 'bug_report.yml',
|
||||
title: '[Bug]: Database migration failed at startup',
|
||||
labels: 'bug',
|
||||
})
|
||||
const errMsg = systemInfo.value?.db_migration_error
|
||||
if (errMsg) {
|
||||
const body = [
|
||||
'### Environment',
|
||||
`- WeKnora version: ${systemInfo.value?.version || 'unknown'}`,
|
||||
`- Commit: ${systemInfo.value?.commit_id || 'unknown'}`,
|
||||
`- DB version reported: ${systemInfo.value?.db_version || 'unknown'}`,
|
||||
'',
|
||||
'### Migration error',
|
||||
'```',
|
||||
errMsg,
|
||||
'```',
|
||||
].join('\n')
|
||||
params.set('body', body)
|
||||
}
|
||||
return `${base}?${params.toString()}`
|
||||
})
|
||||
|
||||
// Methods
|
||||
const loadInfo = async () => {
|
||||
try {
|
||||
@@ -250,6 +315,44 @@ onMounted(() => {
|
||||
}
|
||||
}
|
||||
|
||||
.migration-error-row {
|
||||
display: block;
|
||||
padding: 0 0 20px 0;
|
||||
border-bottom: 1px solid var(--td-component-stroke);
|
||||
}
|
||||
|
||||
.migration-error-desc {
|
||||
margin: 0 0 8px 0;
|
||||
font-size: 13px;
|
||||
line-height: 1.5;
|
||||
color: var(--td-text-color-primary);
|
||||
}
|
||||
|
||||
.migration-error-detail {
|
||||
margin: 0 0 12px 0;
|
||||
padding: 8px 12px;
|
||||
background: var(--td-bg-color-container-hover);
|
||||
border-radius: 4px;
|
||||
font-size: 12px;
|
||||
line-height: 1.5;
|
||||
white-space: pre-wrap;
|
||||
word-break: break-word;
|
||||
max-height: 200px;
|
||||
overflow: auto;
|
||||
color: var(--td-text-color-secondary);
|
||||
}
|
||||
|
||||
.migration-error-actions {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
font-size: 13px;
|
||||
|
||||
.migration-error-actions-sep {
|
||||
color: var(--td-text-color-placeholder);
|
||||
}
|
||||
}
|
||||
|
||||
.setting-control {
|
||||
flex-shrink: 0;
|
||||
min-width: 280px;
|
||||
|
||||
Reference in New Issue
Block a user