技术实践 ·

Fleetd 客户端怎么更新?签名校验、版本判断与失败恢复

结合 Fleetd v0.3.0 源码,拆解发布包签名、架构与版本校验、新程序自检及替换流程,解释手动回滚与自动健康回滚的区别。

远程管理工具最怕的事情之一,是更新客户端以后,再也连不上那台机器。

服务器就在旁边时,还能登录进去修;软路由在另一个地方,更新一旦把连接弄断,后台那个“重试”按钮未必帮得上忙。

所以,接着前面五篇 Fleetd 开发记录,这次聊客户端更新。它不只是下载一个新文件,还要回答三个问题:这个文件能不能信,适不适合这台机器,换上去之后出问题怎么办?

先明确范围:本文依据 Fleetd v0.3.0,提交 c4a066d 的公开源码与文档。这个版本支持管理员发起的远程更新,没有定时自动追新,也没有基于运行健康检查的自动回滚。文中的故障验收是建议,不是一次已经完成的线上升级演练。

远程更新,先把“谁决定什么”分开

Fleetd 的更新流程从后台发起。管理员上传发布包,为单台在线机器选择版本,也可以更新同一架构上版本较旧的在线机器。[1]

服务端负责分发包和传递更新请求,客户端负责决定是否接受。

这个区别很重要:文件出现在自己的后台里,不应该自动等于可信。客户端本地配置了发布公钥 release_key,收到包后必须自行验签;没有配置这个公钥,就拒绝远程更新。[2]

服务端如果也配置了发布公钥,会在上传阶段校验发布包。但服务端这一关不能代替客户端的一关。源码中,服务端未配置发布公钥时可以只解析包的清单用于存储和展示,因此“上传成功”并不能证明客户端一定接受它。[4]

发布私钥决定谁能够制作被信任的包,公钥决定客户端信任谁。自行部署时,应当明确自己的发布密钥归属,而不是把下载到的任意发布包都当成可安装文件。

这也不同于前文的浏览器命令签名:命令签名用于授权具体操作,发布签名用于确认软件包。两者职责和密钥管理不能混为一谈。

签名不是只给文件算一个哈希

v0.3.0 的发布包包含清单、签名和客户端二进制。清单记录版本、CPU 架构、文件大小和 SHA-256。[3]

签名覆盖清单的原始字节,清单里的哈希再约束二进制内容。客户端先用受信公钥验证 Ed25519 签名,再检查二进制的大小和哈希是否与清单一致。

这解决的是两个相连的问题:

  • 清单是否由持有对应私钥的人签发,有没有被改动?
  • 下载到的二进制是否确实是这份清单描述的文件?

只有哈希、没有可信签名来源,不能完成同样的工作。如果攻击者能同时替换文件和旁边的哈希值,两者仍然可以“对得上”。

但有效签名也不证明软件没有 bug。它证明文件来自受信的签发流程,而不是证明程序在所有机器上都运行正常。发布私钥泄露、构建环境出问题,或者维护者自己签出了有缺陷的程序,都需要另外处理。

版本和架构,要由客户端再次判断

验签之后,客户端还会检查清单架构是否等于自身的 runtime.GOARCH,以及清单版本是否比当前运行版本更新。[2]

因此,一个签名正确的 arm64 包,也不能因为出现在后台列表里,就装到 amd64 客户端上。

版本判断也有具体边界。v0.3.0 比较的是三个整数组成的主版本、次版本和修订号;它会忽略连字符后面的后缀。[3]

例如,按这个函数的规则,0.4.0-dev 和 0.4.0 的版本核心相同,后者不会被判成比前者更新。这不是完整的语义化版本预发布排序规则,不能拿一般的 SemVer 直觉替代源码行为。

同版本和较旧版本会被拒绝。这可以阻止通过正常更新入口随意降级,但它不是所有层面的防回退机制:有本地文件修改权限的人仍然能替换程序,恢复旧文件也是文档明确提供的维护途径。

日常发布时,应当让发布清单与二进制内嵌版本一致。项目的构建脚本会设置程序版本;在提供发布版本和签名私钥文件时,还会生成对应架构的签名包。[5]

替换之前,先让新程序回答一次版本号

客户端不会下载完就马上覆盖自己。

