linuxserver/qbittorrent

镜像概述和主要用途

linuxserver/qbittorrent 是由 LinuxServer.io 团队维护的 Docker 镜像，封装了开源 BitTorrent 客户端 qBittorrent。qBittorrent 旨在提供 µTorrent 的开源替代方案，基于 Qt 工具包和 libtorrent-rasterbar 库开发，支持 Web UI 管理，适合个人或家庭网络环境中进行 BT 下载管理。

LinuxServer.io 团队的容器具有以下特点：

• 定期及时的应用更新
• 简单的用户权限映射（PGID、PUID）
• 带有 s6 overlay 的自定义基础镜像
• 每周基础 OS 更新，跨生态系统共享通用层以减少空间占用、 downtime 和带宽
• 定期安全更新

核心功能和特性

支持的架构

该镜像利用 Docker manifest 实现多平台支持，拉取 lscr.io/linuxserver/qbittorrent:latest 即可自动获取对应架构的镜像，也可通过标签指定特定架构：

版本标签

应用设置

Web UI 地址为 <your-ip>:8080，启动时会为 admin 用户生成临时密码并输出到容器日志。必须在 Web UI 的设置部分修改用户名/密码，否则每次容器启动都会生成新密码。

对于非常旧的（3.x）内核，可能会遇到 此问题，可通过 此方法 解决。

WEBUI_PORT 变量

由于 CSRF 和端口映射问题，若需修改 Web UI 端口，需同时更改 -p 参数的两侧端口并设置 WEBUI_PORT 变量为新端口。例如，要将端口改为 8090，需设置 -p 8090:8090 和 -e WEBUI_PORT=8090。

使用方法和配置说明

Docker Compose（推荐）

yaml
---
version: "2.1"
services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - WEBUI_PORT=8080
    volumes:
      - /path/to/appdata/config:/config
      - /path/to/downloads:/downloads
    ports:
      - 8080:8080
      - 6881:6881
      - 6881:6881/udp
    restart: unless-stopped

Docker CLI

bash
docker run -d \
  --name=qbittorrent \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e WEBUI_PORT=8080 \
  -p 8080:8080 \
  -p 6881:6881 \
  -p 6881:6881/udp \
  -v /path/to/appdata/config:/config \
  -v /path/to/downloads:/downloads \
  --restart unless-stopped \
  lscr.io/linuxserver/qbittorrent:latest

参数说明

环境变量文件（Docker Secrets）

可通过特殊前缀 FILE__ 从文件中设置环境变量，例如：

bash
-e FILE__MYVAR=/run/secrets/mysecretvariable

这会将环境变量 MYVAR 的值设置为 /run/secrets/mysecretvariable 文件的内容。

应用运行的 Umask 设置

所有镜像支持通过可选参数 -e UMASK=022 覆盖容器内服务的默认 umask 设置。注意 umask 是从权限中减去而非添加，详情请参考 umask 说明。

用户/组标识符

使用卷（-v 标志）时，主机 OS 与容器之间可能出现权限问题。通过指定用户 PUID 和组 PGID 可避免此问题。确保主机上的卷目录归指定用户所有，权限问题将迎刃而解。

使用 id your_user 命令可获取当前用户的 PUID 和 PGID：

bash
id your_user

示例输出：

text
uid=1000(your_user) gid=1000(your_user) groups=1000(your_user)

Docker Mods

我们发布了多种 Docker Mods 以增强容器功能。上述动态徽章链接包含此镜像的专用 Mods 和适用于所有 LinuxServer.io 镜像的通用 Mods。

支持信息

容器运行时 Shell 访问

bash
docker exec -it qbittorrent /bin/bash

实时监控容器日志

bash
docker logs -f qbittorrent

容器版本号

bash
docker inspect -f '{{ index .Config.Labels "build_version" }}' qbittorrent

镜像版本号

bash
docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/qbittorrent:latest

更新信息

大多数镜像为静态版本，需更新镜像并重新创建容器以更新应用（nextcloud、plex 等少数例外）。不建议在容器内更新应用，请参考 应用设置 部分确认是否适用。

通过 Docker Compose 更新

• 更新镜像：

  • 所有镜像：

    bash
    docker-compose pull
    

  • 单个镜像：

    bash
    docker-compose pull qbittorrent
    

• 更新容器：

  • 所有容器：

    bash
    docker-compose up -d
    

  • 单个容器：

    bash
    docker-compose up -d qbittorrent
    

