WeKnora/docs
wizardchen 6f95c75ed2 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>
2026-05-14 16:34:50 +08:00
..
api feat(knowledge-base): document list filters and explicit batch-management UX 2026-05-12 18:29:47 +08:00
cloud-image docs(cloud-image): add cloud-agnostic image packaging scripts 2026-05-11 12:25:19 +08:00
images docs(readme): enhance layout for Agent Mode and Observability sections across multiple languages 2026-04-27 15:27:24 +08:00
wiki docs(api): restore auth.md and update README/wiki links 2026-05-12 13:16:58 +08:00
zh feat(agent): human-in-the-loop approval for MCP tool calls (#1173) 2026-05-10 22:57:12 +08:00
BUILTIN_MCP_SERVICES.md feat: add built-in MCP service support 2026-03-05 21:57:01 +08:00
BUILTIN_MODELS.md feat:add several mainstream model providers 2026-01-14 17:08:26 +08:00
CHUNKING.md fix(chunking): post-review polish — error surfacing + doc accuracy 2026-05-06 17:17:07 +08:00
IM集成开发文档.md add oidc 2026-03-30 11:13:44 +08:00
KnowledgeGraph.md docs: 更新多语言文档,新增知识图谱与MCP配置指南及目录结构 2025-11-19 16:56:49 +08:00
LITE.md feat: add LAN access configuration for desktop app, allowing users to enable public API access with corresponding UI updates and translations 2026-04-11 18:51:16 +08:00
Langfuse集成.md feat(observability): instrument agent ReAct loop and tool calls in Langfuse 2026-04-24 19:58:08 +08:00
MCP功能使用说明.md feat: Revamp conversation configuration management and enhance localization 2025-11-18 23:18:43 +08:00
OIDC认证调用流程.md simplify oidc callback result payload 2026-04-01 20:47:18 +08:00
QA.md chore(release): v0.5.0 2026-04-27 12:23:02 +08:00
ROADMAP.md feat(roadmap): update progress on document parsing and IM integration 2026-03-31 20:22:34 +08:00
agent-skills.md feat: adjust sandbox setting of agentConfig 2026-02-04 20:08:49 +08:00
docs.go feat(system-info): surface DB migration errors with troubleshooting links 2026-05-14 16:34:50 +08:00
migration-troubleshooting.md feat(system-info): surface DB migration errors with troubleshooting links 2026-05-14 16:34:50 +08:00
swagger.json feat(system-info): surface DB migration errors with troubleshooting links 2026-05-14 16:34:50 +08:00
swagger.yaml feat(system-info): surface DB migration errors with troubleshooting links 2026-05-14 16:34:50 +08:00
使用其他向量数据库.md feat: support Tencent VectorDB keyword retrieval 2026-05-10 00:02:05 +08:00
共享空间说明.md refactor(docs): streamline knowledge base access permissions documentation 2026-02-09 11:40:25 +08:00
开发指南.md feat: optimize security and deployment of agent skills 2026-02-04 20:08:49 +08:00
开启知识图谱功能.md feat: Update VLM configuration in knowledge base and API documentation 2025-11-20 20:08:24 +08:00
快速开发模式说明.md docs: update Air installation command from cosmtrek/air to air-verse/air 2026-02-04 19:27:44 +08:00
数据源导入开发文档.md docs: remove WeCom document integration from data source import documentation 2026-03-30 20:46:07 +08:00
添加新的网络搜索引擎.md feat(web-search): refactor web search provider 2026-03-31 20:22:34 +08:00