qBittorrent-nox 命令行参考指南完整选项、环境变量机制与无头部署实践【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent本文基于 qBittorrent 仓库自带的英文 man 页 doc/en/qbittorrent-nox.1.md系统梳理qbittorrent-nox无头版 BitTorrent 客户端的启动语法、全部命令行选项与环境变量机制并结合 src/app/cmdoptions.cpp、src/app/main.cpp、src/app/application.cpp 等源码讲清每个参数在程序内部的解析路径、取值校验规则与优先级关系帮助你在服务器、容器或脚本自动化场景中正确配置和运行 qBittorrent-nox。一、qBittorrent-nox 是什么qbittorrent-nox是一个用 C / Qt 编写的命令行 BitTorrent 客户端底层使用 Arvid Norberg 的libtorrent-rasterbar库man 页 DESCRIPTION 一节。它的定位是提供与主流图形客户端接近的功能UPnP 端口转发 / NAT-PMP、Vuze 兼容的加密、mainline FAST 扩展、uTorrent 兼容的 PeX支持 Unicode同时以轻量的无头headless形态运行。与 GUI 版最大的区别在于qBittorrent-nox 的设计意图是通过其功能完整的 Web UI 来操控Web UI 默认地址为http://localhost:8080默认管理员用户名为admin。这一点可以从源码直接确认在构建时定义了DISABLE_GUI的分支里src/app/application.cpp 会执行一段专门的输出逻辑若配置中没有设置 WebUI 密码则生成一个 9 位临时随机密码Utils::Password::generate(9)并用 PBKDF2 派生后注入 WebUI 会话将访问 URL 与「临时密码仅本次会话有效、请到程序偏好设置中设置自己的密码」的提示一起打印到控制台若 WebUI 被禁用则提示「The WebUI is disabled! To enable the WebUI, edit the config file manually.」。也就是说man 页中「未设置密码时每次启动生成临时随机密码并打印到控制台」的说法其实现正是上述代码路径。二、启动语法SYNOPSISman 页给出的启动形式共三种qbittorrent-nox [options] [(filename | url)...] qbittorrent-nox --help qbittorrent-nox --version--help显示帮助并退出--version显示版本号并退出(filename | url)...表示把用户传入的.torrent文件路径或磁力链接等 URL 直接加入下载队列。从源码看参数解析入口是 src/app/cmdoptions.cpp 中的parseCommandLine()它以--开头且不以.torrent结尾或形如单字符短选项-x的 token 视为「已知或未知参数」其余 token 一律当作 torrent 源。对于 torrent 源解析时还会做一次存在性判断——路径存在的文件会被规范化为绝对路径cmdoptions.cpp#L544-L550字符串 URL 则原样保留。遇到无法识别的参数时程序记录unknownParameter随后在 src/app/main.cpp 中抛出CommandLineParameterError打印「Bad command line」及「Run application with -h option」的提示后以失败退出。三、全局选项逐项解析以下选项完整继承自 man 页 OPTIONS 一节并补充了源码层面确认的取值规则。选项作用源码确认的细节-h/--help显示帮助并退出在 main.cpp#L211-L215 中优先级最高先于其他一切标志处理-v/--version显示程序版本并退出仅在非 Windows 或DISABLE_GUI构建中启用cmdoptions.cpp#L309-L311--confirm-legal-notice确认法律声明将设置项LegalNotice/Accepted置为 truemain.cpp#L255-L273--webui-portport更改 WebUI 端口必须是 1–65535 的整数否则报错退出见下文--torrenting-portport更改 BitTorrent 监听端口同上1–65535-d/--daemon以守护进程后台模式运行仅无头构建非 Windows可用实现见下文--profiledir将配置文件存储到指定目录解析时会被转换为绝对路径cmdoptions.cpp#L497-L500--configurationname将配置存储到qBittorrent_name目录中用于同机多实例隔离见下文--relative-fastresume改写 libtorrent fastresume 文件使文件路径相对于 profile 目录与 portable 模式互斥警告见下文(filename \| url)...下载用户传入的 torrent位置参数可多个3.1 端口选项的校验规则--webui-port与--torrenting-port都通过IntOption::value()先做整数解析非整数直接抛出「Parameter --webui-port must follow syntax --webui-port 」随后再做范围校验范围外抛出「--webui-port must specify a valid port (1 to 65535)」 cmdoptions.cpp#L470-L485。两个端口在启动流程中的作用方式不同这一点从 src/app/application.cpp#L377-L384 可以看清--webui-port通过Preferences::instance()-setWebUIPort()覆盖偏好设置中的 WebUI 端口--torrenting-port则直接写入设置项BitTorrent/Session/Port。也就是说命令行端口参数优先级高于配置文件中的既有值。3.2 守护进程模式-d / --daemon--daemon只在定义了DISABLE_GUI且非 Windows 的构建下存在cmdoptions.cpp#L313-L317GUI 版本对应的是另一个选项--no-splash。其实际实现在 src/app/main.cpp#L289-L315先销毁当前Application实例调用 POSIX 的::daemon(1, 0)完成双叉后台化成功则重新创建Application对象继续运行若此时发现又出现了别的 qBittorrent 实例记录 CRITICAL 日志并退出::daemon失败则打印strerror(errno)并退出。另外main.cpp#L234-L247 明确禁止在已有实例运行时使用-d会抛出「You cannot use -d (or --daemon): qBittorrent is already running.」。守护模式还有一个与法律声明相关的细节交互判断isInteractive在shouldDaemonize为真时被强制置为 falsemain.cpp#L266-L269。源码注释写得很直白——daemon 模式下用户无法交互因此法律声明只能靠--confirm-legal-notice选项来确认。首次以 daemon 方式部署时建议先以交互方式确认一遍或直接带上--confirm-legal-notice启动。3.3 配置目录--profile、--configuration 与 portable 模式--profile与--configuration共同决定配置文件的存放位置底层由 src/base/profile.cpp 与 src/base/profile_p.cpp 实现未指定--profile且可执行文件所在目录下存在profile/目录时自动启用portable 模式profile 目录即./profileapplication.cpp#L329-L331指定--profiledir时走CustomProfile配置、快进数据等全部落在该目录--configurationname会在标准配置路径后追加_后缀的目录名见 profile_p.cpp#L49 中的_ configurationName从而得到qBittorrent_name风格的隔离配置便于同一机器上并行运行多个实例。--relative-fastresume的语义在 application.cpp#L332-L333 体现它作为convertPathsToProfileRelative传给Profile::initInstance()与 portable 模式自动启用相对路径的行为共用同一开关而 portable 模式又自动隐含该行为因此同时指定时程序会打印 WARNING「Redundant command line flag detected: --relative-fastresume. Portable mode implies relative fastresume.」application.cpp#L363-L368。这个选项的典型用途是把 fastresume 数据库里的文件路径改写成相对 profile 的路径方便整体迁移/备份 profile 目录。四、添加新 torrent 时的选项man 页「Options when adding new torrents」一节列出的选项如下它们作用于本次启动时通过位置参数传入的 torrent选项作用取值规则源码确认--save-pathpathtorrent 保存路径字符串写入AddTorrentParams::savePath--add-stoppedtrue\|false以运行还是停止状态添加三态选项省略值时默认true即添加为停止状态未传该选项则为「未指定」不覆盖既有默认--seed-mode种子模式布尔标志出现即为 true--categoryname指定分类分类不存在则自动创建字符串--sequential按顺序下载文件布尔标志--first-and-last优先下载首尾分块布尔标志--skip-dialogtrue\|false添加时是否弹出「Add New Torrent」对话框三态选项省略值默认true这些选项在 cmdoptions.h#L44-L70 中被聚合为QBtCommandLineParameters结构体的一部分BitTorrent::AddTorrentParams addTorrentParams与std::optionalbool skipDialog。其中--add-stopped和--skip-dialog使用的是专门的三态解析器TriStateBoolOptioncmdoptions.cpp#L242-L306只写--add-stopped不带value时返回构造时给定的默认值两者默认都是true带true/false大小写不敏感时返回对应布尔值出现其他取值则抛出「Parameter --add-stopped must follow syntax --add-stoppedtrue|false」错误。值得说明的是在纯无头nox场景下并不存在 GUI 对话框--skip-dialog更多影响的是同进程转发与 GUI 构建的一致性脚本中通常无需关心它。4.1 单实例转发参数如何送达已运行的实例qBittorrent 只允许一个主实例运行。若已有实例存在第二次启动并不会真正创建新进程来处理 torrent而是把参数序列化后转发给主实例——这条链路完整可查main.cpp#L231-L253app-hasAnotherInstance()为真时调用app-callMainInstance()后直接返回成功application.cpp#L193-L230 的serializeParams()把保存路径、停止状态、分类等参数编码为savePath...、addStopped1形式的 token用|连接并前置在 torrent 源列表之前主实例端processMessage()application.cpp#L550-L581经parseParams()还原这些 token 为QBtCommandLineParameters若此时各组件尚未就绪则先放入m_paramsQueue待初始化完成后再统一processParams()。因此「向已在后台运行的 nox 实例传--save-path等添加参数」是完全有效的这也是 nox 常见的脚本化用法qbittorrent-nox /path/to/file.torrent --save-path/data/downloads即使主实例早已以-d方式启动。五、环境变量机制ENVIRONMENTman 页 ENVIRONMENT 一节规定了通用规则任何名为parameter-name的选项都可以通过环境变量QBT_PARAMETER_NAME大写、-替换为_提供值布尔标志类选项将变量设为1或TRUE即可且命令行参数优先于环境变量。文档示例为修改 WebUI 端口QBT_WEBUI_PORT8081 qbittorrent-nox源码中这套机制的实现非常紧凑变量名生成cmdoptions.cpp#L97-L101 的envVarName()正是QBT_ 大写名称 -→_初始取值QBtCommandLineParameters的构造函数 cmdoptions.cpp#L424-L444 以QProcessEnvironment逐个选项读取环境变量作为默认值命令行覆盖parseCommandLine()先以QProcessEnvironment::systemEnvironment()构造结果再遍历命令行逐项覆盖因此优先级天然就是「命令行 环境变量」布尔解析isTrue()接受1以及大小写不敏感的truecmdoptions.cpp#L62-L65整数选项的环境变量若无法解析会打印调试信息并回退默认值而非崩溃cmdoptions.cpp#L220-L234字符串值会做一层引号剥离Utils::String::unquote因此带空格的路径可以写作QBT_SAVE_PATH/My Dir。按此规则nox 常用选项对应的环境变量包括QBT_WEBUI_PORT、QBT_TORRENTING_PORT、QBT_PROFILE、QBT_CONFIGURATION、QBT_CONFIRM_LEGAL_NOTICE、QBT_RELATIVE_FASTRESUME、QBT_DAEMON值1/TRUE、QBT_SAVE_PATH、QBT_ADD_STOPPEDtrue|false、QBT_CATEGORY等。环境变量方式特别适合 systemd unit 的Environment段落或容器镜像的ENV指令避免把可变的命令行拼进服务定义。六、典型运行场景速查结合前文的 man 页与源码事实给出几种可直接复制的启动方式1. 快速查看帮助与版本qbittorrent-nox --help qbittorrent-nox --version2. 前台启动并添加 torrent首次确认法律声明qbittorrent-nox /path/to/file.torrent # 交互确认法律声明后控制台会打印 WebUI 地址默认 http://localhost:8080 # 以及临时管理员密码admin / 9 位随机密码仅当会话有效3. 指定 WebUI 端口与保存路径添加后立即停止qbittorrent-nox --webui-port9090 /path/to/file.torrent --save-path/data/downloads --add-stopped4. 后台守护 独立配置目录服务化部署qbittorrent-nox --confirm-legal-notice --profile/var/lib/qbittorrent -d # 之后任意时刻添加 torrent参数会被转发给主实例 qbittorrent-nox /path/to/file.torrent --save-path/data/downloads --categorymedia5. 通过环境变量配置systemd / 容器友好QBT_WEBUI_PORT8081 QBT_PROFILE/var/lib/qbittorrent qbittorrent-nox -d6. portable 模式在可执行文件所在目录放置profile/目录后启动不带--profile即可自动启用便携配置与相对 fastresume 路径application.cpp#L363-L368 会记录「Running in portable mode. Auto detected profile folder at: ...」。七、问题报告与作者信息man 页 BUGS 与 AUTHORS 两节说明发现 bug 应提交到 qBittorrent 官方 bug 跟踪系统bugs.qbittorrent.orgqBittorrent 项目由 Christophe Dumezchrisqbittorrent.org发起并持续维护本仓库源码头部注释中也保留了各文件的版权署名与 GPLv2 许可证声明。八、小结qBittorrent-nox 的对外操作面是「命令行选项 环境变量 Web UI」三者命令行负责启动与一次性添加参数环境变量负责常驻服务化配置Web UI 负责日常管理与下载控制选项解析集中在 src/app/cmdoptions.cpp端口有 1–65535 的硬性校验--add-stopped/--skip-dialog为三态选项未知参数会导致启动失败并提示使用-h单实例模型下后续启动的参数含保存路径、分类等会被序列化转发给主实例因此脚本可以放心地「追加式」添加 torrentdaemon 模式、--profile/--configuration、portable 目录自动检测构成了无头部署时的配置隔离与迁移方案均可在 src/app/application.cpp 与 src/base/profile.cpp 中逐一核对实现。【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考