Fleet 的客户端分两套发布:Fleet Agent 面向 Linux 机器,Fleet Desktop 面向 Windows。两边检查更新时都去 releases.leaflow.net 拿对应的 v1/index.json(比如 /fleet-agent/v1/index.json),解析出 channels.stable.version,再到 dl.leaflow.net 拉实际的安装包和 SHA-256。Leaflow 官网的下载页和 /api/download/... 跳转路由复用了这份索引。
索引文件本身放在对象存储里,经 CDN 分发。只靠 HTTPS 没法覆盖存储桶误操作、镜像被改写或者 CDN 长时间返回过期缓存这些情况,所以我们在索引外层加了签名,并让客户端和官网执行同一套校验逻辑。
为什么把索引放进 DSSE 信封
做这层签名的时候没往索引 JSON 里直接塞 signature 字段。Go(客户端)和 Node.js(官网)对 JSON 键排序、空白符和转义字符的默认行为不一样,硬做 canonical JSON 规范化会多出不少边界问题;而且裸字节签名不带类型信息,别处签出来的东西容易跨场景混用。
我们最后采用了 DSSE(Dead Simple Signing Envelope)v1 格式。外层只有三个字段,发布流水线把索引 JSON 序列化后转成 Base64 放进 payload,校验端先拿原始字节验签,验签成功后再 JSON.parse:
{
"payloadType": "application/vnd.leaflow.release-index.v1+json",
"payload": "eyJwcm9kdWN0IjoiZmxlZXQtYWdlbnQiLC4uLn0=",
"signatures": [
{
"sig": "<base64-ed25519-signature>"
}
]
}签名算法固定用 Ed25519,公钥在客户端和官网代码里以 Base64 字符串硬编码,运行时转成 OKP JWK 交给 Node.js node:crypto 的 verify()(客户端侧对应 Go 标准库 crypto/ed25519)。签名的输入按 DSSE 规范拼成 PAE(Pre-Authentication Encoding),把 payloadType 和解码后的 payload 分别加上字节长度前缀:
function buildPae(payloadType: string, payloadBase64: string): Buffer {
const type = Buffer.from(payloadType);
const payload = Buffer.from(payloadBase64, 'base64');
return Buffer.concat([
Buffer.from(`DSSEv1 ${type.length} `),
type,
Buffer.from(` ${payload.length} `),
payload,
]);
}payloadType 写进了 PAE 的最前面,签给别处用的信封拿来冒充发布索引,验签这一步就会直接失败。
客户端与官网的校验清单
官网在渲染下载页和响应 /api/download/... 跳转前,会执行和客户端一致的校验流程,任意一步不满足就抛错退出:
| 检查项 | 对应风险 | 校验规则 |
|---|---|---|
| 响应体积 | 异常上游响应打满内存 | 响应文本超过 256 KiB(256 << 10)直接丢弃 |
| 信封与签名 | 索引被篡改或伪造 | payloadType 完全匹配,且至少一条 Ed25519 签名对得上该产品的固定公钥 |
| 产品字段 | 拿其他产品的有效签名索引跨产品替换 | 解码后的 index.product 与请求的产品名一致 |
| 有效期 | 攻击者或过期缓存重放旧版本索引 | index.expires_at * 1000 大于当前时间戳 |
| 产物路径与校验值 | 镜像路径跳出目录或畸形哈希 | path 匹配 ^v[\w.+-]+/[\w.+-]+$,sha256 为 64 位小写十六进制 |
公钥轮换的处理方式
每个产品的公钥配置写成字符串数组,验签时只要数组中任意一把公钥能对上信封里的任意一条签名即可:
const RELEASE_KEYS = {
'fleet-agent': ['<current-ed25519-public-key>'],
'fleet-desktop/windows': ['<current-ed25519-public-key>'],
} as const;需要更换发布私钥时,先给客户端和官网发一版把新公钥追加进数组,同时留着旧公钥;等活跃版本都带上新公钥后,发布流水线切到新私钥签发 index.json;旧签名索引过了 expires_at 以后,下一版再把旧公钥删掉。
channels.stable.version 指向哪个版本,页面和下载接口就取 releases 里对应的那一项,并将产物相对路径拼到 mirrors[0] 上。
官网服务端的缓存与并发合并
releases.leaflow.net 没有对浏览器开放跨域,索引完全在官网的 Node 服务端读取,缓存间隔设为 300 秒(五分钟)。
这里叠了两层缓存。第一层是 Next.js 的 fetch 数据缓存(next: { revalidate: 300 })配合 10 秒超时(AbortSignal.timeout(10_000)),和下载页的页面重新验证间隔保持一致。第二层是进程内的 memo():下载接口每次被点击都会调用 latestRelease(),并发进来的一批请求会拿到同一个正在执行的 Promise,不会重复去拉索引和反复做 Ed25519 验签。
memo() 在 Promise 拒绝时会立刻删掉对应的键(value.catch(() => entries.delete(key)))。上游抖动或者签发异常恢复之后,下一个访问 Fleet Agent 下载页 或 Fleet Desktop 下载页 的请求就能重新拉到有效索引。