《Steam 游戏平台:开发与商业化》4.3 云存储与游戏设计

多文件存档的正确姿势:用版本化清单 + 数据文件结构承载演进,用批量提交保证原子性,用校验和防篡改,用显式迁移处理旧版存档,并做配额预算与高水位预警。本节讲云存档的工程设计与治理,lab 用 C++ 模拟存档架构与迁移。

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;

工程语义:

  1. 清单文件记录「版本 + 校验和」:v=<version>;sum=<checksum>,数据文件存实际存档字节;加载时以清单版本为准。
  2. BeginFileWriteBatch/EndFileWriteBatch 把多个文件包成一个原子单位:数据写入失败 → 整批回滚,清单不落盘;避免「清单已新、数据已旧」的坏档。
  3. 规范幂等:同一状态反复保存,数据文件逐字节一致,不产生冗余差异。

版本迁移与防篡改

存档会随游戏版本演进;旧存档要能显式迁移到当前架构:

工程语义:

  1. 迁移是显式动作:读到旧版本存档后,游戏主动升级(如 v1 → v3),迁移函数把数据改写并原子回写,存档版本升到当前版本。
  2. 禁止降级:已有新版本存档再写旧版本内容应被拒绝——防止新版本数据被旧逻辑覆盖。
  3. 校验和防篡改:清单里存数据文件的校验和,加载时重算比对;数据被改/损坏 → 拒绝加载(宁可提示坏档,不载入错误数据)。
  4. 空数据存档合法:空字节也是合法存档(如「未开始」状态),不能因数据为空而判定坏档。

配额预算与高水位

云存档有配额(4.1 的 GetQuota);设计上要预算 + 预警:

// isteamremotestorage.h:GetQuota(SDK v1.65 头文件摘录,已删减)
virtual bool GetQuota( uint64 *pnTotalBytes, uint64 *puAvailableBytes ) = 0;

工程语义:

  1. 写入前看可用空间:GetQuota 返回总量与可用;保存前预算「新档大小 ≤ 可用」,否则提示用户或降级(如去掉大截图)。
  2. 高水位预警:已用空间超过阈值(本 lab 用 80% 的模型假设阈值)时就提醒清理或改存小格式——不要等到写不进去才处理。
  3. 真实配额以官方为准:mock 用 1MB 模拟总量复现预算与预警的工程逻辑。

接口签名对照

头文件条目语义
isteamremotestorage.hBeginFileWriteBatch/EndFileWriteBatch多文件原子提交
isteamremotestorage.hFileWrite/FileRead清单与数据文件落盘/读取
isteamremotestorage.hGetQuota总量与可用配额
isteamremotestorage.hGetFileTimestamp/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 覆盖层机制 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图