Hister 规则系统实战:用 Skip、Priority、Versioning 与 Alias 掌控个人搜索引擎的索引与排序

原创2026-09-19 09:58:09196 阅读
文章标签:搜索引擎全文检索后端前端MCP 服务网页爬虫本地部署

Hister 规则系统实战:用 Skip、Priority、Versioning 与 Alias 掌控个人搜索引擎的索引与排序

Hister 是一套自托管的私有搜索引擎,规则(Rules)是它赋予你控制权的核心机制:通过正则模式决定哪些 URL 永不入索引、哪些结果永远置顶、哪些页面需要跟踪变更历史,并借助查询别名把常用过滤条件压缩成短关键词。本文基于官方规则文档,结合仓库源码,完整讲解四类规则的语义、模式语法边界、存储位置,以及通过 Web 界面、TUI、CLI 与 HTTP API 管理规则的实操方法。

读完本文你将掌握:如何用 skip 规则屏蔽广告与登录墙、用 priority 规则把个人 wiki 固定到结果顶部、用 versioning 规则审计隐私政策等页面的每次改动,以及用 work、local 这类别名加速日常检索。

规则存放在哪里

规则定义位于 {data_directory}/rules.json(单用户模式),或者随每个用户独立存储在数据库中(启用 用户管理 后)。Web 界面的 Rules 标签页和 TUI 是管理规则最直观的入口,改动会实时写回规则存储。

从源码看,规则的底层模型非常清晰(config/config.go):

type Rules struct {
	Skip       *Rule   `json:"skip"`
	Priority   *Rule   `json:"priority"`
	Versioning *Rule   `json:"versioning"`
	Aliases    Aliases `json:"aliases"`
}

服务启动时会调用 LoadRules():读取 rules.json,若文件不存在则自动创建一份空规则文件,随后把每一组正则编译成可执行的匹配器(Compile()),任何编译失败都会在启动阶段暴露出来,避免运行期才发现模式写错(config/config.go)。文件以 0600 权限写入(config/config.go),与 Hister 整体"隐私优先"的设计一致。

四类规则详解

Skip 规则:拦截不想进索引的页面

Skip 规则让匹配的 URL 被静默丢弃,不进入索引——无论文档是在浏览器扩展访问页面时自动提交,还是在 hister reindex 重索引阶段被重新处理。

典型用途:屏蔽广告网络、登录页、Cookie 同意墙,或任何你永远不希望出现在搜索结果里的站点:

^https://ads\.example\.com
^https?://(login|mail)\.example\.com/
.*\?utm_source=

注意最后一条:由于模式是匹配完整 URL 的,utm_source 这类营销参数会把同一页面复制出无数个"变体",用一条规则即可整体过滤。

单页强制保存:绕过 skip 规则

如果一个页面命中了 skip 规则,但你仍想保存它,有两个途径:

  • 浏览器扩展:点击 Index this page now 或使用其索引快捷键,该次提交显式覆盖 skip 规则;
  • API 客户端:在提交给 /api/add 或 /add 的 JSON 文档中设置 metadata.ignore_skip_rules: true;对 /api/add_pdf,该字段位于 document.metadata 内;对 /api/batch,每次 add 操作各自携带独立的 metadata。

这个覆盖选择会与文档一起持久化:文档因此在 hister reindex 时得以幸存,并保留在导出文件中。对应实现里,文档模型通过 SetIgnoreSkipRules() 把 ignore_skip_rules 写入 metadata(server/document/document.go),重索引循环中正是用 !d.IgnoreSkipRules() && rules.IsSkip(d.URL) 来判断是否丢弃,并记录日志 "Dropping URL that has since been added to skip rules"(server/indexer/indexer.go)。

需要强调几个边界(文档明确说明,且代码路径可印证):

  • 覆盖仅作用于 URL skip 规则;认证、所有权、敏感内容检查以及 Hister 自身 URL 的排除依然生效;
  • 对已有覆盖的文档执行"接受更新"(accepted update)时,除非显式提交 metadata.ignore_skip_rules: false,否则覆盖被保留;
  • 显式删除文档仍然有效。

API 端点文档中也有对应的说明与字段定义(server/api.go)。

Priority 规则:把信任源顶到最前

Priority 规则无视相关性得分,为匹配 URL 的文档施加一个大幅的分数加成,使它们稳定出现在搜索结果顶部。

典型用途:让个人 wiki、公司内部文档或可信来源永远排在其他结果之前:

^https://wiki\.example\.com/
^https://docs\.example\.com/

在代码里,搜索时通过 effectiveRules().IsPriority(url) 之类的匹配判断给文档加分(config/config.go),从而让"常看的、信任的"内容形成一条隐性的个性化置顶通道。

Versioning 规则:跟踪页面的每次改动

Versioning 规则让 Hister 在每次重索引时跟踪文档变更:当 URL 匹配规则,且新内容与上一次索引的版本不同时,Hister 会在数据库中为 HTML 与文本变化分别存储 diff match patch 记录。

典型用途:监控隐私政策、文档、新闻稿的编辑;为你关注的站点构建个人变更日志;审计某个可信资源最后一次变动的时间。

^https://example\.com/privacy-policy$
^https://docs\.example\.com/

查看已存储的版本

一旦某个文档记录了至少一条版本 diff,预览面板会显示先前版本计数。点击后打开变更日志,逐条展示记录的 diff 与时间戳;从这里你可以查看某个 diff 的细节,或重建并展示某个归档版本。

底层对应 model/version.go 中的版本记录模型(server/model/version.go),以及 "Return all stored version diffs for a document URL" 的 API(server/api.go)——版本记录的触发条件正是"URL 匹配 versioning 规则且文档被重索引"。

