qbittorrent提供四种安装方式：系统包管理器（快速稳定）、docker（环境隔离）、源码编译（最新功能）、静态构建（跨平台即用），并需完成webui基础配置。
一、使用系统包管理器安装
对于大多数主流发行版，系统仓库中已预置qbittorrent或qbittorrent-nox，可直接通过包管理器安装，无需编译，适合快速部署和基础使用。该方法依赖系统维护的软件版本，通常较稳定但可能滞后于上游发布。
1、在基于Debian/Ubuntu的系统上执行：sudo apt update && sudo apt install -y qbittorrent-nox
2、在CentOS 7或RHEL 7系统上执行：sudo yum install -y epel-release && sudo yum install -y qbittorrent-nox
3、在CentOS 8/RHEL 8或Fedora系统上执行：sudo dnf install -y qbittorrent-nox
4、安装完成后，首次运行需接受法律声明：输入qbittorrent-nox，按提示键入y确认。
二、使用Docker容器部署
Docker方式能规避系统依赖冲突，实现版本隔离与环境一致性，特别适用于NAS或云服务器等需要长期稳定运行的场景。官方linuxserver镜像提供多版本支持，推荐指定语义化标签以避免兼容性问题。
1、拉取指定版本镜像（例如4.6.7）：docker pull linuxserver/qbittorrent:4.6.7
2、创建并运行容器，映射配置与下载目录：docker run -d --name qbittorrent -p 18080:8080 -p 6881:6881 -p 6881:6881/udp -v /path/to/config:/config -v /path/to/downloads:/downloads -e PUID=1000 -e PGID=1000 -e WEBUI_PORT=8080 --restart unless-stopped linuxserver/qbittorrent:4.6.7
3、确保宿主机防火墙放行端口：sudo ufw allow 18080（Ubuntu）或sudo firewall-cmd --permanent --add-port=18080/tcp（CentOS/RHEL）
4、通过浏览器访问http://服务器IP:18080，初始用户名为admin，密码为adminadmin。
三、从源码编译安装（含Qt6依赖处理）
当系统仓库版本过旧或需启用最新功能（如WebUI增强、RSS改进）时，必须采用源码编译。此方式对构建环境要求严格，尤其需正确配置Qt6路径及libtorrent-rasterbar开发库，否则cmake阶段将失败。
1、安装基础构建工具与依赖：sudo apt install -y build-essential git cmake pkg-config libtool automake libssl-dev zlib1g-dev libgeoip-dev
2、安装libtorrent-rasterbar开发包：sudo apt install -y libtorrent-rasterbar-dev
3、下载并安装Qt6在线安装器（至少6.5版本），以root权限运行并安装至/opt/Qt；安装完成后创建软链接：sudo ln -s '/opt/Qt/6.10.2/gcc_64/lib/libQt6Core.so.6.10.2' /usr/lib/x86_64-linux-gnu/libQt6Core.so.6
4、在/etc/profile中添加环境变量：export CMAKE_PREFIX_PATH="$CMAKE_PREFIX_PATH:/opt/Qt/6.10.2/gcc_64/lib/cmake/Qt6:/opt/Qt/6.10.2/gcc_64/lib"与export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/opt/Qt/6.10.2/gcc_64/lib"，随后执行source /etc/profile
5、解压qbittorrent源码后，在源码根目录执行：cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build
四、使用静态构建脚本安装qbittorrent-nox-static
静态构建生成的qbittorrent-nox二进制文件内嵌全部依赖库，不依赖宿主系统动态库版本，具备跨发行版即装即用能力，适合Alpine、老旧系统或容器精简镜像等受限环境。
1、安装基础工具：sudo apt-get update && sudo apt-get install -y build-essential git curl bash（Debian/Ubuntu）或sudo apk add --no-cache build-base git curl bash（Alpine）
2、克隆项目仓库：git clone https://gitcode.com/gh_mirrors/qb/qbittorrent-nox-static && cd qbittorrent-nox-static
3、赋予脚本执行权限：chmod +x qbittorrent-nox-static.sh
4、执行全量构建：./qbittorrent-nox-static.sh all
5、构建成功后，生成的二进制文件位于./build/qbittorrent-nox，可直接复制至任意Linux系统运行。
五、基础配置与WebUI初始化设置
首次启动qbittorrent-nox或容器后，WebUI处于默认状态，需完成基本安全与路径配置方可投入实际使用。所有设置均通过浏览器访问WebUI界面完成，无需命令行干预。
1、登录WebUI后，进入Tools → Options → Downloads，设置Default Save Path为实际挂载的下载目录（如/downloads）
2、在Tools → Options → Connection中，将Listening Port设为与Docker端口映射或防火墙开放一致的值（如6881）
3、在Tools → Options → Web UI中，勾选Enable Web UI，修改默认用户名密码，并关闭Use HTTPS for Web UI（除非已配置反向代理SSL）
4、在Tools → Options → Speed中，根据网络带宽设定上传/下载限速，避免影响其他服务
5、保存设置后，重启qbittorrent服务或容器使配置生效。
