HUB
Sign inSign up

nick404/torrenthub-api

By nick404

•Updated 14 days ago

TorrentHub: self-hosted torrent discovery, qBittorrent download, Jellyfin archive.

Image
0

49

nick404/torrenthub-api repository overview

⁠TorrentHub

TorrentHub 是一个自托管的种子发现、下载、归档与播放面板:浏览 5 个公开种子源,按封面和中文标题筛选,交给 qBittorrent 下载;下载完成后自动停止做种、从 qBittorrent 移除任务但保留文件,再按电影/剧集/成人分区归档,写入 NFO 与海报,并可交给 Jellyfin 播放。

本仓库提供两个自定义镜像:api 和 web。qBittorrent、Jellyfin、Amane 使用各自的上游镜像,不包含在本仓库镜像内。

⁠镜像

nick404/torrenthub-api:latest   # FastAPI + SQLite + 下载/归档/维护任务
nick404/torrenthub-web:latest   # Next.js 前端
docker pull nick404/torrenthub-api:latest
docker pull nick404/torrenthub-web:latest

⁠功能

  • 5 个源:TPB、EZTV、YTS、Sukebei Nyaa、iJavTorrent
  • 封面卡片、中文标题优先、按电影/剧集/成人筛选
  • 按大小区间和分辨率(2160p / 1080p / 720p / 480p)筛选
  • 点击下载后自动交给 qBittorrent
  • 完成后停止做种,删除 qBittorrent 任务但保留文件
  • 归档到 media/movies/<source>/、media/tv/<source>/、media/adult/<source>/
  • NFO、poster、fanart;TMDB / TVMaze / iTunes / Amane 元数据
  • Jellyfin 播放页;MKV 自动提示使用 Jellyfin
  • 定时同步(默认 10 分钟)与中文标题翻译
  • 本地容量面板、缓存自动清理、回收站和软配额

⁠最小 Compose

把下面保存为 docker-compose.yml(与 .env 同目录),即可启动 qBittorrent、API 和 Web:

name: torrent-hub

services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: torrent-hub-qbittorrent
    environment:
      PUID: "1000"
      PGID: "1000"
      TZ: Asia/Shanghai
      WEBUI_PORT: "8080"
      TORRENTING_PORT: "6881"
    volumes:
      - ./data/qbt-docker:/config
      - ./data/downloads:/downloads
    ports:
      - "8080:8080"
      - "6881:6881"
      - "6881:6881/udp"
    restart: unless-stopped

  api:
    image: nick404/torrenthub-api:latest
    container_name: torrent-hub-api
    environment:
      DATABASE_URL: sqlite+aiosqlite:////data/app.db
      DATA_DIR_PATH: /data
      MEDIA_ROOT: /media
      DOWNLOAD_ROOT: /downloads
      QBIT_URL: http://qbittorrent:8080
      QBIT_USERNAME: admin
      QBIT_PASSWORD: ${QBIT_PASSWORD}
      QBIT_CATEGORY: torrent-hub
      QBIT_ENABLED: "true"
      SYNC_INTERVAL_MINUTES: "10"
      MEDIA_QUOTA_GB: "80"
      CORS_ORIGINS: http://${LAN_IP}:3000,http://${LAN_IP}:8000
    volumes:
      - ./data:/data
      - ./media:/media
      - ./data/downloads:/downloads
    ports:
      - "8000:8000"
    depends_on:
      - qbittorrent
    restart: unless-stopped

  web:
    image: nick404/torrenthub-web:latest
    container_name: torrent-hub-web
    environment:
      NEXT_PUBLIC_API_BASE: http://${LAN_IP}:8000/api/v1
    ports:
      - "3000:3000"
    depends_on:
      - api
    restart: unless-stopped

完整版本(Jellyfin、Amane、Stash、缓存阈值)见源码仓库的 docker-compose.hub.yml。

⁠快速开始

⁠1. 准备目录
mkdir -p torrent-hub/{data,media}
cd torrent-hub

把上面的最小 Compose 保存为 docker-compose.yml,然后创建 .env:

cat > .env <<'EOF'
# 你宿主机的局域网地址,用于浏览器访问 API
LAN_IP=192.168.1.10

# 必须与 qBittorrent WebUI 的密码一致
QBIT_PASSWORD=change-me

# 可选
TMDB_API_KEY=
JELLYFIN_API_KEY=
EOF
⁠2. 启动
docker compose up -d

默认端口:

服务地址
Webhttp://<LAN_IP>:3000
APIhttp://<LAN_IP>:8000/api/v1
qBittorrent WebUIhttp://<LAN_IP>:8080
Jellyfin(可选)http://<LAN_IP>:8096

请通过 LAN_IP 访问 Web,不要用 localhost。前端会按浏览器当前 hostname 请求 http://<hostname>:8000/api/v1;如果你使用反向代理,请把 NEXT_PUBLIC_API_BASE 指向 API 的公网/局域网地址。

⁠与 qBittorrent 联动

TorrentHub 不替代 qBittorrent,而是通过 qBittorrent WebUI API 驱动它。

⁠1. 设置 qBittorrent 密码

首次启动 qBittorrent 后,查看临时密码:

docker logs torrenthub-qbittorrent 2>&1 | grep -i password

打开 http://<LAN_IP>:8080,用 admin 和临时密码登录,在 Options → Web UI → Password 改成 .env 里的 QBIT_PASSWORD。

API 容器使用以下环境变量连接:

QBIT_URL=http://qbittorrent:8080
QBIT_USERNAME=admin
QBIT_PASSWORD=${QBIT_PASSWORD}
QBIT_CATEGORY=torrenthub
QBIT_ENABLED=true
⁠2. 下载目录必须一致

