src/search/       最终运行的采集存储搜索和接口应用
src/crawler/      可独立复用的 DHT 协议与 Metadata 获取基础库
src/web/          基于 Vue 和 shadcn-vue 的搜索界面
opencodes/        不参与构建且不得修改的参考项目

RocksDB 是唯一权威数据源 Tantivy 索引可以从 RocksDB 完整重建

Tantivy 使用代际影子索引处理 Schema 文档格式损坏和缺失等全量重建用户过滤规则通过可恢复扫描只增量更新真正变化的搜索文档两类进度都可以在搜索提示与系统诊断页查看

重复发现只会精确更新 RocksDB 同一个内容组每六小时最多触发一次 Tantivy 动态状态刷新新内容过滤变化和可用性验证仍会立即更新索引搜索结果返回前会从 RocksDB 补全当前精确状态因此界面数字保持最新但最近发现次数和热度的全局排序允许最多六小时的索引快照延迟

应用全部配置和内容隐藏规则统一位于 config.toml

诊断页默认聚合全部采集器的 DHT 下载和失败原因指标也可以切换到单个采集器查看其历史吞吐和进程资源独立的采集器页面负责节点状态启停与每节点 DHT 配置关闭采集器不会影响已有 RocksDB 数据补建索引和本地搜索

分布式运行

同一个程序通过 [service].role 支持三种运行角色

角色	行为
`standalone`	默认单机模式同时运行存储搜索和本机采集器
`coordinator`	唯一存储搜索协调器不启动 DHT
`collector`	只运行 DHT 采集有效性验证和持久待发送箱

协调器和采集器必须使用相同的 DHT_SEARCH_CLUSTER_TOKEN 环境变量值至少三十二个字符内部接口使用独立端口且不得无保护暴露公网中继必须同时使用防火墙或反向代理来源 IP 白名单限制采集器来源

采集器第一次连接时自动生成并持久化节点 ID 协调器保存每个节点的期望配置和修订号 Metadata 在采集器本地 RocksDB 待发送箱落盘后才确认下载成功协调器断开或积压达到高水位时采集器会暂停并在恢复后继续采集器心跳同时上报 DHT Peer 失败分类队列和当前进程资源协调器把集群汇总与逐节点快照写入可删除的诊断历史

Metadata 待发送箱以最多 32 条和 1 MiB 原始编码软上限组成批次超过软上限的单条 Metadata 仍会独立发送采集器最多并发 8 个批次并使用 Zstandard 压缩协调器限制请求体和解压后数据为 16 MiB 只有收到数量一致的完整批次结果后才从本地 RocksDB 原子确认删除失败批次继续保留并按有上限的指数退避重试

诊断页的本次运行接收和发送表示所选采集器容器从本次启动开始的非回环网络接口累计字节包含 DHT UDP Peer Metadata 下载协调器上传心跳和配置同步全部采集器视图显示各采集器最近上报值的合计不包含宿主机其他服务并在采集器容器重启后重新计数

本地启动一个协调器和两个采集器

export DHT_SEARCH_CLUSTER_TOKEN="请替换为至少三十二个字符的随机令牌"
docker compose -f compose.cluster.yaml up -d --build

PowerShell 使用 $env:DHT_SEARCH_CLUSTER_TOKEN = "请替换为至少三十二个字符的随机令牌"

打开 http://127.0.0.1:18080/system 查看两个节点再到配置页分别启用和修改参数

内部协议使用批量 infohash 租约避免多个采集器重复下载 RocksDB 仍是唯一权威数据源租约丢失或上传重试只影响额外网络开销不会生成重复记录

本地运行

Windows 可以在仓库根目录执行

scripts\run.bat

脚本会在当前窗口同时启动 Rust 后端和 Vite 前端按一次 Ctrl+C 即可统一停止

默认地址

