如何用 Roborock Local Server 玩转 Home Assistant：5分钟装好 Add-on 并重定向 Roborock 集成

Roborock Local Server 是一个免 Root、免硬件改造的Roborock 扫地机本地云端模拟器：它在你家局域网里复刻 Roborock 官方的 HTTPS 和 MQTT 服务，让扫地机、Home Assistant 和 Roborock 集成都能绕过官方云，直接在本地通信。本文带你用Home Assistant Add-on一键装好它，并把 Roborock 集成从官方云重定向到本地服务器——全程不需要改一行代码。🏠

一、装好后你能得到什么？

⚠️ 不同型号扫地机信任的证书链不同。安装前建议先查看已测试机型列表，确认你的机型应该用zerossl、actalis还是自带证书。大多数用户选zerossl即可。

二、安装前准备（1分钟自检）

1. ✅ 一个自己拥有的域名，且家里有本地 DNS（Pi-hole / AdGuard Home / 路由器）
2. ✅ 一个以api-开头的子域名（如api-roborock.example.com），指向运行 Home Assistant 的局域网 IP
3. ✅ 一台可以联网配对的备用机器（手机或电脑，稍后做 Onboarding 用）
4. ✅ Home Assistant 支持 Add-on（OS 发行版）

网络要求细节可参考安装文档。

三、Add-on 安装步骤（3分钟）

第 1 步：添加 Add-on 仓库

打开设置 → Add-on 商店 → 仓库，添加本项目的仓库地址，然后找到Roborock Local Server并安装。

💡 请安装稳定版Roborock Local Server（当前 1.2.1）。Beta 版（1.1.0-rc2）目前未启用，数据和稳定版是分离的。

第 2 步：填写关键配置

在 Add-on 的配置（Options）标签页中，重点填写以下参数（完整定义见 config.yaml）：

证书两种走法：

• tls_mode = cloudflare_acme：填tls_base_domain、tls_email、cloudflare_token，证书自动签发续期；acme_server多数人选zerossl，老机型选actalis（需另填acme_eab_kid和acme_eab_hmac_key）
• tls_mode = provided：指向你已有的证书文件。如果你用的是 Home Assistant 官方 Let's Encrypt Add-on，证书在/ssl目录，例如cert_file = /ssl/fullchain.pem、key_file = /ssl/privkey.pem

第 3 步：启动并打开管理后台

启动 Add-on 后，浏览器访问：

https://api-roborock.example.com:555/admin

⚠️ 请用stack_fqdn配置的域名访问，不要用 HA 主机地址（除非它恰好就是证书覆盖的域名）。

第 4 步：导入云端数据

1. 在/admin后台使用Cloud Import拉取你的 Roborock 账号数据（此时输入 Roborock 云账号邮箱 + 验证码）
2. 确认设备列表中出现你的扫地机
3. 从备用机器运行 Onboarding 完成配对

完成这三步后，你的本地"小云"就真正上线了。🎉

四、重定向 Roborock 集成（1分钟）

Add-on 本身不会自动改写 HA 的 Roborock 集成，需要手动指向本地服务器。HA 官方 Roborock 集成支持自定义服务器（Region 选Manual），无需手改存储文件。

方式 A：全新添加集成（最简单）

1. 打开设置 → 设备与服务，点击添加集成，搜索Roborock
2. 地区下拉框选择Manual
3. 输入本地服务器地址，例如https://api-roborock.example.com:555
4. 输入protocol_login_email，再用你的 6 位protocol_login_pin作为验证码提交

集成会自动连上本地服务器、列出设备并建立本地 MQTT 连接。✅

方式 B：已有云集成，改道本地

如果集成已经连着官方云，有两种选择：

• B1. 删除后重新添加：点集成右上角三点菜单 →删除，再按上面"方式 A"重新添加。最干净，但会失去原有实体 ID、仪表盘和历史记录
• B2. 编辑core.config_entries：保留实体 ID 和历史。先停用集成（或停 HA）→ 备份/config/.storage/core.config_entries→ 找到"domain": "roborock"的条目，把base_url、"a"、"l"改成本地 HTTPS 地址，"m"改为ssl://api-roborock.example.com:8881，username改为protocol_login_email→ 保存重启，按提示输入protocol_login_pin重新认证

🛡️ 手动编辑.storage文件有风险，改之前一定先备份。

五、常见故障排查

日志出现rejected MQTT CONNECT reason=invalid_mqtt_credentials？

这是凭据过期导致的，依次检查：

1. 本地服务器是否用同一 Roborock 账号完成过 Cloud Import
2. base_url、rriot.r.a/l/m是否都指向本地服务器
3. 在 HA 中触发重新认证（Reauth），输入protocol_login_pin，让集成从本地服务器拉取最新 MQTT 凭据

更多问题排查与集成细节见Home Assistant 官方文档页。

六、延伸阅读

装好之后，你的扫地机地图、清洁状态、定时任务全部跑在局域网里——隐私留在自己家，响应快人一步。🚀