企业官网建设流程全解析

• 搜索引擎
• 全文检索
• 后端
• 前端
• CLI

Hister 自带搜索引擎的核心能力之一是本地文件索引：你可以在自己的配置文件中声明若干目录，让 Hister 启动后自动扫描、索引并持续监视它们，从而把 Markdown 笔记、Org 文件、源码、PDF、DOCX 等本地内容与浏览器历史放进同一个可检索的索引。读完本文你将掌握indexer.directories的完整配置语法、默认索引规则与智能过滤机制、file://结果的处理方式，以及将本地文件索引安全暴露在网络上时必须注意的防护要点。

本地文件索引是什么，为什么要用它

对于开发者和知识工作者，重要信息长期分散在两个世界里：浏览过的网页与磁盘上的本地文件。过去要搜索这两类信息，必须依赖两套完全不同的工具，体验割裂且低效。Hister 的本地文件索引把两者统一进同一个索引：搜索 "authentication implementation"，你可以同时命中访问过的 Stack Overflow 页面、自己项目里的认证相关源码、写过的 OAuth README、收藏过的博客文章，并且按相关度统一排序。

需要特别强调：本地文件索引是一个可选功能，默认关闭。你必须在 Hister 配置中显式声明indexer.directories才会启用，这一点在 config/config.go 中体现为Indexer.Directories []*Directory，默认值为空切片。

设置本地文件索引：indexer.directories 配置详解

在 Hister 的config.yml中加入indexer.directories段即可。参考仓库的配置结构（config/config.go），一个完整示例如下：

indexer: directories: - path: ~/Documents label: documents filetypes: ['md', 'txt'] - path: ~/code/projects filetypes: ['txt'] excludes: ['secret/*', '*key'] - path: ~/notes patterns: ['*.org', 'doc_*', 'README']

配置完成后，启动 Hister 服务端，它会自动开始索引。

每个目录条目可用的字段如下（对应源码中Directory结构体 config/config.go）：

filetypes与patterns的组合规则（config/config.go 的Directory.IsMatching）：

• 若设置了filetypes，文件扩展名必须命中列表才被纳入；
• 若设置了patterns，文件名必须匹配其中任一 glob 模式才被纳入；
• 若filetypes与patterns同时为空，则该目录下所有非隐藏、未被excludes排除的文件都会索引；
• excludes与隐藏文件规则始终优先于放行规则。

注意 glob 模式匹配的是文件名（filepath.Base(name)），因此像'secret/*'这样的斜杠模式实际作用于父目录名判断；要排除特定子目录，可以在excludes中列出目录名（如node_modules），因为遍历时会先对每个目录名做排除检查（files/files.go）。

除了目录列表本身，indexer段还提供全局参数：

indexer: max_file_size_mb: 1 # 单个文件索引上限（MB），默认 1 detect_languages: true # 语言检测（会生成按语言划分的子索引） keep_stopwords: false # 是否保留停用词

max_file_size_mb对应 config/config.go 中的Indexer.MaxFileSize，其值会被乘以1024*1024换算成字节（server/indexer/indexer.go）。

什么文件会被索引：默认规则与容量上限

Hister 索引本地文件的默认策略（定义于 server/indexer/files.go）：

• 小于 1MB：defaultMaxFileSize = 1024*1024（1MB），可通过indexer.max_file_size_mb调整；超过上限返回ErrFileTooLarge；
• 有效的 UTF-8 文本：纯文本处理器会调用utf8.Valid(content)校验，非法 UTF-8 内容返回ErrBinaryFile并被跳过（server/indexer/filetypes.go）；
• 非隐藏文件：以.开头的文件与目录默认跳过；
• 空文件：大小为 0 的文件返回ErrEmptyFile，不进入索引。

值得指出的是，原文档在撰写时提到"以后希望支持 PDF、DOCX"，而从当前仓库源码看，这一规划已经落地：文件类型处理器注册表（server/indexer/filetypes.go）包含pdfFileType、docxFileType、markdownFileType、orgFileType和兜底的plainTextFileType，各处理器依次按扩展名匹配、未命中则回落为纯文本。这意味着开箱即用的格式包括：

文档在What Gets Indexed中提到的.py、.js、.go、.rs等代码文件，正是通过最后的纯文本处理器被索引的。

智能过滤：内置跳过列表

除隐藏文件外，Hister 内置了一组"著名依赖/缓存目录"跳过列表（files/files.go）：

node_modules, bower_components, jspm_packages, __pycache__, __pypackages__

这些目录名无歧义且可能包含数以万计的文件，极易耗尽操作系统 watch 上限，因此默认不监视、不索引。用户仍可通过excludes排除其他目录，或通过include_hidden: true选择性地纳入隐藏内容。

工作原理：首次扫描、增量监视与索引队列

Hister 的文件索引链路设计为"简单且自动化"（整体实现见 server/indexer/files.go 与 files/watcher.go）：

1. 目录展开与校验：对每个配置的path先做ExpandHome展开，再os.Stat确认其为目录（server/indexer/files.go）；
2. 递归遍历：filepath.WalkDir逐层深入，目录级排除（隐藏目录、excludes命中的目录、内置 skipDirs）直接filepath.SkipDir剪枝；文件级则经Directory.IsMatching过滤后调用回调（server/indexer/files.go）；
3. 去重更新：IndexFile会先按file://URL 与用户 ID 查询已有文档，若已存在且modTime未变化、类型为本地文件则跳过，避免重复索引；仅当 label 变化时才做轻量更新（server/indexer/files.go）；
4. 增量监视：服务端通过 fsnotify 监视被索引的目录树，新建/写入事件经过200ms 去抖窗口（files/watcher.go）合并后进入FileIndexQueue；删除/重命名事件在delete_on_remove开启时同步从索引移除。文件被替换（编辑器 rename-over 保存）时，监视器会观察父目录来保证不丢事件（files/watcher.go）；
5. 队列消费：FileIndexQueue以pendingmap 去重、notify通道唤醒后台循环，串行处理 add/delete 操作，索引失败仅记 Debug 日志不影响服务运行（server/indexer/files.go）。

因此：新增或修改的文件会被自动重新索引，无需重启服务端。

对于超大目录，Hister 还提供了索引对账机制：CleanupLocalDocuments会扫描所有file://类型的本地文档，将其与当前indexer.directories过滤条件、目录归属用户逐一比对，移除不再匹配的陈旧条目（server/indexer/files.go）；执行hister reindex时同样会跳过已不匹配目录配置的文件并保留归属变更校验（server/indexer/indexer.go）。

搜索本地文件：file:// 结果与 Web 预览

本地文件与网页在搜索结果中完全对等：本地文件以文件路径代替 URL 展示，与网页结果混合按相关度排序。索引时绝对路径会被转换为file://URL 存储（files/files.go 的PathToFileURL），这与staleLocalDocument按file:scheme 识别本地文档的逻辑一致（server/indexer/files.go）。

当你打开一个本地文件结果（以file://scheme 标识）时，Hister 通过自身 Web 界面提供内容渲染与预览，既保留可检索历史，又能快速查看真实文件内容。Markdown 与 Org 文件在索引时会同时保存渲染后的 HTML，因此预览体验与网页一致。

典型使用场景

• 跨项目代码搜索：索引源码目录，在一个查询中找出散落在各项目里的函数定义、API 示例与实现模式；
• 个人知识库：索引 Markdown 笔记、Org 文件或纯文本日记，构建可全文检索的"第二大脑"；
• 文档中心：让项目 README、技术规格、设计文档与引用过的网页资源一起可检索；
• 配置速查：在大量 dotfiles 与配置目录中，几分钟前写过的某个配置项一次搜出。

隐私与安全：索引本地文件的必读清单

Hister 自托管，本地文件索引完全在本机完成，不会向任何外部服务器发送数据。但本地文件可能包含敏感信息——带 API key 的代码、私人笔记、含凭据的配置文件、专有文档——一旦被索引，就都会通过 Hister 的 Web 界面可检索。因此，若要让 Hister 通过局域网或公网访问，必须妥善加固：

1. 使用访问令牌：在配置中设置app.access_token（见 config/config.go 的App.AccessToken），所有 API 请求都要求认证；浏览器扩展原生支持该令牌；
2. 部署在反向代理之后：用 nginx、Caddy 或 Apache 提供 HTTPS 与额外认证（HTTP Basic Auth、OAuth 等）；
3. 保持本地：仅将 Hister 暴露在 localhost（127.0.0.1，这也是默认监听地址），远程访问时通过 SSH 隧道或 VPN；
4. 审查防火墙：确认服务器防火墙规则没有意外把 Hister 暴露到公网。

多用户部署时可额外利用indexer.directories[].user字段，将不同目录的索引归属到不同用户，使搜索结果按用户隔离。

当前能力边界与演进方向

从源码现状看，文件索引在文档之外已实现的能力包括：PDF/DOCX 文本提取、内置依赖目录跳过、delete_on_remove删除同步、目录归属用户、以及与 reindex/cleanup 流程的对账。文档中提到的后续方向——如支持更多文件类型、CLI 列出已索引/已排除文件、结构化格式（JSON/YAML/TOML）的更好处理、超大目录增量索引的进一步优化——仍值得持续关注（例如walkDirectoryFiles目前对每个文件都会重新解析目录配置，超大目录下存在优化空间，这是从代码结构可以推断的）。

快速开始

1. 编辑 Hister 配置（config.yml），按上文语法添加indexer.directories；
2. 重启 Hister 服务端，观察日志中 "Indexing directory" 与 "Directory indexing complete" 输出确认扫描结果；
3. 在搜索框输入关键词，本地文件与网页结果一同按相关度返回；
4. 修改或新增目录内文件，等待去抖窗口（200ms）后自动增量索引。

完整的配置说明可参考仓库中的 configuration.md，索引目录解析与过滤逻辑的单元测试见 server/indexer/files_test.go 与 files/files_test.go。

• 搜索引擎
• 全文检索
• 后端
• 前端
• CLI