BT种子解析插件（torrent）使用文档

版本：1.0.0 | 作者：kuakeba.cn | 适用于 Zsens Admin 3.0+（PHP 8.2+）

一、插件简介

为社区帖子提供 BT 种子（.torrent）附件能力：

• 发帖页上传 .torrent 文件，服务端自动解析种子
• 自动计算 info_hash（SHA1），生成磁力链接（含 Tracker）
• 查询种子健康度：做种数 / 下载数，展示等级徽章，支持手动刷新
• 帖子正文输出文件目录，支持树形目录与普通列表两种视图切换
• 支持单帖挂载多个种子、目录折叠、磁力链接一键复制、种子文件下载

二、环境要求

三、安装步骤

1. 将 torrent 目录整体放入项目 plugins/ 下
2. 进入后台 应用中心，找到「BT种子解析」，点击 安装
3. 安装时自动：

  - 创建数据表 {前缀}topic_torrent

  - 将 plugins/torrent/static/ 复制到 public/static/torrent/

1. 进入 应用中心 → BT种子解析 → 配置，按需调整配置项
2. 确保已安装并启用 社区（community） 插件

插件通过前台渲染钩子自动挂载，无需修改主题模板；发帖页的「BT种子」拓展面板也会自动注册。

四、配置项说明

后台 应用中心 → BT种子解析 → 配置：

五、发帖使用

1. 进入允许的版块发帖，在编辑器下方找到 「BT种子」 拓展面板
2. 点击 选择种子文件，可一次选择多个 .torrent（受「单帖种子数量」限制）
3. 上传成功后自动展示解析结果：种子标题、内容大小、文件数、info_hash、磁力链接
4. 可在列表中删除不需要的种子
5. 正常发布帖子，种子信息随帖子保存

注意事项：

• 前端会先校验后缀、单文件大小与数量；服务端会再次校验
• 保存时服务端会优先重新解析本地种子文件，前端数据仅作兜底，避免伪造 info_hash / 磁力链接
• 上传期间请勿提交表单，避免种子数据未同步
• 后台管理员在后台编辑帖子时同样可以管理种子

六、前台展示

帖子正文下方自动渲染「种子资源」区块，每个种子包含：

健康度等级规则：

七、接口说明

1. 上传并解析种子

POST /torrent/upload

成功返回示例：

{
  "code": 1,
  "msg": "解析成功",
  "data": {
    "name": "示例种子.torrent",
    "path": "torrents/20261017/xxxx.torrent",
    "url": "/storage/torrents/20261017/xxxx.torrent",
    "size": 24576,
    "size_text": "24 KB",
    "content_size": 1234567890,
    "content_size_text": "1.15 GB",
    "file_count": 12,
    "info_hash": "861C4D149FDECE5164BF1B49B2E09F72ED6DA1D1",
    "title": "示例影片",
    "magnet": "magnet:?xt=urn:btih:861c4d...&dn=...&tr=...",
    "trackers": ["http://tracker.example.com/announce"],
    "files": [{ "path": "视频/a.mp4", "size": 1024 }],
    "tree": { "name": "示例影片", "type": "dir", "size": 1024, "children": [] }
  }
}

失败返回 code = 0，msg 为原因（未登录 / 无权限 / 版块不支持 / 后缀不符 / 超出大小 / 解析失败等）。

size 为种子文件自身大小，content_size 为种子内实际内容总大小。

2. 查询种子健康度

GET /torrent/health?id={种子ID}&force={0|1}

成功返回示例：

{
  "code": 1,
  "msg": "ok",
  "data": {
    "ok": true,
    "seeders": 128,
    "leechers": 36,
    "downloads": 2048,
    "tracker_count": 3,
    "queried_at": 1792212061,
    "cached": 0,
    "level": "excellent",
    "label": "优秀",
    "id": 1
  }
}

说明：

• 取所有 Tracker 响应中的最大值作为展示值
• 最多并发查询 12 个 HTTP(S) Tracker，单个超时由配置决定
• 无可用 Tracker 或全部失败时 ok = false，前端显示「未知」

3. 下载种子文件

GET /torrent/download?id={种子ID}

• 需通过社区下载权限校验（CommunityPerm::can('download')）
• 返回 application/x-bittorrent，并累加 download_count

八、数据表

安装后创建 {前缀}topic_torrent，主要字段：

卸载插件会删除该表，上传的种子文件不会自动清理。

九、常见问题

1. 发帖页没有「BT种子」面板？

• 确认插件已安装并启用
• 确认当前用户组在「可发布用户组」中（管理员不受限）
• 确认当前版块在「可用版块」中
• 确认社区（community）插件已安装

2. 上传提示「文件超过服务器 POST 限制」？

调整 PHP 的 uploadmaxfilesize 与 postmaxsize，并重启 PHP / Web 服务；插件自身的单文件上限由「单文件大小(MB)」控制。

3. 健康度一直显示「未知」？

• 种子内没有 announce / announce-list，或全部为 UDP Tracker（本插件仅支持 HTTP/HTTPS）
• Tracker 已失效、被墙或响应超时
• 可适当调大「健康度查询超时(秒)」，或点击帖子内的刷新按钮重试

4. 修改了 plugins/torrent/static/ 下的文件不生效？

静态资源在安装时复制到 public/static/torrent/。修改源文件后，请在后台对插件执行「升级」，或手动将文件复制到 public/static/torrent/ 并刷新浏览器缓存。

5. 单文件种子为什么没有显示目录层级？

单文件种子的树形视图直接显示该文件本身，不会出现「同名目录 → 同名文件」的重复层级；切换到「列表」视图可查看完整路径。

6. 种子文件保存在哪里？

保存在 public/storage/torrents/，访问地址为 /storage/torrents/...；数据库仅保存相对路径与访问 URL。

7. 删除帖子后种子会清理吗？

删除帖子时插件会同步删除对应的 topic_torrent 记录，但磁盘上的种子文件不会自动删除，可按需定期清理 public/storage/torrents/。

版本历史