solana-program-upgrade 是做什么的？
安全地升级一个已部署的 Solana 程序并迁移其链上账户数据——
版本控制、惰性 realloc 迁移、分叉模拟、升级权限卫生以及回滚。这是 Solana 开发中最具灾难性的生命周期步骤，让这一步变得可生存。
补充于
solana-dev-skill。 该技能负责全新的 Anchor/Pinocchio/测试基础。这个技能只负责 升级 + 迁移生命周期——一旦程序已部署并需要更改，才使用它。
黄金法则（安全脊柱）
- 没有版本标签和迁移路径，绝不要更改活动账户的布局。
旧账户是原始字节；使用更改后的结构体读取它们的新代码会导致
AccountDidNotDeserialize或静默损坏。8 字节鉴别器控制的是 类型，而不是版本。 - **在上主网之前，针对真实的克隆主网状态进行模拟。**始终先在一个分叉上运行 精确的升级 + 迁移，并对比账户字节。没有例外。
- **升级权限使用多签。**一个可以替换所有 程序逻辑的热密钥是 rug/妥协向量。将其移至 Squads v4。
- **链上数据迁移通常是只向前的。**设计为增量的和可恢复的；不要假设你可以 还原数据。
- **保留之前的
.so。**即使数据无法还原，你总能快速回滚代码。 - **默认使用 devnet/localnet/fork。**在任何示例中，绝不要自动针对主网。
升级工作流
按顺序执行。每一步都引导到一个专注的文件以获取深度。
- 对比模式 - 比较旧
#[account]结构体与新#[account]结构体。识别 增量更改 vs 破坏性更改（重新排序/移除/修改类型 = 破坏性）。 - 选择策略 - 主动任务 vs 惰性按需迁移 vs 复制到新账户
->
migration-strategies.md。 - 编写版本化结构体 - 添加版本标签，根据存储的版本分支
->
account-versioning.md。 - 实现迁移 - 手动
realloc（可移植基线） ->realloc-migration.md；或者 AnchorMigration类型（如果你的版本支持它） ->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 |
| 惰性“按需迁移” vs 主动一次性迁移 | 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 |
| 批量/任务/看门人迁移，分页，进度跟踪 | 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（模式对比 -> 迁移计划 + 风险评估），/simulate-upgrade（分叉，克隆，运行，对比），/check-upgrade-authority（审计单密钥 vs 多签）。 - 智能体：
program-migration-architect（根据模式对比设计迁移），migration-qa-engineer（编写分叉/LiteSVM 测试，验证无损坏）。 - 规则：
account-layout-guard在编辑#[account]结构体 /state.rs时自动触发，并要求版本提升 + 迁移路径。
准确性契约
路由文件中提到的每个 CLI 标志、Anchor 约束、crate 和账户类型
必须是真实且可验证的。当不确定时，根据已安装的
版本（anchor --version，solana --version，Anchor 变更日志）进行验证 - 绝不要
编造。将 Migration 类型视为可能尚未发布；手动 realloc
模式是默认的可移植方案。