LobeHub
LobeHub

全文搜索

LobeHub 使用全文搜索检索助手、话题、消息、文件、知识库、群聊和记忆等产品数据。这里的全文搜索与助手可调用的联网搜索工具无关。

LobeHub 支持三种产品搜索后端:

后端适用场景额外运维工作
pg_searchPostgreSQL 已支持 ParadeDB pg_search 扩展,希望部署结构尽量简单BM25 索引由 PostgreSQL 维护,不需要单独运行搜索同步任务
elasticsearch数据量较大、需要 BM25 搜索质量,并且能维护独立搜索服务和常驻同步任务需要 Elasticsearch 服务(外部服务,或官方 Docker Compose 附带的可选单节点服务)、首次全量回填、PostgreSQL 变更采集和持续运行的增量消费任务
pg_like使用普通 PostgreSQL 的个人或小型自部署,不想再运维 Elasticsearch无;直接在现有数据表上做子串匹配,不需要扩展、索引或同步任务

FTS_SEARCH_PROVIDER 为整个部署选择唯一的后端,可用值为 pg_search、elasticsearch 和 pg_like,默认值是 pg_search。选中的后端不可用时,LobeHub 不会静默切换到另一个后端。

数据库迁移只在数据库提供 pg_search 扩展时安装它和 BM25 索引,否则跳过这一步。在没有 pg_search 的 PostgreSQL 上,请在启动 LobeHub 前设置 FTS_SEARCH_PROVIDER=pg_like 或 elasticsearch。后端为 pg_search(包括未设置时的默认值)而数据库缺少该扩展或任一 LobeHub BM25 索引时,数据库迁移步骤会报错并给出修复方法:Docker 容器不会启动,Vercel 构建会失败。

如何选择

如果 PostgreSQL 服务支持 pg_search,BM25 索引没有挤占其他数据库工作负载,并且你不希望额外维护一套搜索服务,可以继续使用默认后端。

自建数据库时,LobeHub 的 Docker 示例使用 paradedb/paradedb:latest-pg17 镜像并预加载 pg_search。执行正常的 LobeHub 数据库迁移以安装扩展和项目维护的 BM25 索引,并保持:

FTS_SEARCH_PROVIDER=pg_search

如果数据库是在执行完 LobeHub 迁移之后才安装 pg_search 的,请在 LobeHub 源码目录中先创建扩展和 BM25 索引,再选择这个后端:

*.sh
Shell
psql "$DATABASE_URL" -c 'CREATE EXTENSION IF NOT EXISTS pg_search'
psql "$DATABASE_URL" -f packages/database/migrations/0093_add_bm25_indexes_with_icu.sql

在普通 PostgreSQL 上使用 pg_like

如果 PostgreSQL 服务无法安装 pg_search(很多托管数据库都是如此),而部署规模又小到不值得单独运维一套搜索服务,可以选择 pg_like。它不需要扩展、不需要额外索引、也不需要同步任务:所有搜索都以不区分大小写的子串匹配(ILIKE)直接在与 pg_search 相同的数据表和权限范围上执行。

FTS_SEARCH_PROVIDER=pg_like

与其他后端相比需要注意:

  • 匹配方式。 查询中的每个词都出现在同一个可搜索字段里时才算命中;没有词干还原、拼写容错和短语距离。中日韩文本无需分词即可匹配,因为匹配基于子串。
  • 排序。 结果按简单的相关度打分排序:整字段完全匹配高于前缀匹配,前缀匹配高于短语包含,短语包含高于仅包含全部词语;标题类字段的权重高于正文。
  • 性能。 查询会扫描权限范围内的数据行而不是走搜索索引。个人和小团队实例完全够用;消息或记忆表很大时,请优先考虑 pg_search 或 Elasticsearch。

在没有 pg_search 的 PostgreSQL 上,全新建库和升级都能完成:迁移会跳过扩展和 BM25 索引。如果你之前为了完成升级替换过 0090_enable_pg_search.sql 或 0093_add_bm25_indexes_with_icu.sql 迁移文件,请移除这项覆盖。

使用 Elasticsearch

如果搜索需要独立容量、希望把搜索存储从事务 PostgreSQL 中拆开,并且能够持续运行同步任务,可以选择 Elasticsearch。个人或小型部署在数据库停止支持 pg_search 时,应优先考虑无需额外服务的 pg_like。

