Database migration issue with pgsearch

快速结论：这个报错通常出现在 LobeChat 连接数据库并执行 CREATE EXTENSION IF NOT EXISTS pg_search; 时，当前数据库版本或权限不支持 pg_search。优先检查数据库是否为 PostgreSQL 17，以及当前数据库用户是否有创建扩展的权限。

适用环境：LobeChat 最新版；macOS + Web 浏览器；部署在 Vercel；数据库使用 Neon PostgreSQL 16；另有一条来自 CNPG 集群环境的同类报错。

最快修复方案：暂无确认的一步修复方案。Issue 中提到两个已验证或可优先尝试的方向：将 Neon 数据库迁移到 PostgreSQL 17 后再重新构建；自托管 Docker 用户可把数据库镜像从 pgvector/pgvector:pg17 切换为 paradedb/paradedb:*-pg17，复用已有 PG17 volume 后执行 CREATE EXTENSION IF NOT EXISTS pg_search;，然后升级 LobeChat。

注意事项：Neon 的 Import Data 迁移功能并非完全稳定，官方说明也提示可能带来预期之外的结果；迁移前请先备份数据。CNPG 环境下的报错提示 must be superuser to create a base type，说明由 LobeChat 迁移脚本创建扩展会强制要求过高权限，生产环境不推荐直接授予 SUPERUSER。已有 Docker 复用 volume 的成功案例仅适用于自托管 Docker + PG17 场景，不代表 Neon 场景。

问题场景

用户在 Vercel 上部署 LobeChat，数据库后端使用 Neon 的 PostgreSQL 16。执行构建时，LobeChat 会运行数据库迁移脚本 scripts/migrateServerDB/index.ts，其中包含自定义 SQL 迁移文件，需要执行 CREATE EXTENSION IF NOT EXISTS pg_search;。由于 Neon PostgreSQL 16 默认不支持 pg_search，迁移在这一步失败，构建中断。另有用户在 CNPG 集群环境中遇到相同迁移步骤报错。

报错原文

17:22:07.505 $ cross-env MIGRATION_DB=1 tsx ./scripts/migrateServerDB/index.ts
17:22:15.888 ❌ Database migrate failed: DrizzleQueryError: Failed query: -- Custom SQL migration file, put your code below! --
17:22:15.890 CREATE EXTENSION IF NOT EXISTS pg_search;
17:22:15.890 params: 
17:22:15.890     at NeonPreparedQuery.queryWithCache (/vercel/path0/node_modules/.pnpm/drizzle-orm@0.45.1_@electric-sql+pglite@0.3.16_@neondatabase+serverless@1.0.2_@opentele_7657ae38a4ddd536128194930dcc404a/node_modules/src/pg-core/session.ts:73:11)
17:22:15.891     at process.processTicksAndRejections (node:internal/process/task_queues:103:5)
17:22:15.892     at async NeonPreparedQuery.execute (/vercel/path0/node_modules/.pnpm/drizzle-orm@0.45.1_@electric-sql+pglite@0.3.16_@neondatabase+serverless@1.0.2_@opentele_7657ae38a4ddd536128194930dcc404a/node_modules/src/neon-serverless/session.ts:147:11)
17:22:15.892     at async  (/vercel/path0/node_modules/.pnpm/drizzle-orm@0.45.1_@electric-sql+pglite@0.3.16_@neondatabase+serverless@1.0.2_@opentele_7657ae38a4ddd536128194930dcc404a/node_modules/src/pg-core/dialect.ts:102:7)
17:22:15.893     at async NeonSession.transaction (/vercel/path0/node_modules/.pnpm/drizzle-orm@0.45.1_@electric-sql+pglite@0.3.16_@neondatabase+serverless@1.0.2_@opentele_7657ae38a4ddd536128194930dcc404a/node_modules/src/neon-serverless/session.ts:270:19)
17:22:15.893     at async PgDialect.migrate (/vercel/path0/node_modules/.pnpm/drizzle-orm@0.45.1_@electric-sql+pglite@0.3.16_@neondatabase+serverless@1.0.2_@opentele_7657ae38a4ddd536128194930dcc404a/node_modules/src/pg-core/dialect.ts:95:3)
17:22:15.893     at async migrate (/vercel/path0/node_modules/.pnpm/drizzle-orm@0.45.1_@electric-sql+pglite@0.3.16_@neondatabase+serverless@1.0.2_@opentele_7657ae38a4ddd536128194930dcc404a/node_modules/src/neon-serverless/migrator.ts:10:2)
17:22:15.893     at async runMigrations (/vercel/path0/scripts/migrateServerDB/index.ts:30:5) {
17:22:15.894   query: '-- Custom SQL migration file, put your code below! --\n' +
17:22:15.894     'CREATE EXTENSION IF NOT EXISTS pg_search;',
17:22:15.894   params: [],
...

CNPG 环境下的同类报错尾部：

❌ Database migrate failed. Please check your database is valid and DATABASE_URL is set correctly. The error detail is below:

DrizzleQueryError: Failed query: -- Custom SQL migration file, put your code below! --

CREATE EXTENSION IF NOT EXISTS pg_search;

params:

cause: error: must be superuser to create a base type

原因分析

最可能的原因是当前数据库不支持 pg_search 扩展，或当前数据库用户权限不足，导致 CREATE EXTENSION IF NOT EXISTS pg_search; 无法执行。Issue 中明确指出 Neon PostgreSQL 16 默认不支持 pg_search，Neon 官方文档说明 PostgreSQL 16 需要联系支持手动开启，而 Neon 的 PostgreSQL 17 默认支持该扩展。因此 LobeChat 最新版迁移脚本在 Neon PG16 上会立即失败。

另一种可能原因是数据库用户没有创建扩展所需的权限。CNPG 环境下的报错为 must be superuser to create a base type，说明由迁移脚本直接创建扩展会要求 SUPERUSER 级别权限，普通生产数据库用户通常不具备该权限。

环境排查

确认 LobeChat 部署版本，Issue 中提到为 Latest。
确认数据库后端是否为 Neon，以及 PostgreSQL 版本是 16 还是 17。
确认当前 DATABASE_URL 是否指向目标数据库，迁移时是否使用了正确的连接串。
确认数据库用户是否具备创建扩展的权限；CNPG 报错提示需要 superuser。
确认是否使用 Vercel 构建，构建日志中是否出现 cross-env MIGRATION_DB=1 tsx ./scripts/migrateServerDB/index.ts。
自托管 Docker 场景需确认数据库镜像及版本，例如 pgvector/pgvector:pg17 或 paradedb/paradedb:*-pg17。
确认已有 Docker volume 是否挂载到 /var/lib/postgresql/data。

解决步骤

如果使用 Neon PostgreSQL 16，优先考虑迁移到 Neon PostgreSQL 17。Issue 中提到可按 Neon 官方方式，在 Neon 控制台右上角找到 import data 功能，将数据从原 Neon PG16 实例导入到新的 Neon PG17 实例。
在原 Neon 项目中复制 unpooled connection string；迁移完成后，在 Vercel 控制台修改 DATABASE_URL 为新实例的连接串，然后重新构建。Issuer 提到需要把 Branch 设置为 import。
如果使用自托管 Docker 且已有 PostgreSQL 17 volume，可优先尝试复用原 volume：先备份现有 DB volume，保持挂载路径 lobechat-db:/var/lib/postgresql/data 不变，将数据库镜像从 pgvector/pgvector:pg17 切换为 paradedb/paradedb:0.21.14-pg17 或 paradedb/paradedb:*-pg17。
迁移期间可先把应用固定在 lobehub/lobehub:2.1.39，启动整个 stack，确认复用的 PG17 数据目录能正常启动。
在数据库内手动执行 CREATE EXTENSION IF NOT EXISTS pg_search;，确认扩展可以成功创建。
将应用切换回 lobehub/lobehub:latest，再让 watchtower 将数据库更新到 paradedb/paradedb:latest-pg17，然后重新构建。Issue 中提到该方式无需 dump/restore，也无需 pg_upgrade，迁移可以干净通过。
如果使用 CNPG 或其他受管数据库，可由管理员在基础设施层手动创建 pg_search 扩展，而不是依赖 LobeChat 迁移脚本用业务数据库用户执行 CREATE EXTENSION。Issue 中有观点认为应把扩展创建从数据库迁移中移除，交给管理员手动 provision，否则会迫使生产环境给 lobebub 数据库用户授予 SUPERUSER 权限，这并不合适。

验证方法

重新触发 Vercel 构建或自托管部署重建，观察迁移阶段是否不再停在 CREATE EXTENSION IF NOT EXISTS pg_search;。构建日志中应不再出现 ❌ Database migrate failed。同时可在数据库侧确认扩展已存在，并确认 LobeChat 应用能正常启动、连接数据库。Issue 中自托管 Docker 案例的验证结果是：复用同一 PG17 volume 成功，无需 dump/restore，无需 pg_upgrade，LobeChat latest 解析到 v2.1.40，迁移干净通过。