企业官网建设流程全解析

• 物联网
• 后端
• 前端

Valetudo Companion 是 Valetudo 生态中的一款可选 Android 辅助应用，它的核心价值在于：自动监听局域网内的 Bonjour（mDNS/zeroconf）广播，把网络中所有 Valetudo 实例以列表形式呈现，免去手动配置静态 DHCP 租约或登录路由器后台查 IP 的麻烦；同时内置轻量配置向导，可帮助新实例完成网络初始化（provisioning）。读完本文，你将理解 Companion 应用的定位边界、它在 Valetudo 端对应的广播机制（源码级）、安装渠道差异，以及配置向导背后的前端与后端实现原理。

它是什么：自动更新的书签 + 一个向导

根据 valetudo_companion.md 的官方定位，Valetudo Companion 是一个完全可选的应用，只为了让 Valetudo 更容易被访问。它不会在正常使用过程中提供任何操作 Valetudo 的界面——也就是说，你仍然需要通过浏览器打开实例的 Web UI 来完成清扫、地图、设置等全部操作。

简言之，你可以把它理解为一个"会自动更新的书签"加上一些向导功能。

它做的事情只有两件：

1. 自动发现：监听网络中近期（2021.07.0 及更新版本）Valetudo 实例发出的 Bonjour 广播，并将每个实例显示在列表中，方便一键访问。
2. 简化配置：允许对全新实例进行快速 provisioning，无需在手机上折腾移动数据/热点的切换设置。

为什么需要它：解决"找 IP"与"首次配置"两大痛点

在多设备家庭网络中，Valetudo 实例的地址通常由路由器 DHCP 动态分配。传统做法要么为每个机器人手动配置静态 DHCP 租约，要么频繁登录路由器管理界面查询地址——这两者都繁琐且容易出错。Companion 应用通过被动监听 Bonjour 广播，让"发现实例"变成零配置行为。

而在首次部署场景（例如刚刷好 Valetudo、尚未接入 Wi-Fi 的机器人），Companion 的向导能力让用户不必在手机系统设置中反复切换热点和移动网络，直接在应用内完成网络的扫描与接入，显著降低上手门槛。

值得强调的是，"能被发现"这一能力并非应用单方面实现，而是依赖 Valetudo 后端主动广播服务，二者缺一不可。

底层原理：Valetudo 端如何"广播自己"

Companion 之所以能列出所有实例，前提是 Valetudo 在嵌入式设备上持续发布 Bonjour 服务。这一机制在仓库中由 NetworkAdvertisementManager.js 实现。该类的注释明确写道：

This class handles advertisement via both SSDP (UPnP) and zeroconf/mdns/bonjour

即 Valetudo 同时通过 SSDP（UPnP）与 zeroconf/mDNS（Bonjour）两个协议广播自己的存在。其中 Bonjour 部分使用bonjour-service库，并发布两类服务（见 NetworkAdvertisementManager.js）：

每个服务携带一组 TXT 记录，用于向发现方描述实例身份（源码位置）：

• id：人类可读的系统 ID（见下文）
• model：机器人型号名（来自robot.getModelName()）
• manufacturer：制造商（来自robot.getManufacturer()）
• version：Valetudo 版本号（来自Tools.GET_VALETUDO_VERSION()）
• name（可选）：当配置了friendlyName时附加，来自 ValetudoHelper.js 的getFriendlyName()，未配置时默认格式为Valetudo <型号> <系统ID>

人类可读系统 ID 与 zeroconf 主机名

从 Tools.js 可以看到一套完整的身份生成逻辑：

• GET_SYSTEM_ID()：基于本机网卡 MAC 地址集合，用 UUID v5 生成稳定的实例 ID（Linux 下优先从 sysfs 读取 MAC）；
• GET_HUMAN_READABLE_SYSTEM_ID()：默认由系统 ID 通过zooIDs.generateId()生成便于人读的短 ID，也可通过环境变量覆盖（源码注释指出这是有意"半隐藏"的能力，配置错误可能破坏功能，因此未放进配置文件）；
• GET_ZEROCONF_HOSTNAME()：拼接为valetudo-<系统ID小写>.local，即实例在局域网内的 mDNS 主机名。

也就是说，Companion 列表项背后的每一个 ID、型号、版本字段，都来自上面这套真实运行的广播数据，而不是应用端猜测的。

广播的启用条件与配置

Bonjour 广播并非无条件开启。查看 NetworkAdvertisementManager.js 的setUp()：

• 仅当config.get("embedded") === true（即运行在嵌入式设备上）时才会启动广播；
• 且配置项networkAdvertisement.enabled必须为true（默认配置即开启，见 default_config.json）。

