Homepage 集成 Nginx Proxy Manager代理主机状态 Widget 配置与 API 认证原理【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage导读Nginx Proxy ManagerNPM是自托管场景中常用的反向代理管理面板本指南讲解如何在 Homepage 中通过 Nginx Proxy Manager 的官方 REST API 实时统计已启用enabled、已禁用disabled与全部total代理主机的数量。文章将围绕 docs/widgets/services/nginx-proxy-manager.md 展开完整覆盖 Widget 配置、登录凭证要求、可展示字段并结合仓库源码深入讲解其 Token 认证与缓存机制、403 重试逻辑以及前端统计的底层实现帮助你真正理解这一 Widget 的运行原理并完成落地配置。一、Widget 概述Nginx Proxy Manager Widget 是 Homepage 内置的服务型 Widget之一它的作用不是管理 NPM 的代理规则而是把 NPM 中代理主机的启用状态以三个统计数字的形式呈现在首页Enabled已启用、Disabled已禁用与Total总数。该 Widget 定义在 widgets/npm/widget.jsconst widget { api: {url}/api/{endpoint}, proxyHandler: npmProxyHandler, mappings: { hosts: { endpoint: nginx/proxy-hosts, }, }, };其中api模板声明了 Widget 的数据来源是 NPM 的 REST API路径为{url}/api/{endpoint}mappings.hosts把hosts这个端点映射到 NPM 的nginx/proxy-hosts接口该接口返回所有代理主机及其enabled状态proxyHandler指定了自定义代理处理器 widgets/npm/proxy.js负责完成 NPM 的登录认证与数据转发——这是该 Widget 与普通直接读 API类 Widget 最大的区别。从源码结构看NPM 的 API 需要先换取 Token 才能访问因此 Homepage 为它专门实现了代理层而不是让浏览器直接请求 NPM 接口。二、配置文件与字段说明1. 基础配置在原文档 docs/widgets/services/nginx-proxy-manager.md 中给出了最小可用的配置示例widget: type: npm url: http://npm.host.or.ip username: admin_username password: admin_password需要特别注意的是这里的username与password必须填写访问 NPM Web 管理界面时所用的管理员账号密码而不是 NPM 内部某个应用的用户名。原文档原文明确要求Login with the same admin username and password used to access the web UI.使用与访问 Web UI 相同的管理员用户名和密码登录。这个凭证只会在服务端代理层使用不会暴露给浏览器端。2. 允许展示的字段原文档声明 Widget 允许的字段为[enabled, disabled, total]这三个字段的语义与本地化文案在 public/locales/en/common.json 中定义npm: { enabled: Enabled, disabled: Disabled, total: Total }enabled处于启用状态的代理主机数量disabled处于禁用状态的代理主机数量total代理主机的总数量等于 enabled 与 disabled 之和。3. 在 services 组中的完整用法Widget 通常作为某个服务条目的widget子项出现可参考 Homepage 自带的配置骨架 skeleton/services.yaml 的写法将其组合为- Nginx Proxy Manager: icon: nginx-proxy-manager href: http://npm.host.or.ip widget: type: npm url: http://npm.host.or.ip username: admin_username password: admin_password当配置正确时首页该服务卡片下会显示三个统计块Enabled / Disabled / Total。三、前端展示逻辑统计数字是怎么算出来的前端组件 widgets/npm/component.jsx 使用useWidgetAPI请求hosts端点然后在浏览器端对返回的代理主机数组进行统计const { data: infoData, error: infoError } useWidgetAPI(widget, hosts); const enabled infoData.filter((c) !!c.enabled).length; const disabled infoData.filter((c) !c.enabled).length; const total infoData.length;这里有两个值得注意的实现细节通过!!c.enabled进行布尔化判断因此返回数据中true、1这类真值都会被计入 enabled相应地false、0乃至缺失该字段的条目都会被计入 disabled。数据加载完成前三个统计块会先渲染占位符Block labelnpm.enabled等若请求失败则渲染错误 UIwidget.api_error与具体错误信息。以上行为均被 widgets/npm/component.test.jsx 中的三个测试用例覆盖加载占位渲染、错误渲染、以及[{enabled:true},{enabled:false},{enabled:1},{enabled:0},{enabled:true}]得出 enabled3、disabled2、total5 的统计断言。四、代理层实现原理Token 认证、缓存与 403 重试这是 Nginx Proxy Manager Widget 与大多数其他 Widget 的核心差异所在。NPM 的 REST API 不直接接受用户名密码而是要求先调用登录接口换取 Bearer Token再携带 Token 访问业务接口。整个流程实现在 widgets/npm/proxy.js 中。1. 登录换取 Token代理层首先构造登录地址{url}/api/tokens并以 JSON 形式提交凭证const loginUrl ${widget.url}/api/tokens; const authResponse await httpProxy(loginUrl, { method: POST, body: JSON.stringify({ identity: username, secret: password }), headers: { Content-Type: application/json, }, });对应到 NPM 的 API 语义请求体中的identity即管理员用户名secret即管理员密码登录成功后响应中会携带token与expiresToken 过期时间。2. Token 缓存过期前 5 分钟主动失效为了避免每次刷新首页都重新登录代理层使用memory-cache将 Token 缓存在服务端内存中缓存键为npmProxyHandler__token.{service}TTL 设置为 Token 过期时间再提前 5 分钟const expiration new Date(data.expires) - Date.now(); cache.put(${tokenCacheKey}.${service}, data.token, expiration - 5 * 60 * 1000); // expiration -5 minutes即即使 NPM 返回的 Token 还有效Homepage 也会在到期前 5 分钟主动作废缓存提前换取新 Token避免使用濒临过期的凭证发起请求。3. 携带 Bearer Token 请求业务接口登录完成后代理层向{url}/api/nginx/proxy-hosts发起 GET 请求并在请求头携带Authorization: Bearer {token}[status, , data] await httpProxy(url, { method: GET, headers: { Content-Type: application/json, Authorization: Bearer ${token}, }, });4. 403 自动重试清除缓存并重新登录考虑到缓存中的 Token 可能已失效代理层对 403 响应做了容错收到 403 后删除缓存中的 Token重新调用登录接口换取新 Token并用新 Token 重试业务请求if (status 403) { cache.del(${tokenCacheKey}.${service}); [status, token] await login(loginUrl, widget.username, widget.password, service); ... [status, , data] await httpProxy(url, { ... headers: { Authorization: Bearer ${token} } ... }); }如果重试后仍非 200则把 NPM 返回的状态码与响应体原样透传给前端若代理层自身参数不完整缺少group/service则返回 400 Invalid proxy service type若 Widget 类型不支持 API 调用则返回 403 Service does not support API calls。以上两条核心行为缺失 Token 时先登录再携带 Bearer Token 请求、403 时清缓存重新登录后重试分别被 widgets/npm/proxy.test.js 中的两个测试用例精确验证包括断言登录地址为http://npm/api/tokens、请求头为Bearer t1以及 403 后重试时第二次登录、第三次携带新 Token 的完整调用序列。五、安全与配置注意事项凭证仅存在于服务端NPM 的管理员账号密码只被代理层proxy.js使用前端组件与浏览器始终只与 Homepage 自身的 API 交互不会直接接触 NPM 的登录凭证。Token 缓存在内存中Token 以npmProxyHandler__token.{service}为键缓存在 Node.js 进程内存中进程重启即清空属于无持久化、无跨实例共享的轻量设计如果你的 Homepage 以多副本方式部署各副本会各自独立缓存 Token。配置校验Widget 配置结构type、url、username、password等字段由 widgets/npm/widget.test.js 通过通用的expectWidgetConfigShape断言校验保证配置项齐全且形状合法。URL 规范url应填写 NPM 实例可被 Homepage 服务端访问的地址http://npm.host.or.ip无需携带/api后缀代理层会自动拼接/api/tokens与/api/nginx/proxy-hosts。六、常见问题排查现象可能原因排查方向Widget 显示错误且提示api_error用户名/密码错误登录接口返回 401/403确认username/password与 NPM Web UI 登录凭证一致数据长时间不刷新Token 缓存未过期等待缓存自然过期或重启 Homepage 进程正常情况下过期前 5 分钟会自动刷新返回 403 但配置正确NPM Token 失效代理层会自动清缓存重登录重试若持续失败检查 NPM 侧账号状态三个统计块一直显示占位符前端请求未返回数据检查 Homepage 服务端能否访问{url}/api/nginx/proxy-hosts七、小结Nginx Proxy Manager Widget 是 Homepage 服务型 Widget中一个典型的需认证 API实现范例。通过本文可以掌握三件事第一最小配置仅需type: npm、url、username、password四项凭证复用 NPM Web UI 的管理员账号第二Widget 展示的三个统计字段enabled、disabled、total由前端对nginx/proxy-hosts返回数据实时统计得出第三其底层通过{url}/api/tokens换取 Token、内存缓存提前 5 分钟失效与 403 自动重试机制保证首页展示始终平滑稳定。如需在 k8s、Docker 等不同部署形态下使用可进一步参考 安装文档 与 服务配置说明。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考