Hister 规则系统实战:用 Skip、Priority、Versioning 与 Alias 掌控个人搜索引擎的索引与排序
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,多用户模式落到各自账号的数据库副本。