Ubuntu 22.04 安装 qBittorrent 5.3.0 指南

Ubuntu 22.04 安装 qBittorrent 5.3.0 指南：静态二进制（sha256 校验）与发行版仓库双通道实测对比、专用用户与目录规划、systemd 托管、临时密码改密闭环、监听端口与内存验证、升级备份与卸载，及 GitHub 直连/法律声明/随机端口等排障实录。

qBittorrent下载文件服务2026/10/26

Ubuntu 22.04 安装 qBittorrent 5.3.0 指南

‍‍​​‌​> 本文是 qBittorrent 专栏的部署篇。以下流程于 2026-10-26 在一台真实的 Ubuntu 22.04 LTS 服务器上按官方推荐形态（qbittorrent-nox 服务端 + systemd 托管）实测走通：从版本通道选型、静态二进制获取与校验、专用用户与目录规划、systemd 单元编写，到 Web UI 初始化改密、监听端口与内存占用验证全链路可用。文中所有命令回显均为实测原文（凭据类字段已脱敏标注），组件画像与选型对比见《qBittorrent 5.3.0 介绍与选型指南》。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（jammy），x86_64，内核 5.15 系，systemd 249
  • 安装物：qbittorrent-nox v5.3.0（静态链接二进制，内嵌 Qt 6.12.0 + libtorrent 2.1.2.0，来源为社区静态构建项目 userdocs/qbittorrent-nox-static 的 release-5.3.0_v2.1.2 tag，2026-10-26 发布）
  • 部署形态：单机单二进制 + systemd 托管 + 专用系统用户 qb；Web UI 监听 8080，BT 监听 6881（自定义固定，初始为随机端口，见 9.4 节）
  • 目录规划：可执行文件 /usr/local/bin/qbittorrent-nox；数据与下载根目录 /srv/qbittorrent；配置目录 /opt/qbittorrent/.config/qBittorrent/（用户 qb 的 HOME）
  • 实测时间：2026-10-26
  • 软件信息实查：qBittorrent 最新稳定版 v5.3.0（2026-10-20 发布，GitHub Releases 实查）；Ubuntu 22.04 官方仓库 jammy/universe 自带 qbittorrent-nox 4.4.1-2（apt-cache 实查，见第四章版本通道对比）

⚠️ 选型先行：本文以「发行版二进制/官方静态构建」形态部署（服务器无图形界面的标准形态），全程不涉及 Docker/容器。若需要图形桌面客户端，请在桌面环境安装 qbittorrent 包，不在本文范围。

二、前置条件

2.1 系统更新与基础依赖

apt update && apt upgrade -y
apt install -y curl wget bzip2 mktorrent python3 ca-certificates psmisc

实测回显（apt 环节）：

Setting up qbittorrent-nox (4.4.1-2) ...   ← 此行为第三章方案 B 对比实验产物，全新服务器不会出现

⚠️ mktorrent 仅用于本文第 9 章「自建种子验证」环节的复现，非 qbittorrent-nox 运行依赖，可按需省略。

2.2 端口检查

ss -ltn | grep -E ':8080|:6881' || echo "8080/6881 空闲"

实测回显：

8080/6881 空闲

Web UI 端口默认 8080，BT 监听端口首启为随机（详见 9.4 节），如需固定请确保目标端口空闲。

2.3 磁盘规划

下载目录建议独立分区或大容量数据盘。本实测将 /srv/qbittorrent 作为下载与做种数据根目录：

mkdir -p /srv/qbittorrent

三、版本通道选择

qBittorrent 官方 GitHub Release 只提供源码包，不发布 Linux 预编译产物（2026-10-26 实查 Release 资产清单）。Ubuntu 服务器上的可用通道有三条，本文对前两条做了实测：

通道实测版本适用性结论
A. 社区静态构建（userdocs/qbittorrent-nox-static）v5.3.0单文件即用、内嵌 Qt6/libtorrent、无需编译✅ 本文主方案
B. Ubuntu 22.04 官方仓库（jammy/universe）4.4.1-2apt 管理升级省心，但版本落后两个大版本⚠️ 兼容可用，版本滞后
C. 源码编译（官方构建文档）5.3.0需自备 Qt 6.5+ 与 libtorrent 2.0.x 工具链22.04 原生工具链不满足，成本高，本文未采用

