《Steam 游戏平台:开发与商业化》4.2 存档同步与冲突

云存储的难点在跨设备同步与冲突:FileWriteAsync/FileReadAsync 异步读写、GetLocalFileChange 报告其他设备的变更、本地脏文件与远端版本冲突时用 last-writer-wins 或 keep-local 解决。本节讲同步冲突的接口语义,lab 用 C++ 模拟异步读写、变更事件与两种冲突解决策略。

4.2 存档同步与冲突

4.1 讲了单机视角的文件读写;这一节处理云存储真正麻烦的部分:多设备同时玩,同一存档在两端都改了,谁赢。SDK 提供异步读写与本地变更事件,冲突检测与解决由游戏定义。

本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamremotestorage.h。

本章与站内既有内容的分工

  • Steam 发行专题 (操作手册)讲「后台云存储容量与策略」;本节讲「代码里处理同步冲突的接口语义」。
  • 卷一讲云存档的换机体验设计;本节讲冲突检测的机制与两种解决策略。
  • lab 用纯 C++ 模拟双设备冲突,不依赖 Steam 客户端运行。

异步读写

存档同步天然异步——上传/下载是网络操作:

// isteamremotestorage.h:FileWriteAsync / FileReadAsync / FileReadAsyncComplete(SDK v1.65 头文件摘录,已删减)
STEAM_CALL_RESULT( RemoteStorageFileWriteAsyncComplete_t )
virtual SteamAPICall_t FileWriteAsync( const char *pchFile, const void *pvData, uint32 cubData ) = 0;
STEAM_CALL_RESULT( RemoteStorageFileReadAsyncComplete_t )
virtual SteamAPICall_t FileReadAsync( const char *pchFile, uint32 nOffset, uint32 cubToRead ) = 0;
virtual bool	FileReadAsyncComplete( SteamAPICall_t hReadCall, void *pvBuffer, uint32 cubToRead ) = 0;

回调结构:

// isteamremotestorage.h:RemoteStorageFileReadAsyncComplete_t(SDK v1.65 头文件摘录,已删减)
struct RemoteStorageFileReadAsyncComplete_t
{
	enum { k_iCallback = k_iSteamRemoteStorageCallbacks + 32 };
	SteamAPICall_t m_hFileReadAsync;		// call handle of the async read which was made
	EResult	m_eResult;						// result
	uint32 m_nOffset;						// offset in the file this read was at
	uint32 m_cubRead;						// amount read - will the <= the amount requested
};

工程语义:

  1. 异步函数返回 SteamAPICall_t 句柄:真正结果通过回调结构(RemoteStorageFileWriteAsyncComplete_t/RemoteStorageFileReadAsyncComplete_t)送达,m_eResult 是成败。
  2. FileReadAsync 支持偏移量读取:nOffset+cubToRead 只读文件片段(适合大存档分片);FileReadAsyncComplete 把结果填进缓冲。
  3. 写完不立即本地立即可见:FileWriteAsync 完成回调后才算真正写成功。

本地变更事件

另一台设备改动了云端文件,本机如何知道?SDK 通过「本地文件变更」队列告知:

// isteamremotestorage.h:GetLocalFileChangeCount / GetLocalFileChange(SDK v1.65 头文件摘录,已删减)
virtual int32 GetLocalFileChangeCount() = 0;
virtual const char *GetLocalFileChange( int iFile, ERemoteStorageLocalFileChange *pEChangeType, ERemoteStorageFilePathType *pEFilePathType ) = 0;
// isteamremotestorage.h:ERemoteStorageLocalFileChange(SDK v1.65 头文件摘录,已删减)
enum ERemoteStorageLocalFileChange
{
	k_ERemoteStorageLocalFileChange_Invalid = 0,
	k_ERemoteStorageLocalFileChange_FileUpdated = 1,	// The file was updated from another device
	k_ERemoteStorageLocalFileChange_FileDeleted = 2,	// The file was deleted by another device
};