Aliases:查询期短关键词

Aliases 是查询时的快捷方式:在执行搜索前,Hister 会把别名关键词替换为其展开形式。它们以 JSON 键值对存储:

{
  "gh": "domain:github.com",
  "local": "type:file",
  "work": "domain:(internal.example.com|jira.example.com)"
}

有了上面的 work 别名,搜索 work deployment 就等价于 domain:(internal.example.com|jira.example.com) deployment。

从实现看,别名替换发生在查询管线的早期:服务端在处理查询文本时调用 rules.ResolveAliases(query.Text)(server/endpoints.go),随后才进入查询解析器;ResolveAliases 遍历 Aliases 映射逐一做字符串替换(config/config.go)。CLI 客户端也通过 POST /api/add_alias 与 POST /api/delete_alias 两个端点管理别名(client/rules.go)。

模式语法:匹配完整 URL 的细节与陷阱

Skip、Priority、Versioning 规则都基于完整 URL(包含 scheme、host、path 与 query string)进行匹配,有几个关键细节决定规则是否如你所愿:

  • 模式遵循 Go 正则表达式语法(regexp/syntax 包),不支持前瞻(look-ahead)与后顾(look-behind);
  • 锚定必须包含 scheme:^https://foo.com 或 ^https?://(login|mail)\. 是合法的;^foo.com 匹配不到任何东西;
  • URL 的 hash 片段在匹配前被剥离(https://foo.com/#section 变为 https://foo.com/);
  • query 参数不会被重排,仅 utm_* 参数会被去除;
  • 尾部 $ 锚定无法命中带查询串的 URL:/login$ 匹配不到 https://foo.com/login?auth=1。

这最后一条尤其容易踩坑——如果你需要匹配"带任意查询串的登录页",请写成 ^https?://foo\.com/login(不加 $),或显式包含 .*。

把规则应用到存量数据:删除已匹配文档

新增或编辑 skip 规则时,在 Rules 页面(或从某条结果的 action 菜单添加规则)勾选 Delete matching documents already in the index,即可让新规则立刻作用于索引中已有的文档。需要注意:

  • 该选项仅在规则类型为 skip 时可用,默认关闭(Web 前端在规则类型切换为非 skip 时自动复位该选项,见 BulkRulesDialog.svelte);
  • 当有文档匹配时,页面会显示匹配数量并要求确认后才执行删除;
  • 取消确认会保留已保存的规则,但不删除现有文档。

批量场景下,Web 界面的 "Bulk add rules" 对话框支持一次粘贴多行(每行一个 Go 正则,可横向滚动查看长规则),并实时统计新增/重复条数(BulkRulesDialog.svelte)。配套的 DeleteMatchingDocumentsDialog.svelte 负责展示命中数量与二次确认。

存储与作用域:单用户文件 vs 多用户数据库

规则的存储方式取决于用户处理模式:

  • 单用户模式(未启用用户处理):规则读写于数据目录下的 rules.json。通过 Web 界面或 API 的修改会直接更新该文件——SaveRules() 以 0600 权限原子覆写文件后再重新加载(config/config.go)。
  • 多用户模式(已启用用户处理):每个用户在数据库中拥有一份私有规则副本,存于用户的 rules_json 字段(server/model/user.go)。修改只影响当前认证用户,不会触碰 rules.json。细节参见 用户处理文档。

用 API 与 CLI 管理规则

HTTP API

服务端暴露两组端点(server/api.go):

  • GET /api/rules:返回当前的 skip、priority、versioning 规则与查询别名;
  • POST /api/rules:更新提交的规则组,省略的规则组保持不变,显式传空字符串则清空对应组;Content-Type 为 application/x-www-form-urlencoded。

这个"省略即保留、显式空串即清空"的语义由测试用例锁死:TestSaveRulesPreservesOmittedRuleGroups 验证只提交 skip 时 priority/versioning 原样保留,TestSaveRulesClearsExplicitEmptyRuleGroup 验证显式提交空 versioning 才清空该组(server/rules_test.go);多用户场景的等价行为由 TestSaveUserRulesPreservesOmittedRuleGroups 覆盖(server/rules_test.go)。

Go 客户端

如果你基于 Hister 写脚本或集成,client 包封装了完整操作:

  • FetchRules():GET /api/rules(client/rules.go);
  • SaveRules(skip, priority string, versioning ...string):POST /api/rules,同样遵循"未提供的组保持不变"的语义(client/rules.go);
  • AddAlias(keyword, value) / DeleteAlias(alias):分别对应 /api/add_alias 与 /api/delete_alias(client/rules.go)。

Web 前端对 /rules 的读写同样走这套表单语义:saveRuleLists 把三个列表以换行拼接后通过 URLSearchParams 提交(rules.ts),服务端按行解析回正则列表。

小结

规则系统把 Hister 从"记录一切"变成"按你的意图索引一切":

  • Skip 定义排除边界,ignore_skip_rules 提供单页豁免通道;
  • Priority 构建个人化的结果置顶,让信任源永远排前;
  • Versioning 把重索引变成内容变更审计,隐私政策、文档、新闻的每次编辑都有据可查;
  • Aliases 把常用过滤压缩成短词,让查询更顺手。

规则匹配基于完整 URL 与 Go 正则语法,记住锚定 scheme、剥离 hash、$ 不命中带查询串的 URL 这几条边界即可写出可靠的模式。无论是通过 Web 界面可视化编辑、TUI 快捷键、CLI 客户端,还是直接调用 /api/rules,规则都会立即生效并持久化——单用户模式落到 rules.json,多用户模式落到各自账号的数据库副本。

登录后查看全文
nogon