Hister 团队私有搜索实战:多用户账户、共享文档库与浏览器扩展接入指南
Hister 团队私有搜索实战:多用户账户、共享文档库与浏览器扩展接入指南
每个团队、合作社、研究组或黑客空间,几乎都有一批"人人必读"的页面:成员手册、设备说明书、项目 Wiki,还有那份总会被反复发给新人的指南。与此同时,每个成员在工作中各自发现的内容又各不相同——一个数据库问题的解答、一场有价值的讨论、一篇值得反复回味的文章。Hister 允许你在一台服务器上同时承载这两种形态:每个成员拥有独立账户和私有可搜索收藏,共享文档则出现在每个人的搜索结果中。
本文将以 Hister 官方博客文章 Hister: A Private Search Engine for Teams and Organizations 为主体,结合仓库中的 CLI 源码与配置文档,完整讲解多用户实例的搭建步骤、共享文档库的建立方法、浏览器扩展的接入方式,以及用户管理命令与索引命令的底层实现细节。读完本文,你将掌握在一台服务器上为团队搭建带账户隔离的私有搜索服务的完整方案。
多用户模型:个人收藏与共享文档如何共存
先看一个典型场景。假设 Alice 和 Bob 在同一个项目组工作,两人都需要团队手册和参考文档;Alice 正在研究数据库问题,Bob 则在阅读部署工具链的资料。
管理员把手册作为共享材料索引进来,Alice 和 Bob 各自用自己的账户连接浏览器扩展。在扩展默认的"个人提交"设置下,两人浏览的页面会分别进入各自的收藏。此时两人的搜索覆盖范围如下:
| 被索引的材料 | Alice 能找到 | Bob 能找到 |
|---|---|---|
| 共享团队手册 | 是 | 是 |
| 归在 Alice 名下的文章 | 是 | 否 |
| 归在 Bob 名下的讨论 | 否 | 是 |
当 Alice 搜索 database backup 时,她能同时找到团队备份指南和她自己读过的关于 PostgreSQL 恢复的文章;Bob 同样能找到共享指南,以及他个人账户下索引的一切内容。这个作用域由服务器自动应用——两人都无需在日常查询中手动添加所有权过滤条件。
这套模型的核心机制是文档归属(ownership):启用用户处理(user handling)后,每个文档都带有一个用户 ID;搜索时自动限定为"自己索引的文档 + 归属于用户 ID 0 的全局文档"。用户彼此之间看不到对方的私有文档,这是通过搜索层强制实施的访问控制,而不是靠约定。
搭建团队的 Hister 实例
先按安装指南和服务器部署指南完成一次全新安装。下面的例子使用 https://hister.example.com 作为站点地址,Hister 与 HTTPS 反向代理部署在同一台机器上。
在团队的 config.yml 中添加以下配置:
app:
user_handling: true
public: false
server:
address: 127.0.0.1:4433
base_url: https://hister.example.com
各参数作用如下:
app.user_handling: true:启用多用户模式,为每个成员创建独立账户。该模式默认关闭,单用户部署完全兼容、无需改动(见 config/config.go 中对应的配置结构体字段)。app.public: false:关闭匿名公开搜索。此时对实例的一切搜索(包括共享文档的搜索)都要求登录。从源码校验看,app.public启用时要求配置access_token或user_handling至少其一,否则 Hister 拒绝启动(见 config/config.go)。server.address: 127.0.0.1:4433:Hister 监听本机回环地址,反向代理负责对外暴露。请务必把示例主机名替换为你自己的域名。server.base_url: https://hister.example.com:对外的基础 URL。注意:只设置base_url并不会配置 HTTPS,反向代理仍需自行处理 TLS 终结并把请求转发到127.0.0.1:4433。
接下来在服务器主机上创建一个管理员和两个普通成员账户:
hister --config config.yml create-user admin --admin
hister --config config.yml create-user alice
hister --config config.yml create-user bob
每个命令都会交互式提示输入密码(至少 8 个字符,且需二次确认,见 cmd/users.go)。这些命令必须与运行服务器时使用相同的配置文件和操作系统账户执行,这样它们才会访问同一个数据库和数据目录。从源码看,create-user 与其它用户管理命令一样,通过 requireUserHandlingAndInitDB 前置检查强制要求 user_handling: true(见 cmd/users.go)。
然后启动服务器:
hister --config config.yml listen
Alice 和 Bob 现在就可以打开团队地址并登录了。
如果你是在已有个人安装实例上改造,请先检查现有文档的归属:在未启用用户处理时索引的文档归属于用户 ID 0,开启多用户后会对所有已登录成员可见。如何把这些文档迁移到某个个人账户下,详见用户处理指南中的单用户兼容性一节。
给每个人一份有用的起点收藏
Hister 把归属于用户 ID 0 的文档称为全局文档(global documents)。在本方案中,它们就是全体成员共享的收藏集合。
管理员可以用 --global 索引标志向其中添加内容。首先在服务器主机上取回管理员个人访问令牌:
hister --config config.yml show-user admin --token
将上面输出的令牌替换到下面的 ADMIN_TOKEN 位置。同样使用服务器配置执行抓取,并把手册 URL 与允许域名替换为你自己的:
hister --config config.yml --token 'ADMIN_TOKEN' index \
--recursive \
--global \
--label=team-handbook \
--allowed-domain=handbook.example.com \
--max-depth=4 \
--max-links=200 \
https://handbook.example.com/
各参数的含义与实现(全部来自 cmd/index.go 的 flag 定义):
| 参数 | 说明 | 默认值 |
|---|---|---|
--global |
让被索引文档对所有用户可用;多用户模式下仅管理员可用 | false |
--label |
给所有被索引文档附加一个标签,成员可据此检索 | 空 |
--recursive(-r) |
递归抓取链接页面,进入持久化抓取任务模式 | false |
--allowed-domain |
抓取时允许的域名,可重复指定多个;为空则不限 | 空(全部允许) |
--max-depth |
最大抓取深度,0 表示不限制 |
0 |
--max-links |
最多访问的页面数,0 表示不限制 |
0 |
--global 使页面进入共享集合,此命令中它要求使用管理员的令牌认证。--label 给集合命名,成员搜索时可以直接引用。其余选项把抓取限制在选定站点内并控制规模。
如果手册站点本身需要登录,则需要通过爬虫的认证选项单独配置对该数据源的访问,与 Hister 自身的令牌认证互不影响。
之后 Alice 和 Bob 都可以这样搜索:
label:team-handbook database backup
如果要跨整个共享集合搜索:
user_id:0 database backup
user_id: 是查询构建器原生支持的字段查询——源码测试 Test_build_user_id 验证了 user_id:42 会被解析为数值范围查询子句(见 builder_test.go),因此 user_id:0 可以直接命中全部全局文档。标签用于组织结果,但每个成员依然能搜到所有全局文档,无论其携带什么标签,所以在选择共享来源时要想清楚受众。
起步阶段不需要大而全:手册、项目 Wiki、成员经常问起的参考页就足够了。更多抓取示例可参考为整个文档栈建立索引一文。
接入每个成员的浏览器
Alice 安装浏览器扩展,把服务器地址设为团队的 Hister 地址,并用自己的账户完成认证。认证有两种方式:
- 在她的 Hister 个人资料页生成一个个人访问令牌,填入扩展;
- 在同一浏览器中登录 Web 界面后,点击扩展里的 Authenticate with Browser Session,让扩展直接复制当前登录会话的 Cookie。
Bob 用自己的账户执行同样的步骤。每个成员都使用各自的凭据,命令行客户端也不例外。
对于个人浏览场景,请保持扩展的 "Submit as public documents" 开关处于关闭状态(这是默认值)。从扩展源码看,该选项的界面文案是"Store newly indexed documents as public results with user id 0",即"把新索引的文档作为用户 ID 0 的公共结果存储"(见 Options.svelte)。关闭状态下,Alice 浏览时捕获的页面归在 Alice 名下,Bob 捕获的归在 Bob 名下。扩展还会在未认证时自动重置该开关(见 Options.svelte)。
此外,每个账户还拥有独立的跳过规则、优先级规则和搜索别名。Alice 可以围绕数据库工作调优她的搜索,Bob 可以为部署文档创建快捷方式,这些规则只影响各自账户的搜索与索引行为。个人收藏的隔离由 Hister 的访问控制保证;同时也要清楚,服务器运维方掌握着全部存储数据,所以请把实例托付给团队信任的人。
刻意地分享有价值的内容
假如 Alice 发现了一篇整个团队都能用上的指南,最简单的工作流是把 URL 发给管理员,管理员审核后用它执行带 --global 的索引命令,把页面加入共享集合。
成员也可以直接贡献:在扩展里开启 Submit as public documents 后,新提交的页面会进入全局集合。配合上面的服务器配置(app.public: false),这些页面仅对已登录成员可搜索;如果在服务器上启用 app.public: true,匿名访客也能看到全局文档(详见用户处理指南的 Public Mode 一节)。
注意扩展的这个开关作用于其后的所有提交,直到被再次关闭。一次刻意的分享会话建议这样做:
- 关闭自动索引;
- 开启公共提交;
- 手动索引打算分享的页面;
- 回到个人浏览前,关闭公共提交。
团队可以自行选择贡献习惯:管理员维护核心参考资料,成员在工作中把精选发现补充进来。
让收藏对下一位成员保持有用
共享材料需要有人照看。给每个数据源指定一名负责成员:手册变更时重新跑抓取、检查有价值的页面是否被捕获、移除团队已不再使用的材料。
新成员加入时,为他创建账户并接入扩展。他的个人收藏从空开始,但共享手册和参考资料立即可搜索;随着他自己的浏览,个人上下文逐渐积累,搜索对他才真正变得有用。对一个黑客空间,最初的成果可能是设备说明书和工坊笔记;对一个研究组,可能是背景阅读和项目文档;对一个合作社,则可能是操作规程和新成员经常需要的答案。
源码视角:用户管理命令与权限模型
完整的用户管理命令集(全部要求 user_handling: true 且需要服务器主机直连访问)如下,实现见 cmd/users.go:
| 命令 | 功能 | 关键标志 |
|---|---|---|
create-user USERNAME |
创建账户,交互式设置密码 | --admin:授予管理员权限 |
delete-user USERNAME |
软删除账户;若该用户名下存在索引文档,需加 --purge 才会删除 |
--purge:先删除该用户文档再删账户 |
show-user USERNAME |
显示账户信息 | --token:同时显示个人访问令牌 |
update-user USERNAME |
修改账户 | --username NEW / --password / --regen-token / --toggle-admin |
密码以 bcrypt 哈希存储且永不通过 API 返回;会话 Cookie 只包含随机不透明标识符,会话数据与标识符哈希存储在 SQL 数据库中,登出会立即撤销数据库记录。个人访问令牌用于 API 与 CLI 认证(X-Access-Token 请求头或 hister -t <token>),一旦重新生成,旧令牌立即失效,需要同步更新扩展和脚本。OAuth 登录默认使用 S256 PKCE 防止授权流程中的 CSRF。这些安全细节的完整说明见用户处理指南。
delete-user 的实现值得一提:它会先通过 API 以 user_id:<ID> 查询该用户的文档数,若存在文档且未指定 --purge 则拒绝继续,只有显式 --purge 才会先清理文档再软删除账户(见 cmd/users.go)。这与数据生命周期文档中"多用户所有权"一节描述的语义一致。
部署建议:用户处理模式面向一个可信群体(家庭、团队)的共享实例。如果是对公网开放,请务必在 Hister 前放置带 HTTPS 的反向代理,并且只索引可以公开展示的内容。另外,多用户模式下管理员还可执行
POST /api/reindex(重建全文索引)与POST /api/cleanup(清理失效文档)等特权操作,非管理员调用会收到403 Forbidden。
小结
一套面向团队与组织的 Hister 部署,本质上只有三个步骤:用 user_handling: true 开启账户体系、用 --global 索引建立用户 ID 0 的共享集合、让每个成员用自己的账户接入浏览器扩展。作用域由服务器自动施加,个人收藏彼此隔离,共享文档人人可搜。从你反复发给彼此的页面开始,给它们在 Hister 里安一个共享的家,然后让每个成员围绕它构建属于自己的收藏。