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 下載頁 的請求就能重新拉到有效索引。