Halo 搜索引擎扩展点完全指南：自定义搜索引擎与文档类型开发实战

Halo 将全文搜索能力抽象为一组稳定扩展点，允许插件以统一方式接入 Lucene、Solr、MeiliSearch 等搜索引擎并扩展文章之外的文档类型。本文将围绕 docs/extension-points/search-engine.md 展开，结合 api 与 application 模块中的真实源码，讲解 SearchEngine 与 HaloDocumentsProvider 两个扩展点的接口语义、事件驱动的索引增删改机制，以及插件如何发布事件完成文档的添加、删除与全量重建。读完本文，你将能基于该扩展点协议开发出可被 Halo 搜索模块识别的第三方搜索引擎插件与自定义搜索文档插件。

搜索引擎模块的整体架构

在 Halo 中，搜索引擎模块负责为全站内容提供全文检索能力，是核心模块之一。它遵循"核心抽象 + 扩展实现 + 事件解耦"的设计：

• 搜索引擎抽象：模块定义统一的搜索引擎 SPI，索引与检索逻辑不再与某个具体搜索引擎绑定；
• 内置实现：当前版本内置了基于 Apache Lucene 的本地全文搜索引擎，其他引擎（如 Solr、MeiliSearch、ElasticSearch）均需通过插件方式接入；
• 文档抽象：被索引的内容统一建模为 HaloDocument，不限于是文章，任何业务实体（文章、单页、说说、文档等）都可成为搜索文档；
• 事件驱动：从 Halo 2.17 开始，核心与插件均通过发布事件来触发文档的添加、更新、删除与重建，文档重建所需的源数据由 HaloDocumentsProvider 提供。

整个搜索相关代码集中在两个模块：

• 接口与模型层：api/src/main/java/run/halo/app/search（SPI 定义、文档模型、事件类型）；
• 实现与装配层：application/src/main/java/run/halo/app/search（Lucene 实现、事件监听、默认文档 Provider）。

扩展点一：搜索引擎扩展（SearchEngine）

如果插件想为 Halo 接入新的搜索引擎，需要实现 SearchEngine 接口。该接口继承自 pf4j 的 org.pf4j.ExtensionPoint，因此天然支持插件扩展机制，由 ExtensionGetter 统一管理启用状态。

接口契约如下：

方法	作用
boolean available()	当前搜索引擎是否可用；不可用时会触发 SearchEngineUnavailableException
void addOrUpdate(Iterable<HaloDocument> haloDocuments)	批量添加或更新文档（按文档 id 幂等覆盖）
void deleteDocument(Iterable<String> haloDocIds)	按文档 id 批量删除
void deleteAll()	清空全部索引文档
SearchResult search(SearchOption option)	执行检索并返回命中结果

关于可用性判断需要特别注意：SearchServiceImpl 在检索时通过 ExtensionGetter.getEnabledExtension(SearchEngine.class) 获取启用中的引擎，再执行 filter(SearchEngine::available)；同样，HaloDocumentEventsListener 在消费文档事件时也遵循相同逻辑。若没有可用的搜索引擎，会抛出 SearchEngineUnavailableException，因此插件实现引擎时务必正确上报 available()。

参考实现：Lucene 搜索引擎

Halo 的默认实现是 LuceneSearchEngine，它同时实现了 SearchEngine、InitializingBean 与 DisposableBean，可作为插件接入自定义引擎的最佳范本。其关键实现细节：

• 索引目录：使用 FSDirectory.open(indexRootDir) 将索引持久化到文件系统目录，索引读写均以 IndexWriter 配合 CREATE_OR_APPEND 打开模式完成；
• 分词器：在 afterPropertiesSet() 中通过 CustomAnalyzer 构建分析器，核心链路为 StandardTokenizer → HTMLStripCharFilter（去除 HTML 标签）→ CJK 宽度归一化 → 小写化 → CJKBigramFilter（中文二元语法切分），可良好支持中英文混合内容；
• 新增/更新：addOrUpdate 通过 TermInSetQuery("id", ...) 先删除同 id 旧文档再写入，实现幂等 upsert；
• 删除：deleteDocument 按 id 集合构造 TermInSetQuery 执行批量删除；deleteAll 调用 indexWriter.deleteAll() 清空全部索引；
• 检索：见下文"检索行为"小节。

文档模型：HaloDocument

无论是内置引擎还是第三方引擎，索引与检索的对象都是统一的 HaloDocument 模型，其核心字段及含义如下：