广播期间，管理器每 30 秒检查一次本机 IP 地址集合（NETWORK_STATE_CHECK_INTERVAL = 30 * 1000），一旦检测到网络状态变化（如切换了 Wi-Fi、获得了新 IP），会自动重启 SSDP 与 Bonjour 服务以保证广播与真实地址一致（源码位置）。

面向管理员的 REST 接口

如需查看或调整广播配置，NetworkAdvertisementManagerRouter.js 提供了相应接口：

• GET /config：返回{ "enabled": boolean }；
• PUT /config：接受{ "enabled": boolean }更新配置（非布尔值返回 400）；
• GET /properties：返回{ port, zeroconfHostname }，即 Web 端口与 mDNS 主机名。

这解释了文档中"2021.07.0 及更新版本"的限制：Bonjour 广播机制是自该版本起引入并稳定存在的，Companion 只对广播了自身存在的实例生效。

Companion 的配置向导：provisioning 的前端与后端

文档特别提到，Companion 能在"不用折腾移动数据设置"的前提下完成新实例的 provisioning。仓库前端代码印证了这一体验是如何实现的。

在 RouterChoice.tsx 中，前端会查询当前实例的 Wi-Fi 状态：

• 若wifiConfiguration.state === "not_connected"，渲染 ProvisioningPage.tsx，即进入配置向导；
• 若已connected，则跳过向导直接进入主应用。

ProvisioningPage.tsx 中则包含完整的 Wi-Fi 扫描与选择体验：

• 通过useWifiScanQuery()触发扫描并拉取结果，按 SSID 去重（Map结构），并按信号强度降序排列（源码位置）；
• 结果列表以SCAN_RESULT_BATCH_SIZE = 5分批展示，点击"更多结果"逐批展开，避免长列表卡顿（源码位置）；
• 信号强度通过SignalStrengthIcon组件映射为不同档位图标，直观呈现 Wi-Fi 质量。

从后端能力看，向导依赖 WifiConfigurationCapability.js 提供的getProperties()，其中provisionedReconfigurationSupported字段标志着实例是否支持"已配置状态下的重新配置"。这些接口与前端向导共同构成"无需切换手机热点"的体验——一切扫描、连接操作都直接经由应用与实例间的 HTTP API 完成。

需要说明的是：Companion 应用本身的源码不在本仓库内（其源码以 Apache-2.0 许可另行发布），上文分析的是它交互的 Valetudo 侧实现；应用侧的界面细节请以官方仓库为准。

如何安装

官方推荐的首选渠道是F-Droid（应用 ID 为cloud.valetudo.companion），这是因为它不包含任何跟踪代码，且更新流程完全开放、透明。

其次也可以从Google Play 商店（同一应用 IDcloud.valetudo.companion）获取。官方文档明确提醒：尽管应用本身不含跟踪组件，但Play Store 渠道本身会收集匿名使用数据——这一提醒适用于所有从该商店下载的应用，并非 Valetudo Companion 特有问题。

应用源码以 Apache-2.0 许可发布，允许自由查看、修改与再分发。

透明度：Play Store 渠道会收集哪些数据

这是官方文档专门用一节讨论的话题。即使应用本身干净，经由 Google Play 分发时，商店后台仍会向开发者提供聚合统计（下图即官方文档展示的 Play Store 后台仪表盘截图）：

此外，用户对应用的评论会包含：你的全名、你正在使用的设备型号、以及设备语言。官方对此的结论是：整体上没有严重问题，但用户有权知道这些数据确实在被收集——这正是选择 F-Droid 渠道可以获得更纯粹体验的原因。

使用建议

• 多实例家庭：如果你有多台机器人且未配置静态 DHCP，Companion 的列表式发现体验远比翻路由器后台高效；
• 首次部署：新实例刷机后，直接用 Companion 完成网络配置，无需在手机设置中反复切换热点；
• 隐私敏感用户：优先通过 F-Droid 安装，避开 Play Store 的匿名数据收集；
• 正常使用仍需 Web UI：Companion 只负责"找到并打开"，清扫、地图、设置等操作仍需浏览器访问实例的 Web 界面（地址形如valetudo-<系统ID>.local）。

理解 Valetudo 端的 Bonjour 广播机制（NetworkAdvertisementManager.js）与前端配置向导（ProvisioningPage.tsx）之后，你就能清楚地知道 Companion 应用的能力边界：它是一个称职的"发现器 + 配置助手"，而真正的控制中枢始终是 Valetudo 自身的 Web UI。

• 物联网
• 后端
• 前端