前言
AdGuard Home 接入 Authentik 以后,我在 Homepage 上点卡片,登录一次就能进管理页。把统计组件的地址也换成同一个域名,卡片上的查询次数却读不出来。旁边的 qBittorrent 仍在刷新下载速度,我才发现,点卡片时用的是浏览器里的会话,读统计的却是 Homepage 后端。
我保留了原来的导航布局,只调整每个组件从哪里取数、用哪个账号取数。本文沿用已有的 NPM 和 Proxy Outpost,域名、端口及服务账号均为示例。
一、卡片里的两个地址
| 配置项 | 谁发起请求 | 在哪里验证 |
|---|---|---|
href |
点击卡片的浏览器 | 打开 HTTPS 域名,无痕窗口应先进入 Authentik |
widget.url |
Homepage 后端 | 从 Homepage 所在容器的网络访问服务 API,检查是否返回统计数据 |
description |
读卡片的人 | 记录部署位置及直连入口,反向代理维护时仍能找到服务 |
浏览器登录后的 Cookie 留在浏览器。Homepage 后端轮询统计接口时,需要组件能发送的凭据。对 AdGuard,我让后台也经过域名;对 qBittorrent,保留内网 API 地址。两张卡片的点击入口都可以继续使用 HTTPS。
二、AdGuard Home 通过服务账号读取统计
2.1 创建后台身份
- 在 Authentik 的“目录 → 用户”创建服务账号,例如
svc-homepage-adguard。把它加入第八篇已绑定到 AdGuard 应用的专用访问组。 - 在“目录 → 令牌和应用密码”创建一个 App password,用户选择刚创建的服务账号。把生成的值交给 Homepage。人员账号照常使用原有的登录流程和 MFA。
- 打开 AdGuard 的 Proxy Provider,检查接收入站认证头的设置。NPM 的认证子请求需要把客户端的
Authorization送到 Outpost。原先为 AdGuard 配好的 Send HTTP-Basic Authentication 及后台用户名、密码属性键继续使用。
这里有两组凭据。Homepage 把服务账号和应用密码发给 Outpost;Outpost 根据应用访问策略放行后,NPM 再把前哨给出的后台 Basic 凭据传给 AdGuard。撤销 Homepage 的应用密码即可单独停掉这张卡片的认证。服务账号实际能操作什么,仍由后端凭据决定;卡片只显示统计,并不会让一个后台管理员账号自动获得只读限制。Authentik 认证头说明
2.2 配置服务卡片
下面是 Homepage 配置目录中 services.yaml 的一组条目。若用 TrueNAS 应用,打开 Homepage 的编辑页,在容器环境变量中新增 HOMEPAGE_VAR_ADGUARD_USER 和 HOMEPAGE_VAR_ADGUARD_APP_PASSWORD,分别填服务账号名和上一步生成的应用密码,保存并等待应用就绪。Compose 部署则在 Homepage 服务的 environment 或 env_file 中提供这两个变量,再运行 docker compose up -d 让容器读入新值。示例中的直连地址仅用于说明。
yaml123456789- 网络服务: - AdGuard Home: href: https://dns.example.org/ description: "DNS 管理 · 直连 http://192.0.2.7:3000" widget: type: adguard url: https://dns.example.org username: "{{HOMEPAGE_VAR_ADGUARD_USER}}" password: "{{HOMEPAGE_VAR_ADGUARD_APP_PASSWORD}}"
先从能解析该域名的环境验证代理链。下面的命令会提示输入应用密码,只输出状态码和内容类型。测试时不要加自动跟随跳转的 -L,否则登录页最终返回的 200 容易被误认为接口正常。
bash123curl --user svc-homepage-adguard --silent --show-error \ --output /dev/null --write-out '%{http_code} %{content_type}\n' \ https://dns.example.org/control/stats
预期为 HTTP 200 和 JSON。再刷新 Homepage,观察查询总数或拦截统计是否随实际查询变化。返回 302 时检查认证头有没有进入前哨;返回 401 时分别核对服务账号的应用密码和代理转发的后台凭据。Outpost 能否复用会话取决于客户端是否保留 Cookie,不能按“前哨部署在本地”推算每次轮询都能省去与身份服务的通信。AdGuard Home 小组件
三、qBittorrent 保留内网 API
qBittorrent 的网页同样可以经 Authentik 直接进入。后台组件则按 qBittorrent Web API 的约定取数;浏览器已经通过前哨,不会替 Homepage 建立下载器会话。本次保留如下配置结构,在受控内网中让 Homepage 直接访问 WebUI 的 API 端口。
yaml123456789- 下载服务: - qBittorrent: href: https://downloads.example.org/ description: "下载器 · 直连 http://192.0.2.20:8080" widget: type: qbittorrent url: http://192.0.2.20:8080 username: "{{HOMEPAGE_VAR_QBIT_USER}}" password: "{{HOMEPAGE_VAR_QBIT_PASSWORD}}"
用同样的方法给 Homepage 容器添加 HOMEPAGE_VAR_QBIT_USER 和 HOMEPAGE_VAR_QBIT_PASSWORD,填下载器自己的用户名和密码。已有“下载服务”分组时,只在原分组中添加卡片。先确认容器可以访问该地址,再看小组件能否取得有效列表或传输统计。数字持续变化只说明当前取数成功;要判断究竟是凭据生效还是来源命中了免认证范围,还要核对 qBittorrent 的认证设置。这次没有为了卡片增加免认证网段。其他下载客户端单独改用 API Key,也不要求 Homepage 采用同一种方式。qBittorrent 小组件
四、providers 与统计排错
Homepage 的 settings.yaml → providers 可集中保存受支持组件的共享配置。例如官方天气组件允许在 settings.yaml 定义 providers.openweathermap,在组件里用 provider: openweathermap 引用。这个键负责配置复用;它不会替每一种服务组件交换 Authentik 令牌,也不提供秘密加密。AdGuard 和 qBittorrent 的示例直接使用组件文档列出的字段,变量值留在容器部署配置中。Homepage Providers
我现在按返回内容排查卡片:域名返回 HTML 登录页,先查前哨;应用返回 JSON 错误,查组件使用的接口和版本;网页一直正常而统计停了,先检查 widget.url 与服务账号。Jellyfin 就遇到过一次 401,实际配置需要补上 version: 2,原来的 API Key 仍然可用。最后用无痕窗口验点击入口,再回 Homepage 验统计,两项分别通过才算完成。Jellyfin 小组件版本说明
支付宝
微信