---
tags: [部署, 架構決策]
gloss: 23 個 component worker 不各裝依賴，改成 root 共享一次 install + manifest 內容指紋跳過未變動——減 23× node_modules 膨脹。
---
# Self-Hosted 部署 — 共享 install 加指紋跳過

← [[decisions/00-INDEX]]

**來源**：`system-dev/wiki/decisions-summary.md`（self-hosted 部署）、`cli/src/lib/deploy.ts` §2.5
**最後更新**：2026-06-27

## 摘要
tarball 解開後不每個 component worker 各裝 node_modules（23× 重複 ~324MB），改成 root 共享一次 install；同時用 content hash manifest 記錄部署狀態，相同 hash 跳過已部署 worker，只部署內容變動者。

## 重點
- **問題**：23 個 component worker 的 runtime dep 全是 hono（tier2 另需 zod/mcp-sdk/yaml），各裝 ~324MB node_modules = 23× 重複；且冪等重跑被誤解成「每次重做全部」，22 個沒變的白跑一遍。
- **共享 install 機制**：
  - tarball 根目錄裝一次 hono + wrangler + tier2 deps
  - 各 worker 靠 Node.js 往上搜索路徑 resolve dependencies
  - `wrangler deploy --dry-run` 驗證 tier1+tier2 都被 bundle（確保包完整）
  - 結果：207MB×1 取代 324MB×23
- **Manifest 跳過**：
  - `~/.arcrun/deploy-manifest.json` 記錄 content hash + 上次成功時間戳
  - 新解開 tarball → 算 content hash 與上次成功者比較 → 相同跳過、不同重部
  - Hash 含 accountId（換帳號/KV namespace → 自動重部，不誤跳）
  - `--force` flag 清空 manifest → 全部重新部署
- **失敗恢復**：共享 install 失敗 → 自動退回各 worker 自裝（不破壞既有路徑）
- **只記成功**：manifest 只追蹤成功部署者，失敗者下次必重試

## 實體
- **共享 install**（shared installation）— root 目錄的單一 node_modules，所有 worker 共享。
- **Manifest**（部署清單）— `~/.arcrun/deploy-manifest.json`，記錄 content hash 和成功部署狀態。
- **Content hash**（內容雜湊）— 本次 tarball 內容的唯一指紋，用於比較是否變動。
- **Component worker**（零件 Worker）— `.component-builds/{name}/` 下各個獨立部署單位。

## 關聯
### 內文知識關係
- 共享 install >> 減少 >> 重複 node_modules
- Manifest >> 跳過 >> 未變動 component worker
- Content hash >> 相同時 >> 自動跳過部署
- accountId >> 不同時 >> 強制重新部署
### 卡片關係
- [[self-hosted部署-共享install加指紋跳過]] >> 優化 >> [[不依賴CI-執行鏈路vs零件投稿]]