统一认证实践(15)Homepage 统计组件与后台服务账号
创建于 2026-11-18
更新于 2026-11-18
科技
homepage
qbittorrent
authentik
adguard
3154 字 · 约 11 分钟

前言

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 创建后台身份

  1. 在 Authentik 的“目录 → 用户”创建服务账号,例如 svc-homepage-adguard。把它加入第八篇已绑定到 AdGuard 应用的专用访问组。
  2. 在“目录 → 令牌和应用密码”创建一个 App password,用户选择刚创建的服务账号。把生成的值交给 Homepage。人员账号照常使用原有的登录流程和 MFA。
  3. 打开 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 让容器读入新值。示例中的直连地址仅用于说明。

yaml
1
2
3
4
5
6
7
8
9
- 网络服务: - 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 容易被误认为接口正常。

bash
1
2
3
curl --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 端口。

yaml
1
2
3
4
5
6
7
8
9
- 下载服务: - 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 小组件版本说明

手机扫码阅读
本文作者: 有次元袋的 tiger
本文链接: https://www.superheaoz.top/2026/11/62515/
版权声明: 本站点所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 我的个人天地!