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:
@@ -11,6 +11,10 @@ export interface SystemInfo {
|
||||
graph_database_engine?: string
|
||||
minio_enabled?: boolean
|
||||
db_version?: string
|
||||
/** Human-readable error message when the startup migration failed.
|
||||
* When non-empty, the system info view should surface a troubleshooting
|
||||
* banner (see docs/migration-troubleshooting.md). */
|
||||
db_migration_error?: string
|
||||
}
|
||||
|
||||
export interface ToolDefinition {
|
||||
|
||||
@@ -2416,6 +2416,11 @@ export default {
|
||||
goVersionDescription: 'Go language version used by the backend',
|
||||
dbVersionLabel: 'Database Version',
|
||||
dbVersionDescription: 'Current database migration version',
|
||||
dbMigrationFailedTag: 'Migration failed',
|
||||
dbMigrationFailedTitle: 'Database migration failed',
|
||||
dbMigrationFailedDesc: 'The startup database migration did not complete successfully. Some tables or indexes may be missing, which can break Wiki ingest, the knowledge graph, and other features. Check the troubleshooting guide below first; if the issue persists, report it via the link.',
|
||||
dbMigrationViewDocs: 'View troubleshooting guide',
|
||||
dbMigrationReportIssue: "Can't fix it? Report an issue",
|
||||
keywordIndexEngineLabel: 'Keyword Index Engine',
|
||||
keywordIndexEngineDescription: 'Currently used keyword index engine',
|
||||
vectorStoreEngineLabel: 'Vector Store Engine',
|
||||
|
||||
@@ -1674,6 +1674,11 @@ export default {
|
||||
goVersionDescription: "백엔드에서 사용하는 Go 언어 버전",
|
||||
dbVersionLabel: "데이터베이스 버전",
|
||||
dbVersionDescription: "현재 데이터베이스 마이그레이션 버전",
|
||||
dbMigrationFailedTag: "마이그레이션 실패",
|
||||
dbMigrationFailedTitle: "데이터베이스 마이그레이션 실패",
|
||||
dbMigrationFailedDesc: "시작 시 데이터베이스 마이그레이션이 정상적으로 완료되지 않았습니다. 일부 테이블이나 인덱스가 생성되지 않았을 수 있으며, Wiki와 지식 그래프 기능 등이 동작하지 않을 수 있습니다. 먼저 아래 문제 해결 문서를 확인하여 직접 복구해 보고, 그래도 해결되지 않으면 이슈를 등록해 주세요.",
|
||||
dbMigrationViewDocs: "문제 해결 문서 보기",
|
||||
dbMigrationReportIssue: "해결되지 않나요? 이슈 등록",
|
||||
keywordIndexEngineLabel: "키워드 인덱스 엔진",
|
||||
keywordIndexEngineDescription: "현재 사용 중인 키워드 인덱스 엔진",
|
||||
vectorStoreEngineLabel: "벡터 저장소 엔진",
|
||||
|
||||
@@ -1491,6 +1491,11 @@ export default {
|
||||
goVersionDescription: 'Версия языка Go, используемая backend',
|
||||
dbVersionLabel: 'Версия базы данных',
|
||||
dbVersionDescription: 'Текущая версия миграции базы данных',
|
||||
dbMigrationFailedTag: 'Миграция не удалась',
|
||||
dbMigrationFailedTitle: 'Сбой миграции базы данных',
|
||||
dbMigrationFailedDesc: 'Миграция базы данных при запуске не завершилась успешно. Часть таблиц или индексов могла не создаться, из-за чего Wiki, граф знаний и другие функции могут не работать. Сначала ознакомьтесь с руководством по диагностике ниже; если проблема сохраняется, сообщите о ней по ссылке.',
|
||||
dbMigrationViewDocs: 'Открыть руководство по диагностике',
|
||||
dbMigrationReportIssue: 'Не удаётся починить? Создать issue',
|
||||
keywordIndexEngineLabel: 'Движок индексации ключевых слов',
|
||||
keywordIndexEngineDescription: 'Используемый в настоящее время движок индексации ключевых слов',
|
||||
vectorStoreEngineLabel: 'Движок векторного хранилища',
|
||||
|
||||
@@ -1654,6 +1654,11 @@ export default {
|
||||
goVersionDescription: "后端使用的 Go 语言版本",
|
||||
dbVersionLabel: "数据库版本",
|
||||
dbVersionDescription: "当前数据库迁移版本号",
|
||||
dbMigrationFailedTag: "迁移失败",
|
||||
dbMigrationFailedTitle: "数据库迁移失败",
|
||||
dbMigrationFailedDesc: "启动时数据库迁移未成功完成,部分表或索引可能未创建,会导致 Wiki、知识图谱等功能异常。建议先查看排查文档自助修复;如仍无法解决,请通过下方链接反馈。",
|
||||
dbMigrationViewDocs: "查看排查文档",
|
||||
dbMigrationReportIssue: "无法修复?提交 Issue",
|
||||
keywordIndexEngineLabel: "关键词索引引擎",
|
||||
keywordIndexEngineDescription: "当前使用的关键词索引引擎",
|
||||
vectorStoreEngineLabel: "向量存储引擎",
|
||||
|
||||
@@ -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