10.3 分支与灰度发布
上一节讲了内容怎么上传,这一节回答「内容怎么安全地放出去」:灰度发布。灰度不是一个独立接口,而是分支体系的产品用法——候选 build 先在受限分支上小比例放量,用真实玩家数据做门禁,通过才推向全量。接入工程要理解放量分配、门禁判定与回滚动作三件事,而它们全部构建在上一节的 buildid 推进之上。
本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamapps.h。
本章与站内既有内容的分工
- Steam 发行专题 (操作手册)讲「后台配置分支可见性、把测试分支放给部分玩家」;本节讲「灰度放量与门禁判定怎么建模」。
- 卷一《平台机制与商店》讲商店与下载机制;本节把「版本质量」落成灰度推进/回滚的工程口径。
- lab 用纯 C++ 复现放量分配与门禁判定,不依赖 Steam 客户端运行。
灰度是分支体系的产品用法
灰度发布不需要新接口——它复用的正是前两节的分支工具:
// isteamapps.h:ISteamApps 分支与 buildid(SDK v1.65 头文件摘录,已删减)
virtual bool GetCurrentBetaName( char *pchName, int cchNameBufferSize ) = 0; // returns current beta branch name, 'public' is the default branch
virtual int GetNumBetas( int *pnAvailable, int *pnPrivate ) = 0; // returns total number of known app branches
virtual bool SetActiveBeta( const char *pchBetaName ) = 0; // might need the game to restart so Steam can update to that branch
virtual int GetAppBuildId() = 0; // return the buildid of this app, may change at any time based on backend updates to the game
工程语义:
- 灰度 = 把候选 build 放进一个受限分支,部分玩家可见:受限分支不是「测试者专属」,而是「放量比例可调」——头文件里
pnPrivate表达的分支私有性就是可见性控制的一种。 - 玩家侧的 build 是「按分支解析」的:
GetAppBuildId()返回当前运行分支的 buildid。灰度期间,放量池里的玩家在受限分支、拿到候选 build;池外的玩家在public、拿旧 build。两边运行的是同一份二进制,只是版本不同——灰度判断的依据来自埋点,不是来自分支。 - 放量比例是后台配置,不是 SDK 接口:SDK 运行时看不到「当前放量百分之几」。工程上灰度状态要由自己的配置服务下发,运行时只负责「按收到的配置选 build」。
放量分配与门禁判定
把灰度工程化,需要两个确定性模型:怎么把玩家分进灰度池、怎么判定是否推进。下面的 lab 用确定性分配与阈值门禁表达这两件事:
// 模型:灰度放量与门禁(对应后台灰度配置 + 埋点聚合,非 SDK 头文件)
// 放量:usersOnNew = totalUsers * rolloutPercent / 100
// 门禁:success / (success + failure) >= 90% 才推进;failure 过半则回滚
工程语义:
- 放量分配必须确定性:同一个玩家多次请求应拿到同一个 build。lab 用「前 N 个用户」模拟确定性分配;生产上应基于用户 id 的稳定哈希分桶,避免玩家在灰度池边缘来回跳。
- 门禁阈值要可解释:90% 成功率推进、50% 失败率回滚是模型假设的示例阈值。真正阈值由运营定,但逻辑必须一致:推进看「成功占比」,回滚看「失败占比」,两者是同一组数据的不同口径。
- 样本不足时不动:只有几条上报就推进或回滚都不安全。门禁判定应要求最小样本,未达样本即「继续观察」。lab 里
total == 0返回 false 表达的正是这个意思。
推进与回滚:buildid 指针的移动
灰度决策落地到内容分发,只有两个动作——把分支指针移向新 buildid,或放弃候选:
// 模型:推进/回滚动作(对应后台把分支指向某 buildid,非 SDK 头文件)
// 推进:所有分支的 buildid 都指向候选
// 回滚:保留候选但不生效,玩家仍跑旧 buildid
工程语义:
- 推进是「全分支对齐」:候选 build 通过门禁后,
public等分支的 buildid 统一指到候选。推进后所有玩家(包括池外的)都跑新 build,灰度完成。 - 回滚是「不生效」,不是「删除」:候选 build 已经上传、buildid 已存在,回滚只是不把它写进公开分支。历史 buildid 仍可随时指回——这就是上一节说的「buildid 只增、可回滚」。
- 灰度期间不混版本:同一个分支在推进前只能指向一个 buildid。放量差异体现在「玩家在哪个分支」,而不是「同一分支内版本不一致」——工程上要保证这一点,否则同一分支内的玩家会互相无法联机。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamapps.h | ISteamApps::GetCurrentBetaName | 当前分支名(‘public’ 是默认) |
isteamapps.h | ISteamApps::GetNumBetas | 分支总数与可见/私有分支数 |
isteamapps.h | ISteamApps::SetActiveBeta | 切换活跃分支(可能需要重启) |
isteamapps.h | ISteamApps::GetAppBuildId | 当前运行分支的 buildid(随时可变) |
| —(模型) | 放量分配 / 门禁判定 / 推进 / 回滚 | 灰度发布的产品逻辑 |
数据口径与来源
- 分支查询与 buildid 接口签名:SDK v1.65
public/steam/isteamapps.h可实证(本机镜像已核对)。 - 灰度放量机制、门禁阈值、回滚流程:后台功能与运营口径,partner 文档登录后可见,以官方当前为准;本卷的 90%/50% 阈值为模型假设,不作为官方数值。
- 灰度分支的数量、单分支放量上限等配额:官方不公开,本卷不给假设数值。
以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。
可运行产物:C++ 最小验证
下面的仿真复现「分支与灰度发布」的工程语义:分支各自持有 buildid、灰度按百分比放量、用户确定性分配、成功率门禁推进、失败过半回滚、推进后全分支对齐。它与 src/10-3-branch-gray-release.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:
// file: src/10-3-branch-gray-release.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/10-3-branch-gray-release.cpp -o bin/10-3-branch-gray-release && ./bin/10-3-branch-gray-release
//
// mock:复现分支与灰度发布——分支各自持有 buildid,灰度按百分比放量、
// 以成功率为门禁推进/回滚;对应 isteamapps.h 的 GetCurrentBetaName /
// GetNumBetas / GetBetaInfo / SetActiveBeta / GetAppBuildId 口径。
// 放量与成功率数值为模型假设,非 Valve 实现。
#include "verify.h"
#include <cstdint>
#include <string>
#include <unordered_map>
namespace steam_repro {
class MockGrayRelease {
public:
// 分支:name → buildId
std::unordered_map<std::string, uint32_t> branches_ = {
{"public", 3000}, {"beta", 3000}, {"limited", 3000}};
uint32_t candidateBuild_ = 0;
uint32_t rolloutPercent_ = 0;
uint32_t totalUsers_ = 0;
uint32_t usersOnNew_ = 0;
uint32_t successReports_ = 0;
uint32_t failureReports_ = 0;
bool promoted_ = false;
bool rolledBack_ = false;
std::string activeBranch_ = "public";
// ISteamApps::GetAppBuildId:当前运行分支的 buildid
uint32_t getAppBuildId() const {
auto it = branches_.find(activeBranch_);
return it == branches_.end() ? 0 : it->second;
}
// ISteamApps::GetCurrentBetaName
std::string getCurrentBetaName() const { return activeBranch_; }
// ISteamApps::SetActiveBeta
bool setActiveBeta(const std::string& name) {
if (branches_.count(name) == 0) return false;
activeBranch_ = name;
return true;
}
// 灰度放量:把 candidateBuild 按 rolloutPercent_ 分配给测试池
void stageRollout(uint32_t candidateBuild, uint32_t rolloutPercent, uint32_t totalUsers) {
candidateBuild_ = candidateBuild;
rolloutPercent_ = rolloutPercent;
totalUsers_ = totalUsers;
usersOnNew_ = totalUsers * rolloutPercent / 100;
successReports_ = 0;
failureReports_ = 0;
promoted_ = false;
rolledBack_ = false;
}
// 用户视角的 build 分配(确定性:前 usersOnNew_ 个用户拿到新 build)
uint32_t buildForUser(uint32_t userId) const {
return userId < usersOnNew_ ? candidateBuild_ : branches_.at(activeBranch_);
}
// 上报成功/失败
void report(bool ok) {
if (ok)
++successReports_;
else
++failureReports_;
}
// 判断是否推进:成功率 >= 90% 且样本足够(模型假设阈值)
bool shouldPromote() const {
uint32_t total = successReports_ + failureReports_;
if (total == 0) return false;
return successReports_ * 10 >= total * 9;
}
// 判断是否回滚:失败占比 >= 50%(模型假设阈值)
bool shouldRollback() const {
uint32_t total = successReports_ + failureReports_;
if (total == 0) return false;
return failureReports_ * 2 >= total;
}
// 推进:把 candidate 写回所有分支
void promote() {
for (auto& kv : branches_) kv.second = candidateBuild_;
promoted_ = true;
}
// 回滚:放弃候选
void rollback() { rolledBack_ = true; }
};
} // namespace steam_repro
int main() {
using namespace steam_repro;
MockGrayRelease g;
// 1. 初始 public 分支 buildid 3000
CHECK(g.getAppBuildId() == 3000);
// 2. 默认分支名 public
CHECK(g.getCurrentBetaName() == "public");
// 3. 灰度 10% 放量:100 用户中 10 个拿新 build
g.stageRollout(3100, 10, 100);
CHECK(g.buildForUser(0) == 3100);
CHECK(g.buildForUser(99) == 3000);
// 4. 未放量的用户保持旧 build
CHECK(g.buildForUser(50) == 3000);
// 5. 成功率 100% → 推进门禁通过
for (int i = 0; i < 10; ++i) g.report(true);
CHECK(g.shouldPromote());
CHECK(!g.shouldRollback());
// 6. 推进后 public buildid 更新
g.promote();
CHECK(g.promoted_);
CHECK(g.getAppBuildId() == 3100);
// 7. 回滚判定:失败过半
MockGrayRelease g2;
g2.stageRollout(3200, 30, 100);
for (int i = 0; i < 3; ++i) g2.report(true);
for (int i = 0; i < 4; ++i) g2.report(false);
CHECK(g2.shouldRollback());
CHECK(!g2.shouldPromote());
// 8. 回滚动作不推进 buildid
g2.rollback();
CHECK(g2.rolledBack_);
CHECK(g2.getAppBuildId() == 3000);
// 9. SetActiveBeta 切换分支
CHECK(g.setActiveBeta("beta"));
CHECK(g.getCurrentBetaName() == "beta");
// 10. 未知分支被拒
CHECK(!g.setActiveBeta("no-such-branch"));
CHECK(g.getCurrentBetaName() == "beta");
// 11. 分支 buildid 独立推进:promote 后所有分支一致
CHECK(g.branches_.at("limited") == 3100);
return lab::report("10-3 分支与灰度发布");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 18/18 通过。
小结
- 灰度发布是分支体系的产品用法:候选 build 先放进受限分支小比例放量,门禁通过才推向全量。
- 放量分配必须确定性(按用户稳定分桶),门禁阈值要可解释且要求最小样本。
- 推进是「全分支 buildid 对齐」,回滚是「不生效、保留历史 buildid」,都不是删除。
- 灰度期间同一分支只允许一个 buildid,避免同分支内版本不一致导致无法联机。
阅读导航:上一节:10.2 分发管道与上传 · 下一节:11.1 Playtest 机制 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。