4.3 云存储与游戏设计
4.1/4.2 讲接口与冲突,这一节讲把云存储接进游戏时的架构设计:存档文件怎么组织、怎么升级、怎么防坏。工程目标是:换机不丢档、更新不坏档、存档可信。
本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamremotestorage.h。
本章与站内既有内容的分工
- Steam 发行专题 (操作手册)讲「后台云存储容量」;本节讲「代码里设计云存档结构的工程语义」。
- 卷一讲云存档如何支撑长期产品;本节讲版本迁移、原子提交、配额治理。
- lab 用纯 C++ 模拟多文件存档系统,不依赖 Steam 客户端运行。
多文件存档与原子提交
单文件存档脆弱:写一半崩溃 = 全丢。工程做法是清单 + 数据多文件 + 批量原子提交:
// isteamremotestorage.h:BeginFileWriteBatch / EndFileWriteBatch(SDK v1.65 头文件摘录,已删减)
// Indicate to Steam the beginning / end of a set of local file
virtual bool BeginFileWriteBatch() = 0;
virtual bool EndFileWriteBatch() = 0;
工程语义:
- 清单文件记录「版本 + 校验和」:
v=<version>;sum=<checksum>,数据文件存实际存档字节;加载时以清单版本为准。 BeginFileWriteBatch/EndFileWriteBatch把多个文件包成一个原子单位:数据写入失败 → 整批回滚,清单不落盘;避免「清单已新、数据已旧」的坏档。- 规范幂等:同一状态反复保存,数据文件逐字节一致,不产生冗余差异。
版本迁移与防篡改
存档会随游戏版本演进;旧存档要能显式迁移到当前架构:
工程语义:
- 迁移是显式动作:读到旧版本存档后,游戏主动升级(如 v1 → v3),迁移函数把数据改写并原子回写,存档版本升到当前版本。
- 禁止降级:已有新版本存档再写旧版本内容应被拒绝——防止新版本数据被旧逻辑覆盖。
- 校验和防篡改:清单里存数据文件的校验和,加载时重算比对;数据被改/损坏 → 拒绝加载(宁可提示坏档,不载入错误数据)。
- 空数据存档合法:空字节也是合法存档(如「未开始」状态),不能因数据为空而判定坏档。
配额预算与高水位
云存档有配额(4.1 的 GetQuota);设计上要预算 + 预警:
// isteamremotestorage.h:GetQuota(SDK v1.65 头文件摘录,已删减)
virtual bool GetQuota( uint64 *pnTotalBytes, uint64 *puAvailableBytes ) = 0;
工程语义:
- 写入前看可用空间:
GetQuota返回总量与可用;保存前预算「新档大小 ≤ 可用」,否则提示用户或降级(如去掉大截图)。 - 高水位预警:已用空间超过阈值(本 lab 用 80% 的模型假设阈值)时就提醒清理或改存小格式——不要等到写不进去才处理。
- 真实配额以官方为准:mock 用 1MB 模拟总量复现预算与预警的工程逻辑。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamremotestorage.h | BeginFileWriteBatch/EndFileWriteBatch | 多文件原子提交 |
isteamremotestorage.h | FileWrite/FileRead | 清单与数据文件落盘/读取 |
isteamremotestorage.h | GetQuota | 总量与可用配额 |
isteamremotestorage.h | GetFileTimestamp/FilePersisted | 版本与已同步判定 |
数据口径与来源
- 批量提交、配额接口签名:SDK v1.65
public/steam/isteamremotestorage.h可实证。 - 版本迁移、校验和、禁止降级、高水位 80%:本 lab 的工程设计与模型假设,非 SDK 强制行为/非官方数值,以官方文档为准。
- 各账号实际配额:partner 文档登录后可见,以官方当前为准。
以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。
可运行产物:C++ 最小验证
下面的仿真复现「云存储与游戏设计」的工程语义:多文件存档以 BeginFileWriteBatch/EndFileWriteBatch 原子提交(失败即回滚)、带版本号的清单 + 数据文件结构、加载时的显式版本迁移、校验和防篡改、配额预算与高水位预警、规范幂等与禁止降级。它与 src/04-3-cloud-storage-design.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:
// file: src/04-3-cloud-storage-design.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/04-3-cloud-storage-design.cpp -o bin/04-3-cloud-storage-design && ./bin/04-3-cloud-storage-design
//
// mock:复现「云存储与游戏设计」的工程语义——多文件存档以
// BeginFileWriteBatch/EndFileWriteBatch 原子提交(失败即回滚)、
// 带版本号的清单 + 数据文件结构、加载时的显式版本迁移、校验和防篡改、
// 配额预算与高水位预警、同一状态保存的规范幂等性、禁止降级。
// 签名对照 SDK v1.65 isteamremotestorage.h,非 Valve 实现。
#include "verify.h"
#include <cstdint>
#include <map>
#include <string>
#include <vector>
namespace steam_repro {
class MockCloudSaveSystem {
public:
explicit MockCloudSaveSystem(int currentVersion) : currentVersion_(currentVersion) {}
// isteamremotestorage.h:BeginFileWriteBatch / EndFileWriteBatch 语义:
// 一批写操作要么全部落盘、要么整体丢弃。
static constexpr uint64_t kQuotaTotalBytes = 1024ULL * 1024; // mock 1MB
static constexpr double kHighWaterRatio = 0.8;
// 保存:清单 + 数据两个文件在同一批量内提交。
// 版本不能低于已有清单版本(禁止降级)。
bool saveGame(int slot, int version, const std::vector<uint8_t>& data) {
if (version < slotVersion(slot)) return false; // 禁止降级
beginBatch_();
bool dataOk = writeData_(slot, data);
if (!dataOk) {
abortBatch_();
return false;
}
writeManifest_(slot, version, checksum_(data));
endBatch_();
slots_[slot] = version;
return true;
}
// 读取:校验数据校验和;版本以清单为准(迁移由 migrateSave 显式触发)
bool loadGame(int slot, std::vector<uint8_t>* out, int* version) {
auto man = manifests_.find(slot);
auto data = datas_.find(slot);
if (man == manifests_.end() || data == datas_.end()) return false;
if (checksum_(data->second) != parseSum_(man->second)) return false; // 防篡改
*version = parseVersion_(man->second);
*out = data->second;
return true;
}
// 显式迁移:把旧版本存档升级到当前架构版本并原子回写
bool migrateSave(int slot) {
auto man = manifests_.find(slot);
auto data = datas_.find(slot);
if (man == manifests_.end() || data == datas_.end()) return false;
int fromVersion = parseVersion_(man->second);
if (fromVersion >= currentVersion_) return false;
std::vector<uint8_t> migrated = data->second;
migrated.push_back(static_cast<uint8_t>(0xC0 + fromVersion)); // 迁移标记
beginBatch_();
writeData_(slot, migrated);
writeManifest_(slot, currentVersion_, checksum_(migrated));
endBatch_();
slots_[slot] = currentVersion_;
return true;
}
// 同一状态两次保存 → 数据文件逐字节一致(规范幂等)
bool isCanonical(int slot, const std::vector<uint8_t>& data) const {
auto it = datas_.find(slot);
return it != datas_.end() && it->second == data;
}
int slotVersion(int slot) const {
auto it = slots_.find(slot);
return it == slots_.end() ? 0 : it->second;
}
// isteamremotestorage.h:GetQuota:总量与可用
bool getQuota(uint64_t* pnTotalBytes, uint64_t* puAvailableBytes) const {
*pnTotalBytes = kQuotaTotalBytes;
uint64_t used = usedBytes_();
*puAvailableBytes = kQuotaTotalBytes - std::min(used, kQuotaTotalBytes);
return true;
}
bool warnHighWater() const {
return static_cast<double>(usedBytes_()) >= kQuotaTotalBytes * kHighWaterRatio;
}
size_t slotCount() const { return slots_.size(); }
// 测试辅助:让下一次数据写入失败(模拟写盘错误)
void failNextWrite(bool fail) { failNextWrite_ = fail; }
// 测试辅助:篡改数据文件内容(模拟磁盘损坏/被修改)
void tamperData(int slot) {
auto it = datas_.find(slot);
if (it != datas_.end() && !it->second.empty()) it->second[0] ^= 0xFF;
}
bool manifestExists(int slot) const { return manifests_.find(slot) != manifests_.end(); }
bool dataExists(int slot) const { return datas_.find(slot) != datas_.end(); }
private:
static uint32_t checksum_(const std::vector<uint8_t>& data) {
uint32_t sum = 0;
for (uint8_t b : data) sum = sum * 31 + b;
return sum;
}
static uint32_t parseSum_(const std::string& manifest) {
size_t pos = manifest.find("sum=");
if (pos == std::string::npos) return 0;
return static_cast<uint32_t>(std::stoul(manifest.substr(pos + 4)));
}
static int parseVersion_(const std::string& manifest) {
size_t pos = manifest.find("v=");
if (pos == std::string::npos) return 0;
return std::stoi(manifest.substr(pos + 2, manifest.find(';') - pos - 2));
}
void beginBatch_() { staging_.clear(); }
void endBatch_() {
for (const auto& kv : staging_) commitOne_(kv.first, kv.second);
staging_.clear();
}
void abortBatch_() { staging_.clear(); }
bool writeData_(int slot, const std::vector<uint8_t>& data) {
if (failNextWrite_) {
failNextWrite_ = false;
return false;
}
staging_["data:" + std::to_string(slot)] = std::vector<uint8_t>(data);
return true;
}
void writeManifest_(int slot, int version, uint32_t sum) {
std::string manifest = "v=" + std::to_string(version) + ";sum=" + std::to_string(sum);
staging_["man:" + std::to_string(slot)] =
std::vector<uint8_t>(manifest.begin(), manifest.end());
}
void commitOne_(const std::string& key, const std::vector<uint8_t>& value) {
if (key.rfind("data:", 0) == 0) {
datas_[std::stoi(key.substr(5))] = value;
} else if (key.rfind("man:", 0) == 0) {
manifests_[std::stoi(key.substr(4))] = std::string(value.begin(), value.end());
}
}
uint64_t usedBytes_() const {
uint64_t total = 0;
for (const auto& kv : datas_) total += kv.second.size();
return total;
}
int currentVersion_;
std::map<int, int> slots_; // slot -> version
std::map<int, std::vector<uint8_t>> datas_;
std::map<int, std::string> manifests_;
std::map<std::string, std::vector<uint8_t>> staging_;
bool failNextWrite_ = false;
};
} // namespace steam_repro
int main() {
using namespace steam_repro;
MockCloudSaveSystem sys(3); // 当前存档架构版本 3
const std::vector<uint8_t> saveV1 = {0x01, 0x02, 0x03, 0x04};
// 1. 空槽位读取失败
std::vector<uint8_t> out;
int ver = 0;
CHECK(!sys.loadGame(9, &out, &ver));
// 2. 保存后清单与数据文件都落盘,版本记录为 1
CHECK(sys.saveGame(1, 1, saveV1));
CHECK(sys.slotVersion(1) == 1);
CHECK(sys.manifestExists(1));
CHECK(sys.dataExists(1));
// 3. 读回数据一致,版本为 1
CHECK(sys.loadGame(1, &out, &ver));
CHECK(out == saveV1);
CHECK(ver == 1);
// 4. 校验和防篡改:篡改数据文件后读取失败
sys.tamperData(1);
CHECK(!sys.loadGame(1, &out, &ver));
// 5. 显式迁移:v1 存档升级到当前 v3,数据带迁移标记
CHECK(sys.migrateSave(1));
CHECK(sys.slotVersion(1) == 3);
CHECK(sys.loadGame(1, &out, &ver));
CHECK(ver == 3);
CHECK(out.size() == saveV1.size() + 1);
CHECK(out.back() == 0xC0 + 1); // 迁移标记来自 v1
// 6. 迁移后读取正常
CHECK(sys.loadGame(1, &out, &ver));
CHECK(out.back() == 0xC1);
// 7. 原子性:数据写入失败时整批回滚,清单不落盘
sys.failNextWrite(true);
CHECK(!sys.saveGame(2, 1, saveV1));
CHECK(!sys.manifestExists(2));
CHECK(!sys.dataExists(2));
// 8. 配额:保存后已用字节增加,可用 = 总量 - 已用
CHECK(sys.saveGame(3, 3, saveV1));
uint64_t total = 0, avail = 0;
CHECK(sys.getQuota(&total, &avail));
CHECK(total == MockCloudSaveSystem::kQuotaTotalBytes);
CHECK(avail == total - (5 + 4)); // slot1 已迁移为 5 字节 + slot3 4 字节
// 9. 规范幂等:同一状态再保存 → 数据文件逐字节一致
CHECK(sys.saveGame(3, 3, saveV1));
CHECK(sys.isCanonical(3, saveV1));
CHECK(sys.saveGame(3, 3, saveV1));
CHECK(sys.isCanonical(3, saveV1));
// 10. 禁止降级:已有 v3,再写 v1 被拒
CHECK(!sys.saveGame(3, 1, saveV1));
CHECK(sys.slotVersion(3) == 3);
// 11. 高水位预警:连续写入大存档后已用 > 80% 时告警
std::vector<uint8_t> big(300 * 1024, 0xAB); // 300KB
CHECK(sys.saveGame(4, 3, big));
CHECK(sys.saveGame(5, 3, big));
CHECK(sys.saveGame(6, 3, big));
// 已用 ≈ 9 + 900KB ≈ 921KB > 0.8MB,达到阈值
CHECK(sys.warnHighWater());
// 12. 空数据存档仍然合法
CHECK(sys.saveGame(7, 3, std::vector<uint8_t>()));
CHECK(sys.loadGame(7, &out, &ver));
CHECK(out.empty());
CHECK(ver == 3);
return lab::report("04-3 云存储与游戏设计");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 38/38 通过。
小结
- 多文件架构:清单(版本+校验和)+ 数据文件,批量原子提交。
- 迁移与防篡改:显式升级、禁止降级、校验和拒载。
- 配额治理:写入前预算 + 高水位预警。
- 空数据存档合法,状态由版本/清单表达。
阅读导航:上一节:4.2 存档同步与冲突 · 下一节:5.1 覆盖层机制 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。