前言
Navidrome 的网页和音乐客户端使用不同的登录方式。网页希望通过 DoraTiger Auth 直接进入原音乐库,手机上的 Subsonic 客户端则继续使用 Navidrome 账号。将整个域名都重定向到身份中心,会让音乐客户端收到无法处理的网页登录页面。
本次基于现有 Navidrome 0.55.2、Authentik 2026.8.5 和 NPM 配置:网页通过 Forward Auth 检查身份,再向 Navidrome 传递可信用户名;/rest/ 保留原生认证。
一、认证路径
text12网页 → NPM → Authentik 前哨检查 → 可信用户名头 → Navidrome 客户端 → NPM /rest/ → 清除外部身份头 → Navidrome 原生认证
这不是 OIDC 账号关联。Navidrome 从可信代理的请求头获取用户名,找到已有同名用户后继续使用原音乐库和权限。
本文的配置字段适用于 0.55.2:ReverseProxyUserHeader 和 ReverseProxyWhitelist。新版文档已使用 ExtAuth 配置,不能只对照最新版页面修改旧实例。版本源码
网页身份头认证不会同步 Navidrome 密码,用户名相同也不意味着音乐客户端可以输入 Authentik 密码。当前实例没有配置 OIDC 或 LDAP,/rest/ 继续使用 Navidrome 自己的凭据。选择后续方案时需单独验证 Subsonic 客户端支持,不能只用网页免密登录作为统一账号已完成的依据。
二、容器网络与原数据
2.1 原实例转换
TrueNAS 原目录应用不方便加入已有的外部 Docker 网络。本次使用 TrueNAS 的 app.convert_to_custom 将原应用转为自定义应用,保留已有镜像、运行配置和挂载,再加入 NPM 网络。
操作前导出应用配置并备份 Navidrome 数据库。转换后核对 /data 与 /music 的宿主路径、UID/GID、扫描参数和端口,不重新初始化空数据目录。转换为自定义应用后,镜像升级由自定义应用维护,不再沿用原目录应用的升级入口。
2.2 自定义配置示例
下面是已有应用所需网络与环境字段的示例,挂载路径、UID/GID 和其他原参数需从当前实例保留:
yaml12345678910111213141516171819services: navidrome: image: deluan/navidrome:0.55.2 restart: unless-stopped environment: ND_PORT: "30043" ND_REVERSEPROXYUSERHEADER: X-Authentik-Username ND_REVERSEPROXYWHITELIST: "192.0.2.42/32" volumes: - /mnt/pool/apps/navidrome/data:/data - /mnt/pool/media/music:/music:ro networks: npm_backend: aliases: - navidrome-web networks: npm_backend: external: true name: npm_backend
这里的 192.0.2.42/32 只是 NPM 容器来源地址的示例,必须从实际网络检查结果替换。若 NPM 通过 IPv6 连接,还需添加其精确 /128 地址,用逗号分隔。没有 ports,业务只从 NPM 网络进入。
2.3 可信来源
Navidrome 校验的是到达后端的代理来源地址,不能直接填浏览器地址、域名解析地址或整个局域网。
本次避免经过宿主机发布端口:那条路径可能让后端只看到 Docker 网关,信任网关会扩大能够注入身份头的范围。NPM 与 Navidrome 直接连接后,白名单只允许 NPM 当前 IPv4/IPv6 地址。
NPM 重建后要重新核对地址。地址变化应更新精确白名单,不为省事扩大成整个 Docker 网段。外部认证说明
三、Authentik 应用配置
3.1 访问组
在“目录 → 组”创建 truenas-navidrome-users,不启用超级用户权限,加入允许访问音乐库的用户。该组独立于其他应用,不保存或继承 AdGuard 等服务的凭据。
准备接入已有用户时,先确认 Authentik 用户名与 Navidrome 用户名一致。本例以 music-user 表示两侧已经核对的原账号。
3.2 Proxy Provider
创建 Proxy Provider,填写:
| 字段 | 配置 |
|---|---|
| Name | doratiger-truenas-navidrome |
| Mode | Forward auth (single application) |
| External host | https://music.example.com |
| Authentication flow | doratiger-authentication |
| Authorization flow | doratiger-provider-authorization-implicit-consent |
| Invalidation flow | doratiger-provider-invalidation |
| HTTP Basic 转发 | 关闭 |
| Unauthenticated paths | 留空,由 NPM 单独处理客户端路径 |
保存后以 with existing provider 创建应用,名称 TrueNAS · Navidrome,Slug truenas-navidrome,Launch URL 填 https://music.example.com/app/,选择上述 Provider。
在应用的策略/组/用户绑定中添加 truenas-navidrome-users,Order 为 0,启用,Negate 关闭。编辑现有 TrueNAS Proxy Outpost,在列表中加入该应用并保存。
网页使用身份头,不需要把 Navidrome 明文密码交给 Provider。客户端凭据继续由 Navidrome 管理,改密码不会自动同步到其他应用。
四、NPM 路由配置
4.1 HTTPS 站点
创建或编辑 Proxy Host:域名 music.example.com,上游 http://navidrome-web:30043,启用 WebSocket 支持,配置证书并开启 Force SSL。
Advanced 中添加认证路径与登录跳转,authentik-outpost 替换为现有前哨别名:
nginx123456789101112131415161718port_in_redirect off; set $ak_http_host $host; location /outpost.goauthentik.io { proxy_pass http://authentik-outpost:9000; proxy_set_header Host $ak_http_host; proxy_set_header X-Original-URL $scheme://$ak_http_host$request_uri; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $remote_addr; proxy_pass_request_body off; proxy_set_header Content-Length ""; } location @goauthentik_proxy_signin { internal; add_header Set-Cookie $auth_cookie; return 302 /outpost.goauthentik.io/start?rd=$scheme://$ak_http_host$request_uri; }
这些配置按标准 HTTPS 443 编写。Authentik Nginx 模板
4.2 网页根路径
在 Custom Locations 添加 /,上游与主站一致。齿轮中的自定义配置填写:
nginx1234567auth_request /outpost.goauthentik.io/auth/nginx; error_page 401 = @goauthentik_proxy_signin; auth_request_set $auth_cookie $upstream_http_set_cookie; add_header Set-Cookie $auth_cookie; auth_request_set $authentik_username $upstream_http_x_authentik_username; proxy_set_header X-Authentik-Username $authentik_username; proxy_set_header Remote-User "";
用户名从认证子请求结果取得,并覆盖发给后端的同名头。不能把浏览器自行填写的 X-Authentik-Username 直接透传。
4.3 Subsonic 客户端路径
再添加 /rest/ Custom Location,上游仍为 navidrome-web:30043,自定义配置为:
nginx123auth_request off; proxy_set_header X-Authentik-Username ""; proxy_set_header Remote-User "";
它不经过网页登录,但仍由 Navidrome 验证原生凭据。清空身份头后,不能通过伪造头冒充已登录用户。没有在服务端全局关闭认证,也没有把全部 API 都匿名放行。
保存 NPM 配置后检查站点在线状态,确认 /rest/ 比根路径更具体,客户端请求不会落入网页认证分支。
五、账号与客户端
5.1 网页原账号
用无痕窗口访问 /app/,完成 Authentik 登录后应直接回到原用户。核对管理员状态、播放列表及收藏,再播放音乐。本次原账号进入音乐库和播放已确认正常。
源码中的身份头登录会在找不到同名用户时尝试建号;本次已有用户数据库,新身份不应被当作首次初始化管理员。不要把未使用过的空数据库与已有实例混用,开放其他用户前仍需检查账号权限。
5.2 音乐客户端
客户端继续填写 https://music.example.com 和 Navidrome 自己的用户名、密码。OIDC 或 Forward Auth 不会把 Authentik 密码自动写入 Navidrome。
先用正确凭据验证 Subsonic 请求,再用错误凭据或无凭据请求确认拒绝;还要检查仅伪造身份头不能登录。本次原生认证正反检查通过,网页和客户端分别走各自路径。
5.3 撤销权限
移出 Authentik 访问组只影响网页认证入口。用户仍可能持有 Navidrome 密码和已有会话,停用时需要在 Navidrome 同时处理;不能把组成员变化当成所有音乐客户端立即失效。
六、配置问题与解答
6.1 HTTP/2 协议错误
Q:浏览器出现 ERR_HTTP2_PROTOCOL_ERROR,是否需要关闭 HTTP/2?
本次迁移期间代理上游名称尚未可解析,NPM 曾把站点标记离线。容器网络和别名就绪后重新保存代理配置,我先用无痕窗口确认匿名请求会跳到 Authentik,再登录打开原音乐库播放一首歌。恢复访问后,NPM 仍启用 HTTP/2。
6.2 登录后仍出现 Navidrome 密码框
Q:Authentik 已通过,为什么还不能免密进入?
依次核对响应中的用户名、NPM 是否覆盖写入身份头、后端看到的代理来源是否在精确白名单内,以及两侧用户名是否一致。通过前哨只说明入口认证成功,不代表 Navidrome 接受了身份头。
6.3 手机客户端被跳转到登录页
Q:浏览器正常,客户端却报响应格式错误?
检查 /rest/ 是否错误继承网页 Forward Auth。客户端需要原生 API 响应,不能把 HTML 登录页当作 Subsonic 结果。修复路由后仍要保留 Navidrome 凭据校验。
七、备份与升级
保留原应用定义、Navidrome 数据库和 NPM 站点配置。自定义应用升级时检查镜像版本、身份头字段和网络地址,尤其不要直接把新版 ExtAuth 配置复制到 0.55.2。
回退时恢复原应用配置和 NPM 路由,保持原数据库挂载。若恢复宿主端口发布,要重新检查直接访问是否仍需要密码,不保留可伪造身份头的入口。
参考
支付宝
微信