Homepage 集成 MySpeed 测速 Widget：配置详解与源码级原理分析

Homepage 集成 MySpeed 测速 Widget：配置详解与源码级原理分析

【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage

MySpeed 是一款自托管的网络速度测试工具，可定期运行测速并记录历史数据。Homepage 项目（A highly customizable homepage / startpage / application dashboard）原生提供了myspeed类型的服务 Widget，让你无需打开 MySpeed 管理界面，就能在个人首页仪表盘上直接看到最近一次测速的下载、上传和 Ping 结果。本文将基于仓库中的 MySpeed Widget 文档 为主体，结合 widget 源码、渲染组件、代理处理逻辑 与 测试用例，从零开始讲解配置方法、认证机制、数据来源与显示细节，帮助你快速将 MySpeed 接入 Homepage 仪表盘。

一、快速开始：最小可运行配置

在 Homepage 的services.yaml中，为某个服务组添加myspeed类型的 widget，只需三行核心配置。以下是文档给出的最小示例：

widget: type: myspeed url: http://myspeed.host.or.ip:port password: password # only required if password is set

• type固定为myspeed，用于声明该 widget 走 MySpeed 集成逻辑；
• url是 MySpeed 服务的访问地址（主机或 IP，带端口）；
• password仅在 MySpeed 实例设置了密码时才需要填写，未设置密码的实例可以省略该项。

将该配置嵌入到完整服务定义中，即可在首页渲染出 MySpeed 的三个指标块，例如：

- MySpeed: icon: sh-myspeed href: http://myspeed.host.or.ip:port description: Network speed test widget: type: myspeed url: http://myspeed.host.or.ip:port password: yourpassword # 仅当 MySpeed 设置了密码

二、配置参数详解

url：API 地址基址

url不仅用于服务跳转展示，更关键的是它被用作后端 API 代理请求的基址。从 widget 定义 可以看到，MySpeed 集成的 API 模板为：

api: "{url}/api/{endpoint}"

也就是说，Homepage 后端会向{url}/api/{endpoint}发起请求，{url}即替换为你配置的url值，{endpoint}由内部映射决定。这意味着你配置的url必须能被运行 Homepage 的服务器（而非浏览器所在机器）直接访问到，否则代理请求会失败。

password：API 访问口令

password是 MySpeed 实例的访问密码。它并不是通过常规的Authorization: Bearer ...头传递，而是在 Homepage 代理转发时以自定义请求头Password发送。对应实现位于 credentialed.js：

} else if (widget.type === "myspeed") { headers.Password = `${widget.password}`; }

因此在 MySpeed 端，Homepage 代理请求的身份标识就是名为Password的请求头。若你的 MySpeed 开启了密码保护却漏配此字段，接口将返回认证错误；反之，未开启密码保护时配置了密码也无妨，但文档建议仅在确有设置密码时才填写。

三、字段说明与显示控制

文档明确声明 MySpeed widget 的允许字段为：

["ping", "download", "upload"]

这三个字段对应 MySpeed 最近一次测速结果中的三项核心指标。它们既决定了组件渲染的数据项，也支持通过 Homepage 通用的fields属性控制哪些指标块显示。根据 服务配置通用说明（其中说明了fields属性），你可以这样只显示下载与上传：

widget: type: myspeed url: http://myspeed.host.or.ip:port password: password fields: - download - upload

字段在界面上的文案由国际化文件定义，见 public/locales/en/common.json：

"myspeed": { "ping": "Ping", "download": "Download", "upload": "Upload" }

其他语言（如中文）对应文案可在public/locales/zh-Hans/common.json中查看。

四、数据来源：API 调用链剖析

MySpeed widget 的数据并非凭空生成，而是由 Homepage 后端代理转发 MySpeed 的 REST API 结果。整个过程可分为三步：

第一步：映射声明。在 widget.js 中定义了info映射：

mappings: { info: { endpoint: "speedtests?limit=1", }, },

结合前文的 API 模板，实际请求 URL 为：

{url}/api/speedtests?limit=1

该接口返回 MySpeed 记录的历史测速列表，limit=1意味着只取最近一次测速记录。