Neon 已于 2026 年 3 月 19 日停止为新项目提供 pg_search。现有项目的停用安排以 Neon 发给该项目的通知为准;收到停用通知的 LobeHub 用户应按 Neon pg_search 迁移指南选择 pg_like 或 Elasticsearch。执行前请核对 Neon 的最新 pg_search 公告。

Elasticsearch 有两种受支持的运行方式。两者使用同一套回填和增量同步命令、同一个 ES_INDEX_NAMESPACE,区别只在于 LobeHub 如何连接集群。

外部 Elasticsearch(Elastic Cloud 或托管集群)

  • LobeHub 服务端可以通过 HTTPS 访问的 Elasticsearch 项目;
  • 官方 ICU 分析插件;Elastic Cloud Serverless 已内置,自建集群则必须在每个节点安装;
  • ES_URL、ES_API_KEY 和保持不变的 ES_INDEX_NAMESPACE;
  • 先完成全量回填,再持续消费 PostgreSQL 增量队列;
  • 只有全量回填完成且增量队列追平后,才能设置 FTS_SEARCH_PROVIDER=elasticsearch。

明文 HTTP 只允许用于本地开发时的回环地址。LobeHub 拒绝把 API 密钥通过明文 HTTP 发送到任何其他主机。

Docker Compose 单节点 Elasticsearch

官方 docker-compose/deploy/docker-compose.yml 附带一个默认关闭的可选 elasticsearch 服务,以及基于官方 LobeHub 镜像的回填和同步命令,适合希望在单机上使用 Elasticsearch、又不想申请外部账号的部署。该 Elasticsearch 关闭了安全认证,只能在 Compose 内部网络访问,因此必须通过 ES_ALLOW_INSECURE_HTTP=true 显式允许无 API 密钥的明文连接。详见下文 使用 Docker Compose 运行 Elasticsearch。

两种方式的数据库支持

Elasticsearch 不要求 PostgreSQL 支持 pg_search:数据库不提供该扩展时,LobeHub 迁移会跳过 BM25 相关设置。如果数据库中已有 pg_search 对象,回填完成后由 Elasticsearch 接管搜索流量,这些对象可以之后通过项目提供的清理命令移除。

选择建议和迁移入口,请参阅 Neon pg_search 迁移指南。

Elasticsearch 如何同步数据

PostgreSQL 始终是数据事实来源。启用 Elasticsearch 路径后,采集触发器会把源数据变更合并写入持久化增量队列,持续运行的消费任务再把这些变更写入 Elasticsearch。搜索时,Elasticsearch 只返回候选标识,LobeHub 仍会回到 PostgreSQL 校验权限并读取最终结果。

运行链路如下:

*.txt
Plaintext
PostgreSQL 写入
  -> 采集触发器
  -> 全文搜索增量队列
  -> 持续运行的 fts-search:sync 消费任务
  -> Elasticsearch 索引
  -> 候选结果检索
  -> PostgreSQL 权限校验和结果读取

全量回填只负责首次快照,不能代替持续消费任务。只要 Elasticsearch 仍在提供搜索,就必须持续调度 fts-search:sync。

使用 Docker Compose 运行 Elasticsearch

docker-compose/deploy/docker-compose.yml 中的可选服务都由 Compose profile 控制,默认的 docker compose up 既不会下载也不会启动它们:

服务Profile作用
elasticsearchelasticsearch基于固定版本官方镜像在本机构建并内置 analysis-icu 的单节点,使用命名数据卷和健康检查,不向宿主机公开端口
fts-search-reindexelasticsearch-reindex基于 lobehub/lobehub 镜像的一次性回填 / 状态命令;checkpoint 保存在 fts-search-reindex-state 卷中
fts-search-syncelasticsearch-sync基于 lobehub/lobehub 镜像的长期增量消费任务;遇到失败或死信任务时退出并由 Compose 重启,同时输出日志

