# DHT 元数据搜索服务

这是一个用于持续发现持久化索引和搜索 BitTorrent DHT 元数据的 Rust 服务

当前已经具备可即时启停的 DHT 采集 Metadata 下载 RocksDB 精确去重 Tantivy 全文搜索 内容聚合 可用性验证 HTTP API Web 搜索界面 运行诊断 配置管理 备份恢复和 Docker 部署能力

## 项目结构

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

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

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

Web 右上角的无线电图标可以即时停止或恢复 DHT 持续采集 状态会写回 `dht.enabled` 关闭后不会建立 DHT 和 Metadata 网络任务 但现有 RocksDB 数据仍会继续补建索引并提供本地搜索

## 本地运行

Windows 可以在仓库根目录执行

```powershell
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` |

也可以分别启动

```powershell
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` 进程

```shell
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 秒

端口冲突时可以临时覆盖

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

常用管理命令

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

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

导出并传输镜像

```shell
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`](docs/xray-transparent-proxy.md)

## 测试

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

默认 Rust 验证命令

```powershell
$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
```

Web 验证命令

```shell
cd src/web
bun run typecheck
bun run build
```

## 性能基线

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

| 记录数 | 内容文档 | RocksDB 写入 | Tantivy 索引 | 总磁盘 | 峰值内存 |
|---:|---:|---:|---:|---:|---:|
| 10,000 | 9,000 | 149,584 条/秒 | 3,794 文档/秒 | 52.42 MiB | 86.21 MiB |
| 100,000 | 90,000 | 118,833 条/秒 | 3,261 文档/秒 | 452.65 MiB | 360.04 MiB |
| 1,000,000 | 900,000 | 102,115 条/秒 | 2,520 文档/秒 | 4.36 GiB | 1.70 GiB |

百万级查询 P95

| 查询类型 | P95 |
|---|---:|
| 中文关键词 | 2.571 ms |
| 英文关键词 | 5.793 ms |
| 文件路径片段 | 0.110 ms |
| 精确 infohash | 0.008 ms |
| 有限状态正则 | 656.086 ms |
| 最近收录排序 | 3.346 ms |
| 大小扩展名过滤 | 6.451 ms |

百万级基准中普通搜索过滤排序精确哈希索引吞吐磁盘和峰值内存均达到当前目标 大命中集合正则仍是继续扩大规模前最值得优化的查询路径

## 相关文档

- 当前实施状态和后续计划见 [`TODOS.md`](TODOS.md)
- 开发约定和架构边界见 [`AGENTS.md`](AGENTS.md)
- 应用命令参数 API 和基准工具见 [`src/search/README.md`](src/search/README.md)
- DHT 基础库用法和指标见 [`src/crawler/README.md`](src/crawler/README.md)
- Web 开发说明见 [`src/web/README.md`](src/web/README.md)