• 清理旧镜像：

  bash
  docker image prune
  

通过 Docker Run 更新

• 更新镜像：

  bash
  docker pull lscr.io/linuxserver/qbittorrent:latest
  

• 停止运行中的容器：

  bash
  docker stop qbittorrent
  

• 删除容器：

  bash
  docker rm qbittorrent
  

• 使用相同参数重新创建容器（若卷映射正确，/config 目录和设置将保留）

• 清理旧镜像：

  bash
  docker image prune
  

通过 Watchtower 自动更新（仅在忘记原始参数时使用）

bash
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --run-once qbittorrent

警告：不建议将 Watchtower 用作现有 Docker 容器的自动更新解决方案。长期来看，强烈推荐使用 Docker Compose。

镜像更新通知 - Diun (Docker Image Update Notifier)

提示：推荐使用 Diun 获取更新通知。不建议或支持使用其他自动更新容器的工具。

本地构建

如需为开发或自定义修改本地构建镜像：

bash
git clone [***]
cd docker-qbittorrent
docker build \
  --no-cache \
  --pull \
  -t lscr.io/linuxserver/qbittorrent:latest .

可使用 multiarch/qemu-user-static 在 x86_64 硬件上构建 ARM 变体：

bash
docker run --rm --privileged multiarch/qemu-user-static:register --reset

注册后，使用 -f Dockerfile.aarch64 指定架构的 Dockerfile。

版本历史

• 07.10.23: - 从 linuxserver 仓库 安装 unrar。
• 10.08.23: - 将 unrar 升级至 6.2.10。
• 17.06.23: - 弃用 armhf 架构，详见 [***]
• 10.06.23: - 将 unrar 升级至 6.2.8。
• 23.02.23: - 添加 qt6-qtbase-sqlite 以支持 SQLite 数据库用于续传文件。
• 29.11.22: - 为 qbittorrent-cli 添加 openssl1.1-compat。
• 31.10.22: - 添加 libtorrentv1 分支。
• 31.08.22: - 重新基于 Alpine Edge 以跟踪最新版本。
• 12.08.22: - 将 unrar 升级至 6.1.7。
• 16.06.22: - 从 Edge 重新基于 Alpine 3.16。
• 25.05.22: - 从上游仓库获取 qbitorrent-cli。
• 02.03.22: - 添加 unrar、7zip 和 qbitorrent-cli。
• 01.03.22: - 添加 python 以支持搜索插件。
• 23.02.22: - 重新基于 Alpine Edge，从 Alpine 仓库安装。
• 19.02.22: - 在构建阶段添加 jq。
• 07.01.22: - 重新基于 Alpine，从源码构建。
• 06.01.22: - 弃用 unstable 分支。
• 10.02.21: - 重新基于 focal。
• 20.01.21: - 用基础镜像中的 UMASK 替代 UMASK_SET，详见上文说明。
• 12.11.20: - 停止在启动时创建 /config/data 目录。
• 03.04.20: - 修复添加搜索引擎插件的问题。
• 02.08.19: - 添加 qbitorrent-cli 用于处理脚本。
• 23.03.19: - 切换到新基础镜像，迁移至 arm32v7 标签。
• 14.01.19: - 重新基于 Ubuntu，添加多架构和流水线逻辑。
• 25.09.18: - 使用构建阶段类型构建，将 qbitorrent 升级至 4.1.3。
• 14.08.18: - 重新基于 Alpine 3.8，将 libtorrent 升级至 1.1.9，qbittorrent 升级至 4.1.2。
• 08.06.18: - 将 qbittorrent 升级至 4.1.1。
• 26.04.18: - 将 libtorrent 升级至 1.1.7。
• 02.03.18: - 将 qbittorrent 升级至 4.0.4，libtorrent 升级至 1.1.6。
• 02.01.18: - 弃用 cpu_core 例程，因缺乏扩展性。
• 19.12.17: - 更新至 v4.0.3。
• 09.02.17: - 重新基于 Alpine 3.7。
• 01.12.17: - 更新至 v4.0.2。
• 27.11.17: - 更新至 v4 并使用 cpu_core 例程加速构建。
• 16.09.17: - 升级至 3.3.16，添加 WEBUI_PORT 变量并在 README 中添加说明。
• 01.08.17: - 初始发布。
• 12.02.18: - 初始发布。