lukapeschke/deluge

Deluge Docker镜像文档

1. 镜像概述和主要用途

1.1 Deluge简介

Deluge是一款轻量级、跨平台的BitTorrent客户端，支持多种用户界面（Web UI、桌面GUI、命令行），具备完整的BT协议支持和丰富的扩展功能。其设计注重高效性和可定制性，适合个人和企业级BT下载需求。

1.2 Docker镜像优势

Deluge Docker镜像封装了Deluge运行所需的完整环境，简化部署流程，实现环境隔离，避免依赖冲突。支持快速启停、版本管理和跨平台一致性运行，适用于各类容器化部署场景。

2. 核心功能和特性

2.1 Deluge核心功能

• 完整BT协议支持：兼容BitTorrent、DHT、PEX、Magnet链接、uTorrent协议等。
• 多界面管理：内置Web UI（默认端口8112）、支持远程桌面GUI和命令行控制。
• 高级下载管理：支持队列优先级、带宽限制（全局/单任务）、速度监控。
• 插件扩展：提供丰富插件生态（如标签管理、RSS订阅、统计分析等）。
• 安全特性：支持协议加密、IP过滤、代理设置（SOCKS5/HTTP）。

2.2 Docker镜像特性

• 轻量级基础：基于Alpine或Debian Slim，镜像体积小，资源占用低。
• 配置灵活：通过环境变量、数据卷挂载实现自定义配置。
• 权限控制：支持通过PUID/PGID指定运行用户，避免宿主机权限冲突。
• 持久化存储：配置文件、下载数据可通过数据卷持久化到宿主机。
• 跨平台兼容：支持AMD64、ARM等架构，适配服务器、NAS、嵌入式设备。

3. 使用场景和适用范围

3.1 个人用户

适用于个人电脑、笔记本的BT下载管理，通过Web UI远程控制下载任务，支持自定义带宽策略（如夜间全速下载）。

3.2 家庭媒体中心

配合Plex、Emby等媒体服务器，自动下载影视资源并存储到媒体库，实现家庭影音资源自动化管理。

3.3 服务器环境

企业或个人服务器中批量处理BT下载任务，支持多任务并行、带宽限流，避免占用核心业务资源。

4. 使用方法和配置说明

4.1 安装前提

• 已安装Docker Engine（20.10+）和Docker Compose（可选，推荐v2+）。
• 宿主机开放必要端口（如8112、58846），或配置防火墙允许端口访问。

4.2 基本使用（docker run）

通过docker run快速启动Deluge容器：

bash
docker run -d \
  --name=deluge \
  --restart=unless-stopped \
  -e PUID=1000 \  # 运行用户ID（宿主机用户ID，避免权限问题）
  -e PGID=1000 \  # 运行组ID（宿主机组ID）
  -e TZ=Asia/Shanghai \  # 时区（如Asia/Shanghai、UTC）
  -e DELUGE_LOGLEVEL=info \  # 日志级别（debug/info/warn/error）
  -p 8112:8112 \  # Web UI端口映射
  -p 58846:58846 \  # BT监听TCP端口（可自定义）
  -p 58946:58946/udp \  # BT监听UDP端口（可自定义）
  -v /path/to/deluge/config:/config \  # 配置文件持久化（宿主机路径）
  -v /path/to/deluge/downloads:/downloads \  # 下载目录持久化（宿主机路径）
  lscr.io/linuxserver/deluge:latest  # 镜像名称（以linuxserver版为例）

4.3 Docker Compose配置

创建docker-compose.yml文件，简化部署和管理：

yaml
version: "3.8"

services:
  deluge:
    image: lscr.io/linuxserver/deluge:latest
    container_name: deluge
    restart: unless-stopped
    environment:
      - PUID=1000  # 替换为宿主机用户ID（通过`id`命令查看）
      - PGID=1000  # 替换为宿主机组ID
      - TZ=Asia/Shanghai
      - DELUGE_LOGLEVEL=info
    ports:
      - "8112:8112"       # Web UI
      - "58846:58846"     # BT TCP
      - "58946:58946/udp" # BT UDP
    volumes:
      - /path/to/deluge/config:/config       # 配置目录（需提前创建）
      - /path/to/deluge/downloads:/downloads # 下载目录（需提前创建）
    # 可选：添加网络模式（如host模式，适合复杂网络环境）
    # network_mode: host

启动命令：docker-compose up -d

4.4 环境变量说明

4.5 数据持久化

容器内关键目录需通过宿主机挂载实现持久化，避免容器重建后数据丢失：

• /config：存储Deluge配置文件（core.conf、auth等），需挂载到宿主机目录（如/opt/deluge/config）。
• /downloads：默认下载目录，需挂载到宿主机大容量存储目录（如/mnt/hdd/deluge/downloads）。

权限注意：宿主机挂载目录的权限需与PUID/PGID匹配，可通过chown -R 1000:1000 /path/to/directory调整。

4.6 网络配置

端口映射

• Web UI：默认8112，用于浏览器访问管理界面。
• BT监听端口：TCP默认58846，UDP默认58946（需在路由器或防火墙中开放端口转发，提升BT连接性）。

自定义端口

若需修改BT监听端口，需同步修改：

1. 容器端口映射（如-p 60000:60000）；
2. Deluge配置文件/config/core.conf中的"listen_ports": [60000, 60000]。

4.7 Web UI访问

1. 启动容器后，通过浏览器访问 http://宿主机IP:8112。
2. 首次登录默认密码为 deluge，登录后需立即修改（路径：首选项 > 界面 > 密码）。
3. 功能界面包括：任务列表、添加任务（通过URL/文件）、带宽设置、插件管理等。

4.8 高级配置

4.8.1 修改核心配置

配置文件路径：/config/core.conf（宿主机挂载目录下），可通过文本编辑器修改，常见配置项：

• "download_location": "/downloads"：默认下载路径；
• "max_connections_global": 200：全局最大连接数；
• "max_download_speed": -1：最大下载速度（-1为无限制，单位KB/s）；
• "encryption": { "mode": "required" }：加密模式（required/preferred/disabled）。

修改后需重启容器生效：docker restart deluge。

4.8.2 插件安装

1. 下载插件（.egg格式）至宿主机/path/to/deluge/config/plugins目录。
2. Web UI中进入 首选项 > 插件，勾选插件名称启用。
3. 常用插件：LabelPlus（标签管理）、Stats（统计分析）、RSS（订阅下载）。

5. 常见问题解决

• 权限错误：检查宿主机挂载目录的PUID/PGID是否与容器一致。
• BT下载慢：确认端口转发已配置，或尝试启用UPnP（首选项 > 网络 > 启用UPnP）。
• Web UI无法访问：检查容器是否运行（docker ps）、端口映射是否正确（docker port deluge）。