企业官网建设流程全解析

• 物联网
• 后端
• 前端

导读

本文围绕 Valetudo 的升级机制展开，覆盖两条主线：一是 Valetudo 2021.11.0 及以后版本内置的集成更新器（integrated updater）的架构、配置与安全校验流程；二是针对 Roborock（S5/V1/S6）与 Dreame 机型的旧版本手动升级步骤，包括 SSH 刷镜像、双系统切换、二进制替换等实操命令。读者读完后，将能根据自己机器人型号与 Valetudo 版本，选择最合适的升级路径，并理解底层"检查→下载→校验→应用"的完整调用链，避免升级中常见的 "Text file busy"、磁盘空间不足等问题。

一、升级方式总览：内置更新器与手动升级

Valetudo 的升级策略以2021.11.0 版本为分界线：

• 如果你运行的 Valetudo 是2021.11.0 或更新版本，应优先使用其**内置更新器（integrated updater）**功能，无需 SSH、无需手动下载二进制文件，升级过程由 Web 界面/API 触发并自动完成；
• 如果你运行的是更早的旧版本，则只能走本文后面给出的手动升级路径（Roborock 刷镜像、Dreame 替换二进制）。

内置更新器并非一个简单的"下载即覆盖"，而是一个带状态机的多步骤流程。在源码中，它由 backend/lib/updater/Updater.js 中的Updater类实现，整个流程被拆解为三个阶段（Step）：

1. 检查阶段（ValetudoUpdaterCheckStep）：确认嵌入式环境、机器人状态、磁盘空间，并从更新源获取版本清单；
2. 下载阶段（ValetudoUpdaterDownloadStep）：流式下载新二进制并做 SHA-256 校验；
3. 应用阶段（ValetudoUpdaterApplyStep）：把下载的二进制替换到当前可执行文件路径，然后重启（或"重生"）。

下面先说明内置更新器的工作原理与配置，再给出旧版本的手动升级实操。

二、内置更新器（2021.11.0+）：架构、配置与触发方式

2.1 触发入口：Web API 与状态查询

内置更新器通过 HTTP API 暴露，路由实现在 backend/lib/webserver/UpdaterRouter.js：

• GET /api/v2/updater/state：查询更新器当前状态（空闲、错误、待确认、下载中、待应用等）；
• PUT /api/v2/updater/：触发动作，body.action可取check、download、apply三种值，其中check动作还可带force: true强制检查；
• GET /api/v2/updater/config与PUT /api/v2/updater/config：读写更新源（updateProvider）配置，可选值为github与github_nightly。

也就是说，Web 前端点击"检查更新 → 确认 → 应用"的每一步，最终都会落到Updater.triggerCheck()/triggerDownload()/triggerApply()这三个方法上。

2.2 配置项与默认值

更新器相关的配置集中在 backend/lib/res/default_config.json，默认配置如下：

"updater": { "enabled": true, "updateProvider": { "type": "github", "implementationSpecificConfig": {} } }

参数说明：

• enabled：是否启用内置更新器。若为false，Updater会进入ValetudoUpdaterDisabledState，不进行任何检查（见 backend/lib/updater/Updater.js）；
• updateProvider.type：更新源类型。github对应GithubValetudoUpdateProvider，github_nightly对应GithubValetudoNightlyUpdateProvider。如果配置了无效类型，会退化为NullUpdateProvider并记录错误日志；
• implementationSpecificConfig：扩展配置，默认空对象。

2.3 检查阶段（Check）：嵌入式约束与前置条件

ValetudoUpdaterCheckStep（backend/lib/updater/lib/steps/ValetudoUpdaterCheckStep.js）在拿到"检查更新"请求后，会依次完成如下前置校验，任一不满足都会以ValetudoUpdaterError拒绝升级：

磁盘空间评估逻辑见 backend/lib/updater/lib/UpdaterUtils.js：

• 常规二进制需要约40 MB（SPACE_REQUIRED_REGULAR = 40 * 1024 * 1024）可用空间；
• 若空间不足但大于20 MB（SPACE_REQUIRED_UPX），更新器会自动改用UPX 压缩二进制（文件名带.upx后缀）；
• 若二进制所在分区的总容量本身小于40 MB * 3，也会强制走 UPX 路径；
• 下载暂存位置按可用空间从大到小依次尝试/tmp与/dev/shm。

架构与二进制选择方面（backend/lib/updater/Updater.js）：

Updater.ARCHITECTURES = { "arm": "armv7", "arm64": "aarch64" };

检查阶段会根据process.arch映射出armv7/aarch64目标，并结合低内存主机（Tools.IS_LOWMEM_HOST()）与是否 UPX，拼接出期望的二进制名：valetudo-{arch}{-lowmem}{.upx}，然后从发布源中精确匹配该文件名。

2.4 发布源（Update Provider）：GitHub 与 Nightly

GithubValetudoUpdateProvider（backend/lib/updater/lib/update_provider/GithubValetudoUpdateProvider.js）实现了更新源接口：

• 通过 GitHub Releases API（https://api.github.com/repos/Hypfer/Valetudo/releases）拉取发布列表；
• 只保留**非预发布（prerelease=false）且非草稿（draft=false）**的正式版本，并按发布时间倒序排列；
• 每个 Release 还需要配套的valetudo_release_manifest.json清单文件，清单内记录每个二进制的sha256sums与version；清单版本与 Release 版本不一致即视为无效；
• 除清单外的其余 Release assets 会被解析为可下载的二进制，携带downloadUrl与sha256sum。

版本选择策略实现在determineReleaseToDownload()（backend/lib/updater/lib/UpdaterUtils.js）：

