在 Homepage 中集成 Stash 媒体库统计 Widget：配置、字段与 GraphQL 数据链路解析

在 Homepage 中集成 Stash 媒体库统计 Widget配置、字段与 GraphQL 数据链路解析【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepageStash 是一款自托管的媒体管理器Homepage 为其提供了专用服务 Widget可直接在首页展示场景Scenes、图片Images、演员Performers、播放时长等核心统计数据。本文以 Stash Widget 配置文档 为主体结合仓库中的 Widget 定义源码、展示组件 与测试用例完整讲解如何获取 API Key、编写配置、理解全部可用字段并深入剖析数据从配置到 Stash GraphQL API 再到前端渲染的完整链路。前置准备在 Stash 中获取 API Key在配置 Widget 之前需要先从 Stash 实例中获取 API Key打开 Stash 的Settings设置 Security安全 API Key页面复制生成的 Key 值。注意仅当你的 Stash 实例启用了登录凭据时才必须提供 API Key若实例未开启登录认证可省略key字段。该 Key 在 Homepage 请求 Stash 时以查询参数的形式携带。从 widget.js 的 API 模板可以看到完整调用约定api: {url}/{endpoint}?apikey{key},即 Homepage 会用 Widget 配置中的url、key以及具体端点Endpoint拼接出形如http://stash.host.or.ip/graphql?apikeystashapikey的请求地址。因此请勿在 Key 中混入多余空格或换行否则请求会被 Stash 拒绝。最小可运行配置将以下片段放入 Homepage 的services.yaml或 Docker 环境下的 docker.yaml对应服务条目中widget: type: stash url: http://stash.host.or.ip key: stashapikey fields: [scenes, images] # optional - default fields shown各参数说明参数必填说明type是固定为stash用于匹配仓库中注册的 Widget 定义url是Stash 实例的地址如http://192.168.1.100:9999需可从运行 Homepage 的主机访问key否Stash 的 API Key仅当实例开启登录认证时必需fields否要展示的统计字段列表不填时使用默认字段[scenes, images]全部可用字段与底层数据映射原文档声明允许的字段完整列表为[scenes, scenesPlayed, playCount, playDuration, sceneSize, sceneDuration, images, imageSize, galleries, performers, studios, movies, tags, oCount]这 14 个字段并非 Stash API 的原始返回键而是 Homepage 前端展示层的标签Label。从 component.jsx 可以看出每个字段通过Block组件绑定到 GraphQLstats查询结果的具体属性Widget 字段界面文案en对应 stats 数据键格式化方式scenesScenesscene_count数值numberscenesPlayedScenes Playedscenes_played数值playCountTotal Playstotal_play_count数值playDurationTime Watchedtotal_play_duration时长durationsceneSizeScenes Sizescenes_size字节1 位小数sceneDurationScenes Durationscenes_duration时长imagesImagesimage_count数值imageSizeImages Sizeimages_size字节1 位小数galleriesGalleriesgallery_count数值performersPerformersperformer_count数值studiosStudiosstudio_count数值moviesMoviesmovie_count数值tagsTagstag_count数值oCountO Counttotal_o_count数值字段的中英文标签定义可在 public/locales/en/common.json 的stash节点中查到其他语言的翻译文件如 zh-Hans/common.json结构一致Homepage 会依据浏览器语言自动选择。展示规则默认字段与 4 字段上限Widget 的展示遵循两条明确规则文档声明 组件实现双重印证未配置fields时使用默认值组件在渲染前检查widget.fields若未设置则回退为[scenes, images]与初始加载时的占位符Placeholder一致见 component.jsx。最多只展示 4 个字段若配置的字段超过 4 个仅保留前 4 个见 component.jsxif (widget.fields.length 4) { widget.fields widget.fields.slice(0, 4); }需要注意的是该截断发生在组件内部并未改动用户配置文件中fields的原有顺序——因此fields的书写顺序决定了优先展示哪些字段。例如想展示总播放次数 观看时长 场景数 图片数应写成widget: type: stash url: http://stash.host.or.ip key: stashapikey fields: [playCount, playDuration, scenes, images]数据链路剖析从配置到 GraphQL 查询Stash Widget 的数据获取并非简单的 REST 调用而是经过 Homepage 通用代理generic proxy handler向 Stash 的 GraphQL 端点发起 POST 查询。全链路如下1. 前端发起代理请求组件挂载后通过formatProxyUrl生成代理地址并发送 POST 请求component.jsxconst url formatProxyUrl(widget, stats); const res await fetch(url, { method: POST });formatProxyUrl定义在 utils/proxy/api-helpers.js最终指向/api/services/proxy端点。2. 通用代理拼接目标地址generic.js 中Homepage 用 Widget 定义的api模板替换占位符{url}→ 配置中的url{endpoint}→graphqlstats 映射中指定{key}→ 配置中的key得到http://stash.host.or.ip/graphql?apikeystashapikey。3. 构造 GraphQL 查询体widget.js 中stats映射定义了POST方法与请求体一次性向 Stash 查询全部统计字段mappings: { stats: { method: POST, endpoint: graphql, headers: { content-type: application/json, }, body: JSON.stringify({ query: { stats { scene_count scenes_size scenes_duration image_count images_size gallery_count performer_count studio_count movie_count tag_count total_o_count total_play_duration total_play_count scenes_played } }, }), map: (data) asJson(data).data.stats, }, },4. 响应映射与前端渲染代理返回后map函数取出 GraphQL 响应中的data.stats对象返回给前端组件收到后按fields顺序渲染对应Block。测试用例 component.test.jsx 完整模拟了这一流程先渲染stash.scenes、stash.images两个占位符随后断言 fetch 返回的scene_count: 1、image_count: 7正确渲染为 Block 数值。而 widget.test.js 则验证了 Widget 定义api、proxyHandler、mappings结构合法可被 Homepage 的 Widget 注册体系正确加载。常见问题与排查思路页面只显示占位符、数值不出现多为请求失败或返回结构不符。可先确认url在浏览器可直接访问并检查key是否正确开启登录认证时必须填写。fields超过 4 个但顺序不对Widget 只取前 4 个请调整fields书写顺序以控制展示优先级。返回 Invalid data 错误代理在validateWidgetData校验失败时会返回该错误见 generic.js通常意味着 Stash 版本较旧、GraphQLstats查询结果缺失字段或 API Key 鉴权失败导致响应非预期结构。小结Stash Widget 是 Homepage 服务型 Widget 中典型的代理 GraphQL 映射实现配置侧只需url、key、fields三个核心参数底层则由 widget.js 定义 API 模板与查询体、component.jsx 负责字段渲染与数量限制前后端配合完成从 Stash 实例到首页看板的完整数据流。掌握字段映射表与 4 字段上限规则后即可按需组合出最贴合自己媒体库的统计面板。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考