企业官网建设流程全解析

qBittorrent Web UI 如何配置 Basic 认证（HTTP Basic Auth）登录？

【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent

qBittorrent 的 Web UI（WebAPI，/api/v2/接口）默认要求客户端先通过auth/login登录并持有会话 Cookie 才能调用接口。从 v5.1.0 开始（WebAPI changelog 2.15.0：WebAPI credentials can now be supplied via Basic auth），WebAPI 还支持直接用 HTTP Basic 认证携带凭据，省去"先登录拿 Cookie 再带 Cookie 请求"的两步流程——这对脚本、curl 和第三方集成的调用方很实用。本文说明 Basic 认证的工作机制、需要什么条件，以及如何用 curl 验证配置是否生效。

前提：v5.1.0 及以上

只有 qBittorrent 5.1.0 或更新版本才支持通过 Basic 认证提供 WebAPI 凭据。低版本即使发送Authorization: Basic头也不会被接受，只能走 Cookie 会话登录。

另外注意一个常见误解：Basic 认证不需要"开启"或额外配置。Web UI 的用户名和密码（偏好设置 WebUI 页面里的用户名/密码，存储于WebUI/Username、WebUI/Password_PBKDF2，用户名默认值为admin）就是 Basic 认证要用的凭据，和auth/login使用的是同一套校验逻辑（见 webapplication.cpp 中的认证分支）。

Basic 认证的工作机制

请求处理入口在 webapplication.cpp 的 processRequest：

1. 服务端读取请求的Authorization头，用正则^(?<scheme>\S+)\s+(?<value>.+)$拆出认证方案（scheme）和凭据值。
2. 如果 scheme 是Basic（比较忽略大小写），且当前请求没有携带有效会话 Cookie、并且该客户端地址被要求认证，就进入 validateBasicAuth：
   • 把 Base64 编码的值解码，得到用户名:密码形式（按第一个:拆分，冒号之后的全部作为密码）；
   • 调用validateCredentials与 WebUI 配置的用户名/密码比对（密码用 PBKDF2 校验）；
   • 校验通过后sessionStart()建立会话，响应里会像普通登录一样设置QBT_SID_前缀的会话 Cookie；校验失败抛出 401。
3. 如果 scheme 是Bearer，则按 API key 处理，走完全不同的分支（此时auth/开头的端点会直接返回 403，非 API 路径返回 404）。Basic 与 Bearer 二选一，不能混用。

因此 Basic 认证的适用条件是：

• 请求没有已登录的会话 Cookie。已经持有有效会话时，Cookie 优先，Basic 头不会被处理（见 cookieSessionInitialize）；
• 客户端地址不满足"免认证"条件：来自回环地址且未启用"本地访问免认证"、或 IP 不在认证子网白名单中的请求才需要认证（见 isAuthNeeded）。反过来，如果某个 IP 被免认证，Basic 头只是多余信息，不是登录手段；
• 用户名或密码错误时返回 401；同一 IP 连续失败次数达到 WebUI 的"认证失败次数上限"后会被临时封禁，期间请求返回 403（Your IP address has been banned after too many failed authentication attempts.，见 validateCredentials）。

用 curl 验证 Basic 认证是否生效

下面是最短验证路径。user:password替换为你的 WebUI 用户名和密码，127.0.0.1:8080替换为实际的 WebUI 地址（WebUI/Port默认 8080）。curl -u会按标准生成Authorization: Basic base64(user:password)头，与 qBittorrent 期望的格式一致：

curl -u user:password -s http://127.0.0.1:8080/api/v2/app/version

也可以显式手写请求头，方便观察具体发出去的内容（<...>处替换为你的实际值）：

curl -s http://127.0.0.1:8080/api/v2/app/version \ -H "Authorization: Basic base64(user:password)"

判断结果：

• 凭据正确：接口正常返回（例如app/version返回版本信息），说明 Basic 认证被接受；
• 凭据错误：返回 401（Unauthorized）；
• 失败次数过多被封禁：返回 403，此时只能等待封禁期结束再重试。

与 auth/login（Cookie 会话）路径的对比

如果你不需要每个请求都带凭据，仍可用原来的登录流程作为替代路径：

1. POST /api/v2/auth/login，参数为username、password（实现见 authcontroller.cpp）。凭据错误时该端点返回 401；
2. 响应中设置QBT_SID_前缀的会话 Cookie；
3. 后续请求携带该 Cookie 即可，无需再带认证头。

两条路径用同一套凭据：Basic 适合每次请求都自包含认证的场景（脚本、curl、第三方集成）；Cookie 会话适合一次登录多次调用的场景。

限制与边界

• Basic 认证头只对 WebAPI 请求有效。非 API 路径（直接打开 Web UI 页面）遇到Authorization: Basic时同样走会话逻辑，但 API key（Bearer）请求访问非 API 路径会返回 404；
• 凭据中的密码部分取第一个:之后的全部内容，因此含:的密码也能正确解析；
• 请求若同时带有效会话 Cookie 和 Basic 头，以 Cookie 为准；
• 启用 CSRF 保护时，跨站请求会被拒绝（401）；使用 API key 的请求会跳过 CSRF 检查。这一行为同样约束带 Basic 头的浏览器跨站请求；
• Basic 认证把明文凭据（Base64 可逆）放进每个请求头，仅建议用于本机或 HTTPS 环境，不要暴露在不加密的公共网络上。

配置完成后，用app/version能正常返回、错误凭据得到 401，即说明 Basic 认证路径已按预期工作。

【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent