Home Assistant iperf3.speedtest 动作实战如何手动触发按需网络带宽测试【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本文以 Home Assistant 官方文档仓库中的iperf3.speedtest动作文档为骨架系统讲解如何在 Home Assistant 中通过 UI 或 YAML 手动触发一次 iperf3 网络带宽测试。你将掌握该动作的全部可用参数、它与iperf3集成定时扫描scan_interval的关系以及如何在自动化与脚本中编写“按需测速”的完整配置示例实现网络变更后立刻获得最新测量结果。动作定位让测速不再等待定时任务在 Home Assistant 中iperf3集成负责测量本机与私有或公共 iperf3 服务器之间的网络带宽性能。启用集成后系统会为下载速度、上传速度等监测项自动创建传感器并默认每小时整点自动运行一次测试频率可通过配置中的scan_interval调整。而iperf3.speedtest动作官方文档页见 source/_actions/iperf3.speedtest.markdown的作用正是立即运行一次 iperf3 速度测试而不是等待下一次定时测试。当你想要一份最新测量值时例如调整网络配置后检查连接状态这一动作可以立刻给出结果非常适合用在自动化或脚本中。从该动作的描述description: Runs an iperf3 speed test on demand.可以看出其核心语义是on-demand按需触发只要集成已配置好服务器列表你就可以随时调用它获取实时带宽数据。前提先完成 iperf3 集成的基础配置iperf3.speedtest动作本身不含服务器连接信息它依赖iperf3集成配置好的服务器列表。因此在使用该动作前需要先在configuration.yaml中启用集成详见 source/_integrations/iperf3.markdown# Example configuration.yaml entry iperf3: hosts: - host: iperf.he.net该集成需要操作系统上已安装iperf3命令行工具配置完成后需要重启 Home Assistant 使其生效。集成提供以下顶层配置项配置项说明必填默认值monitored_conditions要在前端显示的传感器列表可选download下载速度Mbit/s与upload上传速度Mbit/s否全部hosts要执行测试的 iperf3 服务器列表是—scan_interval两次更新之间的最小时间间隔支持HH:MM:SS、HH:MM及时间字典格式否60 分钟manual设为true开启手动模式将禁用定时测试否false每个服务器条目还支持port默认5201、duration测试时长秒数默认10合法范围 510、parallel并发流数量默认1合法范围 120、protocoltcp或udp默认tcp。需要说明的是duration默认值与合法范围来自当前仓库集成文档实际行为以所运行的 Home Assistant 版本为准。scan_interval还支持时间字典写法scan_interval: # At least one of these must be specified: days: 0 hours: 0 minutes: 3 seconds: 30 milliseconds: 0在 source/changelogs/core-2026.6.markdown 的变更记录中可以看到该集成持续有代码层面的维护例如将重复常量替换为homeassistant.const导入说明其实现始终与 Home Assistant 核心框架保持同步演进。通过用户界面调用该动作iperf3.speedtest是标准的 Home Assistant 动作完全可以通过可视化界面配置无需编写 YAML进入Settings Automations scenes自动化与场景。打开一个现有的自动化或脚本如果没有选择Create automation Create new automation新建。如果是新建自动化在When触发条件区域添加触发器脚本不需要触发器它们在被其他对象调用时运行。在Then do执行动作区域选择Add action。在搜索框中搜索并选择Iperf3: Speedtest。可选设置Host字段指定针对某一台已配置服务器进行测试。选择Save保存。需要特别注意的是该动作不支持 targets目标对象。在 UI 中它不会提示你选择区域area、设备device、实体entity或标签label因为测速动作作用于整个集成配置而非某个具体实体。UI 中的选项该动作在界面中只有一个可选字段选项说明必填Host要测试的目标 iperf3 服务器的主机名或 IP 地址。留空则对所有已配置服务器执行测试否YAML 用法与参数参考在 YAML 中该动作被引用为iperf3.speedtest。一个基础示例如下action: iperf3.speedtest data: host: iperf.he.net这段配置会对iperf.he.net服务器执行一次速度测试。YAML 侧的参数与 UI 一一对应参数类型必填说明hoststring否已配置 iperf3 服务器的主机名或 IP 地址省略时对所有已配置服务器执行测试实战示例路由器重启后自动测速iperf3.speedtest最常见的用法之一是结合连接状态传感器触发按需测速。例如当路由器重新上线后自动运行一次 iperf3 测速从而获得最新的连接质量测量结果触发器Trigger路由器连接状态传感器变为开启动作ActionIperf3: Speedtest对应的完整自动化 YAML 如下automation: alias: Run iperf3 test after router reboot triggers: - trigger: state entity_id: binary_sensor.router_online to: on actions: - action: iperf3.speedtest这个场景正是该动作的核心价值所在你不需要把定时扫描间隔缩短来换取“新鲜”数据只需在特定事件发生时触发一次手动测试既省资源又能第一时间拿到结果。仓库中动作文档的 “Good to know” 部分也强调了两个要点留空 host 即可一次性测试所有已配置服务器当你把扫描间隔设置得较长、又希望在不等待下一次自动测试的情况下获得最新结果时该动作最有用。如果你不希望配置定时测试也可以在集成配置中开启manual: true手动模式禁用定时任务然后完全依靠iperf3.speedtest动作在需要时触发测试。源码层面的佐证从引入到持续演进关于该功能的演进可以在仓库的发布记录中看到清晰的脉络。iperf3 客户端传感器首次引入于 Home Assistant 0.71 版本见 source/_posts/2018-06-10-release-71.markdown该版本发布说明中还记录了后续为传感器加入UDP 协议支持与 parallel 并发流支持的改进后续版本中iperf3 组件又经历了基于EntityDescription的重构source/_posts/2021-10-06-release-202110.markdown、发现逻辑由列表改为字典source/_posts/2022-02-02-release-20222.markdown以及统计支持与图标调整source/changelogs/core-2023.2.markdown等维护。这些记录表明iperf3及其按需测速能力是一套长期演进、持续受官方维护的功能模块。此外集成文档还提到可以通过sensor.iperf3_update动作触发一次针对所有传感器的手动测速而iperf3.speedtest动作则更进一步允许你针对特定实体/服务器执行测试两者搭配可以覆盖“全量刷新”与“定点测速”两种场景。尝试与排障建议如果你不想写任何 YAML可以直接在Settings Tools Actions开发者工具 动作中搜索iperf3.speedtest填写字段后点击Perform action即可在真实实体上立即观察测速结果。若测试未按预期执行通常可以从以下方向排查确认iperf3命令行工具已安装且hosts列表配置正确检查目标服务器是否可达、端口是否匹配默认 5201注意集成文档中的提示若服务器位于公网建议使用 TCP 而非 UDP因为 UDP 测试可能因数据包重传问题导致传感器无法正常更新若使用并发流parallel或自定义协议请结合 iperf3 官方 man page 谨慎调整参数并发流并非越多越好。关于本动作更多可用示例可继续查阅仓库中的 iperf3 集成文档 与 动作文档 获取完整配置参考。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考