Qbittorrent 部署方式

上周末我花了一整晚折腾家里的 NUC，把一直裸奔在 Windows 上的 Qbittorrent 迁移到了 Docker 环境。说实话，刚开始我是抗拒的。Windows 版图标拖进去就能用，多省心？直到有一次我重启电脑，下载任务全断，还得重新手动添加磁链，那一刻我下定决心：必须得搞个 7x24 小时无人值守的方案。

这里不扯什么“架构优雅”的大道理，直接分享我踩坑后的两套可行路径：原生 Linux 安装和 Docker 部署。如果你是软路由或者树莓派用户，前者可能更直观；但如果你像我一样有个闲置的 x86 主机，Docker 绝对是更干净的选择。

为什么我放弃了 Windows 和原生 Linux

先说 Windows。虽然 QBT 在 Win 上很稳定，但它是个后台服务，关机就等于停服。我试过设置开机自启，结果每次系统更新后路径都会变，经常连不上。

后来我想着直接装个轻量级的 Debian 系统，结果翻车了。原生安装需要手动配置 qbittorrent.conf，还要处理 systemd 服务单元。一旦我想升级版本，就得重新编译或者替换二进制文件，还得注意依赖库版本冲突。

有一次升级后 Web UI 直接白屏，查了半天日志才发现是前端静态文件权限问题。这种“黑盒”维护，对不想整天修机器的人来说太折磨了。

最后我选了 Docker。理由很简单：环境隔离，配置即代码，坏了直接删了重建，五分钟搞定。

Docker 部署的实操细节

我用的镜像是 linuxserver/qbittorrent，比官方镜像更新快，而且自带了一些便利性脚本。

1. 数据卷挂载（最关键的一步）

很多新手直接 docker run 起来就完了，结果发现下载完的文件找不到，因为容器内部的文件系统重启后清空了。你必须显式挂载两个目录：

/config：存放配置、会话状态。
/downloads：实际存放文件的地方。

docker run -d \
  --name qbittorrent \
  --restart unless-stopped \
  -p 8080:8080 \
  -e PUID=1000 -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -v /opt/qbittorrent/config:/config \
  -v /mnt/data/downloads:/downloads \
  ghcr.io/linuxserver/qbittorrent:latest

注意 -e PUID=1000 和 -e PGID=1000。 这是我踩得最大的坑。如果不指定用户组，容器内以 root 身份创建的文件，宿主机的普通用户读不了，挂载点权限混乱。根据你的宿主机实际用户 UID/GID 改这两个值。

2. 网络模式的选择

默认 bridge 模式够用，但如果你希望 QBT 获取到内网 IP 以便局域网访问，或者需要更复杂的端口映射，可以考虑 host 模式。我推荐先用 bridge，因为隔离性好，不容易跟宿主机其他服务端口冲突。

自动化与防“假死”

部署完只是第一步，真正的痛点在于“僵尸任务”。QBT 偶尔会卡在一个种子上了，进度条不动，也不报错。

我加了一个简单的健康检查脚本，每 10 分钟跑一次。如果 QBT 的 Web API 响应超时，就自动 docker restart qbittorrent。

#!/bin/bash
# healthcheck.sh
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:8080/api/v2/app/getVersion" --user "admin:yourpassword")
if [ "$RESPONSE" != "200" ]; then
    echo "QBT unresponsive, restarting..."
    docker restart qbittorrent
fi

把这个脚本扔到 Docker 的 HEALTHCHECK 指令里，或者直接在宿主机跑个 cron 任务。这比你自己记得去检查强多了。

避坑指南：关于 Web UI 密码

Docker 起容器后，第一次登录 Web UI（默认 http://IP:8080）需要初始密码。很多人会在这里卡住，因为默认密码是“空”，但界面却提示“请输入密码”。

解决方法：

去 /config 目录下找到 qbittorrent.conf。
编辑 [WebUI] 部分，把 Password 改掉。
重启容器。
或者在启动容器时通过环境变量注入初始密码（看镜像文档支持与否）。

千万别把默认的空密码用在生产环境，除非你的局域网有防火墙严格管控。

总结

Qbittorrent 本身是个成熟的软件，部署方式无非就是“怎么让它永远不关机”和“怎么方便管理文件”。

图省事：树莓派/软路由直接装包，配好开机自启。
图干净：用 Docker，挂载好卷，设好用户权限，加个健康检查。

我现在每天早上起来，看着 NUC 的硬盘灯闪烁，打开网页就能管理几百个种子的状态，这才是工具该有的样子。别被技术细节吓住，先把容器跑起来，再慢慢调优配置。

Qbittorrent 迁移 Docker：解决 Windows 关机断连与原生 Linux 权限难题的实操记录