一个基于 FastAPI + 可切换 SQLite/MySQL + DHT/HTTP metadata 抓取 的磁力搜索网站，提供公开搜索页面、后台管理面板，以及 qBittorrent WebUI API 快速投递能力。

本项目适合用于学习以下主题：

• DHT / info_hash 发现与 metadata 获取流程；
• 基于 SQLite / MySQL 的轻量搜索服务设计；
• 后台可热更新的爬虫调度、过滤与容量控制；
• 与 qBittorrent WebUI API 联动；
• Docker / Docker Compose 快速部署与开源整理。

本项目仅供技术研究、协议学习与私有环境实践使用。请遵守你所在地区的法律法规，以及站点、网络和内容使用规范。

magnet-fix/
├── app.py
├── config.py
├── database.py
├── dht_crawler.py
├── qbittorrent_client.py
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── static/
│   ├── index.html
│   └── admin.html
├── tests/
│   ├── test_fix_regression.py
│   └── validate_runtime.py
├── docs/
│   └── deployment.md
├── data/
│   └── .gitkeep
├── .dockerignore
├── .gitignore
├── LICENSE
└── README.md

git clone <your-repo-url> magnet-fix
cd magnet-fix

# 仅启动搜索站点（默认 SQLite）
docker compose up -d --build

# 同时启动搜索站点和示例 qBittorrent 服务
docker compose --profile with-qb up -d --build

# 同时启动搜索站点和示例 MySQL 服务
docker compose --profile with-mysql up -d --build

# 同时启动搜索站点、qBittorrent、MySQL
docker compose --profile with-qb --profile with-mysql up -d --build

启动后默认访问：

如果你使用的是外部已有 qBittorrent 或 MySQL，也可以只启动 magnet-search 服务，再在后台填入对应配置。

python3 -m pip install -r requirements.txt
mkdir -p data
export CONFIG_PATH=./data/config.json
export DB_PATH=./data/magnet.db
python3 -m uvicorn app:app --host 0.0.0.0 --port 8080

如果希望启用更完整的 DHT metadata 能力，请在宿主机额外安装系统版 libtorrent。

系统首次启动时会自动生成配置文件，默认后台密码为：

admin123

首次登录后请立即在后台修改密码。

后台新增 数据库配置 区域，支持以下模式：

保存前必须先通过连接验证；验证失败则不能保存。数据库切换成功后会立即生效，并自动停掉正在运行的爬虫，避免跨库写入冲突。

后台新增 站点主题设置，支持：

保存后前台搜索页和后台管理页会同步应用。

后台新增以下高级项：

后台新增 按规则批量删除，支持以下组合条件：

后台新增了 qBittorrent 对接 配置区，支持以下项目：

配置完成后，前台搜索结果会显示 添加到 qBittorrent 按钮，点击即可通过站点后端转发到 qBittorrent。

在 DHT 抓取场景里，“发现 hash 很快，但 metadata 成功率明显低于发现数”本身是常见现象。常见原因包括：

1. hash 已经失活，没有在线 peer；
2. 公共缓存未命中；
3. 服务器没有开放 UDP / 没有正确启用 libtorrent；
4. 公开源能发现 hash，但无法保证元数据始终可取。

当前版本已经进一步优化了失败统计口径、重试逻辑、回退链路、队列控制和高 CPU 档位下的吞吐策略，但无法从根本上消除公共网络环境导致的天然失败率。

仓库保留了两个基础验证脚本：

python3 tests/validate_runtime.py
python3 tests/test_fix_regression.py

本项目以 MIT License 开源，详见 LICENSE。