资源说明:节点默认使用 1 GB JVM 堆内存(ES_JAVA_OPTS);堆内存不要超过分配给容器内存的一半,并为 Elasticsearch 单独预留至少 2 GB 内存。Linux 宿主机必须设置 vm.max_map_count=262144。启用该 profile 后首次执行 docker compose up 会基于固定版本的官方镜像构建一次镜像并安装 analysis-icu,构建时需要能访问 docker.elastic.co 和 artifacts.elastic.co;之后重建容器不再需要外网。构建上下文是 Compose 文件旁边的 elasticsearch/Dockerfile,setup.sh 会一并下载。升级 Elasticsearch 时,同时修改 elasticsearch 服务中 image 和 build.args 的版本号,再执行 docker compose up -d --build。

  1. 启用节点。 在 .env 中取消 Elasticsearch 配置块的注释,并继续让 pg_search 提供搜索:

    *.sh
    Shell
    COMPOSE_PROFILES=elasticsearch
    ES_URL=http://elasticsearch:9200
    ES_ALLOW_INSECURE_HTTP=true
    ES_INDEX_NAMESPACE=lobehub
    # FTS_SEARCH_PROVIDER 在最后一步之前保持默认值 pg_search

    然后启动整套服务并等待包括新节点在内的所有服务通过健康检查;同一版本的数据库迁移会创建增量队列的基础结构:

    docker compose up -d --wait
  2. 全量回填。 先查看状态,再执行一次性回填。--apply 会安装 PostgreSQL 变更采集、按 ICU 映射创建 14 类索引、复制数据并创建别名:

    *.sh
    Shell
    docker compose run --rm fts-search-reindex --status
    docker compose run --rm fts-search-reindex --apply --fresh-run --yes

    只有第一次执行需要 --fresh-run。如果中断,去掉 --fresh-run 重新执行同一命令即可从 checkpoint 卷续跑。反复执行 --status,直到状态为 ready_for_incremental_sync、所有数据类型为 completed 且所有 failedCount 为 0。

  3. 启动持续同步。 加上同步 profile 并重新创建服务:

    *.sh
    Shell
    COMPOSE_PROFILES=elasticsearch,elasticsearch-sync
    *.sh
    Shell
    docker compose up -d
    docker compose logs -f fts-search-sync

    该任务循环执行 fts-search-elasticsearch-sync.cjs --max-steps=8 --interval-seconds=15 --yes (FTS_SEARCH_SYNC_INTERVAL_SECONDS 可调整没有新任务时的等待时间)。遇到失败或死信任务时它会以非零状态退出,Compose 会重启它,因此容器反复重启说明队列需要人工处理。只要 Elasticsearch 仍在提供搜索,就必须保持它运行。

  4. 显式切换。 当 docker compose run --rm fts-search-reindex --status 显示 pending、ready、 retrying、inFlight、dead 和 revisionLag 全部为 0 时,在 .env 中设置 FTS_SEARCH_PROVIDER=elasticsearch,并重新创建应用容器:

    docker compose up -d lobe

    任何步骤都不会自动切换搜索后端。回滚只需恢复 FTS_SEARCH_PROVIDER=pg_search 并重新创建 lobe;同步任务可以继续运行。

外部目标:fts-search-reindex 和 fts-search-sync 只依赖 PostgreSQL,不依赖内置节点。如果要改为对接 Elastic Cloud,请不要在 COMPOSE_PROFILES 中启用 elasticsearch profile,在 .env 中设置 ES_URL 和 ES_API_KEY, 且不要设置 ES_ALLOW_INSECURE_HTTP;第 2 到第 4 步完全相同。

重建当前 Elasticsearch schema generation

如果投影或 capture 行为的改动要求重新生成全部历史文档,先升级所有应用和持续同步 worker,再从 PostgreSQL 创建一个 mapping 版本不变的新物理 generation:

*.sh
Shell
docker compose run --rm fts-search-reindex \
  --apply --rebuild-current --entity=messages --yes

命令会输出 run ID,以及类似 <namespace>-messages-v1-r<run-id> 的索引名。若任务中断,使用相同命令并增加 --run-id=<run-id> 继续。持续同步会同时写入现有 generation 和重建 generation;不要暂停应用写入或同步 worker。首次创建 checkpoint 时只会短暂阻挡能够生成所选实体更新的 PostgreSQL 表;续跑同一 checkpoint 不会再次执行这一步。回填显示 ready_for_incremental_sync 且 messages Outbox 空闲后,按精确物理索引名切换:

*.sh
Shell
docker compose run --rm fts-search-reindex \
  --promote --entity=messages --generation=<精确索引名> --yes

