161 lines
5.7 KiB
Markdown
161 lines
5.7 KiB
Markdown
# 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 完整重建
|
|
|
|
Tantivy 使用代际影子索引处理 Schema 文档格式损坏和缺失等全量重建 用户过滤规则通过可恢复扫描只增量更新真正变化的搜索文档 两类进度都可以在搜索提示与系统诊断页查看
|
|
|
|
应用全部配置和内容隐藏规则统一位于 [`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 | 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 |
|
|
| 有限状态正则 | 675.803 ms |
|
|
| 最近收录排序 | 3.367 ms |
|
|
| 大小扩展名过滤 | 6.641 ms |
|
|
|
|
百万级基准中普通搜索过滤排序精确哈希索引吞吐磁盘和峰值内存均达到当前目标 大命中集合正则仍是继续扩大规模前最值得优化的查询路径
|
|
|
|
大型种子会先按文件大小降序和规范化路径稳定排序 最多索引 2048 个文件且完整路径文本总量不超过 256 KiB 以优先覆盖主体内容并限制极端 Metadata 的索引放大
|
|
|
|
搜索索引对标题使用最多 10 字符的有限 N-Gram 对文件名使用最多 8 字符的有限 N-Gram 完整路径仅按目录段和单词分词 普通文本查询会按各字段策略拆分 正则和通配符继续使用完整规范化文本字段 索引不保存未使用的词位置信息并在首次写入前延迟创建 Tantivy writer
|
|
|
|
每条记录包含 2048 个文件的极端基准中 450 个内容文档的 Tantivy 索引为 19.84 MiB 平均每文档 46.2 KiB 峰值内存为 113.08 MiB
|
|
|
|
## 相关文档
|
|
|
|
- 当前实施状态和后续计划见 [`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)
|