数据库与迁移

本章梳理 WeKnora 的数据库支持矩阵、migrations/ 目录全部迁移叠加后的最终表结构、表间关系（ER 图）、golang-migrate 迁移机制，以及新增迁移与常见问题排查。

1. 支持的数据库

主应用通过 GORM 连接数据库，驱动由环境变量 DB_DRIVER 决定。internal/container/container.go 的 initDatabase() 中的 switch 只接受两个值：

MySQL 不是主库选项：go.mod 里的 go-sql-driver/mysql 是给 Doris 检索引擎（MySQL 协议、database/sql）注册协议驱动用的（见 container.go import 注释）。migrations/mysql/00-init-db.sql 是一份仅含 7 张核心表（tenants/models/knowledge_bases/knowledges/sessions/messages/chunks）的一次性 MySQL 建表脚本，没有任何 Go 代码或脚本引用它，未接入应用启动流程，可视为遗留/外部初始化用途。

检索引擎（向量/关键词索引的存储）与主库解耦，由 RETRIEVE_DRIVER 控制（postgres / elasticsearch / qdrant / milvus / sqlite 等，详见《扩展点指南》）。当 RETRIEVE_DRIVER 不含 postgres 时，迁移 DSN 会带上 options=-c app.skip_embedding=true，embeddings 表相关迁移通过该 GUC 条件跳过。

2. 迁移目录结构

migrations/
├── versioned/     # PostgreSQL/ParadeDB 版本化迁移：000000-000079 共 80 版（160 个 .up/.down.sql 文件）
├── sqlite/        # SQLite 迁移：000000_init（压平的全量 schema）+ 其后的增量版本
├── paradedb/      # ParadeDB 附加脚本：00-init-db.sql（扩展初始化）、01-migrate-to-paradedb.sql（存量库切换）
└── mysql/         # 00-init-db.sql，遗留的一次性 MySQL 建表脚本（未接入代码）

• versioned/ 是唯一的"增量历史"，从 000000_init 到 000079_knowledge_folder_path；
• sqlite/ 以 000000_init 作为压平后的全量初始化（JSONB→TEXT、SERIAL→AUTOINCREMENT 等方言差异已适配），其后按需追加增量版本（当前有 000001_remove_wiki_log、000002_knowledge_folder_path），同样由 golang-migrate 顺序执行；
• paradedb/00-init-db.sql 创建 pg_search 等扩展；BM25 索引使用中文 Lindera 分词器建在 embeddings.content 上。

2.1 versioned/ 迁移史概览（按主题）

3. 最终表结构

以下为全部 up 迁移叠加后的最终生效结构（后续迁移对早期表的 ALTER 已合并）。所有业务表统一带 created_at / updated_at，多数带 deleted_at（GORM 软删除），不再逐一列出。

3.1 租户与用户

3.2 模型与知识库

3.3 会话与消息

3.4 Agent 与 MCP

3.5 跨租户协作（组织）

3.6 Wiki

3.7 数据源 / 渠道 / 搜索

3.8 存储 / 资源 / 任务 / 可观测

4. ER 图（核心表）

