DHTSearch

API 文档

DHTSearch的公开只读 API:搜索本站基于 DHT 网络实时收录的磁力链接,读取种子文件列表与相似推荐,订阅 RSS,或提交游客举报。接口返回 JSON(RSS 除外),支持跨域(Access-Control-Allow-Origin: *)。 下文地址以 https://api.example.com 代指部署的 API 服务地址,替换为实际地址即可。机器可读的 OpenAPI 3 描述文件在 /openapi.yaml。

鉴权与限流

是否需要令牌由部署方设置(PUBLIC_API_REQUIRE_TOKEN,默认关)。关闭时三个门控接口可匿名调用;开启后必须携带令牌。无论开关如何,令牌门控只作用于 /api/search、/api/stats、/api/trending 三个接口;文件列表、相似推荐、RSS、站点信息、健康检查与举报接口不要求令牌。

获取令牌:由站点管理员在管理端「API 令牌」页创建。令牌形如 dht_ 加 64 位十六进制字符(共 68 字符),明文只在创建时显示一次,之后只能看前缀。每个令牌有独立的每分钟配额(创建时默认 600 次/分钟,管理员可逐个修改,0 = 不限)。

携带方式(二选一,不支持查询参数传令牌):

Authorization: Bearer <redacted>
# 或
X-API-Key: dht_xxxxxxxx...

鉴权失败按原因区分(响应体均为 {"error": "..."}):

参数类型默认说明
401未带令牌api token required门控开启且请求未携带令牌;同时返回 WWW-Authenticate 头
401令牌无效invalid api token令牌不存在或已删除
403令牌被禁用api token disabled令牌存在但已被管理员禁用
429令牌配额用尽api token rate limit exceeded超过该令牌的每分钟配额;响应带 Retry-After
503公开 API 被关闭public api disabled部署方关闭了公开 API 总开关,三个门控接口对所有人返回 503

全局限流:除令牌配额外,所有公开接口共享按客户端 IP 的限流(默认每秒 3 次、突发 30 次,部署方可调),超限返回 429 rate limit exceeded 并带 Retry-After: 1。带令牌不豁免全局限流。搜索类接口在服务器饱和时可能返回 503 server busy 或 search timed out,稍后重试即可。

接口参考

GET/api/search受令牌门控

关键词搜索。无关键词时为浏览最新收录。没有独立的种子详情接口——搜索结果条目即完整记录(名称、大小、文件预览、磁力链接、做种数据),文件全量列表与相似推荐见下方两个接口。

参数类型默认说明
qstring(空)关键词,最长 200 字符(超出截断);空 = 浏览最新
pageint1页码,从 1 起;可达深度上限为偏移 10000 条,超出自动钳制
page_sizeint20每页条数,最大 100
categorystring(全部)video / audio / image / doc / software / archive / other;非法值 400
sortstringrelevancerelevance(相关性)/ newest(最新)/ size(体积)/ seeders(做种数);非法值 400
hide_deadstring01 或 true 时隐藏 health=likely_dead 的结果;其他取值 400
curl "https://api.example.com/api/search?q=shawshank&sort=seeders&page_size=2"
{
  "total": 2,
  "page": 1,
  "page_size": 2,
  "category": "",
  "sort": "seeders",
  "hide_dead": false,
  "categories": { "video": 2, "audio": 0, "image": 0, "doc": 0,
                  "software": 0, "archive": 0, "other": 0 },
  "trackers": ["udp://tracker.opentrackr.org:1337/announce", "..."],
  "results": [
    {
      "info_hash": "4cd02e56c0237fcd5190dc9e9430592040431aaa",
      "name": "The Shawshank Redemption 1994 2160p UHD BluRay REMUX",
      "total_size": 58000000000,
      "file_count": 1,
      "files": [
        { "path": "The.Shawshank.Redemption.1994.2160p.UHD.BluRay.REMUX.mkv",
          "size": 58000000000 }
      ],
      "magnet": "magnet:?xt=urn:btih:4cd0...&dn=...&tr=...(已截短)",
      "created_at": 1795236227,
      "category": "video",
      "seeders": 41, "leechers": 9, "completed": 233,
      "scraped_at": 1795235327, "zero_since": 0, "zero_count": 0,
      "health": "alive"
    }
  ]
}

结果条目字段:files 只内嵌前 100 个文件作预览(全量走文件列表接口);alias 为订阅源发布的别名标题,非空时才出现;seeders / leechers / completed / scraped_at / zero_since / zero_count 是最近一次 tracker 刮削快照,从未被刮削过的种子这些字段为 null(与真实的 0 严格区分);health 是由快照推导的健康度: alive(有做种)/ no_seed(无做种但有人下载)/ likely_dead(连续多次全零、跨度 ≥48 小时)/ suspect(全零但证据不足)/ unknown(无刮削数据)。created_at 为收录时间(Unix 秒)。

GET/api/torrents/{hash}/files无需令牌

分页读取一个种子的完整文件列表。

参数类型默认说明
pageint1页码,从 1 起
page_sizeint100每页条数,最大 500
qstring(空)按文件路径子串过滤;total 统计过滤后的条数
curl "https://api.example.com/api/torrents/0f09bec639b50b57e0c817048a1eef0bfda69e2e/files?page=1&page_size=2"
{
  "info_hash": "0f09bec639b50b57e0c817048a1eef0bfda69e2e",
  "total": 3,
  "total_all": 3,
  "page": 1,
  "page_size": 2,
  "total_pages": 2,
  "files": [
    { "path": "The.Shawshank.Redemption.1994.1080p.BluRay.x264.mkv", "size": 2140000000 },
    { "path": "The.Shawshank.Redemption.1994.1080p.BluRay.x264.srt", "size": 103456 }
  ]
}

