《Steam 游戏平台:开发与商业化》10.2 分发管道与上传

分发管道是 SteamPipe 客户端(后台构建上传工具)的职责,产出清单-分块-完整性校验-发布推进 buildid 的闭环。本节讲清单以 depot 归属、大文件分块、变更检测与 buildid 推进的工程语义,lab 用 C++ mock 验证清单校验与变更检测逻辑。

10.2 分发管道与上传

上一节讲了 depot 与分支的「读取侧」,这一节讲「内容怎么从开发机走到玩家」:构建上传、内容校验、buildid 推进。这里有一个重要的工程认知——上传分发不是 SDK 运行时接口,而是 SteamPipe 客户端(partner 后台登录后的构建工具)的职责。SDK 运行时能看到的只是结果:GetAppBuildId() 返回当前 App 的 buildid,且注释明确它随时可能变。接入工程要能把「构建 → 上传 → 发布 → buildid 推进」这条管道拆成可验证的环节。

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

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

  • Steam 发行专题 (操作手册)讲「后台用 SteamPipe 传 depot、配置分支可见性」;本节讲「上传管道的清单/分块/校验逻辑与 buildid 语义」。
  • 卷一《平台机制与商店》讲商店与下载机制;本节把「版本号」落成 buildid 的推进口径。
  • lab 用纯 C++ 复现清单校验与变更检测,不依赖 Steam 客户端运行。

上传分发的归属:SteamPipe 客户端

先把职责划清楚。把内容从开发机搬到 Steam 内容服务器(SteamPipe)的流程,由 SteamPipe 构建客户端 完成:

// isteamapps.h:ISteamApps::GetAppBuildId(SDK v1.65 头文件摘录,已删减)
virtual int GetAppBuildId() = 0; // return the buildid of this app, may change at any time based on backend updates to the game

工程语义:

  1. 上传是构建工具的事,运行时 SDK 看不到上传接口:SDK 里没有「上传文件到 Steam」的 API——那是后台 SteamPipe 客户端与构建系统的事。运行时侧能读到的只有上传结果:GetAppBuildId() 告诉你当前 buildid。
  2. buildid 随时可变:头文件注释明确 “may change at any time based on backend updates to the game”。工程上不要缓存 buildid 当不可变版本号,版本判断应以实时读取为准。
  3. 管线可拆成可验证环节:即使上传不在 SDK 运行时,管道逻辑仍可建模:构建清单 → 按 depot 归属 → 分块 → 上传 → 完整性校验 → 发布推进 buildid。下面 lab 验证其中与工程正确性最相关的三段:清单校验、变更检测、buildid 推进。

构建清单:文件以 depot 归属

上传的起点是一份「构建清单」:每个文件记录路径、归属 depot、大小与哈希。这是后续一切校验的基准:

// 模型:构建清单结构(对应 SteamPipe 上传前的内容快照,非 SDK 头文件)
struct MockManifestFile {
  std::string path;
  uint32_t depotId;   // 文件归属的 depot
  uint64_t sizeBytes; // 文件大小
  uint64_t sha1;      // 内容哈希
};

工程语义:

  1. 清单是「内容快照」,不是「变更集」:它描述这一次构建的完整内容——哪些文件、各归哪个 depot、多大、哈希多少。上传与校验都以它为准。
  2. 按 depot 归属是清单的第一维:一个文件只能属于一个 depot,清单按 depot 汇总,上传时才能分 depot 传、分 depot 校验。depot 归属错位会导致「文件到了、却挂在错误的分发单元」——这类问题往往在玩家侧以「下载到一半缺文件」暴露。
  3. 哈希是内容一致性的唯一凭据:本地文件与清单哈希逐一比对,任何不匹配都意味着「本地不是这份构建」,不能发布。

大文件分块与变更检测

构建可能包含大文件。上传按固定块大小切分,先做分块计划;发布前做变更检测,只重传变化的内容:

// 模型:分块与变更检测口径(对应 SteamPipe 上传优化,非 SDK 头文件)
// 分块:sizeBytes / chunkSize 向上取整,块总数 = 各文件块数之和
// 变更:清单内缺失/哈希变化 + 清单外新增,都算「需要重传」

