Hister 入门指南:构建完全属于你自己的私有搜索引擎
Hister 入门指南:构建完全属于你自己的私有搜索引擎
Hister 是一款私有的、自托管的搜索引擎,专门索引你访问过的网页和你保存的文件,并对它们的完整内容建立全文索引,让你可以随时通过 Web 界面、终端、API 或通过 MCP 接入的 AI 助手找回信息。本文基于官方入门文档,系统讲解 Hister 的定位、目标用户、客户端/服务器架构、数据存储与隐私边界,以及从零开始的本地部署路径,帮助你判断它是否适合你的个人知识库场景,并快速跑通第一个搜索。
什么是 Hister:搜索你自己的内容集合
Hister 的核心定位可以概括为:它不是通用互联网搜索引擎,也不是托管的云服务,而是索引你个人内容集合的私有搜索工具。
它的数据来源完全由你掌控,主要包括:
- 你通过浏览器扩展访问过的网页;
- 导入的浏览器历史;
- 本地目录中的文件(被监听的目录);
- 通过爬虫抓取的站点;
- 以及通过 API 客户端提交的任意文档。
项目根目录的 README.md 用一句话定义了它的使命——"Your own search engine"。与主流搜索引擎不同,Hister 不会去爬取整个互联网,而是从你选择保留的网页和文件中构建一个个人搜索索引;你的内容始终停留在你自己的 Hister 服务器上,不依赖任何第三方搜索服务商。
从源码结构看,Hister 由 hister.go 作为程序入口,通过 cmd/root.go 注册了一整套命令体系,包括 listen(启动服务器)、search(搜索)、import(导入浏览器历史与各类书签服务)、crawl(爬虫任务管理)、delete(删除文档)、cleanup(清理)等。这印证了它作为一个完整自托管搜索引擎的产品形态。
谁适合使用 Hister
Hister 面向任何希望从自己认为重要或相关的信息中构建可搜索知识库的人。它把来自不同来源的内容汇聚到一个由你控制的集合中,包括网页、浏览器历史、本地文件和爬取的站点。
同时,文档也明确划定了它的边界:
- 它不是托管服务;
- 不是自动云同步系统;
- 不是记录管理系统(records management system)。
你需要自己运行服务器,并自行决定数据如何被安全保护和保留。这意味着运维责任(存储监控、备份、删除策略)都由你承担,这也是它"私有"的本质体现。
Hister 的工作原理:客户端与服务器架构
Hister 采用客户端与服务器(client-server)架构:
- 服务器负责存储文档并提供搜索能力;
- 客户端负责收集内容或发起搜索。
关键的架构事实是:hister 这一个程序既可以扮演服务器,也可以扮演客户端,而浏览器扩展则是纯粹的客户端。整个系统可以运行在一台电脑上,也可以让多个客户端连接同一个服务器——这正是它能够支撑"团队和组织私有搜索"的基础形态。
在 server/server.go 的 Listen 函数中可以看到,服务器最终通过 http.ListenAndServe 监听配置的地址(默认 127.0.0.1:4433)来提供服务。
内容从哪里来
Hister 的内容采集有五种主要途径,官方文档将其归纳为:
| 途径 | 说明 |
|---|---|
| 浏览器扩展 | 在你访问页面时捕获渲染后的页面内容 |
| 浏览器历史导入 | 读取旧 URL 并抓取其当前内容 |
| 被监听的目录 | 自动索引本地目录中的文件 |
| 爬虫 | 按 robots 规则抓取整个公开站点 |
| API 客户端 | 通过 API 提交文档 |
其中"浏览器扩展捕获"与"浏览器历史导入"是两种容易被混淆的路径,二者的核心区别见 浏览器摄入文档:
- 扩展捕获:只处理扩展安装并启用之后你新访问的页面,读取的是浏览器已经渲染好的页面(含 JavaScript 渲染结果和登录态可见内容);
- 历史导入:从浏览器数据库中读取历史 URL,然后让爬虫去抓取这些页面当前存在的内容——页面可能已变更、消失、迁移或开始要求登录,因此索引到的内容可能与你当初看到的不同。
浏览器摄入是单向的,不是双向同步:清除浏览器历史不会删除 Hister 中的文档;删除 Hister 文档也不会改动浏览器历史、书签或源网站。Hister 对每个规范化后的 URL 与所有者只保留一份当前文档,重复提交同一 URL 会更新当前文档并增加提交次数,而不是为每次访问保留完整快照。
隐私与存储:数据到底存在哪里
隐私是 Hister 最核心的卖点之一,官方文档给出了两个明确承诺:
- 无遥测(no telemetry):Hister 不收集任何使用统计数据;
- 无强制云服务:不要求连接 Hister 官方的任何云端。
索引数据存储在你选择的服务器上,Hister 本身不对数据加密。官方建议:需要时使用磁盘加密,客户端跨不可信网络连接时使用 HTTPS。
数据存储位置
根据 数据存储与生命周期文档,默认 SQLite 部署下,app.directory 配置项是 Hister 的主数据目录,其中各文件/目录的职责如下:
| 位置 | 内容 |
|---|---|
index.db 与 index_LANG.db |
可搜索文档字段与全文索引 |
data/html/ |
按内容哈希寻址的压缩 HTML 预览 |
data/favicon/ |
按内容哈希寻址的压缩图标 |
db.sqlite3 |
用户、浏览器会话、搜索历史、爬虫任务、版本差异与内部任务状态 |
vectors.sqlite3 |
语义搜索的分块与向量(当语义搜索使用 SQLite 时) |
rules.json |
单用户模式下的规则与别名 |
.secret_key |
用于派生全局令牌会话认证证明的密钥 |
值得注意的设计细节:相同的 HTML 或图标会共享同一个按内容哈希寻址的文件,从而减少重复存储;当 server.database 配置为 PostgreSQL 连接串时,SQL 数据与语义向量转入 PostgreSQL,而 Bleve 搜索索引与 HTML/图标数据仍保留在 app.directory 下。文档在 server/server.go 中的数据库会话逻辑(sessionStore 与 sessionMaxAge = 30 天过期策略)也能印证这一存储设计。
保留策略:没有自动过期,也没有配额
Hister 对文档不施加自动过期时间、不设最大文档数、也没有总磁盘配额。平均存储一个页面大约需要 100 KB 磁盘空间(数据生命周期文档给出的参考值)。服务器运维者需要自己负责:
- 监控存储占用;
- 创建备份;
- 按需制定删除计划。
若要控制存储增长,官方建议的手段包括:设置 app.disable_previews: true 关闭 HTML 预览存储、用跳过规则过滤低价值页面、只对需要追溯历史内容的页面启用版本记录、用日期查询删除陈旧文档、清理已完成但无用的持久化爬虫任务等。
生命周期关键行为
数据生命周期文档用一张表概括了各种事件的结果,其中几个关键行为值得强调:
| 事件 | 结果 |
|---|---|
| 提交新 URL | 为该 URL 与所有者创建可搜索文档 |
| 再次提交同一规范化 URL | 替换当前文档内容并增加提交次数 |
| 被监听的本地文件被删除 | 除非配置了 delete_on_remove: true,否则保留文档 |
| 在 Hister 中删除文档 | 移除当前索引记录与相关当前资产 |
运行 hister cleanup |
移除不再匹配配置目录的本地文档与未被引用的 HTML/图标文件 |
另外要注意:删除文档不会删除源浏览器历史、书签、本地文件或远程页面,也不会删除 SQL 数据库中的版本差异记录、持久化爬虫任务、导出文件或备份。官方明确说明:Hister 目前没有一条命令能抹除所有相关副本,若需要彻底清除,运维者必须另行处理版本记录、任务元数据、日志、导出与备份。
快速上手:五分钟跑通本地搜索
官方快速上手的核心结论是:最简单的用法完全不需要配置。安装好二进制后(Windows 下为 hister.exe),只需以下几步:
1. 启动服务器
在终端中运行:
./hister listen
Windows 用户在 PowerShell 中运行 .\hister.exe listen。服务器会在 http://127.0.0.1:4433 启动,由于监听地址默认绑定回环地址,因此只能从本机访问——这非常适合单机个人使用。
需要注意:不要关闭运行该命令的终端,否则服务器会随之关闭(也可以按 Ctrl+C 正常关闭)。服务器可以随时关闭和重新打开,但客户端索引页面时服务器必须处于运行状态,否则会报错。更多高级部署方式(存储、日志、监听接口、数据库、认证等)见 服务器配置 中的 app 与 server 配置段,以及 服务器部署文档。
2. 安装浏览器扩展
安装 Firefox 或 Chrome 的 Hister 扩展后,你新访问的页面就会被索引。扩展设置中的服务器地址默认即为 http://127.0.0.1:4433,无需修改。
官方对扩展的隐私行为有明确说明:扩展不访问网络,唯一的例外是收集页面数据时下载页面图标(favicon)。它永远不会向你正在访问的站点发起请求(只查看浏览器自身已加载的内容),因此对被索引的网站完全透明。
如果想从浏览器地址栏直接搜索 Hister,可以在浏览器设置中把 Hister 实例添加为自定义搜索引擎(甚至可以设为默认)。Hister 的搜索界面还提供了把当前查询转发到 DuckDuckGo、Google 等外部搜索引擎的按钮。
3. 访问 Web 界面并验证索引
在浏览器中打开 http://127.0.0.1:4433(等价于 http://localhost:4433)即可访问 Hister 的 Web 界面,在其中可以执行搜索、添加索引规则等操作。随着你在浏览器中不断访问新页面(保持扩展启用),索引的页面数量会持续增长——刷新页面即可看到数字更新。如果数字不增长,请检查扩展是否安装、启用并指向正确的服务器地址;如果 Web 界面完全无法访问,先确认服务器是否在运行。
下一步:把 Hister 变成你的知识基础设施
跑通首个搜索之后,官方推荐的进阶路径包括:
- 导入文件、浏览器历史或 Linkwarden 书签,把存量内容纳入索引;
- 配置本地目录索引,让 Hister 自动索引并监听本地目录中的文档(支持按
filetypes、patterns、excludes过滤,配合delete_on_remove实现删除同步); - 启用语义搜索,通过你配置的 OpenAI 兼容 Embedding 端点实现"按语义找文档"(默认关闭,需显式开启);
- 在 Web 界面配置忽略规则、优先级规则和关键词别名,让搜索结果更精准;
- 学习完整的 Hister 查询语言,掌握
title:、domain:、text:、language:、visits:、updated:等字段过滤、短语、通配符、否定与 OR 交替组合; - 配置 Web 快捷键 与敏感内容模式(
sensitive_content_patterns默认覆盖 AWS 密钥、GitHub Token、SSH/PGP 私钥等常见敏感信息)。
无论你最终把它部署成单机个人搜索工具,还是通过多用户模式(user_handling)支撑一个团队的共享知识库,Hister 的基本原则始终如一:内容由你采集,索引由你托管,检索能力完全属于你自己。