total_all 是该种子的文件总数(未过滤);哈希不存在返回 404。

GET/api/torrents/{hash}/similar无需令牌

与指定种子名称相近的推荐,结果条目结构与搜索一致,但 files 为 null。

参数类型默认说明
limitint6返回条数,钳制在 1..12
curl "https://api.example.com/api/torrents/0f09bec639b50b57e0c817048a1eef0bfda69e2e/similar"
{
  "results": [
    {
      "info_hash": "4cd02e56c0237fcd5190dc9e9430592040431aaa",
      "name": "The Shawshank Redemption 1994 2160p UHD BluRay REMUX",
      "total_size": 58000000000,
      "file_count": 1,
      "files": null,
      "magnet": "magnet:?xt=urn:btih:4cd0...&dn=...&tr=...(已截短)",
      "created_at": 1795236227,
      "category": "video",
      "seeders": 41, "leechers": 9, "completed": 233,
      "scraped_at": 1795235327, "zero_since": 0, "zero_count": 0,
      "health": "alive"
    }
  ]
}

哈希不存在返回 404。

GET/api/stats受令牌门控

索引与管线统计(服务端缓存约 10 秒)。顶层为累计计数:收录总数、已发现、已抓取与各过滤类别计数;fetch 是元数据抓取结果(含按来源 by_source 拆分与实时队列深度);moderation 是审核计数。部署启用了对应子系统时还会出现 crawler / scraper / feeds 段。

curl "https://api.example.com/api/stats"
{
  "torrents": 3,
  "seen": 0, "fetched": 0,
  "adult_filtered": 0, "spam_filtered": 0,
  "size_filtered": 0, "blocked_filtered": 0,
  "fetch": {
    "fetched": 0, "timed_out": 0, "failed": 0, "prescreen_dropped": 0,
    "skipped_stored": 0, "skipped_backoff": 0,
    "peer_hint_items": 0, "peer_hint_fetched": 0,
    "by_source": [
      { "source": "dht", "attempts": 0, "fetched": 0, "timed_out": 0,
        "failed": 0, "prescreen_dropped": 0, "success_rate": 0 }
    ],
    "queue_depth": 0, "backend": "anacrolix"
  },
  "moderation": { "reviewed": 0, "adult_removed": 0, "spam_removed": 0,
                  "errors": 0, "pending": 3, "blocked": 0 }
}
GET/api/trending受令牌门控

首页榜单数据:豆瓣热门影视标题(英文名为主,日韩剧为中文名)与更新时间(Unix 秒)。

curl "https://api.example.com/api/trending"
{
  "movies": ["The Odyssey", "..."],
  "tv": ["VisionQuest", "..."],
  "tv_jp": ["白色巨塔", "..."],
  "tv_kr": ["百日谎言", "..."],
  "updated_at": 1795200000
}
GET/api/site无需令牌

站点展示配置:名称、主题色与默认外观。

curl "https://api.example.com/api/site"
{ "name": "DHTSearch", "theme_color": "teal", "theme_appearance": "system" }
GET/api/healthz无需令牌

健康检查,不受任何门控与限流影响。

curl "https://api.example.com/api/healthz"
# { "ok": true }
GET/rss无需令牌

RSS 2.0 订阅:某关键词的最新收录(最多 50 条,按最新排序),无 q 时为全站最新。每条的链接即磁力链接, guid 为 infohash。

参数类型默认说明
qstring(空)关键词,最长 200 字符
categorystring(全部)同 /api/search 的分类枚举;非法值 400
curl "https://api.example.com/rss?q=ubuntu"
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"><channel>
  <title>DHTSearch 搜索:ubuntu</title>
  <link>https://api.example.com/</link>
  <description>基于 DHT 网络实时收录的磁力链接,已过滤成人内容与垃圾信息。</description>
  <item>
    <title>Ubuntu 24.04 LTS Desktop amd64</title>
    <link>magnet:?xt=urn:btih:a99dfe...&amp;dn=...&amp;tr=...(已截短)</link>
    <guid>a99dfe6400d029b848d18a9b6ff1611af03aadf8</guid>
    <pubDate>Fri, 21 Nov 2026 05:23:47 +0000</pubDate>
    <description>大小 5880.00 MB · 1 个文件</description>
    <category>software</category>
  </item>
</channel></rss>
POST/api/report无需令牌

游客举报一个已收录种子,进入管理员的举报队列。同一客户端对同一种子的举报有频率限制(约 3 次/分钟),超限 429。

参数类型默认说明
info_hashstring(必填)40 位十六进制 infohash
reasonstring(必填)adult(成人内容)/ spam(垃圾信息)/ infringement(侵权)/ other(其他)
notestring(空)补充说明,最长 500 字符
curl -X POST "https://api.example.com/api/report" \
  -H "Content-Type: application/json" \
  -d '{"info_hash":"0f09bec639b50b57e0c817048a1eef0bfda69e2e","reason":"spam","note":"重复垃圾"}'
# 201 { "ok": true }

错误模型

所有 JSON 错误响应体统一为 {"error": "消息"},状态码与常见消息如下:

参数类型默认说明
400参数错误invalid category / invalid sort / invalid hide_dead / invalid info_hash / invalid reason / bad request参数不合法,按消息修正即可
401未鉴权api token required / invalid api token见「鉴权与限流」
403令牌被禁用api token disabled联系站点管理员
404不存在not found哈希对应的种子不存在
429限流rate limit exceeded / api token rate limit exceeded / too many reports for this torrent按 Retry-After 等待后重试
500服务器错误search failed / stats failed / report failed / feed failed服务端内部错误
503暂不可用public api disabled / server busy / search timed out公开 API 被关、服务器饱和或查询超时,稍后重试