字段	说明
id	全局唯一的文档 ID，是 upsert 与删除的主键（必填）
metadataName	对应业务扩展资源的 metadata name
title / description / content	文档标题、摘要与正文；content 要求为去除 HTML 标签后的安全内容
categories / tags	分类、标签集合，元素为对应分类/标签的 metadata name
published / recycled / exposed	是否已发布、是否在回收站、是否公开可见
ownerName	文档所有者的 metadata name
creationTimestamp / updateTimestamp	创建与更新时间
permalink	文档永久链接
type	文档类型，用于区分文档来源，如 post.content.halo.run、singlepage.content.halo.run、moment.moment.halo.run、doc.doc.halo.run 等

字段上的校验注解（@NotBlank、@PastOrPresent）保证了进入索引的数据结构合法性，插件构造文档时也应遵守这些约束。

扩展点二：搜索文档扩展（HaloDocumentsProvider）

搜索引擎只负责"存"与"取"，索引重建的数据源则由另一个扩展点提供。HaloDocumentsProvider 同样继承 ExtensionPoint，只定义了两个方法：

• Flux<HaloDocument> fetchAll()：拉取该类型下的全部文档（响应式流，供重建索引时遍历）；
• String getType()：声明该 Provider 负责的文档类型。

插件若要支持新的搜索文档类型（例如新增"笔记"内容模型并希望其可被全站搜索），就实现该接口并声明自身 @Extension，使其进入扩展点列表。

参考实现：文章文档 Provider

Halo 默认实现 PostHaloDocumentsProvider 是扩展新文档类型的标准范式，要点如下：

• 声明文档类型常量 POST_DOCUMENT_TYPE = "post.content.halo.run"；
• fetchAll() 通过 ReactiveExtensionPaginatedOperator 分页遍历 Post 资源，并使用字段选择器过滤掉软删除（metadata.deletionTimestamp 为空）的记录，再调用 PostService.getReleaseContent(post) 取发布内容，最终逐个 convert(post, contentWrapper) 为 HaloDocument；
• 静态方法 convert(...) 演示了字段映射约定：id = "post.content.halo.run" + '-' + metadataName，即推荐以 类型 + '-' + 元数据名 构造文档 id，保证全局唯一且便于按实体定位；同时把摘要映射到 description、正文去除 HTML 后映射到 content，并写入 published、recycled、exposed、permalink 等状态字段。

注意：文档仅描述"有哪些内容可被索引"；至于是否公开给匿名用户，属于检索侧策略，由 SearchOption 过滤条件与搜索引擎负责，Provider 只负责如实上报实体状态。

事件机制：从 Halo 2.17 开始的统一索引操作入口

从 Halo 2.17 开始，文档的增删改与重建统一收敛为三类共享事件，它们都定义在 api/src/main/java/run/halo/app/search/event 下，并被标注为 @SharedEvent，因而可跨"核心 / 插件"边界发布与监听：

事件类	携带数据	语义
HaloDocumentAddRequestEvent	Iterable<HaloDocument>	添加或更新一批文档
HaloDocumentDeleteRequestEvent	Iterable<String> docIds	按 id 删除文档；docIds 为 null 时表示删除全部文档
HaloDocumentRebuildRequestEvent	无	请求全量重建索引

这些事件由 HaloDocumentEventsListener 以 @EventListener + @Async 方式异步消费，通过 ExtensionGetter 拿到当前启用的搜索引擎后执行对应操作。其中重建索引的内部流程清晰地串联了上文两个扩展点：

1. 获取可用的 SearchEngine；
2. 调用 searchEngine.deleteAll() 清空旧索引；
3. 遍历所有启用的 HaloDocumentsProvider 扩展，调用各自的 fetchAll() 拉取全量文档；
4. 以 200 为缓冲批量调用 searchEngine.addOrUpdate(...) 写回新索引（bufferSize 可在测试中调整）；
5. 整体超时上限为 1 分钟。

核心内部对索引的日常维护也遵循同一事件通道。例如 PostEventsListener 监听文章业务事件：PostUpdatedEvent 触发时先将文章转成 HaloDocument，再发布 HaloDocumentAddRequestEvent；PostDeletedEvent 触发时直接发布携带 "post.content.halo.run-" + postName 的删除事件；永久删除的文章则同样走删除路径。插件开发者在实现第三方文档类型时，完全可以参照这一模式，在自己的业务事件监听器中发布对应事件。

插件中发布事件的完整示例

下面三个示例完整覆盖了插件侧控制索引的全部操作（均通过注入的 ApplicationEventPublisher 发布共享事件）：