它先把验过的二进制写到可执行文件旁边的 .new 文件,再运行这个新文件的 version 子命令,要求程序在限定时间内结束,且输出与签名清单的版本一致。[2]

这一步能挡住一部分明显错误,例如程序无法启动、构建产物不对,或者报告了另一个版本。

它仍然只是一个很小的自检。能输出版本号,不代表读取配置、连接服务端、采集指标、执行授权操作这些路径全部正常。已经通过 version 的程序,仍可能在正常启动时失败。

自检通过之后,程序尝试保留 .old 旧文件,再通过重命名把 .new 替换到正式路径。把临时文件放在同一目录,是这个替换流程的一部分;不能把它理解成任意跨文件系统复制都具备同样行为。

替换完成后,当前进程报告结果并退出,后续启动交给 systemd 或 procd。项目安装模板为它们配置了重启机制;如果你手动运行客户端,或者自己改过服务配置,就要单独确认谁负责把新程序拉起来。

所以,后台收到安装成功结果,和新进程已经健康上线,是两个时间点。

失败恢复,要看失败发生在哪里

“失败会回滚”这句话太笼统。按 v0.3.0 的实现,至少要区分以下阶段:

失败阶段 当前实现会做什么 还需要确认什么
下载、签名、内容、架构或版本检查失败 返回错误,不替换正式程序 错误原因是否已记录,原客户端是否仍正常工作
新程序版本自检失败 删除临时文件,保留正式程序 是否是构建、运行环境或版本标记问题
替换重命名失败 返回错误并清理临时文件 目录权限、文件系统与磁盘状态
替换后,新进程启动或业务运行失败 没有基于健康状态的自动回滚流程 带外登录、旧文件、配置备份和人工恢复能力

还有一个容易忽略的细节:源码先尝试硬链接保存旧程序,失败后尝试读写复制;这条备用路径上的部分失败没有阻止后续替换。[2]

因此,不能仅凭实现里出现 .old,就承诺每次都已经生成了可用备份。正式发布前应验证旧文件确实存在、内容正确、能够执行,并保留独立恢复入口。

同样,重命名替换不是整机升级事务,也不等于断电后的数据持久性保证。本文没有对断电、磁盘故障或实际 OpenWrt 设备进行验证。

先更新一台,再谈批量

项目文档明确说明没有做全自动更新:有缺陷的版本如果同时推到所有机器,可能让所有客户端掉线,而掉线之后就无法再依赖这个后台修复。[1]

我更愿意把更新验收拆成三段。

第一段是安装前拒绝测试。在隔离环境准备错误签名、被修改的内容、错误架构、相同或较旧版本,确认客户端拒绝安装,正式文件没有被替换。

第二段是替换测试。检查新程序版本自检、旧文件保存,以及服务管理器是否真正启动了新进程。

第三段是上线后的业务检查。确认新版本重新连接、指标继续上报、必要操作能够完成,观察一段适合自身业务的时间,再扩大范围。这里不规定一个通用的“等几分钟就安全”门槛。

仓库已有发布包和安装逻辑测试,覆盖错签名、文件篡改、版本和架构拒绝、版本输出不一致,以及正常替换后保留旧文件等路径。[6] 本次阅读了这些测试,但没有重新运行,也没有把它们当成真实设备升级成功的证据。

如果新程序已经失联,恢复需要按部署环境操作。官方指南提供的是手动替换旧二进制后重启服务的方式;Linux 与 OpenWrt 的程序路径和服务管理方式不同,不宜照抄另一类机器的命令。[1]

一次可靠的更新,应该以“机器重新上线并完成必要工作”为结束条件。签名和版本检查是前面的门,后面的恢复路径也必须留着。

参考资料

核对日期:2026-11-09。实现分析固定在 v0.3.0,不代表后续版本行为。前一篇:服务器监控之后,怎样让告警真正有用?

  1. Fleetd v0.3.0:客户端更新指南。
  2. 客户端更新与自检实现。
  3. 发布包签名、校验与版本比较。
  4. 服务端发布包上传及分发。
  5. 构建脚本与客户端服务安装模板。
  6. 安装测试与发布包测试。

AI 生成的概念配图,不是产品实测照片、真实界面或接线图。