Roborock Local Server 全功能概览：免刷机、免拆机、免焊线，把石头云搬到家里
Roborock Local Server 全功能概览：免刷机、免拆机、免焊线，把石头云搬到家里
🏠 Roborock Local Server 是一个运行在家庭内网的 Local HTTPS 和 MQTT 云模拟器，让你把石头扫地机器人的"云端服务"完整搬到自己的路由器后面。无需刷机（no rooting）、无需拆机焊线，扫地机器人就能保留实时地图、本地控制等全部功能，即使断网也照常工作。
为什么需要 Roborock Local Server
在官方体系下，石头机器人有两个"云端枷锁"，让完全离线控制一直不可能：
- 地图数据被云锁死：尽管地图其实存在机器人本地，但所有地图请求必须经过 Roborock 官方云服务器；
- 云端健康检查：一旦机器人连不上官方服务器，它会反复重启网络接口，直接掐断局域网通信。
上图是 Onboarding 过程中本地服务器上报的设备状态（查询样本数、公钥恢复、MQTT 连接情况）
Roborock Local Server 的思路是"接管"而非"对抗"：通过在局域网内 DNS 改写 + 完成一次初始 Onboarding 握手，让机器人把本地服务器当成官方云，之后一切通信都留在家里。
核心功能一览
| 功能 | 说明 |
|---|---|
| 🗺️ 本地地图流 | 实时地图、房间清扫全部走局域网，无需外网 |
| 🔧 零硬件改动 | 不拆机、不焊线、不解锁 bootloader，普通用户也能玩 |
| 🆕 Greenfield Onboarding | 全新机器人未注册过官方云也能直接入网（V1/V2 协议均支持） |
| ↩️ 完全可逆 | 重置机器人 Wi-Fi 即可回到出厂配对状态，随时"后悔" |
| 📱 多前端支持 | Home Assistant 官方集成、开源 App LocalRock、官方 Roborock App 三选一 |
| 📷 摄像头直播 | 带摄像头的机型可通过 TURN 中继 + go2rtc 实现本地 WebRTC 实时预览 |
它是怎么工作的（一句话版原理）
整个过程可以概括为三步：
- 域名注入：Onboarding 时把
api-xxx.你的域名注入机器人固件的 URL 拼接逻辑，让它访问你的本地服务器而不是api-us.roborock.com； - 公钥恢复：机器人每次请求都携带 RSA 签名，服务器通过收集足够多的签名样本做数学推导（GCD 求模数），恢复出机器人的公钥——这正是免刷机的关键，详见 docs/technical_writeup.md；
- MQTT 桥接：内置 Mosquitto broker + topic bridge，把
rr/d/i（设备进）与rr/m/o（用户出）等四类 topic 互相转发，App 和 HA 就像在跟官方云通信一样。
核心实现都在 src/roborock_local_server/bundled_backend/ 目录下，按 HTTPS 路由、MQTT broker、TLS 代理分模块组织。
兼容性：哪些机型能用？
- ✅ 支持：大多数石头机型，包括 S 系列、Qrevo 系列、Saros 系列、G30U 等，V2 协议新机型在 1.1.0 起也已支持；
- ❌ 不支持：入门级 Q 系列（Q7、Q10 X5/M5 等，因证书校验机制不同）；
- 📋 每台机型的固件版本 + 证书链（ZeroSSL / Actalis / Let's Encrypt / SSL.com）实测结果，都记录在 docs/tested_vacuums.md 的表格里，装之前先查表，不同机型信任的证书链不一样；
- 🇨🇳 中国区机型在区外使用受固件
rrcheck地域校验限制，暂不可用。
安装方式：两条路径
路径一：Docker Compose（最通用）
适合任何跑得了 Docker 的 Linux 主机或虚拟机：
- 克隆仓库（仓库地址：
https://gitcode.com/gh_mirrors/lo/local_roborock_server），uv sync安装依赖； - 运行配置向导
uv run roborock-local-server configure，它会交互式地问你要stack_fqdn（必须api-开头）、端口、MQTT 模式、证书策略、admin 密码和"协议登录邮箱 + PIN"； docker compose up -d --build启动。
完整步骤见 docs/installation.md，配置项可参考根目录的 config.example.toml。
路径二：Home Assistant Add-on（最省心）
如果你的 HA 支持 Add-on，直接在插件商店添加本仓库，安装 Roborock Local Server，填好 stack_fqdn、端口、证书和登录凭据即可，镜像与 Docker 部署完全相同。Add-on 定义见 roborock_local_server_addon/config.yaml，详细指南见 docs/home_assistant.md。
前置要求速查
- 一个你拥有的域名 + 本地 DNS 改写（Pi-hole / AdGuard Home / 路由器均可）；
- 证书：Cloudflare DNS-01 自动签发（推荐 ZeroSSL）或自带证书文件；
- 一台带 Wi-Fi 的备用电脑（或手机，走 LocalRock），用于 Onboarding；
- 容器至少 1 核 CPU + 1GB 内存（公钥恢复涉及大量密码学运算，资源不足会"卡住"）。
Onboarding：把机器人接进本地云
服务器跑起来后，在第二台机器上运行引导脚本：
uv run start_onboarding.py --server api-roborock.example.com
脚本会自动：登录服务器 → 列出可入网设备 → 提示你重置机器人 Wi-Fi 并连上它的热spot → 发送 cfgwifi 配对包 → 轮询等待公钥恢复与连接（最多 5 分钟）。不想碰终端可以用浏览器版 start_onboarding_gui.py（配合 ui.html），五个阶段带步进器和实时日志。
几个实用点：
- 全新未注册过的机器人可选 New vacuum 盲配模式，服务器会自动把它的身份加入设备清单；
- 部分机型需要 2–4 个配对周期，公钥恢复可能耗时几分钟，耐心即可；
- 手机党可用开源 App LocalRock 直接从手机端完成 Add vacuum 全流程，无需备用电脑；
- 详细流程与排错见 docs/onboarding.md。
三种前端，总有一款适合你
| 前端 | 特点 | 适用人群 |
|---|---|---|
| 🏡 Home Assistant | 集成原生支持 Region: Manual 自定义服务器，填邮箱 + 6 位 PIN 即完成本地化 |
智能家居玩家（最推荐） |
| 📱 LocalRock（开源） | 原生直连本地 HTTPS/MQTT，不怕官方 App 更新破坏配置；可能缺少部分高级功能 | 想简单用、不想折腾证书的人 |
| 📲 官方 App | iOS 走 MITM Profile 重定向；Android 需打补丁 APK（内置 patcher/patch_librrcodec.py 移除签名完整性校验） | 必须用官方 UI 全部功能的人 |
官方 App 的 MITM 重定向工具为 mitm_redirect.py，完整玩法见 docs/roborock_app.md。
进阶玩法
- 📷 摄像头直播：带摄像头的机型（如 Saros 10R、Qrevo MaxV）可配置 TURN 中继（
compose.turn.yaml），配合 go2rtc 在本地播放 WebRTC 实时画面，见 docs/camera.md； - 🔀 自定义 MQTT：不想要内置 broker？在
config.toml设置broker.mode = "external"指向你自己的 Mosquitto，见 docs/custom_mqtt.md； - 🌐 反向代理：支持 Caddy/nginx 等代理终止 TLS，通过
advertised_*_port分离对外端口与后端监听端口，见 docs/reverse_proxy.md； - 📜 云端数据导入：admin 后台（
/admin）支持输入官方云邮箱 + 验证码一键拉取你的房屋、房间、例程和已知设备，让切换无缝衔接； - 🔁 升级路径清晰：
docker compose pull && up -d或 Add-on 商店升级即可，注意事项见 docs/updating.md。
已知局限（先说实话）
- ❌ 固件 OTA 更新不支持；
- ❌ 定时任务（Schedules）不支持，但例程/场景（Routines/Scenes）可用；
- ⚠️ 摄像头直播依赖 TURN 中继，且不同固件的 bootstrap 行为有差异；
- ⚠️ 中国区机型在境外不可用。
完整列表见 docs/known_limitations.md。
快速上手清单
- ☑️ 查 docs/tested_vacuums.md 确认机型与证书链；
- ☑️ 配置域名 + 本地 DNS 解析到服务器内网 IP；
- ☑️ Docker Compose 或 HA Add-on 拉起服务；
- ☑️ 打开
/admin完成云端数据导入； - ☑️ 第二台机器跑
start_onboarding.py完成配对； - ☑️ 在 HA / LocalRock / 官方 App 中登录本地服务器，见证地图流起来的那一刻 🎉
⚠️ 本项目以"现状"提供，任何因网络改动导致的后果需自行负责。本项目与 Roborock 官方无任何关联。
📚 继续深入：docs/index.md（文档总目录）｜docs/installation.md（安装）｜docs/onboarding.md（配对）｜docs/home_assistant.md（HA 集成）｜docs/technical_writeup.md（逆向工程原理）