alias 和逻辑 schema 版本保持不变。观察期内保留旧 generation,出现问题时可按其精确名称切回。确认无需回滚后,执行 --purge --entity=messages --yes。Purge 会先安装精确索引名的防自动创建规则,再删除每个已脱离 alias 的旧索引。自建集群可以先用 --retire --entity=messages --yes 关闭旧索引;Elastic Cloud Serverless 不支持关闭索引,应跳过 retire,直接 purge。

这一模式的安全边界:ES_ALLOW_INSECURE_HTTP=true 允许向非回环主机使用明文 HTTP,并允许省略 ES_API_KEY;但它永远不允许通过明文 HTTP 发送 API 密钥,因此不要把它与 ES_API_KEY 和 http:// 地址同时使用。Elasticsearch 服务没有公开端口,也不要为它添加端口,因为该节点接受未认证的请求。Elastic Cloud 路径保持不变:不设置这个变量时,LobeHub 仍然要求 HTTPS 和 API 密钥。

配置项

变量用途
FTS_SEARCH_PROVIDER整个部署使用的搜索后端:pg_search、elasticsearch 或 pg_like
ES_URLElasticsearch 地址。使用 HTTPS;明文 HTTP 只允许用于回环地址,或在 ES_ALLOW_INSECURE_HTTP=true 时用于 elasticsearch 这类 Compose 内部主机名
ES_API_KEY具备建索引、批量写入、刷新、统计、别名和搜索权限的 Elasticsearch 密钥;除 ES_ALLOW_INSECURE_HTTP=true 外均为必需
ES_ALLOW_INSECURE_HTTP设为 true 时显式允许对只能在私有容器网络访问的 Elasticsearch 节点使用无 API 密钥的明文 HTTP;永远不会通过 HTTP 发送密钥
ES_INDEX_NAMESPACE当前部署独占且保持不变的物理索引和别名前缀
FTS_SEARCH_SYNC_ENABLED启用增量消费任务;首次全量回填就绪后才能设为 true。Compose 的同步服务会自行设置

仅由 docker-compose/deploy/docker-compose.yml 读取的 Compose 变量:

变量用途
COMPOSE_PROFILESelasticsearch 启动节点;elasticsearch,elasticsearch-sync 同时启动同步任务
ES_JAVA_OPTSElasticsearch 容器的 JVM 堆内存,默认 -Xms1g -Xmx1g
FTS_SEARCH_SYNC_INTERVAL_SECONDS同步任务在一次没有新任务的消费后等待的秒数,默认 15

不同 LobeHub 部署不能共用同一个索引前缀。迁移或增量消费期间不能更改此前缀。

监控 Elasticsearch 搜索

LobeHub 会输出有限维度的 OpenTelemetry 指标和链路,不会记录原始查询、用户标识、文档标识或索引正文。主要指标包括:

指标可以回答的问题
fts_search_backend_operations_total按后端、数据类型、操作和结果统计的请求量及失败量
fts_search_backend_operation_duration搜索后端的端到端耗时
fts_search_backend_result_count请求数量、候选数量和 PostgreSQL 最终返回数量
fts_search_elasticsearch_requests_total实际 Elasticsearch 请求量和结果
fts_search_elasticsearch_request_duration包含响应解析的 Elasticsearch 请求耗时
fts_search_elasticsearch_request_size序列化后的请求体大小
fts_search_elasticsearch_response_decoded_size解码后的响应体大小
fts_search_elasticsearch_response_hits每次 Elasticsearch 请求返回的候选数量
fts_search_elasticsearch_server_tookElasticsearch 上报的服务端处理时间

链路名称为 fts.search.backend.<operation>。分析 Elasticsearch 成本时,需要同时查看请求量、请求与响应大小、 候选数量、服务端耗时和索引存储,不能只看其中一项。自部署 OpenTelemetry 环境请参阅 Grafana 可观测性。

运维原则

  • 生产迁移前先备份 PostgreSQL,并使用隔离的数据库副本和 Elasticsearch 项目完成演练。
  • 同一次全量回填的每次续跑都必须使用同一个持久化状态目录,不能让两个任务同时操作同一份状态和物理索引。
  • 所有数据类型完成、失败数为 0、增量队列追平前,必须继续让 pg_search 对外提供搜索。
  • 切换后使用项目提供的清理命令,不需要手工复制数据库对象 SQL。
  • 必须保留 Elasticsearch 依赖的增量队列、采集触发器和持续消费任务;它们与 Neon 删除 pg_search 无关。