1. 添加/更新文档

class HaloDocumentAddExample {

  private final ApplicationEventPublisher eventPublisher;

  void addDocuments() {
    // concrete Halo documents
    List<HaloDocument> documents = ...;
    eventPublisher.publishEvent(new HaloDocumentAddRequestEvent(this, documents));
  }
}

2. 删除文档

class HaloDocumentDeleteExample {

  private final ApplicationEventPublisher eventPublisher;

  void deleteDocuments() {
    Set<String> docIds = ...;
    eventPublisher.publishEvent(new HaloDocumentDeleteRequestEvent(this, docIds));
  }
}

3. 全量重建索引

class HaloDocumentRebuildExample {

  private final ApplicationEventPublisher eventPublisher;

  void rebuildDocument() {
    eventPublisher.publishEvent(new HaloDocumentRebuildRequestEvent(this));
  }
}

检索行为：SearchOption 与 SearchResult

搜索引擎扩展的 search(SearchOption) 方法是检索能力的出口，插件开发者有必要理解 SearchOption 的过滤语义，确保自定义引擎与内置 Lucene 行为对齐：

字段	默认值	语义
keyword	必填	搜索关键词
limit	10	返回条数上限，取值 1~1000
highlightPreTag / highlightPostTag	<B> / </B>	高亮片段的包裹标签
filterExposed / filterRecycled / filterPublished	null	是否按公开/回收站/发布状态过滤；null 表示不过滤
includeTypes	null	限定命中文档类型（或关系），null 表示包含全部
includeOwnerNames	null	限定作者集合（或关系）
includeCategoryNames / includeTagNames	null	限定分类/标签（且关系，多值取交集）
annotations	无	供其他搜索引擎扩展自定义参数的地图

从 Lucene 实现（LuceneSearchEngine#search）可以对照上述语义在真实引擎中如何落地：

• 关键词经 QueryParserBase.escape 转义后，以 MUST 子句命中 title、description、content 三个多字段，字段加权为 title: 1.0、description: 0.5、content: 0.2，标题命中权重最高；
• exposed、recycled、published 三个状态与 type、ownerName 以 FILTER 子句过滤（不影响相关性打分），category、tag 则逐值叠加为 AND 语义的过滤；
• 结果按相关性 Sort.RELEVANCE 排序，随后用 Highlighter + QueryTermScorer 对标题、摘要与正文生成高亮片段（片段为空时回退为原文）；
• 响应对象为 SearchResult，包含 hits（命中文档，其中的 title/description/content 已被替换为高亮片段）、keyword、total、limit 与 processingTimeMillis；
• 索引为空时返回 total 为 0 的空结果集。

底层索引写入时，HaloDocument 的字段（含 type、ownerName、category、tag、三个布尔状态等）会被转换为对应 Lucene 域，才使得上述过滤查询成立。

开发建议与注意事项

基于对接口定义与现有实现的梳理，为插件开发者总结如下实践要点：

1. 按类型区分文档并约定 id 前缀：参考 post.content.halo.run-{metadataName} 的做法，用 类型 + '-' + 实体名 构造唯一 id，天然避免多类型文档 id 冲突，也让删除事件可以精确按实体定位；
2. 正文写入前去除 HTML：HaloDocument.content 约定为无标签安全文本，Lucene 实现自身也配置了 HTMLStripCharFilter 兜底，第三方引擎接入时同样应遵守此约定以保证索引质量与内容安全；
3. 重建操作只做数据供给：插件实现 HaloDocumentsProvider.fetchAll() 即可，清空与回填由 HaloDocumentEventsListener 编排，无需关心引擎细节；若被索引实体与 Post 类似拥有"发布状态/回收站/公开性"，应如实映射到对应布尔字段，把权限策略留给检索侧过滤；
4. 以事件而非直接调用引擎：核心与插件统一通过三个 @SharedEvent 事件驱动索引变更，既解耦引擎实现，又保证多引擎并存时的行为一致性；删除事件传 null 文档 id 可清空索引，需谨慎使用；
5. 引擎可用性需要如实上报：available() 返回 false 的引擎不会收到检索与事件请求，并会以 SearchEngineUnavailableException 明确暴露"无可用引擎"状态，便于上层捕获与提示。

如需进一步掌握扩展点运行机制，可继续阅读本仓库 docs/extension-points 下的其他扩展点文档；接口定义与默认实现则是验证行为细节的第一手资料（SearchEngine、HaloDocumentsProvider、LuceneSearchEngine、PostHaloDocumentsProvider）。