erDiagram
    tenants ||--o{ users : "tenant_id (SET NULL)"
    tenants ||--o{ tenant_members : "租户成员"
    users ||--o{ tenant_members : "user_id"
    users ||--o{ auth_tokens : "登录令牌"
    tenants ||--o{ models : "模型配置"
    tenants ||--o{ knowledge_bases : "知识库"
    tenants ||--o{ tenant_api_keys : "API Key"
    tenants ||--o{ audit_logs : "审计"
    users ||--o{ audit_logs : "actor_user_id"

    knowledge_bases ||--o{ knowledges : "文档"
    knowledge_bases }o--|| models : "embedding_model_id"
    knowledge_bases }o--o| vector_stores : "vector_store_id"
    knowledge_bases }o--o| storage_backends : "storage_backend_id"
    knowledge_bases }o--o| users : "creator_id"
    knowledges ||--o{ chunks : "分块"
    chunks ||--o| chunks : "parent_chunk_id (父子分块)"
    chunks ||--o| embeddings : "source_id (向量/BM25)"
    knowledge_bases ||--o{ knowledge_tags : "标签"
    knowledge_tags ||--o{ knowledge_tag_relations : "多标签关联"
    knowledges ||--o{ knowledge_tag_relations : "knowledge_id"

    tenants ||--o{ sessions : "会话"
    sessions ||--o{ messages : "消息"
    sessions }o--o| custom_agents : "agent_id"
    sessions }o--o| knowledge_bases : "knowledge_base_id"
    messages }o--o| knowledges : "knowledge_id"
    messages ||--o{ message_suggestion_sets : "建议问题"
    message_suggestion_sets ||--o{ message_suggestion_events : "事件"
    sessions ||--o{ temporary_documents : "临时文档"

    tenants ||--o{ custom_agents : "自定义 Agent"
    tenants ||--o{ mcp_services : "MCP 服务"
    mcp_services ||--o{ mcp_tool_approvals : "工具审批"
    mcp_services ||--o{ mcp_oauth_clients : "OAuth 客户端"
    mcp_services ||--o{ mcp_oauth_tokens : "OAuth 令牌"

    users ||--o{ organizations : "owner_id"
    organizations ||--o{ organization_tenant_members : "租户成员"
    organizations ||--o{ kb_shares : "知识库共享"
    organizations ||--o{ agent_shares : "Agent 共享"
    organizations ||--o{ organization_join_requests : "加入申请"
    knowledge_bases ||--o{ kb_shares : "被共享"
    custom_agents ||--o{ agent_shares : "被共享 (id, tenant_id)"

    knowledge_bases ||--o{ wiki_pages : "Wiki 页面"
    wiki_pages }o--o| wiki_folders : "folder_id"
    wiki_folders ||--o{ wiki_folders : "parent_id (树)"
    knowledge_bases ||--o{ wiki_page_issues : "问题上报"

    knowledge_bases ||--o{ data_sources : "数据源"
    data_sources ||--o{ sync_logs : "同步日志"
    tenants ||--o{ web_search_providers : "联网搜索配置"
    tenants ||--o{ im_channels : "IM 渠道"
    im_channels ||--o{ im_channel_sessions : "渠道会话映射"
    im_channel_sessions }o--|| sessions : "session_id"
    tenants ||--o{ embed_channels : "嵌入渠道"

    tenants ||--o{ storage_backends : "存储后端"
    tenants ||--o{ resources : "资源"
    resources }o--o| storage_backends : "storage_backend_id"
    resources ||--o{ resource_bindings : "多态绑定 (message/knowledge/session)"
    resources ||--o{ resource_access_grants : "访问授权"

    tenants ||--o{ task_pending_ops : "任务队列"
    tenants ||--o{ task_dead_letters : "死信"
    knowledges ||--o{ knowledge_processing_spans : "处理 trace"

5. 迁移机制（golang-migrate）

迁移工具是 golang-migrate/migrate v4（go.mod：github.com/golang-migrate/migrate/v4 v4.19.1），状态记录在 schema_migrations 表（version + dirty）。有两条执行路径：

5.1 应用启动时自动迁移（默认）

internal/container/container.go 的 initDatabase()：

• AUTO_MIGRATE != "false" 时（默认开启），调用 database.RunMigrationsWithOptions(migrateDSN, opts)；
• AUTO_RECOVER_DIRTY != "false" 时（默认开启）设置 MigrationOptions.AutoRecoverDirty = true，遇到 dirty state 自动尝试恢复；
• 迁移失败只打 Warn 日志不阻断启动（假设迁移可能由外部管理），排查问题时务必看启动日志；
• postgres 的 migrate DSN 会拼上 options=-c app.skip_embedding=<true|false>（取决于 RETRIEVE_DRIVER 是否包含 postgres），控制 embeddings 相关迁移是否实际建表建索引。

internal/database/migration.go 中的路径选择逻辑：

// internal/database/migration.go
migrationsPath := "file://migrations/versioned"
if strings.HasPrefix(dsn, "sqlite3://") {
    migrationsPath = "file://migrations/sqlite"
}

即 postgres/ParadeDB 走 migrations/versioned/，SQLite 走 migrations/sqlite/。

5.2 手工执行：scripts/migrate.sh

scripts/migrate.sh 是 migrate CLI 的包装（Makefile 的 migrate-* 目标调用它）：

• 自动加载根目录 .env；
• DSN 优先取 DB_URL（并把 sslmode=require/prefer 强制替换为 disable），否则由 DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME 拼装（默认 localhost:5432/postgres/WeKnora），密码用 Python urllib.parse.quote URL 编码以兼容特殊字符；
• 迁移目录默认 MIGRATIONS_DIR=migrations/versioned；
• 未安装 migrate 时提示：go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest。

make migrate-up                    # 应用全部待执行迁移
make migrate-down                  # 回滚
make migrate-version               # 查看当前版本与 dirty 标志
make migrate-create name=add_xxx   # 创建 000080_add_xxx.up.sql / .down.sql
make migrate-force version=74      # 强制标记版本（恢复 dirty）
make migrate-goto version=60       # 迁移/回滚到指定版本

6. 如何新增一个迁移

1. 创建文件：make migrate-create name=add_my_feature，在 migrations/versioned/ 下生成下一个版本号（当前最大为 000079，新迁移将是 000080_add_my_feature.up.sql / .down.sql）；
2. 编写 up SQL：注意 PostgreSQL 方言（JSONB、部分索引、TIMESTAMP WITH TIME ZONE）；若涉及 embeddings 表，参考既有迁移用 app.skip_embedding GUC 做条件门控（SELECT current_setting('app.skip_embedding', true)），保证非 postgres 检索引擎部署也能通过迁移；
3. 编写 down SQL：必须可逆（drop column/table/index），否则回滚链会断；
4. 同步 SQLite：migrations/sqlite/000000_init.up.sql 是压平的全量 schema，新增列/表必须合并进去（注意方言转换：JSONB→TEXT、SERIAL→INTEGER AUTOINCREMENT、无部分索引语法差异等）。若变更需要在已有 Lite 库上生效（例如删表、删数据），还要在 migrations/sqlite/ 追加一个增量版本；
5. 同步 GORM 模型：在 internal/types/ 对应 struct 增加字段（GORM 只做 ORM 映射，生产库不使用 AutoMigrate 建表，schema 完全由 SQL 迁移驱动）;
6. 验证：make migrate-up → make migrate-down → make migrate-up 三连确认可逆；SQLite 侧用 DB_DRIVER=sqlite 启动一次 Lite 版验证初始化脚本。

7. 常见迁移问题排查

7.1 dirty state（最常见）

迁移中途失败/进程被杀后，schema_migrations.dirty = true，后续迁移拒绝执行。

# 1. 确认状态
make migrate-version            # 输出形如 "74 (dirty)"
# 或直接查表
# SELECT version, dirty FROM schema_migrations;

# 2. 人工检查该版本的 up SQL 实际执行到哪，把残留补齐或清理

# 3. 强制回到上一个干净版本后重试
make migrate-force version=73
make migrate-up

应用默认 AUTO_RECOVER_DIRTY 开启（container.go），启动时会自动尝试恢复；若关闭（设为 false），日志会提示手工使用 force。

7.2 迁移"成功"但表没建出来

检查启动日志：自动迁移失败只是 Warn（Database migration failed ... Continuing with application startup），不会让进程退出。另外 embeddings 相关对象受 app.skip_embedding 门控——若 RETRIEVE_DRIVER 不含 postgres，不建 embeddings 索引属预期行为。

7.3 密码特殊字符导致连接失败

migrate CLI 要求 URL 形式 DSN，密码含 @ # ! 等字符必须 URL 编码。scripts/migrate.sh 和 container.go 都已处理（分别用 Python quote 与 Go url.QueryEscape）；自己手拼 DB_URL 时需自行编码。

7.4 ParadeDB / 原生 Postgres 差异

BM25 索引（USING bm25、Lindera 中文分词）只在 ParadeDB 可用；原生 Postgres 部署需保证相应迁移的条件分支生效或改用 Elasticsearch 等外部检索引擎。存量原生 Postgres 库切到 ParadeDB 可参考 migrations/paradedb/01-migrate-to-paradedb.sql。

7.5 版本文件冲突

多个分支同时新增同一个版本号（如两个 000080_*）会冲突：golang-migrate 按数字排序且版本号唯一。合并时后合入者需要把自己的迁移改成下一个空闲版本号（up/down 两个文件都要改名）。