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

qBittorrent Web UI 如何配置 Basic 认证HTTP Basic Auth登录【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrentqBittorrent 的 Web UIWebAPI/api/v2/接口默认要求客户端先通过auth/login登录并持有会话 Cookie 才能调用接口。从 v5.1.0 开始WebAPI changelog 2.15.0WebAPI credentials can now be supplied via Basic authWebAPI 还支持直接用 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服务端读取请求的Authorization头用正则^(?scheme\S)\s(?value.)$拆出认证方案scheme和凭据值。如果 scheme 是Basic比较忽略大小写且当前请求没有携带有效会话 Cookie、并且该客户端地址被要求认证就进入 validateBasicAuth把 Base64 编码的值解码得到用户名:密码形式按第一个:拆分冒号之后的全部作为密码调用validateCredentials与 WebUI 配置的用户名/密码比对密码用 PBKDF2 校验校验通过后sessionStart()建立会话响应里会像普通登录一样设置QBT_SID_前缀的会话 Cookie校验失败抛出 401。如果 scheme 是Bearer则按 API key 处理走完全不同的分支此时auth/开头的端点会直接返回 403非 API 路径返回 404。Basic 与 Bearer 二选一不能混用。因此 Basic 认证的适用条件是请求没有已登录的会话 Cookie。已经持有有效会话时Cookie 优先Basic 头不会被处理见 cookieSessionInitialize客户端地址不满足免认证条件来自回环地址且未启用本地访问免认证、或 IP 不在认证子网白名单中的请求才需要认证见 isAuthNeeded。反过来如果某个 IP 被免认证Basic 头只是多余信息不是登录手段用户名或密码错误时返回 401同一 IP 连续失败次数达到 WebUI 的认证失败次数上限后会被临时封禁期间请求返回 403Your 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 认证被接受凭据错误返回 401Unauthorized失败次数过多被封禁返回 403此时只能等待封禁期结束再重试。与 auth/loginCookie 会话路径的对比如果你不需要每个请求都带凭据仍可用原来的登录流程作为替代路径POST /api/v2/auth/login参数为username、password实现见 authcontroller.cpp。凭据错误时该端点返回 401响应中设置QBT_SID_前缀的会话 Cookie后续请求携带该 Cookie 即可无需再带认证头。两条路径用同一套凭据Basic 适合每次请求都自包含认证的场景脚本、curl、第三方集成Cookie 会话适合一次登录多次调用的场景。限制与边界Basic 认证头只对 WebAPI 请求有效。非 API 路径直接打开 Web UI 页面遇到Authorization: Basic时同样走会话逻辑但 API keyBearer请求访问非 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考