工程语义:

  1. 变更队列是一次性消费:每次同步后 GetLocalFileChangeCount 反映本轮变化;处理一条取一条。
  2. 事件类型区分新增/更新与删除:FileUpdated 表示其他设备更新了文件,FileDeleted 表示其他设备删了文件。
  3. 变更事件是游戏的「重新加载」信号:收到 FileUpdated 后应重新读该存档文件。

冲突检测与解决

本机已改(本地脏文件)且远端也被另一设备改过,同步时就产生冲突:

工程语义:

  1. 脏文件先上传:本地有未同步改动时,同步先把脏文件推上服务器;远端无冲突版本则直接标记已同步。
  2. 冲突判定:本地脏 + 远端有另一设备的更新 → 冲突,不能静默覆盖任何一方。
  3. 两种解决策略:
    • last-writer-wins:比较两端时间戳,取新的一方覆盖旧的一方。
    • keep-local:保留本地版本,把本地内容重新上传(覆盖远端)。
  4. 批量原子提交:多文件存档(清单 + 数据)用 BeginFileWriteBatch/EndFileWriteBatch 包裹,要么全部落盘、要么整体丢弃。
// 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;

接口签名对照

头文件条目语义
isteamremotestorage.hFileWriteAsync/FileReadAsync/FileReadAsyncComplete异步读写
isteamremotestorage.hRemoteStorageFileWriteAsyncComplete_t/RemoteStorageFileReadAsyncComplete_t异步完成回调
isteamremotestorage.hGetLocalFileChangeCount/GetLocalFileChange本地变更事件
isteamremotestorage.hERemoteStorageLocalFileChange变更类型(Updated/Deleted)
isteamremotestorage.hBeginFileWriteBatch/EndFileWriteBatch批量原子提交
isteamremotestorage.hGetFileTimestamp文件时间戳(冲突裁决依据)

数据口径与来源

  • 接口签名、回调结构字段、ERemoteStorageLocalFileChange 枚举值、批量提交注释:SDK v1.65 public/steam/isteamremotestorage.h 可实证。
  • 冲突解决策略(last-writer-wins / keep-local)是游戏侧设计,非 SDK 强制行为;本 lab 按常见工程实践模拟。
  • 时间戳比较的具体规则、多设备最终一致性:以官方文档与 Steam 客户端实际行为为准。

以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。

可运行产物:C++ 最小验证

下面的仿真复现「存档同步与冲突」的工程语义:异步读写(句柄 + 完成回调)、本地文件变更事件(FileUpdated/FileDeleted)、双设备冲突检测与两种解决策略(last-writer-wins / keep-local)、批量原子提交与中途丢弃。它与 src/04-2-save-sync-conflict.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:

// file: src/04-2-save-sync-conflict.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/04-2-save-sync-conflict.cpp -o bin/04-2-save-sync-conflict && ./bin/04-2-save-sync-conflict
//
// mock:复现存档同步与冲突的工程语义——异步读写
// (FileWriteAsync/FileReadAsync/FileReadAsyncComplete 与
//  RemoteStorageFileWriteAsyncComplete_t/RemoteStorageFileReadAsyncComplete_t)、
// 本地文件变更事件(GetLocalFileChangeCount/GetLocalFileChange,
//  ERemoteStorageLocalFileChange_FileUpdated/FileDeleted)、
// 多设备冲突检测与两种解决策略(last-writer-wins / keep-local),
// 以及 BeginFileWriteBatch/EndFileWriteBatch 的批量原子提交。
// 签名对照 SDK v1.65 isteamremotestorage.h,非 Valve 实现。
#include "verify.h"

#include <algorithm>
#include <cstdint>
#include <map>
#include <string>
#include <vector>