方案 A 与 B 的取舍核心是版本时效：v4.4.1 与 v5.3.0 之间 Web API 行为有实质差异（如登录响应码、会话 Cookie 命名、任务暂停/恢复端点语义），对自动化脚本影响很大；且 5.x 修复了大量 libtorrent 2.0 适配问题。追新选 A，求稳且接受旧版可选 B。

3.1 方案 B 实测记录（发行版仓库）

apt install -y qbittorrent-nox
which -a qbittorrent-nox
qbittorrent-nox --version
/usr/bin/qbittorrent-nox --version

实测回显：

Setting up qbittorrent-nox (4.4.1-2) ...
/usr/local/bin/qbittorrent-nox
/usr/bin/qbittorrent-nox
/bin/qbittorrent-nox
qBittorrent v5.3.0
/usr/bin/qbittorrent-nox
qBittorrent v4.4.1

💡 实测发现：若先按方案 A 装了 /usr/local/bin/qbittorrent-nox，再执行 apt install qbittorrent-nox，PATH 优先命中 /usr/local/bin，直接敲 qbittorrent-nox 仍是 5.3.0，容易误判通道来源；请用 which -a 双向核对。对比完成后本机已执行 apt remove -y qbittorrent-nox 清理仓库版，最终保留方案 A 的 5.3.0 单通道：

Removing qbittorrent-nox (4.4.1-2) ...
qBittorrent v5.3.0

四、方案 A：安装 qbittorrent-nox 5.3.0

4.1 下载静态二进制

从静态构建项目的 Release 页获取与 qBittorrent 5.3.0 对应的构建（tag release-5.3.0_v2.1.2 即「qBittorrent 5.3.0 + libtorrent 2.1.2」组合），x86_64 下载文件名 x86_64-qbittorrent-nox：

curl -fL -o /tmp/x86_64-qbittorrent-nox \
  https://github.com/userdocs/qbittorrent-nox-static/releases/download/release-5.3.0_v2.1.2/x86_64-qbittorrent-nox

实测环境直连 GitHub 失败，改走代理后成功（网络受限服务器的常见路径，代理地址换成你自己的）：

curl: (7) Failed to connect to github.com port 443: Connection refused

curl -fL -x http://192.168.1.62:7897 -o /tmp/x86_64-qbittorrent-nox \
  https://github.com/userdocs/qbittorrent-nox-static/releases/download/release-5.3.0_v2.1.2/x86_64-qbittorrent-nox
ls -l /tmp/x86_64-qbittorrent-nox

实测回显：

-  69.1M  100 69.1M    0     0  3359k      0  0:00:21  0:00:21 --:--:-- 6271k
-rw-r--r-- 1 root root 72455104 Oct 26 08:24 /tmp/x86_64-qbittorrent-nox

4.2 完整性校验

官方 Release 页同时发布 .sha256 校验文件，下载后比对：

curl -fsL -x http://192.168.1.62:7897 -o /tmp/x86_64-qbittorrent-nox.sha256 \
  https://github.com/userdocs/qbittorrent-nox-static/releases/download/release-5.3.0_v2.1.2/x86_64-qbittorrent-nox.sha256
sha256sum /tmp/x86_64-qbittorrent-nox

实测回显：

563e695a2b830e62e627e1ae403bcfcc494e444d5cabb5ecc1e09907353d8ed5  /tmp/x86_64-qbittorrent-nox

与官方 .sha256 文件中的摘要一致（实测环境比对通过）。校验不通过时严禁安装。

4.3 安装二进制

install -m 0755 /tmp/x86_64-qbittorrent-nox /usr/local/bin/qbittorrent-nox
qbittorrent-nox --version

实测回显：

qBittorrent v5.3.0

五、专用用户与目录规划

禁止 root 直接运行。创建无登录权限的专用系统用户 qb（HOME 定为 /opt/qbittorrent，配置文件将落在 /opt/qbittorrent/.config/qBittorrent/）：

useradd -r -m -d /opt/qbittorrent -s /usr/sbin/nologin qb
mkdir -p /srv/qbittorrent/downloads /srv/qbittorrent/torrents /srv/qbittorrent/watch
chown -R qb:qb /srv/qbittorrent /opt/qbittorrent