qBittorrent 和 API 必须看到同一个下载目录:

qbittorrent:
  volumes:
    - ./data/downloads:/downloads

api:
  volumes:
    - ./data/downloads:/downloads

qBittorrent 的保存路径应设为 /downloads;API 的 DOWNLOAD_ROOT 也是 /downloads。否则 API 找不到下载完成后的文件。

⁠3. 完成后的动作

API 的下载监控每 5 秒轮询 qBittorrent:

  1. 任务进入完成状态
  2. 调用 POST /api/v2/torrents/stop 停止做种
  3. 调用 POST /api/v2/torrents/delete,固定 deleteFiles=false
  4. 从 /downloads 找到最大视频文件
  5. 硬链接/复制到 /media
  6. 写 NFO、poster、fanart
  7. 触发 Jellyfin / Stash 刷新(若已配置)
  8. 下载记录标记 completed

因此 qBittorrent 任务列表会变空,但文件仍保留在 data/downloads;归档到 media 后通常使用硬链接,不会重复占用一份完整视频空间。

⁠4. 不要让 qBittorrent 自己移动文件

请关闭 qBittorrent 的 Options → Downloads → Keep torrents in default save path 之外的自定义“完成后移动”规则,避免 API 在归档时找不到源文件。

⁠Jellyfin(可选)

docker compose --profile media up -d jellyfin  # 需使用包含 jellyfin 服务的完整 compose

首次打开 Jellyfin 完成向导,然后在 TorrentHub 设置 JELLYFIN_URL=http://jellyfin:8096 和 JELLYFIN_API_KEY。API 会用 Jellyfin 的 Authorization: MediaBrowser ... 头查询媒体并代理播放;MP4 可直接在浏览器播放,MKV 会提示跳转 Jellyfin。

Jellyfin 媒体库目录:

/media/movies
/media/tv
/media/adult

⁠Amane(可选,成人刮削)

docker compose --profile amane up -d amane  # 需使用包含 amane 服务的完整 compose
  • 地址:http://<LAN_IP>:8010
  • Token:data/amane/token
  • 允许目录:/media/adult
  • Amane 负责成人元数据/NFO;它不提供播放,播放仍由 Jellyfin 负责

⁠数据与备份

路径内容
data/app.dbSQLite 数据库
data/downloads/qBittorrent 下载暂存
media/归档后的电影/剧集/成人视频、NFO、海报
data/covers/封面缓存
data/trash/回收站(默认保留 7 天)
data/jellyfin/Jellyfin 配置/缓存
data/amane/Amane 数据

备份至少包含 data/app.db、media/ 和 .env。data/downloads 可按需保留;删除前确认归档文件已存在。

⁠缓存与容量

  • 每日 04:00 自动清理可再生缓存;磁盘低于 15 GB 时触发紧急缓存清理
  • 封面 30 天 / 512 MB;Jellyfin 转码 7 天 / 2 GB;Amane 512 MB;render 14 天;trash 7 天
  • 种子元数据 14 天 / 50,000 条,保留被下载/资料库引用的条目
  • 资料库媒体默认不自动删除,软配额默认 80 GB
  • 前端右上角容量面板可预览/执行清理
  • 宿主机 Docker 清理:
# 在项目目录
docker builder prune --filter until=168h
docker image prune -a --filter until=336h
docker container prune --filter until=168h

⁠环境变量

完整变量见 .env.example⁠。最常用的:

变量默认说明
LAN_IP192.168.50.36宿主机局域网 IP
QBIT_PASSWORDchange-meqBittorrent WebUI 密码
QBIT_CATEGORYtorrenthubqBittorrent 分类名
TMDB_API_KEY空TMDB 元数据
JELLYFIN_API_KEY空Jellyfin token
SYNC_INTERVAL_MINUTES10种子同步周期
MEDIA_QUOTA_GB80资料库软配额
MEDIA_AUTO_PRUNEfalse是否自动移走旧媒体

⁠常见问题

Web 打开后 API 请求 localhost?
请用 http://<LAN_IP>:3000 访问,不要用 localhost;或重新构建 web 镜像并设置 NEXT_PUBLIC_API_BASE。

下载完成但资料库没有条目?
检查 qBittorrent 与 API 的 /downloads 是否指向同一个宿主机目录,并确认 qBittorrent 任务已完成。API 日志会显示归档错误。

qBittorrent 任务消失但文件还在?
这是预期行为:停止做种后删除任务,deleteFiles=false 保留文件;归档文件在 media/。

Jellyfin 提示密码错误?
Jellyfin 密码与 qBittorrent 无关。用 admin 登录 Jellyfin 后重置;若 API token 失效,重新登录 Jellyfin 并更新 JELLYFIN_API_KEY。

⁠安全提示

  • 不要把 .env 提交到公开仓库。
  • 不要把 qBittorrent WebUI、Jellyfin、Amane 直接暴露到公网;如需远程访问,使用 VPN 或带认证的反向代理。
  • 公开种子站的内容版权归各自权利人,请遵守所在地法律与站点条款。

⁠源码

  • API:services/api
  • Web:apps/web
  • 维护与缓存:services/api/app/maintenance
  • 部署:docker-compose.hub.yml

⁠License

MIT(示例文档;第三方镜像与站点内容遵循各自许可证/条款)。

Tag summary

Content type

Image

Digest

sha256:e2a956af9…

Size

73.4 MB

Last updated

14 days ago

docker pull nick404/torrenthub-api