自托管BT索引器Bitmagnet部署教程：全网资源自由检索，附备份恢复方案

一、Bitmagnet是什么？

Bitmagnet 是一款开源自托管的BT索引器，核心功能包括网络搜索、内容分类、种子索引，支持检索全网活跃的电影、电视剧、电子书、音乐、软件和游戏等BT资源。

它的特点很鲜明：

  • 双容器架构（bitmagnet主服务 + postgres数据库），支持Docker Compose一键部署；
  • 内置DHT爬虫，自动抓取全网活跃种子；
  • 支持TMDB元数据刮削（海报、剧情简介等），可选配；
  • 兼容Torznab接口，可对接PT客户端；
  • 资源质量“开盲盒”：热门资源分享率高，下载速度能突破10M/s，冷门资源可能速度较慢。

如果你想摆脱第三方BT搜索的限制，搭建自己的私人资源检索库，Bitmagnet是绝佳选择！

二、部署前准备

1. 环境要求

  • 已安装 Docker 和 Docker Compose（建议Docker版本≥20.10，Compose版本≥3.8）；
  • 服务器/设备至少预留 2GB 内存 + 10GB 存储空间（数据库会随索引量增长，建议预留更多空间）；
  • 网络环境支持DHT网络连接（无需公网IP，但需开放相关端口）。

2. 文件夹创建

在宿主机的Docker存储目录下创建Bitmagnet专用文件夹（用于持久化配置、数据和数据库）：

1
2
# 示例路径（请根据自己的实际存储路径修改）
mkdir -p /volume1/docker/bitmagnet/{config,data,postgres-init}
  • config：存储Bitmagnet配置文件、日志；
  • data：存储应用临时数据和缓存；
  • postgres-init：数据库初始化脚本目录（可选）。

三、Docker Compose部署配置

1. 创建docker-compose.yml文件

进入Bitmagnet目录，创建并编辑docker-compose.yml文件：

1
2
cd /volume1/docker/bitmagnet
nano docker-compose.yml

2. 完整配置代码（已修复原代码问题）

将以下代码复制到文件中，注意修改标注的自定义项：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
version: '3.8'

services:
  # Bitmagnet主服务
  bitmagnet:
    image: ghcr.io/bitmagnet-io/bitmagnet:latest
    container_name: bitmagnet
    ports:
      - "3333:3333"         # WebUI访问端口（可修改左侧宿主机端口）
      - "3334:3334/tcp"     # 内部通信TCP端口
      - "3334:3334/udp"     # DHT网络UDP端口
    restart: unless-stopped
    environment:
      # 数据库连接配置（与下方postgres服务保持一致）
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres  # 生产环境建议修改为强密码
      - POSTGRES_DB=bitmagnet
      
      # TMDB元数据配置（可选，不填不影响核心功能）
      - TMDB_API_KEY=your_tmdb_api_key  # 替换为自己的TMDB API密钥（下文说明获取方法）
      - TMDB_ENABLED=true
      
      # 日志配置
      - LOG_LEVEL=info
      - LOG_DEVELOPMENT=false
      - LOG_JSON=false
      - LOG_FILE_ROTATOR_ENABLED=true
      - LOG_FILE_ROTATOR_PATH=/config/logs
      - LOG_FILE_ROTATOR_LEVEL=info
      
      # DHT爬虫配置（根据设备性能调整）
      - DHT_CRAWLER_SAVE_FILES_THRESHOLD=100
      - DHT_CRAWLER_SAVE_PIECES=false
      - DHT_CRAWLER_SCALING_FACTOR=10  # 数值越大爬取越快，消耗资源越多
      
      # 处理器配置（CPU核心数少则设为1）
      - PROCESSOR_CONCURRENCY=1
      
      # HTTP服务配置（已修复不支持的status选项）
      - HTTP_SERVER_OPTIONS=cors,graphql,import,prometheus,torznab,webui
      - HTTP_SERVER_CORS_ALLOWED_ORIGINS=http://localhost:3333,https://your-domain.com  # 替换为自己的域名（无则保留localhost）
      
      # Torznab接口密钥（PT客户端连接用，自定义强密码）
      - TORZNAB_API_KEY=your_secure_api_key
      
      # 配置目录
      - BITMAGNET_CONFIG_DIR=/config
    volumes:
      # 替换为第一步创建的实际路径（宿主机路径:容器路径）
      - /volume1/docker/bitmagnet/config:/config
      - /volume1/docker/bitmagnet/data:/data
    command:
      - worker
      - run
      - --keys=http_server
      - --keys=queue_server
      - --keys=dht_crawler
    depends_on:
      postgres:
        condition: service_healthy
    deploy:
      resources:
        limits:
          cpus: '2'       # 最大CPU核心数（根据设备调整）
          memory: 2G      # 最大内存（建议≥2G）
        reservations:
          cpus: '1'
          memory: 1G
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3333/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  # PostgreSQL数据库服务
  postgres:
    image: postgres:16-alpine  # 轻量级镜像，节省资源
    container_name: bitmagnet-postgres
    volumes:
      # 数据库数据持久化（替换为实际路径）
      - /volume1/docker/bitmagnet/postgres-data:/var/lib/postgresql/data
      - ./postgres-init:/docker-entrypoint-initdb.d
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: postgres  # 与上方POSTGRES_PASSWORD保持一致
      POSTGRES_DB: bitmagnet
      POSTGRES_USER: postgres
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=C --lc-ctype=C"
      PGDATA: /var/lib/postgresql/data/pgdata
    shm_size: 1g  # 优化数据库性能
    sysctls:
      - kernel.shmmax=1073741824
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d bitmagnet"]
      start_period: 30s
      interval: 10s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

