用途:在 Internet Computer 的 canister 升级后保留状态。Rust 堆内存(thread_local! { RefCell<T> }、static)每次升级会被清空,需把数据放入 stable memory;Motoko 默认启用增强正交持久化,persistent actor 中的 let/var 自动跨升级保留,transient 声明会被清空。
主要能力:Rust 的 ic-stable-structures 提供 StableBTreeMap、StableCell、StableLog,可直读写 stable memory,无需在 pre_upgrade/post_upgrade 中序列化;MemoryManager 把 stable memory 划分为多个虚拟内存,每个结构用唯一 MemoryId,禁止复用。自定义类型需实现 Storable 的 BOUND、to_bytes、into_bytes、from_bytes,示例用 CBOR(ciborium);基本类型、String、Vec<u8>、Principal 已实现。建议用 Bound::Unbounded 避免加字段后反序列化失败。
使用方式:Rust 在 Cargo.toml 引入 ic-stable-structures = "0.7",用 #[init] 与 #[post_upgrade];Motoko 在 mops.toml 依赖 core = "2.0.0",moc >= 1.7.0,无需 stable 关键字与升级钩子,推荐设置 moc args = ["--default-persistent-actors"]。升级后数据应保持,可用 icp deploy 后再次调用查询验证。
限制:heap 内存上限 4GB/6GB,stable memory 可达数百 GB,但用 pre_upgrade 序列化大 HashMap 会触发指令上限并 brick;改变持久变量持有的 record 类型属于不兼容升级,需要迁移,规则由 migrating-motoko-actors 负责;不兼容升级被拒绝时旧状态保留,并非数据丢失。其余细节暂未提供。