Docker qBittorrent Web UI登录提示Unauthorized？

Question

Docker qBittorrent Web UI 登录提示 “Unauthorized” 是常见且易被误判的问题。典型原因包括：1）默认凭据变更后未同步更新（如 `admin:adminadmin` 已被强制修改，但用户仍尝试旧密码）；2）qBittorrent 启动时未正确加载配置（`/config/qbittorrent.conf` 权限错误或挂载路径错位，导致重置为默认安全策略）；3）Web UI 认证被意外禁用（`WebUI\Enabled=true` 未启用，或 `WebUI\Username/Password` 为空）；4）反向代理（如 Nginx/Caddy）未透传认证头或错误添加了 `Authorization` 缓存；5）容器重启后凭据未持久化（配置卷未正确挂载，导致每次启动均初始化空配置）。排查需优先检查容器日志（`docker logs `）中是否输出 `Web UI authentication enabled` 及 `Loaded configuration file` 提示，并验证挂载路径（如 `-v ./qbconfig:/config`）权限为 `755` 且属主为 `UID=1001`（qBittorrent 默认用户）。

Answer 1

```html

一、现象层：识别“Unauthorized”错误的表征与误判陷阱

当访问 http://localhost:8080（或反向代理路径）时，浏览器返回 HTTP 401 或空白登录页直接跳转至 /login?redirect=... 并静默失败，即为典型“Unauthorized”表现。需警惕：该提示不等于密码错误，而是 Web UI 认证流程在某环节被中断或绕过。5年+运维者常因惯性输入 admin/adminadmin 而忽略 qBittorrent v4.3.0+ 已强制首次启动时生成随机 salted hash 密码——旧凭据在配置未持久化时根本不存在。

二、日志层：容器启动阶段的关键诊断锚点

执行 docker logs qbittorrent 后，必须定位以下两行：

• [Info] Web UI authentication enabled —— 若缺失，说明认证模块未激活；
• [Info] Loaded configuration file: /config/qbittorrent.conf —— 若显示 Failed to load config 或路径为 /tmp/...，则挂载失效。

注意：qBittorrent 容器默认以 UID=1001 运行，若宿主机 ./qbconfig 目录属主为 root:root 且权限非 755，则进程无法写入配置，强制回退至内存默认值（WebUI\Enabled=false）。

三、配置层：qbittorrent.conf 的五维校验矩阵

配置项	合法值示例	常见错误	验证命令
WebUI\Enabled	true	注释掉或设为 false	grep -A1 "WebUI\\\\Enabled" /path/to/qbittorrent.conf
WebUI\Username	admin	为空或含不可见 Unicode 字符	hexdump -C /path/to/qbittorrent.conf | grep -A5 "Username"

四、挂载层：Docker Volume 的权限-路径-生命周期三重契约

正确挂载必须同时满足：

1. 路径映射精准：使用 -v $(pwd)/qbconfig:/config:z（SELinux）或 :rw（常规），禁止 -v ./qbconfig:/config/qbittorrent.conf 错误映射；
2. 宿主机权限合规：执行 chown -R 1001:1001 ./qbconfig && chmod -R 755 ./qbconfig；
3. 容器内可写验证：进入容器执行 touch /config/test && ls -l /config/test。

五、代理层：Nginx/Caddy 中 Authorization 头的透传陷阱

反向代理配置中，以下错误高发：

# ❌ 危险：缓存 Authorization 头导致凭据复用失效
proxy_cache_key "$scheme$request_method$host$request_uri$http_authorization";

# ✅ 正确：强制透传且禁用缓存认证头
proxy_set_header Authorization $http_authorization;
proxy_pass_request_headers on;
proxy_no_cache $http_authorization;

六、纵深防御：自动化排查流程图（Mermaid）

graph TD A[访问Web UI返回Unauthorized] --> B{docker logs qbittorrent
含'Web UI authentication enabled'?} B -- 否 --> C[检查qbittorrent.conf是否存在
及WebUI\Enabled=true] B -- 是 --> D{含'Loaded configuration file'?} C --> E[修复挂载路径与权限] D -- 否 --> E D -- 是 --> F[检查反向代理Authorization透传] F --> G[验证Nginx/Caddy配置中
proxy_set_header Authorization] E --> H[重启容器并验证日志循环] G --> H

七、进阶实践：使用 docker exec 注入式调试

当配置疑似损坏时，可跳过重启直接验证：

1. 进入容器：docker exec -u 1001 -it qbittorrent /bin/sh；
2. 手动加载配置：qbittorrent-nox --profile=/config --configuration=/config/qbittorrent.conf --no-sandbox；
3. 观察实时日志输出是否出现认证启用标志——此操作可隔离 Docker 启动参数干扰。

八、安全加固：凭据持久化的最小可行方案

推荐采用环境变量注入 + 配置模板初始化模式，规避手动修改 conf 文件风险：

# 使用官方镜像支持的环境变量
-e QB_WEBUI_PORT=8080 \
-e QB_USERNAME=admin \
-e QB_PASSWORD='MyS3cureP@ssw0rd!' \
-v ./qbconfig:/config:rw \

该方式由入口脚本自动渲染 qbittorrent.conf，确保 salted hash 密码写入磁盘且权限受控。

```