# 专用网络隔离
networks:
  default:
    driver: bridge
    name: bitmagnet-network

3. 关键配置说明（必须修改）

  1. 路径替换：将所有/volume1/docker/bitmagnet替换为你第一步创建的实际路径；
  2. TMDB API Key（可选）：
    • 作用：刮削影视资源的海报、剧情简介等元数据；
    • 获取方法：访问TMDB官网注册账号，进入「设置→API→创建API密钥」，按提示申请即可；
    • 不填影响：仅无元数据展示，不影响搜索和下载。
  3. TORZNAB_API_KEY：自定义一个强密码（如random123!@#），后续PT客户端连接时需要；
  4. 资源限制：根据设备性能调整deploy.resources中的CPU和内存限制（比如树莓派可设cpus: '1'、memory: 1G）。

四、启动部署

1. 启动容器

在docker-compose.yml所在目录执行：

1
docker compose up -d
  • 首次启动会拉取镜像并初始化数据库，耗时约1-5分钟（取决于网络速度）；
  • 查看启动日志（可选）：docker logs -f bitmagnet。

2. 验证部署

  1. 访问WebUI：浏览器输入http://服务器IP:3333（如http://192.168.1.100:3333）；
  2. 检查服务状态：
    • 点击页面右上角的「三角形图标」（服务控制）；
    • 除了第3个「关闭」选项，其余（HTTP Server、Queue Server、DHT Crawler）需为「开启状态」；
    • 若DHT Crawler未开启，执行docker restart bitmagnet重启主服务即可。

五、数据备份与恢复（解决官方方法报错问题）

Bitmagnet的核心数据存储在PostgreSQL数据库中，推荐定期备份，避免索引数据丢失。

方案一：pg_dump备份（推荐，稳定无报错）

1. 备份步骤

  1. 停止Bitmagnet主服务（避免数据写入冲突）：

    1
    docker stop bitmagnet

    ⚠️ 注意：postgres数据库服务保持运行，无需停止。

  2. 创建备份文件（替换路径为你的备份目录）：

    1
    2
    3
    4
    docker exec -t bitmagnet-postgres pg_dump \
      -U postgres \
      -d bitmagnet \
      > /volume1/backup/bitmagnet_$(date +%F).sql
    • 备份文件名自动带上日期（如bitmagnet_2025-11-25.sql）；
    • 备份耗时取决于数据库大小，等待命令执行完成（无输出即为结束）。

  3. 重启Bitmagnet服务：

    1
    docker start bitmagnet

2. 恢复步骤

  1. 停止Bitmagnet主服务：

    1
    docker stop bitmagnet

  2. 清空旧数据并导入备份（替换备份文件路径）：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    # 进入数据库容器，清空现有数据
    docker exec -i bitmagnet-postgres psql -U postgres -d bitmagnet << EOF
    DROP SCHEMA public CASCADE;
    CREATE SCHEMA public;
    GRANT ALL ON SCHEMA public TO postgres;
    \c
    EOF

    # 导入备份文件（替换为你的备份文件路径）
    cat /volume1/backup/bitmagnet_2025-11-25.sql | docker exec -i bitmagnet-postgres psql -U postgres -d bitmagnet

  3. 重启服务完成恢复：

    1
    docker start bitmagnet

方案二：直接复制数据目录（简单粗暴）

适合快速迁移或备份，成功率略低于方案一：

  1. 备份：停止所有服务，复制postgres-data目录（数据库存储目录）到备份位置：

    1
    2
    docker compose down
    cp -r /volume1/docker/bitmagnet/postgres-data /volume1/backup/

  2. 恢复：停止所有服务，删除原有postgres-data目录，将备份目录覆盖回去：

    1
    2
    3
    docker compose down
    rm -rf /volume1/docker/bitmagnet/postgres-data
    cp -r /volume1/backup/postgres-data /volume1/docker/bitmagnet/

  3. 权限设置：恢复后需确保目录权限正确（否则数据库无法启动）：

    1
    chown -R 999:999 /volume1/docker/bitmagnet/postgres-data

    ⚠️ 注意：999是postgres容器的默认用户ID，若修改过容器用户需对应调整。

六、常见问题排查

1. DHT Crawler一直关闭？

  • 解决方案1：重启Bitmagnet服务：docker restart bitmagnet；
  • 解决方案2：给容器赋予高权限，修改docker-compose.yml中bitmagnet服务的deploy部分，增加privileged: true：
    1
    2
    3
    bitmagnet:
      # 其他配置不变
      privileged: true  # 增加此行，赋予高权限
    然后执行docker compose up -d重启服务。

2. WebUI无法访问？

  • 检查端口是否占用：netstat -tulpn | grep 3333，若占用则修改docker-compose.yml中的3333:3333为其他端口（如3335:3333）；
  • 检查防火墙：开放3333、3334端口（TCP+UDP）；
  • 检查容器状态：docker ps，若bitmagnet容器未运行，查看日志：docker logs bitmagnet。

3. 数据库启动失败？

  • 检查目录权限：确保postgres-data目录的所有者是999:999（执行ls -ld /volume1/docker/bitmagnet/postgres-data查看）；
  • 检查存储空间：确保磁盘有足够空间（至少预留1GB）。

七、总结

Bitmagnet是一款功能强大的自托管BT索引器，部署简单且核心功能免费开源。通过它可以摆脱第三方搜索的广告和限制，打造自己的私人资源库。

使用体验上，热门资源的下载速度确实很惊艳，冷门资源则需要耐心等待。建议定期备份数据库，避免长时间爬取的索引数据丢失。如果需要更精准的元数据展示，不妨申请一个TMDB API Key，体验会更好～

如果遇到其他问题，可参考Bitmagnet官方文档或在评论区交流！