为 Gitea 建立有范围的仓库代码索引

Gitea 文档贡献者；中文编译、结构整理与静态审核：未完纪。

来源：Repository indexer。核对日期：2026-10-08。

小仓库里，代码搜索不一定需要额外索引服务。Gitea 已经能通过 git grep 在单个仓库内搜索；当搜索需求超出这种方式，再考虑启用仓库索引。先分清两条路径，能避免把“还没开全站代码索引”误判成“仓库完全不能搜索”。

先决定索引哪些文件

索引复制了源代码中的可搜索信息，也增加了磁盘、CPU和内存成本。首次建立索引或升级后的全量更新尤其需要资源。原文没有给出每个仓库统一适用的容量系数，因此应以自己的仓库数量、文件分布和更新频率规划，而不是用一个示例阈值推断容量足够。

建议先列出真正需要搜索的语言文件、文档及构建脚本，再确认生成文件、二进制产物和供应商代码是否应纳入。这个清单解决的是检索质量和容量问题，不会更改仓库本身的权限。

在 app.ini 中启用索引

以下为官方页面的最小配置。修改的是 Gitea 实例配置，不是某个仓库的普通源文件。

[indexer]
REPO_INDEXER_ENABLED = true
REPO_INDEXER_PATH = indexers/repos.bleve
MAX_FILE_SIZE = 1048576
REPO_INDEXER_INCLUDE =
REPO_INDEXER_EXCLUDE = resources/bin/**

REPO_INDEXER_ENABLED 开启仓库索引；REPO_INDEXER_PATH 指定索引位置。示例大小阈值为 1,048,576 字节，即 1 MiB：大于此值的文件会被跳过。它既不是仓库总大小上限，也不是索引总大小上限。文档说的是“大于”阈值，不应自行改写为“大于或等于”。

REPO_INDEXER_INCLUDE 留空代表包含所有候选文件；示例再排除 resources/bin 下的整个文件树。上线前检查索引目录所在卷的容量和写权限，并为首次扫描安排可观察、可回退的变更窗口；本文没有启动 Gitea，也没有测量建立索引的时间。

大小之外，路径模式决定真正的范围

包含和排除参数都是以逗号分隔的 glob 模式。一个文件即使匹配包含模式，只要同时匹配排除模式，也不会进入索引：排除规则优先。此外，REPO_INDEXER_EXCLUDE_VENDORED 默认是 true，会排除被识别为供应商代码的文件。需要研究 vendored 实现时，应明确评估这一默认行为。

两处细节特别容易出错。第一，写成 resources/bin 只是匹配目录名，不会自动包含或排除里面的文件；应明确写出 /** 或 /*。第二，Gitea 会把路径和模式归一化为小写，因此 **Makefile、**makefile 和 **MAKEFILE 等价。这里使用的是文档指定的 gobwas/glob 语义，不应直接套用 shell、gitignore 或另一种 glob 库的直觉。

搜索不到时，沿过滤链排查

先检查是否只使用仓库内搜索，还是已经启用了完整索引；再检查索引是否已完成。随后确认文件大小、包含模式、排除模式和 vendor 分类。只改包含规则却忽略优先级更高的排除规则，是常见的误判来源。

选几份已知内容的文件，分别覆盖根目录、子目录、被排除目录、大小阈值两侧以及 vendor 目录，再由管理员在自己的测试实例中核对结果。这里列的是建议验证样本，并非本文已经跑过的测试。文件未被索引只意味着搜索覆盖不完整，不能证明仓库里没有这段内容。

索引不是备份，也不是秘密隔离层

索引可以重建，不能代替仓库备份。将秘密文件排除在索引之外也不能使已入库的秘密安全：有仓库读取权的人仍可能直接访问原文件。若凭证已经提交，应按泄露事件处理，不能仅通过调整搜索规则收尾。

示例没有硬编码秘密，也没有发现可直接归因于这段配置的注入问题。实际部署仍需要保护索引目录、维持仓库权限检查，并观察重建期间的磁盘和内存压力。静态核查只能说明这些参数在文档中的含义，无法证明某个实例已经正确实施。

来源、版本与检查说明

基于2026-10-08读取的当前官方 Repository indexer 文档。规范URL未固定版本；部署时应切换到实际安装版本的配置文档。本文不承诺任意旧版本具有相同匹配行为。

原文署名归 Gitea 文档贡献者（原页未列个人作者）。原页面未显示适用于文档内容的公开许可证；本文为经授权的中文翻译整理，不将 Gitea 软件许可套用于文档。保留来源与原作者归属；本原创示意图署名未完纪。授权说明单独留存；本文不把 Gitea 软件许可套用于未单独标注开放许可的文档。

本文仅对源代码和配置做静态检查，未进行安装、运行或性能测试。文中的期望结果属于原文说明或逻辑推导，不能当作本次实测结果。

• https://docs.gitea.com/administration/repo-indexer/