solana-program-upgrade
Ein laufendes Solana-Programm upgraden und seine On-Chain-Kontodaten sicher migrieren -
Versionierung, lazy realloc-Migration, Fork-Simulation, Upgrade-Authority-Hygiene
und Rollback. Dies ist der mit Abstand katastrophalste Lebenszyklusschritt in der Solana-Entwicklung,
und dieser Guide macht ihn überlebbar.
Addon zu
solana-dev-skill. Dieses Skill besitzt die Grundlagen von Greenfield Anchor/Pinocchio/Testing. Dieses Skill besitzt nur den Upgrade + Migrations-Lifecycle - greife darauf zu, sobald ein Programm bereits deployed ist und geändert werden muss.
Goldene Regeln (das Sicherheitsfundament)
- Ändere niemals ein Live-Account-Layout ohne Versionstag + Migrationspfad.
Alte Accounts sind rohe Bytes; neuer Code, der sie mit einem geänderten Struct liest ->
AccountDidNotDeserializeoder stille Korruption. Der 8-Byte-Diskriminator schützt den Typ, nicht die Version. - Simuliere gegen echten geklonten Mainnet-Zustand, bevor es ans Mainnet geht. Führe immer das exakte Upgrade + Migration auf einem Fork durch und vergleiche die Account-Bytes. Keine Ausnahmen.
- Multisig für die Upgrade-Authority. Ein einzelner Hotkey, der die gesamte Programmlogik ersetzen kann, ist ein Rug/Compromise-Vektor. Verschiebe ihn zu Squads v4.
- On-Chain-Datenmigrationen sind normalerweise vorwärtsgerichtet. Gestalte sie additiv und fortsetzbar; gehe nicht davon aus, dass du Daten zurücksetzen kannst.
- Behalte die vorherige
.so. Du kannst den Code immer schnell zurückrollen, auch wenn die Daten nicht rückgängig gemacht werden können. - Verwende standardmäßig Devnet/Localnet/Fork. Zielniemals automatisch Mainnet in irgendeinem Beispiel.
Der Upgrade-Workflow
In dieser Reihenfolge vorgehen. Jeder Schritt führt zu einer fokussierten Datei für die Vertiefung.
- Schema diff - vergleiche alte und neue
#[account]-Structs. Identifiziere additive vs. brechende Änderungen (Reihenfolge ändern/entfernen/Typ ändern = brechend). - Wähle eine Strategie - eager crank vs. lazy migrate-on-touch vs. copy-to-new-account ->
migration-strategies.md. - Schreibe versionierte Structs - füge einen Versionstag hinzu, verzweige basierend auf der
gespeicherten Version ->
account-versioning.md. - Implementiere die Migration - manuelles
realloc(portable Baseline) ->realloc-migration.md; oder der AnchorMigration-Typ falls deine Version ihn hat ->anchor-migration-type.md. - Simuliere auf einem Fork - klone echte Accounts, führe das Upgrade durch, diff die Bytes,
überprüfe Idempotenz ->
fork-simulation.md. - Sichere die Authority - überprüfe/verschiebe zu Squads Multisig, bevor du Mainnet berührst
->
upgrade-authority.md. - Deploye das Binary - Buffer-Flow,
extendfalls größer, IDL,--final->program-deploy-upgrade.md. - Verifiziere und behalte einen Rollback-Plan - bestätige, dass Accounts deserialisieren; behalte die vorherige
.sound einen Halbmigrations-Wiederherstellungspfad ->rollback-recovery.md.
Routing-Tabelle
Finde die Zeile, die zu deiner Situation passt, und lies diese Datei.
| Symptom / Aufgabe | Lies |
|---|---|
AccountDidNotDeserialize / Größenkonflikt / falsche Werte nach einem Upgrade | account-versioning.md, dann realloc-migration.md |
Hinzugefügtes/entferntes/umgestelltes/neues Feld in einem #[account]-Struct | account-versioning.md |
| „Wie versioniere ich meinen Account, damit ich ihn später ändern kann? |