目录用途说明：

  • /srv/qbittorrent/downloads：默认下载保存路径；
  • /srv/qbittorrent/torrents：种子文件归档（自建/待投递）；
  • /srv/qbittorrent/watch：监控目录（可选，Web UI 中配置后自动扫描 .torrent 入列）。

六、systemd 托管

6.1 编写单元文件

cat > /etc/systemd/system/qbittorrent-nox.service <<'EOF'
[Unit]
Description=qBittorrent-nox service (headless BitTorrent client)
Documentation=https://github.com/qbittorrent/qBittorrent/wiki
After=network-online.target
Wants=network-online.target

[Service]
Type=exec
User=qb
Group=qb
UMask=0022
ExecStart=/usr/local/bin/qbittorrent-nox --confirm-legal-notice --webui-port=8080
Restart=on-failure
RestartSec=5
RuntimeDirectory=qBittorrent

[Install]
WantedBy=multi-user.target
EOF

参数说明：

  • --confirm-legal-notice：跳过首启的法律声明交互（否则 systemd 启动会因等待确认而卡住）；
  • --webui-port=8080：显式固定 Web UI 端口（不写则用默认 8080，写明便于审计；注意命令行参数优先级高于配置文件）；
  • Type=exec + Restart=on-failure：进程异常退出时自动拉起，间隔 5 秒。

6.2 启动与自启

systemctl daemon-reload
systemctl enable qbittorrent-nox
systemctl start qbittorrent-nox

实测回显：

Synchronizing state of qbittorrent-nox.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable qbittorrent-nox
Created symlink /etc/systemd/system/multi-user.target.wants/qbittorrent-nox.service → /etc/systemd/system/qbittorrent-nox.service.

6.3 获取首次登录临时密码

v5.x 的安全策略：Web UI 管理员密码未设置时，每次启动生成会话级随机临时密码，仅打印在控制台/journal 中，服务重启即失效：

journalctl -u qbittorrent-nox --no-pager -n 20 | tail -14

实测回显（临时密码每次启动随机变化，以你自己的为准）：

Oct 26 08:26:53 qbserver qbittorrent-nox[2793]: ******** Information ********
Oct 26 08:26:53 qbserver qbittorrent-nox[2793]: To control qBittorrent, access the WebUI at: http://localhost:8080
Oct 26 08:26:53 qbserver qbittorrent-nox[2793]: The WebUI administrator username is: admin
Oct 26 08:26:53 qbserver qbittorrent-nox[2793]: The WebUI administrator password was not set. A temporary password is provided for this session: HHdmmhb7w
Oct 26 08:26:53 qbserver qbittorrent-nox[2793]: You should set your own password in program preferences.

⚠️ 旧版 4.x 默认账号密码 admin/adminadmin 的做法在 5.x 已废弃，不存在固定默认密码；临时密码登录后必须在 Web UI 中立即设置正式密码，否则每次重启都要重新捞 journal。

七、Web UI 初始化

7.1 登录

浏览器访问 http://<服务器IP>:8080，输入用户名 admin 与 6.3 节取到的临时密码登录。登录后 qBittorrent 会提示设置正式密码。

7.2 设置正式密码

进入「工具 → 选项 → Web UI → 验证」，将用户名与密码改为正式值（本实测设为 admin / q1w2e3r4）。也可通过 Web API 直接写入（命令行场景）：

SID=$(curl -s -i -X POST http://localhost:8080/api/v2/auth/login \
  --data "username=admin&password=HHdmmhb7w" | grep -i "set-cookie" | grep -oP "QBT_SID_8080=\K[^;]+")
curl -s -b "QBT_SID_8080=$SID" -X POST http://localhost:8080/api/v2/app/setPreferences \
  --data-urlencode "json={\"web_ui_username\":\"admin\",\"web_ui_password\":\"q1w2e3r4\"}" -w "HTTP:%{http_code}\n"

实测回显：

HTTP:200

7.3 验证新密码生效

curl -s -X POST http://localhost:8080/api/v2/auth/login --data "username=admin&password=HHdmmhb7w" -w "|HTTP:%{http_code}\n"
curl -s -X POST http://localhost:8080/api/v2/auth/login --data "username=admin&password=q1w2e3r4" -w "|HTTP:%{http_code}\n"