工程语义:

  1. 分块让大文件上传可断点续传、可并行:超过块大小的文件切成 N 块,进度按块记。块数 = (size + chunk - 1) / chunk 向上取整。工程上「已传多少」应按块数而非字节数算,避免把最后一块的剩余字节计成已传。
  2. 变更检测是「相对上次发布」:清单内文件哈希变化 → 重传;清单外出现新文件 → 重传。两者都要进变更集。只比哈希、不看新增,会漏掉新加的文件;只比新增、不看哈希,会漏掉修改过的文件。
  3. 检测的目的是最小上传:SteamPipe 的核心价值之一是「只传变化」,玩家侧也据此只下变化。工程上把变更集算准,直接决定带宽与玩家等待时间。

发布推进 buildid

上传与校验通过后,发布动作把某个分支指向新的 buildid。运行时侧可见的只是 buildid 单调变化:

// isteamapps.h:ISteamApps::GetAppBuildId(SDK v1.65 头文件摘录,已删减)
// 发布后 App 的 buildid 单调递增;同一时刻不同分支指向不同 buildid。

工程语义:

  1. 发布 = 把分支指向新 buildid:buildid 单调递增,每发布一次就推进一个号。玩家切到该分支时,Steam 按分支当前指向的 buildid 拉内容。
  2. buildid 是「内容版本」,不是「代码版本」:同一份代码可以发布多次(补配置、补资源),每次 buildid 都变。工程上做崩溃上报、Bug 复现时,记录 buildid 比记录版本号更接近玩家实际跑的内容。
  3. 回滚 = 把分支指回旧 buildid:发布错误不销毁历史——buildid 是只增的,回滚只是指针回移。这也解释了为什么上一节强调「buildid 可能随时变」:后端可以把分支指到任何历史 buildid。

接口签名对照

头文件条目语义
isteamapps.hISteamApps::GetAppBuildId()当前 App 的 buildid(随时可变)
—(模型)构建清单(文件/depot/大小/哈希)SteamPipe 上传前的内容快照
—(模型)分块与变更检测上传优化逻辑:只传变化内容
—(模型)发布推进 buildid分支指向新 buildid,单调递增

数据口径与来源

  • GetAppBuildId() 签名与「随时可变」注释:SDK v1.65 public/steam/isteamapps.h 可实证(本机镜像已核对)。
  • 构建清单结构、分块算法、变更检测细节、buildid 编号规则:SteamPipe 客户端内部逻辑,partner 文档登录后可见,以官方当前为准;本卷以模型描述,不给假设数值。
  • 上传速度、带宽配额等:官方不公开,本卷不给假设数值。

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

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

下面的仿真复现「分发管道与上传」的工程语义:构建清单按 depot 归属、清单完整性校验、大文件分块计划、变更检测(哈希变化 + 新增文件)、发布推进 buildid。它与 src/10-2-distribution-upload.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:

// file: src/10-2-distribution-upload.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/10-2-distribution-upload.cpp -o bin/10-2-distribution-upload && ./bin/10-2-distribution-upload
//
// mock:复现分发管道与上传——构建清单(文件+哈希+大小)、按 depot 归属、
// 大文件分块上传与进度、上传后完整性校验、分支 buildid 推进。
// 上传分发属 SteamPipe 客户端(partner 登录后工具),本 mock 验证清单与
// 归属/校验逻辑,签名对照 SDK v1.65 isteamapps.h 的 buildid 口径,非 Valve 实现。
#include "verify.h"

#include <cstdint>
#include <string>
#include <unordered_map>

namespace steam_repro {

struct MockManifestFile {
  std::string path;
  uint32_t depotId;
  uint64_t sizeBytes;
  uint64_t sha1;
};

class MockSteamPipeUploader {
 public:
  // 构建清单:以 depot 归属,记录文件哈希与大小
  void addFile(const std::string& path, uint32_t depotId, uint64_t size, uint64_t sha1) {
    manifest_[path] = MockManifestFile{path, depotId, size, sha1};
  }

  // 校验本地文件集合与清单一致:路径存在 + 哈希匹配
  bool verifyManifest(const std::unordered_map<std::string, uint64_t>& localHashes) const {
    if (localHashes.size() != manifest_.size()) return false;
    for (const auto& kv : manifest_) {
      auto it = localHashes.find(kv.first);
      if (it == localHashes.end()) return false;
      if (it->second != kv.second.sha1) return false;
    }
    return true;
  }

  // 分块计划:超过 chunkSize 的文件切块,返回总块数
  size_t planChunks(uint64_t chunkSize) const {
    size_t total = 0;
    for (const auto& kv : manifest_) {
      uint64_t sz = kv.second.sizeBytes;
      total += static_cast<size_t>((sz + chunkSize - 1) / chunkSize);
    }
    return total;
  }