服务	地址
Web 开发界面	`http://127.0.0.1:5173`
HTTP API	`http://127.0.0.1:8080`
健康检查	`http://127.0.0.1:8080/health`
就绪检查	`http://127.0.0.1:8080/ready`
内部采集接口	`127.0.0.1:8081`

也可以分别启动

cargo run -p dht-search --bin dht-search -- --config config.toml

cd src/web
bun install
bun run dev -- --host 127.0.0.1

Windows 构建 RocksDB 需要 LLVM 并让 LIBCLANG_PATH 指向包含 libclang.dll 的目录

Docker

镜像使用 Bun Rust 和 debian:trixie-slim 三个阶段构建最终容器只运行非 root dht-search 进程

docker build --platform linux/amd64 -t dht-search:dev .
docker compose up -d
docker compose logs -f

默认 Compose 行为

config.toml 映射到 /dht-search/config.toml
dht-search-data 命名卷保存 RocksDB Tantivy SQLite 日志和检查点
HTTP 只发布到宿主机 127.0.0.1:8080
DHT UDP 发布到宿主机 12313/udp
容器文件句柄上限为 65536
停止宽限时间为 120 秒

端口冲突时可以临时覆盖

$env:DHT_HTTP_BIND = "127.0.0.1:18080"
$env:DHT_UDP_PORT = "22313"
docker compose up -d

常用管理命令

docker compose ps
docker compose logs -f
docker compose stop
docker compose start
docker compose down

docker compose down 不删除数据卷不要执行 docker compose down --volumes 除非已经确认权威数据不再需要

导出并传输镜像

docker save dht-search:dev -o dht-search-dev.tar
docker load -i dht-search-dev.tar

如果宿主机启用了 Xray TProxy 等全局透明代理 DHT 流量可能需要单独旁路判断和处理方式见 docs/xray-transparent-proxy.md

测试

单个规则和私有状态机测试放在对应 Rust 模块底部跨层公开契约测试放在 crate 的 tests/ 目录真实 DHT 长时间运行远程部署和浏览器交互不进入默认 cargo test

默认 Rust 验证命令

$env:LIBCLANG_PATH = "$PWD\.tools\libclang\clang\native"
cargo fmt --all --check
cargo test --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings

手动验证高延迟限速和请求失败条件下的持久待发送箱批量清空

cargo test -p dht-search --all-features compressed_batches_drain_a_mixed_outbox_over_a_limited_link -- --ignored --nocapture

Web 验证命令

cd src/web
bun run typecheck
bun run build

性能基线

基准使用 Windows x86_64 release 构建和确定性合成数据内容重复比例为十分之一每批索引 1000 个内容文档

记录数	内容文档	RocksDB 写入	Tantivy 索引	总磁盘	峰值内存
10,000	9,000	102,433 条/秒	9,050 文档/秒	21.88 MiB	53.07 MiB
100,000	90,000	86,452 条/秒	8,423 文档/秒	174.24 MiB	182.23 MiB
1,000,000	900,000	75,248 条/秒	5,435 文档/秒	1.49 GiB	433.14 MiB

百万级查询 P95

查询类型	P95
中文关键词	4.774 ms
英文关键词	7.746 ms
文件路径片段	1.063 ms
精确 infohash	0.031 ms
最近收录排序	3.367 ms
大小扩展名过滤	6.641 ms

百万级基准中普通搜索过滤排序精确哈希索引吞吐磁盘和峰值内存均达到当前目标

大型种子会先按文件大小降序和规范化路径稳定排序最多索引 2048 个文件且完整路径文本总量不超过 256 KiB 以优先覆盖主体内容并限制极端 Metadata 的索引放大

搜索索引对标题使用最多 10 字符的有限 N-Gram 文件名使用 2 至 3 字符 Basic 倒排和独立四字符位置字段长文件名关键词通过短语查询保证连续匹配完整路径仅按目录段和单词分词普通文本查询会按各字段策略拆分 *.iso 一类扩展名快捷查询直接使用扩展名词项索引并可与普通关键词组合搜索侧不执行正则或任意通配符扫描并在首次写入前延迟创建 Tantivy writer

