solana-program-upgrade
安全地升級線上 Solana 程式並遷移其鏈上帳戶資料 - 版本控制、惰性 realloc 遷移、分支模擬、升級權限衛生與回滾。這是 Solana 開發中最具災難性的生命週期步驟，讓它變得可應對。
solana-dev-skill的附加技能。 該技能負責全新 Anchor/Pinocchio/測試基礎。此技能僅負責升級 + 遷移生命週期 - 一旦程式已部署且需要變更時才使用。
黃金法則（安全主幹）
- 絕不要在沒有版本標籤和遷移路徑的情況下更改線上帳戶佈局。 舊帳戶是原始位元組；新程式使用已變更的結構體讀取舊帳戶 ->
AccountDidNotDeserialize或靜默資料損毀。8 位元組鑑別器控制的是類型，而非版本。 - 在正式環境前，先針對真實克隆的主網狀態進行模擬。 始終先在分支上執行精確的升級和遷移，並比較帳戶位元組。沒有例外。
- 升級權限使用多重簽章。 單一熱鍵可以替換所有程式邏輯，是詐騙/攻擊向量。將其移至 Squads v4。
- 鏈上資料遷移通常只能是前向的。 設計為增量且可恢復的；不要假設你可以還原資料。
- 保留先前的
.so檔案。 即使資料無法還原，你總是可以快速回滾程式碼。 - 預設使用 devnet/localnet/分支。 在任何範例中都不要自動以主網為目標。
升級工作流程
依序進行。每個步驟會導向特定的深度文件。
- 比對 schema - 比較新舊
#[account]結構體。識別增量變更與破壞性變更（重新排序/移除/變更類型 = 破壞性）。 - 選擇策略 - 積極 crank 與惰性遷移（使用時觸發）與複製到新帳戶 ->
migration-strategies.md。 - 編寫版本化結構體 - 新增版本標籤，根據儲存的版本進行分支 ->
account-versioning.md。 - 實作遷移 - 手動
realloc（可移植的基準線） ->realloc-migration.md；或 Anchor 的Migration類型（如果你的版本支援） ->anchor-migration-type.md。 - 在分支上模擬 - 克隆真實帳戶，執行升級，比較位元組，驗證冪等性 ->
fork-simulation.md。 - 保護權限 - 在觸碰主網前，驗證/移至 Squads 多重簽章 ->
upgrade-authority.md。 - 部署二進位檔 - buffer 流程，如果更大則
extend，IDL，--final->program-deploy-upgrade.md。 - 驗證並保留回滾計劃 - 確認帳戶能反序列化；保留先前的
.so和半遷移恢復路徑 ->rollback-recovery.md。
路由表
根據情況找到對應的行，並閱讀該文件。
| 症狀/任務 | 閱讀 |
|---|---|
AccountDidNotDeserialize / 大小不符 / 升級後值錯誤 | account-versioning.md，然後 realloc-migration.md |
在 #[account] 結構體中新增/移除/重新排序/變更了欄位類型 | account-versioning.md |
| "我該如何為帳戶加上版本，以便之後可以變更？" | account-versioning.md |
| 需要就地增加/縮小現有帳戶 | realloc-migration.md |
| 惰性「使用時遷移」與積極的一次性遷移 | realloc-migration.md，migration-strategies.md |
realloc::zero 過時位元組的陷阱 / 租金補充方向 | realloc-migration.md |
| 每個指令 10 KB 的 realloc 增長限制，大規模增長 | realloc-migration.md |
想要新的 Anchor Migration<'info, From, To> 類型 | anchor-migration-type.md |
AccountAlreadyMigrated / AccountNotMigrated 錯誤 | anchor-migration-type.md |
| 選擇積極 vs 惰性 vs 複製到新帳戶 | migration-strategies.md |
| 遷移大量帳戶集合（例如數萬個）的廉價方式 | migration-strategies.md |
| 批次/crank/keeper 遷移、分頁、進度追蹤 | migration-strategies.md |
| 就地 realloc 不可行（資料縮小、類型變更） | migration-strategies.md |
| 重新部署/升級程式二進位檔 | program-deploy-upgrade.md |
solana program write-buffer / deploy --buffer 流程 | program-deploy-upgrade.md |
新的 .so 比已部署的大（solana program extend） | program-deploy-upgrade.md |
升級 IDL（anchor idl upgrade） | program-deploy-upgrade.md |
| 就地部署 vs 新程式 ID（對 PDA/帳戶的影響） | program-deploy-upgrade.md |
| 誰控制程式？單一金鑰 vs 多重簽章 | upgrade-authority.md |
| 將升級權限移至 Squads v4 多重簽章 | upgrade-authority.md |
set-upgrade-authority、時間鎖、金鑰管理 | upgrade-authority.md |
使程式不可變（--final）及其代價 | upgrade-authority.md |
| 在正式環境前測試升級 / 克隆真實狀態 | fork-simulation.md |
| Surfpool 主網分支；比較前後帳戶位元組 | fork-simulation.md |
| 遷移指令的 LiteSVM / Mollusk 單元測試 | fork-simulation.md |
| 證明遷移是冪等的（執行兩次 = 無操作） | fork-simulation.md |
| 升級出錯 - 快速恢復舊程式碼 | rollback-recovery.md |
| 半遷移的帳戶集合；安全恢復 | rollback-recovery.md |
| 暫停 / 遷移保護 / 緊急功能開關 | rollback-recovery.md |
| 原生 / Pinocchio 程式（無 Anchor 糖衣） | realloc-migration.md，account-versioning.md |
| 權威連結與文件（驗證當前版本） | resources.md |
配套工具
- 指令：
/plan-upgrade（schema 差異分析 -> 遷移計劃 + 風險報告），/simulate-upgrade（分支、克隆、執行、差異分析），/check-upgrade-authority（審計單一金鑰 vs 多重簽章）。 - 代理：
program-migration-architect（根據 schema 差異設計遷移），migration-qa-engineer（編寫分支/LiteSVM 測試，驗證無資料損毀）。 - 規則：
account-layout-guard會自動在編輯#[account]結構體 /state.rs時觸發，並要求版本提升加上遷移路徑。
準確性合約
路由文件中的每個 CLI 標誌、Anchor 約束、crate 和帳戶類型都必須是真實且可驗證的。如果不確定，請根據已安裝的版本（anchor --version，solana --version，Anchor 變更日誌）進行驗證 - 絕不虛構。將 Migration 類型視為可能尚未釋出；手動 realloc 模式是可移植的預設方式。