实测回显：

|HTTP:401
|HTTP:204

💡 实测沉淀（v5.3.0 Web API 行为，旧文档常写错）：登录成功返回 HTTP 204（无 Ok. 正文），失败返回 HTTP 401（无 Fails. 正文）；会话 Cookie 名为 QBT_SID_<WebUI端口>（如 QBT_SID_8080），不是旧版的 SID，用 curl -b 回带会话时必须带全名。

八、安装验证

systemctl status qbittorrent-nox --no-pager -n 0
ss -ltn | grep -E '8080|6881'
curl -s -X POST http://localhost:8080/api/v2/auth/login --data "username=admin&password=q1w2e3r4" -c /tmp/qb.cookie -o /dev/null
curl -s -b /tmp/qb.cookie http://localhost:8080/api/v2/app/version
curl -s -b /tmp/qb.cookie http://localhost:8080/api/v2/app/buildInfo
ps -eo user,pid,rss,args | grep [q]bittorrent-nox

实测回显：

● qbittorrent-nox.service - qBittorrent-nox service (headless BitTorrent client)
     Loaded: loaded (/etc/systemd/system/qbittorrent-nox.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-26 08:35:34 UTC; 1min 19s ago
   Main PID: 3938 (qbittorrent-nox)
      Tasks: 10 (limit: 3172)
     Memory: 5.8M
        CPU: 95ms
        └─3938 /usr/local/bin/qbittorrent-nox --confirm-legal-notice --webui-port=8080
LISTEN 0      30        127.0.0.1%lo:6881        0.0.0.0:*
LISTEN 0      30     10.89.61.2%eth0:6881        0.0.0.0:*
LISTEN 0      50                   *:8080          *:*
v5.3.0
{"bitness":64,"boost":"1.92.0","libtorrent":"2.1.2.0","openssl":"4.1.0","platform":"linux","qt":"6.12.0","zlib":"1.3.2"}
qb  3938  29296 /usr/local/bin/qbittorrent-nox --confirm-legal-notice --webui-port=8080

指标解读：

  • Web UI 监听 *:8080（IPv4/IPv6），BT 端口绑定在各网卡地址上（首启随机端口，固定方法见 9.4 节）；
  • 进程 RSS 约 29 MB（挂 4 个任务、其中一个 512 MB 做种中），systemd cgroup 口径空闲态约 5.8 MB，资源占用符合轻量预期；
  • buildInfo 确认内嵌组件版本：Qt 6.12.0、libtorrent 2.1.2.0、boost 1.92.0。

下载/做种/限速/RSS 等功能级闭环验证不在本文展开，见命令篇的 Web API 实操矩阵。

九、常见问题（排障实录）

9.1 下载二进制时 GitHub 直连失败

现象：curl: (7) Failed to connect to github.com port 443: Connection refused。原因：服务器出网受限。处理：为 curl 追加代理参数 -x http://<代理地址>:<端口> 后重试（实测走代理 21 秒完成 69.1 MB 下载）。

9.2 服务启动卡死在法律声明

现象：不写 --confirm-legal-notice 时，systemd 下服务反复重启或超时，journal 中出现：

*** Legal Notice ***
qBittorrent is a file sharing program. When you run a torrent, its data will be made available to others by means of upload. Any content you share is your sole responsibility.
If you have read the legal notice, you can use command line option `--confirm-legal-notice` to suppress this message.

处理：在 ExecStart 中补上 --confirm-legal-notice 后 systemctl daemon-reload && systemctl restart qbittorrent-nox。该声明只在配置目录首次初始化时出现一次，但单元文件中长期保留该参数可避免换配置目录（迁移/多实例）时复发。

9.3 Web UI 登录密码不知道

v5.x 无固定默认密码。处理路径：journalctl -u qbittorrent-nox | grep "temporary password" 取当前会话的临时密码登录后立即改密；若已设置过密码但遗忘，官方口径为删除配置文件重建（会丢失任务列表，建议先按第 10.2 节迁移备份）。

9.4 BT 监听端口是随机数

现象：首启后 app/preferences 读到 listen_port: 18617 之类随机值（v5.x 行为，不再是固定 6881）。处理：停止服务后改配置文件，再启动：

systemctl stop qbittorrent-nox
sed -i 's|^Session\\Port=.*|Session\\Port=6881|' /opt/qbittorrent/.config/qBittorrent/qBittorrent.conf
systemctl start qbittorrent-nox

实测验证（改后 API 读回）：

listen_port: 6881

⚠️ 配置文件必须在服务停止状态下修改：qBittorrent 退出时会把内存态参数整体写回 qBittorrent.conf，运行中直接改文件会被覆盖（实测复现：运行中把 Session\Port 改成 6999，systemctl restart 后又回到 18617）。完整参数清单见配置篇。

9.5 防火墙放行

Web UI 端口（8080）与 BT 端口（6881 TCP+UDP，DHT/uTP 依赖 UDP）都需放行：

ufw allow 8080/tcp
ufw allow 6881/tcp && ufw allow 6881/udp

公网暴露 Web UI 前务必完成：改默认 admin 口令、启用 HTTPS、配置 IP 白名单（配置篇安全参数章节有逐项实测）。

十、升级与卸载

10.1 升级

静态二进制升级=替换文件+重启，任务状态保留：

curl -fL -x http://192.168.1.62:7897 -o /tmp/x86_64-qbittorrent-nox <新版本下载地址>
sha256sum /tmp/x86_64-qbittorrent-nox    # 与 Release 页 .sha256 比对
systemctl stop qbittorrent-nox
install -m 0755 /tmp/x86_64-qbittorrent-nox /usr/local/bin/qbittorrent-nox
systemctl start qbittorrent-nox
qbittorrent-nox --version

⚠️ 大版本升级（4.x→5.x、5.x 内跨次版本）前先备份配置目录（10.2 节）；5.x 首启会自动迁移配置并打印迁移日志，任务列表由 BT_backup 中的 fastresume 文件恢复。

10.2 配置与任务备份（迁移必读）

tar -C / -czf qb-backup-$(date +%F).tar.gz \
  /opt/qbittorrent/.config/qBittorrent/qBittorrent.conf \
  /opt/qbittorrent/.local/share/qBittorrent/BT_backup

实测（迁移/备份关键文件清单，BT_backup 目录内容）：

38dc2094ce26bf6a45b1eec4a048509770a829ba.fastresume
38dc2094ce26bf6a45b1eec4a048509770a829ba.torrent
3b25b3c279ef5402dc721d330d5c80de54ebdbba.fastresume
3b25b3c279ef5402dc721d330d5c80de54ebdbba.torrent
c631f87db27a8ec45e4cbc00791a03f592665aad.fastresume
c631f87db27a8ec45e4cbc00791a03f592665aad.torrent
queue

每个任务对应同名 <infohash>.torrent（种子元数据）+ <infohash>.fastresume（任务状态：保存路径/进度位图/分类标签等），queue 记录任务顺序。迁移到新机时恢复这两个目录并保持下载文件原路径一致，启动后任务直接续传。

10.3 卸载

systemctl disable --now qbittorrent-nox
rm /etc/systemd/system/qbittorrent-nox.service
systemctl daemon-reload
rm /usr/local/bin/qbittorrent-nox
rm -rf /opt/qbittorrent /srv/qbittorrent   # 数据按需保留

若装过仓库版（方案 B），另执行 apt remove -y qbittorrent-nox && apt autoremove -y。

十一、参考链接

  1. 官方 Wiki「Running qBittorrent without X server (WebUI)」：https://github.com/qbittorrent/qBittorrent/wiki/Running-qBittorrent-without-X-server-(WebUI)
  2. 官方 GitHub Releases：https://github.com/qbittorrent/qBittorrent/releases
  3. 静态构建项目 Releases（本篇二进制来源）：https://github.com/userdocs/qbittorrent-nox-static/releases
  4. Web API 官方规范：https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1+)
  5. 本专栏选型篇：《qBittorrent 5.3.0 介绍与选型指南》（https://www.quzuo.net/document/9druyGP9Dj7s）
  6. 本专栏配置篇：《qBittorrent 5.3.0 配置参数详解》（https://www.quzuo.net/document/QpclLf30QgMV）
  7. 本专栏命令篇：《qBittorrent 5.3.0 常用 CLI 命令详解》（https://www.quzuo.net/document/JpDuhoZ8VvfR）