每条记录包含 2048 个文件的极端基准中 450 个内容文档的 Tantivy 索引为 19.84 MiB 平均每文档 46.2 KiB 峰值内存为 113.08 MiB

运行诊断中的 index_refresh_scheduled 和 index_refresh_suppressed 分别表示重复发现实际安排和被时间桶合并的索引刷新数 index_documents_written 和 index_documents_skipped 用于确认待索引任务最终是否产生 Tantivy 文档写入

真实索引空间测量

使用 dht-index-inspect 可以只读统计 CURRENT 指向的活动 Tantivy 索引不会创建 writer 或修改索引

cargo run -p dht-search --bin dht-index-inspect -- data/search-index

2026-08-11 在远端 624801 个活动文档上的测量覆盖 99.9998% 的索引文件字节总索引为 14.71 GiB 其中物理文档 1036396 个删除文档比例为 39.71% 按物理文档比例估算相同 Schema 全新重建约为 8.87 GiB

字段或组件	占用	比例
文件名 N-Gram `file_names`	9.02 GiB	61.34%
别名 N-Gram `aliases`	1.73 GiB	11.78%
标题 N-Gram `name`	1.73 GiB	11.75%
已停用查询字段 `regex_text`	0.83 GiB	5.62%
精确文件名 `exact_file_names`	0.64 GiB	4.35%
路径分词 `files_text`	0.30 GiB	2.04%
全部 stored fields	0.20 GiB	1.39%
全部 fast fields	0.01 GiB	0.09%

空间瓶颈是文件名 N-Gram 不是 stored field fast field 热度或可用性字段新 Schema 已删除没有查询调用方的 regex_text 并停止在 aliases 中重复索引代表标题不同 infohash 提供的其他标题仍保留为可搜索别名精确文件名字段暂时保留用于相关性排序

在 10 万条确定性记录的相同数据集上对比文件名 N-Gram 2..8 与 2..4 后 file_names 从 18232514 字节降到 5068096 字节单字段下降 72.20% 其中词典下降 91.20% 倒排表下降 65.64% 总 Tantivy 索引下降 12.01% 索引吞吐从每秒 8079 文档提高到 9015 文档

两组常规查询结果数量保持一致 P95 查询多数变化很小文件路径片段从 0.213 ms 增加到 0.326 ms 简单 2..4 会把长关键词拆成多个四字符词项测试已确认多个文件分别包含零散片段时 Tantivy 候选可能误匹配

为避免读取 RocksDB 复核候选破坏稳定分页实验方案将 2 至 3 字符片段保存为无词频基础倒排将四字符片段保存到独立位置字段长关键词使用短语查询多文件零散片段误匹配测试被精确拦截连续长文件名搜索保持通过

在相同 10 万条数据上拆分位置方案的两个文件名字段合计从 18232514 字节降到 5584568 字节下降 69.37% 总索引下降 11.51% 索引吞吐从每秒 8079 文档提高到 8934 文档文件路径片段 P95 为 0.500 ms 位置数据为 1240496 字节

每条 100 个高度重复短文件名的压力数据中拆分位置方案空间基本持平但索引吞吐提高约 32% 说明收益取决于真实文件名长度和多样性按远端字段占比线性推算相同 Schema 的全新索引可能从约 8.87 GiB 降到约 5.1 GiB

生产索引已经切换到拆分位置方案 Schema 或文档格式变化时通过影子索引从 RocksDB 全量重建旧索引在重建完成和原子切换前继续提供搜索最终体积峰值磁盘和真实查询延迟仍需通过远端重建验证

README.md

DHT 元数据搜索服务

项目结构

分布式运行

本地运行

Docker

测试

性能基线

真实索引空间测量

相关文档