• 强制检查（force=true）时直接选最新版；
• 当前版本不在发布列表中时，默认升到最新版；
• 当前版本在列表中且非最新时，只升到下一个相邻版本（逐级升级，避免跨大版本直接跳升）；
• 当前已是最新时返回updateRequired: false，即"无需更新"。

2.5 下载与校验：流式下载 + SHA-256 防篡改

ValetudoUpdaterDownloadStep（backend/lib/updater/lib/steps/ValetudoUpdaterDownloadStep.js）负责实际下载：

• 使用流式管道（pipeline）把 HTTP 响应流写入暂存文件，并通过PipelineThroughputTracker按content-length计算下载进度百分比（供 Web 界面展示）；
• 下载完成后对文件计算SHA-256，与 Release 清单中记录的expectedHash比对；
• 校验失败会以INVALID_CHECKSUM错误终止并清理暂存文件，防止安装被篡改或损坏的二进制。

下载完成后进入"待应用"状态，等待用户确认。值得注意的是，如果用户10 分钟内未确认，更新器会自动清理下载文件并回到空闲状态（见 backend/lib/updater/Updater.js）。

2.6 应用阶段：原子替换与重启

ValetudoUpdaterApplyStep（backend/lib/updater/lib/steps/ValetudoUpdaterApplyStep.js）执行最后的替换动作：

1. 从已校验的暂存文件复制内容到目标目录下的临时文件<binary>.upd（并设置可执行权限）；
2. fs.renameSync(tmpDestination, process.argv0)原子替换当前正在运行的二进制；
3. 执行sync落盘；
4. 若启用了 Phoenix 重生机制（phoenixManager.canReincarnate()），则以REBIRTH_REASONS.UPDATED触发进程重生（携带新旧版本号）；否则执行reboot重启设备。

因此升级完成后系统会自动重启或重生，无需手动干预。

2.7 常见错误速查

内置更新器的错误类型定义在 backend/lib/updater/lib/ValetudoUpdaterError.js，遇到失败时可在 Web 界面或/state接口中看到对应的type：

三、手动升级 Roborock 吸尘器（旧版本）

若你的 Valetudo 早于 2021.11.0（没有内置更新器），可按机型选择下面的手动方案。

3.1 S5、V1 与 S6：刷写新镜像（双系统切换）

S5 / V1 / S6 的推荐升级方式是刷写新镜像，前提是你拥有机器人的SSH 访问权限。完整步骤如下：

1. 在 Dustbuilder 中选择"Build for manual installation (requires SSH to install)"选项，之后会通过邮件收到一个tar.gz归档包的下载链接。
2. SSH 登录机器人。
3. 将 tar.gz 下载到/mnt/data目录并解压：

cd /mnt/data wget <url to tar from dustbuilder> tar xzf <file.tar.gz>

4. 机器人存在A/B 双系统，正在使用的系统不能被直接更新。默认你在系统 A，因此先在系统 A 下更新系统 B，然后重启进入系统 B：

./install_b.sh reboot

5. 重启后重新 SSH 登录（此时已在系统 B），反过来更新系统 A，再重启回系统 A 正常运行：

cd /mnt/data ./install_a.sh rm -f <file.tar.gz> reboot

完成上述步骤后，机器人即运行最新版本。

3.2 替代方案：直接替换二进制

除刷镜像外，也可以停止 Valetudo 服务后用 scp 直接替换二进制：

/etc/init/S11valetudo stop # 通过 scp 上传新二进制到对应路径 # 然后重启或重新启动服务

3.3 排障与兜底

• 升级后出现 "No Map Data" 或设置丢失等问题：建议直接做一次完整重刷（full reflash），这是官方文档明确给出的兜底手段；
• 没有 SSH 权限：无法手动升级，需要先对受支持的机型做**恢复出厂设置（factory reset）**以重新启用 OTA 更新，然后走首次安装流程。

四、手动升级 Dreame 吸尘器

Dreame 机型的手动升级更为直接——替换二进制文件即可：

1. SSH 登录吸尘器并停掉正在运行的 Valetudo：

killall valetudo

2. 用新版本二进制替换/data/valetudo下的旧二进制：

wget https://github.com/Hypfer/Valetudo/releases/latest/download/valetudo-{armv7,armv7-lowmem,aarch64} -O /data/valetudo

注意：

• 务必根据 supported robots 文档中的说明选择与机型匹配的正确二进制（armv7、armv7-lowmem或aarch64）；
• 如果遇到"Text file busy"错误，说明 Valetudo 仍在运行，先再次执行killall valetudo；
• 若问题依旧，先删除旧二进制，再上传新二进制。

3. 重启机器人：

reboot

Dreame 机型的 "Text file busy" 之所以出现，是因为 Linux 不允许覆盖正在执行的二进制文件——这正是内置更新器在 ValetudoUpdaterApplyStep.js 中采用"先写临时文件再rename原子替换"这一做法的原因，手动替换时则需要先确保进程退出。

五、升级方式选择速查

结语

从内置更新器的check → download → apply状态机，到 Roborock 的 A/B 双系统镜像刷写，再到 Dreame 的二进制直替，Valetudo 为不同版本、不同机型都设计了明确的升级路径。理解底层约束——嵌入式模式、机器人必须回充、磁盘空间门槛（40MB/20MB + UPX 兜底）、SHA-256 校验与"先写临时文件再原子替换"的策略——不仅能帮你顺利完成升级，也能在升级失败时快速定位根因。若升级后出现地图数据丢失等异常，请务必回到完整重刷的兜底方案。

• 物联网
• 后端
• 前端