  // 按 depot 汇总内容
  size_t depotFileCount(uint32_t depotId) const {
    size_t n = 0;
    for (const auto& kv : manifest_) {
      if (kv.second.depotId == depotId) ++n;
    }
    return n;
  }

  // 内容变更检测:给定新哈希集合,返回需要重新上传的文件数
  // (清单内缺失/变更 + 本地新增文件都算)
  size_t changedFileCount(const std::unordered_map<std::string, uint64_t>& newHashes) const {
    size_t n = 0;
    for (const auto& kv : manifest_) {
      auto it = newHashes.find(kv.first);
      if (it == newHashes.end() || it->second != kv.second.sha1) ++n;
    }
    for (const auto& kv : newHashes) {
      if (manifest_.count(kv.first) == 0) ++n;
    }
    return n;
  }

  // 上传完成后推进 buildid(模拟 SteamPipe 发布后 App 的 buildid 单调递增)
  uint32_t publishBuild(uint32_t branchBuildId) { return ++branchBuildId; }

  size_t manifestSize() const { return manifest_.size(); }

 private:
  std::unordered_map<std::string, MockManifestFile> manifest_;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockSteamPipeUploader up;

  // 1. 构建清单:三个文件分属两个 depot
  up.addFile("game.exe", 1, 1024, 0xAA11);
  up.addFile("res.dat", 1, 2048, 0xBB22);
  up.addFile("audio.dat", 2, 4096, 0xCC33);

  // 2. 清单校验:本地文件与清单完全一致
  std::unordered_map<std::string, uint64_t> local = {
      {"game.exe", 0xAA11}, {"res.dat", 0xBB22}, {"audio.dat", 0xCC33}};
  CHECK(up.verifyManifest(local));

  // 3. 缺少文件 → 校验失败
  std::unordered_map<std::string, uint64_t> missing = {
      {"game.exe", 0xAA11}, {"res.dat", 0xBB22}};
  CHECK(!up.verifyManifest(missing));

  // 4. 哈希不匹配 → 校验失败
  std::unordered_map<std::string, uint64_t> corrupt = {
      {"game.exe", 0x9999}, {"res.dat", 0xBB22}, {"audio.dat", 0xCC33}};
  CHECK(!up.verifyManifest(corrupt));

  // 5. 按 depot 归属:depot1 两个文件,depot2 一个
  CHECK(up.depotFileCount(1) == 2);
  CHECK(up.depotFileCount(2) == 1);

  // 6. 分块计划:chunk 1024 → game.exe 1 块、res.dat 2 块、audio.dat 4 块
  CHECK(up.planChunks(1024) == 7);

  // 7. 分块计划:chunk 2048 → 1 + 1 + 2 = 4 块
  CHECK(up.planChunks(2048) == 4);

  // 8. 内容变更检测:game.exe 哈希变化 → 1 个文件需重传
  std::unordered_map<std::string, uint64_t> changed = {
      {"game.exe", 0xDEAD}, {"res.dat", 0xBB22}, {"audio.dat", 0xCC33}};
  CHECK(up.changedFileCount(changed) == 1);

  // 9. 新增文件 → 视为变更需重传
  std::unordered_map<std::string, uint64_t> added = {
      {"game.exe", 0xAA11}, {"res.dat", 0xBB22}, {"audio.dat", 0xCC33}, {"new.dat", 0x1234}};
  CHECK(up.changedFileCount(added) == 1);

  // 10. 发布推进 buildid(单调递增)
  CHECK(up.publishBuild(3000) == 3001);
  CHECK(up.publishBuild(3100) == 3101);

  // 11. 清单规模核对
  CHECK(up.manifestSize() == 3);

  return lab::report("10-2 分发管道与上传");
}

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

小结

  • 上传分发是 SteamPipe 客户端(构建工具)的职责,SDK 运行时只有 GetAppBuildId() 可读,且 buildid 随时可变。
  • 构建清单以 depot 归属记录文件,哈希是内容一致性的唯一凭据。
  • 大文件分块让上传可断点续传,变更检测(哈希变化 + 新增文件)实现最小上传。
  • 发布把分支指向新 buildid,buildid 单调递增、可回滚指回旧值。

阅读导航:上一节:10.1 Depot 与内容分支 · 下一节:10.3 分支与灰度发布 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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