namespace steam_repro {

// k_EResultOK 对照 steamclientpublic.h
static constexpr int kEResultOK = 1;
// ERemoteStorageLocalFileChange / ERemoteStorageFilePathType 对照 isteamremotestorage.h
static constexpr int kLocalChangeFileUpdated = 1;
static constexpr int kLocalChangeFileDeleted = 2;
static constexpr int kFilePathAPIFilename = 2;

struct MockFileRec {
  std::vector<uint8_t> content;
  uint64_t mtime = 0;
  uint64_t originDevice = 0;
  bool dirty = false;
};

struct MockLocalChange {
  std::string file;
  int changeType = kLocalChangeFileUpdated;
  int pathType = kFilePathAPIFilename;
};

// RemoteStorageFileWriteAsyncComplete_t 结构字段对照 isteamremotestorage.h
struct MockWriteComplete {
  int result = 0;
};

// RemoteStorageFileReadAsyncComplete_t 结构字段对照 isteamremotestorage.h
struct MockReadComplete {
  uint64_t handle = 0;
  int result = 0;
  uint32_t offset = 0;
  uint32_t cubRead = 0;
};

class MockSteamRemoteStorageSync {
 public:
  explicit MockSteamRemoteStorageSync(uint64_t deviceId) : deviceId_(deviceId) {}

  // isteamremotestorage.h:FileWrite:批量中先进 staging
  bool fileWrite(const char* pchFile, const void* pvData, int32_t cubData) {
    const uint8_t* bytes = static_cast<const uint8_t*>(pvData);
    std::vector<uint8_t> data(bytes, bytes + cubData);
    if (inBatch_) {
      staging_[pchFile] = data;
      return true;
    }
    return commitLocal_(pchFile, data);
  }

  bool fileExists(const char* pchFile) const {
    return local_.find(pchFile) != local_.end();
  }

  // isteamremotestorage.h:FileRead
  int32_t fileRead(const char* pchFile, void* pvData, int32_t cubDataToRead) {
    auto it = local_.find(pchFile);
    if (it == local_.end()) return -1;
    int32_t n = std::min(cubDataToRead, static_cast<int32_t>(it->second.content.size()));
    if (n > 0) {
      uint8_t* out = static_cast<uint8_t*>(pvData);
      for (int32_t i = 0; i < n; ++i) out[i] = it->second.content[i];
    }
    return n;
  }

  // isteamremotestorage.h:FileWriteAsync:返回 SteamAPICall_t,回调记录结果
  uint64_t fileWriteAsync(const char* pchFile, const void* pvData, uint32_t cubData) {
    const uint8_t* bytes = static_cast<const uint8_t*>(pvData);
    std::vector<uint8_t> data(bytes, bytes + cubData);
    if (!inBatch_) commitLocal_(pchFile, data);
    else staging_[pchFile] = data;
    lastWriteComplete_.result = kEResultOK;
    return ++nextCall_;
  }

  // isteamremotestorage.h:FileReadAsync
  uint64_t fileReadAsync(const char* pchFile, uint32_t nOffset, uint32_t cubToRead) {
    pendingReads_[++nextCall_] = PendingRead{pchFile, nOffset, cubToRead};
    return nextCall_;
  }

  // isteamremotestorage.h:FileReadAsyncComplete:填充缓冲并记录回调
  bool fileReadAsyncComplete(uint64_t hReadCall, void* pvBuffer, uint32_t cubToRead) {
    auto it = pendingReads_.find(hReadCall);
    if (it == pendingReads_.end()) return false;
    const PendingRead& pr = it->second;
    auto fit = local_.find(pr.file);
    if (fit == local_.end()) return false;
    uint32_t n = std::min({pr.cubToRead, cubToRead,
                           static_cast<uint32_t>(fit->second.content.size() - pr.offset)});
    if (n > 0) {
      uint8_t* out = static_cast<uint8_t*>(pvBuffer);
      for (uint32_t i = 0; i < n; ++i) out[i] = fit->second.content[pr.offset + i];
    }
    lastReadComplete_ = MockReadComplete{hReadCall, kEResultOK, pr.offset, n};
    pendingReads_.erase(it);
    return true;
  }

  // isteamremotestorage.h:BeginFileWriteBatch / EndFileWriteBatch:批量原子提交
  bool beginFileWriteBatch() {
    if (inBatch_) return false;
    inBatch_ = true;
    staging_.clear();
    return true;
  }
  bool endFileWriteBatch() {
    if (!inBatch_) return false;
    inBatch_ = false;
    for (const auto& kv : staging_) commitLocal_(kv.first, kv.second);
    staging_.clear();
    return true;
  }
  // 未 End 即丢弃(模拟批量中途崩溃)
  void abortBatch() {
    inBatch_ = false;
    staging_.clear();
  }

  // 模拟另一台设备把新文件推上服务器
  void applyRemoteFile(const char* pchFile, const std::vector<uint8_t>& data,
                       uint64_t mtime, uint64_t originDevice) {
    remote_[pchFile] = MockFileRec{data, mtime, originDevice, false};
  }
  void applyRemoteDelete(const char* pchFile) {
    remoteDeleted_.push_back(pchFile);
  }

  // 同步:先上传本地脏文件(远端无冲突版本时标记为已同步),
  // 再拉取服务器状态到本地,检测冲突并产生本地变更事件。
  // 本机本次已协调(上传/一致)的文件不再重复产生变更事件。
  void sync() {
    changes_.clear();
    conflicts_.clear();
    std::vector<std::string> synced;
    for (auto& kv : local_) {
      if (!kv.second.dirty) continue;
      auto rit = remote_.find(kv.first);
      if (rit == remote_.end()) {
        remote_[kv.first] = kv.second;
        kv.second.dirty = false;
        synced.push_back(kv.first);
      } else if (rit->second.mtime == kv.second.mtime &&
                 rit->second.originDevice == kv.second.originDevice) {
        kv.second.dirty = false;
        synced.push_back(kv.first);
      }
    }
    for (auto& kv : remote_) {
      const std::string& name = kv.first;
      const MockFileRec& remote = kv.second;
      if (std::find(synced.begin(), synced.end(), name) != synced.end()) continue;
      auto localIt = local_.find(name);
      if (localIt == local_.end()) {
        local_[name] = remote;
        changes_.push_back(MockLocalChange{name, kLocalChangeFileUpdated, kFilePathAPIFilename});
      } else if (localIt->second.dirty && remote.originDevice != deviceId_) {
        conflicts_.push_back(name);
      } else {
        bool differs = localIt->second.content != remote.content;
        localIt->second = remote;
        if (differs && remote.originDevice != deviceId_) {
          changes_.push_back(MockLocalChange{name, kLocalChangeFileUpdated, kFilePathAPIFilename});
        }
      }
    }
    for (const std::string& name : remoteDeleted_) {
      remote_.erase(name);  // 服务器端已删除,同步后不再拉取
      if (local_.erase(name) > 0) {
        changes_.push_back(MockLocalChange{name, kLocalChangeFileDeleted, kFilePathAPIFilename});
      }
    }
    remoteDeleted_.clear();  // 删除事件一次性消费
  }

  // 冲突解决策略:last-writer-wins(取新 mtime)或 keep-local(保留本地)
  void resolveConflictLastWriterWins(const char* pchFile) {
    auto lit = local_.find(pchFile);
    auto rit = remote_.find(pchFile);
    if (lit == local_.end() || rit == remote_.end()) return;
    if (rit->second.mtime > lit->second.mtime) lit->second = rit->second;
    lit->second.dirty = false;
    removeConflict_(pchFile);
  }
  void resolveConflictKeepLocal(const char* pchFile) {
    auto lit = local_.find(pchFile);
    if (lit == local_.end()) return;
    lit->second.dirty = false;
    removeConflict_(pchFile);
  }

  bool hasConflict(const char* pchFile) const {
    for (const std::string& c : conflicts_) {
      if (c == pchFile) return true;
    }
    return false;
  }

  // isteamremotestorage.h:GetLocalFileChangeCount / GetLocalFileChange
  int32_t getLocalFileChangeCount() const { return static_cast<int32_t>(changes_.size()); }
  const char* getLocalFileChange(int iFile, int* pEChangeType, int* pEFilePathType) {
    if (iFile < 0 || static_cast<size_t>(iFile) >= changes_.size()) return nullptr;
    const MockLocalChange& c = changes_[iFile];
    *pEChangeType = c.changeType;
    *pEFilePathType = c.pathType;
    return c.file.c_str();
  }

  // isteamremotestorage.h:GetFileTimestamp / FilePersisted
  int64_t getFileTimestamp(const char* pchFile) const {
    auto it = local_.find(pchFile);
    return it == local_.end() ? -1 : static_cast<int64_t>(it->second.mtime);
  }
  bool filePersisted(const char* pchFile) const {
    auto it = local_.find(pchFile);
    return it != local_.end() && !it->second.dirty;
  }

  const MockWriteComplete& lastWriteComplete() const { return lastWriteComplete_; }
  const MockReadComplete& lastReadComplete() const { return lastReadComplete_; }

 private:
  struct PendingRead {
    std::string file;
    uint32_t offset = 0;
    uint32_t cubToRead = 0;
  };

  bool commitLocal_(const std::string& name, const std::vector<uint8_t>& data) {
    MockFileRec& rec = local_[name];
    rec.content = data;
    rec.mtime++;
    rec.originDevice = deviceId_;
    rec.dirty = true;
    return true;
  }

  void removeConflict_(const char* pchFile) {
    for (auto it = conflicts_.begin(); it != conflicts_.end();) {
      it = (*it == pchFile) ? conflicts_.erase(it) : it + 1;
    }
  }

  uint64_t deviceId_;
  std::map<std::string, MockFileRec> local_;
  std::map<std::string, MockFileRec> remote_;
  std::vector<std::string> remoteDeleted_;
  std::vector<MockLocalChange> changes_;
  std::vector<std::string> conflicts_;
  bool inBatch_ = false;
  std::map<std::string, std::vector<uint8_t>> staging_;
  std::map<uint64_t, PendingRead> pendingReads_;
  uint64_t nextCall_ = 0;
  MockWriteComplete lastWriteComplete_;
  MockReadComplete lastReadComplete_;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockSteamRemoteStorageSync s(1);  // 本机 device 1

  const uint8_t localSave[] = {1, 2, 3, 4};
  const std::vector<uint8_t> remoteSave = {9, 9, 9, 9};
  const std::vector<uint8_t> newerRemote = {7, 7, 7, 7, 7};
  uint8_t buf[16] = {0};

  // 1. 异步写:返回句柄,完成回调 result == k_EResultOK
  uint64_t hw = s.fileWriteAsync("slot1.dat", localSave, 4);
  CHECK(hw != 0);
  CHECK(s.lastWriteComplete().result == kEResultOK);

  // 2. 异步读:FileReadAsyncComplete 按偏移读回正确字节并记录回调字段
  uint64_t hr = s.fileReadAsync("slot1.dat", 1, 3);
  CHECK(hr != 0);
  CHECK(s.fileReadAsyncComplete(hr, buf, 3));
  CHECK(buf[0] == 2 && buf[1] == 3 && buf[2] == 4);
  CHECK(s.lastReadComplete().offset == 1);
  CHECK(s.lastReadComplete().cubRead == 3);

  // 3. 无远端变化同步:无冲突、无变更事件
  s.sync();
  CHECK(!s.hasConflict("slot1.dat"));
  CHECK(s.getLocalFileChangeCount() == 0);

  // 4. 远端新文件(device 2):同步后本地更新并产生 FileUpdated 事件
  s.applyRemoteFile("slot2.dat", remoteSave, 10, 2);
  s.sync();
  CHECK(s.getLocalFileChangeCount() == 1);
  int ctype = 0, ptype = 0;
  CHECK(s.getLocalFileChange(0, &ctype, &ptype) != nullptr);
  CHECK(ctype == kLocalChangeFileUpdated);
  CHECK(ptype == kFilePathAPIFilename);
  CHECK(s.fileRead("slot2.dat", buf, 4) == 4);
  CHECK(buf[0] == 9);

  // 5. 冲突:本机改了 slot1(dirty)且 device 2 也改过
  CHECK(s.fileWrite("slot1.dat", localSave, 4));  // 本机 dirty
  s.applyRemoteFile("slot1.dat", newerRemote, 20, 2);
  s.sync();
  CHECK(s.hasConflict("slot1.dat"));

  // 6. last-writer-wins:远端 mtime 更新 → 内容取远端
  s.resolveConflictLastWriterWins("slot1.dat");
  CHECK(!s.hasConflict("slot1.dat"));
  CHECK(s.fileRead("slot1.dat", buf, 5) == 5);
  CHECK(buf[0] == 7);

  // 7. keep-local:本机优先,内容保留本机
  CHECK(s.fileWrite("slot1.dat", localSave, 4));
  s.applyRemoteFile("slot1.dat", newerRemote, 30, 2);
  s.sync();
  CHECK(s.hasConflict("slot1.dat"));
  s.resolveConflictKeepLocal("slot1.dat");
  CHECK(!s.hasConflict("slot1.dat"));
  CHECK(s.fileRead("slot1.dat", buf, 4) == 4);
  CHECK(buf[0] == 1);

  // 8. 远端删除:同步后产生 FileDeleted 变更事件
  s.applyRemoteDelete("slot2.dat");
  s.sync();
  int dcount = 0;
  for (int i = 0; i < s.getLocalFileChangeCount(); ++i) {
    int t = 0, p = 0;
    const char* fn = s.getLocalFileChange(i, &t, &p);
    if (fn != nullptr && t == kLocalChangeFileDeleted) ++dcount;
  }
  CHECK(dcount == 1);
  CHECK(s.fileRead("slot2.dat", buf, 4) == -1);

  // 9. 批量原子提交:Begin → 写两个文件 → End → 全部可见
  CHECK(s.beginFileWriteBatch());
  CHECK(s.fileWrite("batch_a.dat", localSave, 4));
  CHECK(s.fileWrite("batch_b.dat", remoteSave.data(), 4));
  CHECK(s.endFileWriteBatch());
  CHECK(s.fileExists("batch_a.dat"));
  CHECK(s.fileExists("batch_b.dat"));

  // 10. 批量中途丢弃:文件不落盘
  CHECK(s.beginFileWriteBatch());
  CHECK(s.fileWrite("ghost.dat", localSave, 4));
  s.abortBatch();
  CHECK(s.fileRead("ghost.dat", buf, 4) == -1);

  // 11. 未 Begin 就 End 返回 false
  CHECK(!s.endFileWriteBatch());

  // 12. FilePersisted:dirty 时 false,同步上传后 true
  CHECK(s.fileWrite("upload.dat", localSave, 4));  // 本地新建,dirty
  CHECK(!s.filePersisted("upload.dat"));
  s.sync();  // 上传本地脏文件
  CHECK(s.filePersisted("upload.dat"));

  // 13. 远端更新后 GetFileTimestamp 反映远端 mtime
  CHECK(s.getFileTimestamp("slot2.dat") == -1);  // 已删除
  s.applyRemoteFile("slot2.dat", remoteSave, 55, 2);
  s.sync();
  CHECK(s.getFileTimestamp("slot2.dat") == 55);

  return lab::report("04-2 存档同步与冲突");
}

本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 42/42 通过。

小结

  • 异步读写:句柄 + 回调,偏移量分片读取。
  • 变更事件:其他设备更新/删除会进本地变更队列。
  • 冲突:本地脏 + 远端被改 → 显式解决;last-writer-wins 或 keep-local。
  • 批量提交:Begin/End 原子性,中途丢弃不落盘。

阅读导航:上一节:4.1 云存储机制 · 下一节:4.3 云存储与游戏设计 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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