第二步：代理转发。widget 指定了proxyHandler: credentialedProxyHandler，即由 credentialed.js 统一处理。处理器会先根据group、service参数从配置中解析出 widget 定义，拼装目标 URL，注入Password请求头，然后通过httpProxy向后端服务发起请求，并把响应原样返回给前端（若状态码为 4xx/5xx 则包装为错误结构）。

第三步：数据校验。返回数据会经过 validate-widget-data.js 的 JSON 解析与结构校验，只有合法的 JSON 数组才会被交给前端渲染组件使用。

五、渲染逻辑：数值格式化与单位换算

前端渲染由 component.jsx 完成。组件通过useWidgetAPI钩子请求info映射，拿到数据后按如下逻辑渲染：

下载与上传速率：MySpeed API 返回的download、upload字段以 Mbps 为单位，Homepage 在展示前将其乘以1000 * 1000，再交给common.bitrate翻译函数格式化为带单位的速率文本：

<Block label="myspeed.download" value={t("common.bitrate", { value: data[0].download * 1000 * 1000, decimals: 2, })} />

Ping 延迟：ping字段以毫秒为单位，使用common.ms翻译函数按国际单位制（unit:millisecond）渲染，同时支持highlightValue阈值高亮：

<Block label="myspeed.ping" value={t("common.ms", { value: data[0].ping, style: "unit", unit: "millisecond", })} highlightValue={data[0].ping} />

空数据处理：当接口返回空数组（尚无任何测速记录）时，组件会渲染三个占位块，等待数据出现；当接口报错或返回错误结构时，则展示统一的错误提示 UI。这些分支行为都有对应的单元测试覆盖，见 component.test.jsx，其中测试用例验证了「加载中渲染三个占位块」「错误时展示 api_error 文案」「数据到达后正确显示 download/upload/ping 数值」三种场景。

六、结合 highlight 进行指标高亮

Homepage 支持为 widget 的数值块配置自动变色规则，MySpeed 的ping字段本身已通过highlightValue与高亮机制关联。你也可以利用highlight属性进一步自定义，例如将延迟分为「优秀 / 一般 / 较差」三档：

widget: type: myspeed url: http://myspeed.host.or.ip:port password: password highlight: ping: - "0-20": green - "20-60": yellow - "60-999": red

需要说明的是，highlight规则作用于服务 widget 的数值块（具体机制见 docs/configs/services.md 中的说明），而 ping 块的高亮值与规则值即 MySpeed 返回的毫秒数。

七、常见问题排查

现象一：widget 显示 API 错误（api_error）。多为url配置错误，或 Homepage 运行环境无法访问 MySpeed 服务。请确认url的协议、主机与端口均正确，且可从 Homepage 容器/宿主机内直接curl {url}/api/speedtests?limit=1验证。

现象二：MySpeed 开了密码但请求返回 401/403。检查是否遗漏password字段。Homepage 通过Password请求头传递该值（见 credentialed.js），需与 MySpeed 实例中设置的密码完全一致。

现象三：三个指标块显示为空。说明接口成功返回但列表为空（data.length === 0），即 MySpeed 尚未执行过任何测速任务。在 MySpeed 中手动运行一次测速后，Homepage 的 widget 便会在刷新后显示结果。

现象四：数值单位不符预期。注意download/upload为 Mbps 量纲，Homepage 展示时按位速率换算（乘以10^6）；ping为毫秒量纲。若 MySpeed 返回字段结构不同，校验环节会判定数据无效并提示Invalid data（日志由 validate-widget-data.js 输出）。

八、小结

MySpeed widget 是 Homepage「服务 Widget 集成」体系中的一个典型范例：以{url}/api/speedtests?limit=1为数据源、以Password请求头完成认证、以download / upload / ping三个字段完成展示，并完整支持fields裁剪与highlight高亮。理解这一调用链与配置语义后，你不仅能在几分钟内把测速数据接入首页，也能触类旁通地排查其他基于 credentialed 代理的 widget 故障。

更多 Widget 集成说明可参考 Widgets 总览，服务配置的通用属性（多 widget、fields、highlight 等）详见 docs/configs/services.md。

【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage