Buf、Protobuf 与 gRPC Schema：从字段编号到兼容门禁

Buf、Protobuf 与 gRPC Schema 治理链高清原图

一次看似普通的字段重构，可能在灰度发布后才暴露真正代价。服务端把 int32 days = 2 改成 string days = 2，新代码编译、单测和 RPC 冒烟都成功；仍在运行的旧客户端看到不匹配的 wire type 时，会把新条目当成未知字段，业务层最终只拿到缺失状态或默认值。另一个团队删除字段后复用了编号，历史消息里的地址又被解释成新的备注字段，最终把敏感数据带进日志。事故现场最容易出现的误判是：“.proto 能编译，所以接口兼容。”

Protobuf 的兼容契约不在字段名上，而在 package、消息与服务身份、field number、wire type、presence、枚举数值和编码格式的组合上。gRPC 又把 package、service 和 method 拼成线上方法名；代码生成器把 descriptor 转成各语言 API；运行时库负责真正的序列化、反序列化和调用。只看源文件 diff，会漏掉这条链上的大部分风险。

Buf 把这条链变成可重复执行的工程对象：buf.yaml 描述工作区、模块与规则，buf.lock 固定外部 schema 依赖，buf build 产出 descriptor image，buf breaking 比较新旧 image，buf.gen.yaml 固定代码生成输入、插件与选项。它不是另一种 gRPC 框架，也不会替代各语言的 Protobuf 和 gRPC runtime；它负责让 schema 在进入 runtime 之前拥有一致的构建和治理入口。

先固定 Buf CLI，再让每台机器执行同一配置

Buf 安装文档提供 Homebrew、Scoop、WinGet、npm、Release 二进制、Docker 和源码安装入口。团队选择入口时，重点不是哪条命令最短，而是版本能否锁定、来源能否验证、CI 能否复现、卸载时会留下什么。

macOS 或 Linux 开发机可以用官方 Homebrew tap；Windows 可以选择 WinGet 或 Scoop：

brew install bufbuild/buf/buf
buf --version

winget install bufbuild.buf
buf --version

# 或使用 Scoop
scoop install buf
buf --version

这些系统级入口适合交互式开发，但默认会随包管理器升级。仓库希望把工具版本和提交绑定时，可以把 Buf CLI 作为项目本地依赖。下面以 Buf CLI 1.71.0 作为可复现实验基线；升级时修改精确版本并提交 lockfile，不能使用 latest 或宽松版本段：

npm install --save-dev --save-exact @bufbuild/buf@1.71.0
npx buf --version

不使用 Node.js 的仓库可以从 Buf GitHub Releases下载与操作系统、CPU 架构匹配的二进制，同时验证发布页提供的签名和 SHA-256 文件。CI 应固定版本和制品摘要，把二进制放入只读工具缓存；不要每次构建临时下载浮动版本。官方还明确提醒，使用 go install 时应安装 github.com/bufbuild/buf/cmd/buf@<exact-version>，不要通过项目的 tools.go 或 go tool 解析 Buf 自身依赖，否则项目 go.mod 可能把 Buf 的依赖图改成不兼容组合。

Buf CLI 及 @bufbuild/buf 包采用 Apache-2.0 许可，本地 format、lint、build、breaking 和本地插件生成可以作为开源工具链独立运行。BSR 是另一条产品边界：公共 buf.build 有 Community、Teams 等订阅，Pro/Enterprise 使用私有实例，on-prem BSR还需要 Buf 签发的许可证。远程插件、私有仓库、集中策略、审计、SSO、bot user 和保留额度不能因为 CLI 开源就推断为免费或离线可用；采购前应把本地 CLI 能力、公共 BSR、私有托管实例和 on-prem 实例分别列项核对。

临时容器适合只做 schema 检查：

docker run --rm \
  --volume "$PWD:/workspace" \
  --workdir /workspace \
  bufbuild/buf:1.71.0 lint

镜像的入口已经是 buf，命令里不要再写一遍 buf。官方镜像只包含 Buf CLI，不包含 protoc 和本地插件；远程插件可以直接使用，需要本地 protoc 插件的生成链则要自建镜像并锁定其中每个工具版本。无论采用哪种入口，流水线第一步都应打印 buf --version，失败时再检查 PATH、CPU 架构、代理、企业 CA 和下载来源，而不是直接改 schema 规避报错。

proto3 的默认值不是“调用方明确传了零”

先建立一个最小 gRPC schema。目录路径和 package 保持一致，可以让 lint、import 与代码审查更直观：

schema-lab/
  buf.yaml
  buf.gen.yaml
  proto/
    acme/weather/v1/weather.proto

syntax = "proto3";

package acme.weather.v1;

message GetForecastRequest {
  string city = 1;
  optional int32 days = 2;
}

message GetForecastResponse {
  repeated string summaries = 1;
}

service WeatherService {
  rpc GetForecast(GetForecastRequest) returns (GetForecastResponse);
}

package acme.weather.v1 是 Protobuf 类型命名空间的一部分，不等于 Java package、Go import path 或 C# namespace。gRPC 方法的完整身份会包含它，例如 /acme.weather.v1.WeatherService/GetForecast。修改 package 不只是移动目录：服务发现、鉴权规则、指标标签、反射客户端和生成代码引用都可能同时变化。稳定 API 应把不兼容系列放入新的 package，例如从 v1 演进到 v2，并在迁移期并行提供两个服务身份。

每个字段编号必须在 1 到 536870911 之间，且不能使用 Protobuf 保留的 19000 到 19999。编号 1 到 15 的 tag 通常只占一个字节，16 到 2047 通常占两个字节，因此高频字段适合使用较小编号；可读性排序不能成为重新编号的理由。wire 数据保存的是 field number、wire type 和值，并不保存源代码中的字段名。修改字段名在 binary wire 上可能安全，改编号却等价于删除旧字段再添加新字段。

days 使用 optional 是有意为之。Protobuf field presence 文档指出，proto3 未标记 optional 的基础标量采用 implicit presence：整数 0、布尔 false、空字符串等默认值不会被序列化，解析后也无法区分“调用方没传”和“调用方明确传了默认值”。这会让 PATCH、默认策略和审计语义变得含糊。显式 optional 会生成 presence API，使“未设置”和“已设置为 0”成为两个状态；message 与 oneof 本身已有 presence，repeated 和 map 则没有这种已设置/未设置区分。

枚举也有相同陷阱。proto3 要求第一个枚举值为 0，它也是字段未出现时的默认值。把零值命名为 WEATHER_STATUS_UNSPECIFIED，并在业务入口拒绝或显式处理它，比让 0 代表某个真实业务状态更稳妥。新增枚举值在 binary wire 上通常可解析，但旧语言代码的穷举 switch 仍可能编译失败或落入错误分支，所以 wire-safe 不等于 source-safe、JSON-safe 或 business-safe。

字段退役后同时保留编号和名称：

message GetForecastRequest {
  string city = 1;
  reserved 2;
  reserved "days";
  optional string locale = 3;
}

reserved 2 阻止未来复用 wire 身份，reserved "days" 降低 TextFormat 和 JSON 名称复用风险；在 proto2/proto3 语法中，名称和编号不能写在同一条 reserved 语句中。字段刚停止写入时不应立刻删除：先标记 deprecated = true，确认生产者、消费者、历史消息、缓存和持久化 Proto 都不再依赖，再删除并 reserved。deprecated 多数语言只影响生成代码的提示，不会阻止线上流量继续携带该字段。

proto3 语言指南还区分 binary wire 与 ProtoJSON。生成消息解析新字段时会把它保存在 unknown field set，并在再次进行 binary 序列化时带回；但“保留”不是所有中间处理都成立。把消息转成 JSON、逐字段复制到新对象，或经过不保留 unknown fields 的动态映射层，都会丢掉旧客户端不认识的数据。ProtoJSON 默认按字段名传输，移除字段、重命名字段、改变枚举名称或让旧解析器遇到未知 JSON 字段都可能失败。代理服务若承担透传职责，应增加一次“新消息 -> 旧代理解析并重序列化 -> 新消费者”的二进制反证，并单独回放 JSON 网关样本；只跑 binary breaking 检查不能证明这两条链安全。

Protobuf Editions 已经把语言演进从 syntax = "proto2"/"proto3" 切换为 edition 与 feature set；当前最新发布的是 Edition 2024 版本。Edition 2023/2024 版本的单值基础字段默认采用 explicit presence，迁移后的 proto3 隐式字段若要保持原语义，会显式带上 features.field_presence = IMPLICIT。另一个容易踩坑的差异是 reserved 名称：Editions 写成 reserved days;，不再使用引号；机械复制 proto3 的 reserved "days"; 会直接编译失败。

Edition 迁移本身可以保持 binary、TextFormat 和 JSON 编码不变，但 feature 默认值会影响生成 API、命名检查、符号可见性和语言专属行为。Edition 2024 版本还改变了部分 Go、C++、Java 默认生成行为，因此迁移门禁必须同时比较 descriptor image、全量生成 diff、各语言编译测试和 runtime 版本矩阵。只把第一行改成 edition = "2024";，既不能证明插件声明支持该 edition，也不能证明生成代码与旧消费者 source-compatible。

三个配置文件分别保存声明、生成和解析结果

仓库根目录的 buf.yaml 使用 v2 配置，把本地 proto 目录声明为一个模块，并设置团队规则：

version: v2
modules:
  - path: proto
    name: buf.build/your-org/weather
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

modules[].path 决定 import root。文件 proto/acme/weather/v1/weather.proto 的 import path 是 acme/weather/v1/weather.proto，不是带 proto/ 前缀的文件系统路径。name 把本地模块映射到 BSR 仓库；只在本地和 Git 比较时可以暂不配置，使用 --against-registry 或 buf push 时必须存在且与有权限的 BSR 仓库一致。

lint.use: STANDARD 检查目录、package、命名、请求响应类型和常见 schema 约定。例外应该精确到规则和路径，并带 owner 与移除条件；把整个目录放进 ignore 会让新文件也永久绕过门禁。v2 配置允许模块级 lint 或 breaking 配置覆盖工作区默认值，但这是整段覆盖而不是合并，子模块只写一条例外时可能意外丢掉所有默认规则。

breaking.use: FILE 是默认且最严格的内置类别，保护按文件生成的 source API，同时包含较宽松类别的约束。PACKAGE 允许类型在同一 package 的文件间移动；WIRE_JSON 关注 binary 与 JSON 编码；WIRE 只关注 binary wire。库型 schema 或大量外部消费者通常从 FILE 开始。若团队只选择 WIRE，就必须用多语言编译和消费者契约补回 source API 风险，不能把“检查通过”解释成所有客户端都兼容。

仓库里的 buf.yaml 和 CI 只能证明当前提交按当前配置执行过检查，不能阻止拥有写权限的人删除规则后再 push。需要集中约束时，可以把 lint、breaking 和自定义 check plugin 组合成 buf.policy.yaml；本地 policy 仍随仓库权限变化，上传到 BSR 并在实例、组织或仓库范围强制执行则属于 Enterprise schema checks。BSR 侧检查会覆盖本地较宽松配置，并把失败提交拒绝或送入 owner review flow。没有该商业能力的团队，应依靠受保护分支、CODEOWNERS、不可由 PR 修改的 CI 模板和发布身份分离补上控制面，不能把 buf breaking 命令存在视为策略不可绕过。

引用外部模块时，在 buf.yaml 增加 deps：

deps:
  - buf.build/googleapis/googleapis

随后运行：

buf dep update
buf build

buf dep update 解析直接与传递依赖，生成 buf.lock。应同时提交 buf.yaml 和 buf.lock：前者保存期望依赖，后者保存 BSR commit 与内容 digest。根据 Buf 依赖管理文档，构建会校验下载内容是否与 lockfile 摘要一致；不一致时直接失败，避免上游内容被静默替换。团队升级依赖时单独执行 buf dep update、审查 lockfile diff、重新运行 breaking 和生成代码编译，普通 CI 则不得偷偷重写锁文件。

Buf 会缓存下载过的依赖。缓存优先使用 BUF_CACHE_DIR，其次是 XDG_CACHE_HOME/buf，默认落在用户缓存目录；Windows 默认在 %LocalAppData%\buf。共享 runner 可以缓存该目录以节省网络和 CI 时间，但 cache key 至少要包含操作系统、CPU、Buf 版本和 buf.lock 摘要。缓存是加速层，不是事实源；出现 digest mismatch、权限错误或疑似污染时先保留日志，再删除对应 runner 的 Buf 缓存并从受信入口重新获取，不要删除开发者整个用户缓存目录。

buf.gen.yaml 只描述生成过程。下面使用经过验证的固定插件版本生成 Go 消息代码和 gRPC stub：

version: v2
clean: true
managed:
  enabled: true
  disable:
    - file_option: go_package_prefix
      module: buf.build/googleapis/googleapis
  override:
    - file_option: go_package_prefix
      module: buf.build/your-org/weather
      value: example.com/your-org/weather/gen
plugins:
  - remote: buf.build/protocolbuffers/go:v1.35.2
    revision: 1
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/grpc/go:v1.5.1
    revision: 1
    out: gen/go
    opt: paths=source_relative
inputs:
  - directory: proto

clean: true 会在生成前删除每个插件的 out 目录、zip 或 jar 输出。gen/go 必须是纯生成目录，不能混放手写代码，否则一次生成就会删除手工文件。inputs 在 v2 中把生成输入也收进配置；命令行的 --path、--type 等过滤仍能进一步收窄输入，临时过滤不应成为 CI 的隐藏默认值。

remote plugin 引用必须固定 upstream version；revision 再固定 Buf 对同一 upstream 版本的重新打包序号。不写版本会解析最新插件，只写 upstream version 而不写 revision 仍可能在重新打包后得到不同制品。示例中的 revision: 1 只是配置形态，真实仓库应从 BSR 插件页读取存在的 revision，并把插件版本、revision、生成输出摘要和 runtime 版本一起纳入升级 PR。

Managed mode在生成时重写 go_package、java_package、csharp_namespace 等语言选项，让 schema producer 不必为每个 consumer 固化语言目录。它不会修改仓库里的 .proto，却会改变插件收到的 descriptor，因此也是生成 API 的一部分。上面的 disable 避免把 googleapis 依赖错误地映射到本地 Go 前缀；带 module 条件的 override 则只管理自有模块。新加外部依赖时仍要检查它是否已有正确语言选项，不能假设一条 disable 覆盖所有第三方模块。多语言团队应为不同消费方保留独立、命名清晰的生成配置，不能用一套 override 强迫所有语言共享目录模型。

不允许 schema 离开内网、需要自定义插件或必须离线生成时，改用本地插件：

version: v2
plugins:
  - local: protoc-gen-go
    out: gen/go
    opt: paths=source_relative
  - local: protoc-gen-go-grpc
    out: gen/go
    opt: paths=source_relative

本地模式把供应链责任交回团队：插件是会读取编译后 schema 并在 runner 上执行的外部程序，不是被动模板。插件必须由受信仓库或制品库提供，版本和摘要由工具镜像或 lockfile 固定，CI 打印解析到的绝对路径与版本；来自不受信 PR 的 local 命令不能在持有发布 token、签名密钥或云凭证的 job 中运行。远程插件省去本地安装，但会把生成输入及其依赖、options 和可选 source info 发送给 BSR 的远程执行器；私有 API、受出口管控的 schema 和自定义 options 必须先确认数据处理、网络出口、租户、保留和权限策略。两种模式都要审查插件发布者、许可证和生成 diff，并编译测试，不能只比较有没有生成文件。

从 format 到 descriptor image 跑通第一次闭环

在 schema-lab 根目录执行：

buf format -w
buf format --exit-code
buf lint
buf build -o schema.binpb
buf generate

第一条把 .proto 写回统一格式；第二条在文件仍需格式化时返回非零，适合作为 CI 门禁。格式正确时它会把格式化内容写到标准输出，因此 CI 可以重定向输出或使用 -d 查看 diff。Windows 上若出现 exec: "diff": executable file not found in %PATH%，说明当前 Buf 分发入口无法找到外部 diff，不是 schema 语法错误；把 Git for Windows 的 usr/bin 或组织批准的 diff 工具加入 runner PATH 后重试，并记录最终解析到的可执行文件。

buf lint 成功时通常没有输出。失败证据应包含文件、行列、规则和消息，例如 package 与目录不一致、RPC 请求类型命名不合规。不要用 except: [RULE] 先消掉红灯；先判断是 schema 设计错误、迁移期遗留，还是规则确实不适合该模块。

buf build -o schema.binpb 会解析 import、校验 descriptor 并构建 Buf image。这个 image 与 FileDescriptorSet wire-compatible，是 lint、breaking、反射、文档和生成链共享的中间事实。文件大小会随 schema、source info 和依赖变化，不能用固定字节数做通用成功标准；可靠判据是命令退出 0、image 可被下一步读取、同一锁定输入重复构建得到稳定内容。

buf generate 使用远程插件后，应看到：

gen/go/acme/weather/v1/weather.pb.go
gen/go/acme/weather/v1/weather_grpc.pb.go

前者包含消息、字段访问和 descriptor，后者包含 gRPC client、server interface、方法常量与注册代码。若只生成 weather.pb.go，通常是缺少 gRPC 插件；若报 plugin not found，检查 local/remote 类型、插件版本、PATH 和 BSR 网络；若 import path 异常，检查 managed override、外部模块 disable 和 paths=source_relative。生成成功后立即运行目标语言的依赖解析、编译和测试，因为 Buf 不能证明 runtime 依赖已经匹配。

临时实验结束后删除 schema.binpb 和纯生成目录；项目若提交生成代码，则先用 Git 确认没有手写文件再清理：

rm -f schema.binpb
rm -rf gen/go

PowerShell 应使用已确认的仓库内相对路径：

Remove-Item -LiteralPath .\schema.binpb -ErrorAction SilentlyContinue
Remove-Item -LiteralPath .\gen\go -Recurse -Force -ErrorAction SilentlyContinue

不要把“重新生成”当成 schema 回滚。生成目录可以重建，已经被客户端、消息和持久化数据使用的 field number 却不能安全擦除。

用 Git 基线证明哪些改动真的会破坏契约

先把格式化后的最小 schema 提交为基线：

git init -b main
git add buf.yaml buf.gen.yaml proto
git commit -m "建立 weather v1 schema 基线"

正向实验给请求增加一个从未使用过的编号：

message GetForecastRequest {
  string city = 1;
  optional int32 days = 2;
  optional string locale = 3;
}

执行：

buf format -w
buf lint
buf breaking --against '.git#branch=main'
echo $?

预期没有 violation，退出码为 0。新发送方携带字段 3 时，旧 binary consumer 会把它作为未知字段处理；但业务上线仍需验证旧服务是否代理后重新序列化、JSON 网关是否拒绝未知字段、数据库或日志是否保存完整消息，以及新代码如何解释 locale 未设置。

接着制造稳定失败：把编号 2 的类型从 int32 改成 string，保持名称不变。

message GetForecastRequest {
  string city = 1;
  optional string days = 2;
  optional string locale = 3;
}

buf breaking --against '.git#branch=main'

可观察到的核心错误为：

proto/acme/weather/v1/weather.proto:6:10:Field "2" with name "days" on message "GetForecastRequest" changed type from "int32" to "string".

命令返回非零；Buf CLI 对 check violation 使用专门退出码，CI 应按“非零即阻断”处理，不要依赖某个长期不变的数字。错误把身份钉在 message 与 field number 2 上，说明改字段名无法修复问题。正确迁移是保留字段 2，新增 optional string days_text = 4，让生产者双写或服务端转换，等待所有消费者迁移后再停止字段 2，并最终 reserved 编号和名称。

删除 RPC、移动类型、修改 package 或更换 streaming 形态也应各做一次反向实验。FILE 会把同一 package 内跨文件移动视为 source break；团队若改用 PACKAGE 放行这类移动，仍要验证 Java outer class、Go import、生成文件路径和消费者编译结果。Buf 的 breaking checker不理解任意 custom option 的业务语义，例如 google.api.http 路由变化；HTTP 映射、鉴权 annotation、校验 option 和数据分类 option 需要额外策略插件或专用测试。

Git 和 BSR 是两种不同的兼容基线

Git 基线适合代码库拥有 schema 事实源的团队。PR 中比较主分支：

buf breaking --against '.git#branch=main'

CI 经常使用 shallow clone，主分支对象可能根本不存在。不要把 fatal: reference not found 当成“没有 breaking change”；显式 fetch 基线，或使用 Buf breaking usage guide支持的远程 Git 输入：

buf breaking \
  --against 'https://github.com/your-org/your-project.git#branch=main,subdir=path/to/schema'

私有 Git 仓库不要把 token 拼进 URL。Buf 的 Git 输入通过系统 Git 处理 SSH，可复用 ssh-agent 和 known_hosts；也支持专用 SSH key 文件与 known-hosts 配置。CI deploy key 只授予目标仓库只读权限，日志屏蔽命令回显，主机指纹必须固定，不能为了“先跑通”关闭 host key verification。

BSR 基线适合 schema 已作为独立模块发布、消费者跨仓库或需要统一文档和生成 SDK 的组织。buf.yaml 中每个模块都配置 name 后，可以比较 Registry 默认分支的最新提交：

buf breaking --against-registry

也可以显式比较单个模块：

buf breaking --against buf.build/your-org/weather

Git 比较回答“相对代码主分支是否破坏”，BSR 比较回答“相对消费者可见的已发布模块是否破坏”。发布流水线晚于 Git 合并、多个仓库共享一个模块或发生紧急回退时，两者可能指向不同状态。生产门禁应指定哪一个是发布权威，并把 Git commit、BSR commit/label 与生成 SDK 版本关联起来。

推送模块前按顺序执行：

buf dep update
buf format --exit-code
buf lint
buf build
buf breaking --against-registry
buf push

buf push 会解析工作区内模块依赖并按依赖顺序发布。开发者本机使用 buf registry login，浏览器授权后 token 写入 .netrc；退出使用 buf registry logout。该 logout 会清理 .netrc 中的 BSR 凭证，机器连接多个 BSR 时应先确认影响。公开模块读取通常不需要凭证，私有模块读取、push 和管理操作需要授权。

CI 把短期、可撤销 token 放入 secret store，通过 BUF_TOKEN 注入。环境变量优先级高于 .netrc，任务结束后不应把环境、debug trace 或 home 目录打包为制品。公共 BSR 与私有实例并用时，BUF_TOKEN 支持按 hostname 绑定多个 token；每个 token 都只授予所需组织、仓库和动作。共享个人 token 会让离职回收和审计失效；私有 BSR 实例可使用不绑定个人的 bot user，公共 buf.build 不提供同一能力，需按实际租户的账号和组织策略设计自动化身份。

让 CI 同时检查 schema、生成物和 runtime

一个最小 GitHub Actions PR 作业可以保持命令透明：

name: schema

on:
  pull_request:

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: bufbuild/buf-setup-action@v1
        with:
          version: 1.71.0
      - run: buf --version
      - run: buf format --exit-code >/dev/null
      - run: buf lint
      - run: buf build -o schema.binpb
      - run: buf breaking --against '.git#ref=refs/remotes/origin/main'
      - run: buf generate
      - run: git diff --exit-code -- gen

fetch-depth: 0 保证 Git 基线对象存在；大型仓库也可以显式 fetch 单一 ref。format 的标准输出被丢弃，只保留退出码和错误；schema.binpb 可以作为后续文档或策略检查的 job artifact，但若含私有 options、注释或敏感 API 名称，就要限制下载权限和保留周期。

git diff --exit-code -- gen 适用于“生成代码提交进仓库”的策略：开发者忘记生成或插件输出漂移时，CI 会失败。若选择“构建时生成、不提交生成物”，则应在干净 runner 生成后直接编译、测试并打包 SDK，制品元数据记录 schema commit、Buf 版本、插件版本和 runtime 依赖。两种策略都成立；最危险的是部分语言提交生成物、部分语言临时生成，却没有 owner 说明谁负责升级和发布。

生成代码与 runtime 漂移不能靠 buf breaking 发现。Protobuf cross-version runtime guarantee明确把语言绑定分成 gencode 和 runtime：较新的生成代码配较旧 runtime 不受支持，多 major runtime 在同一进程共存也不受支持；C++ 和 Rust 要求生成代码与 runtime 精确匹配，C++ 还不承诺跨发布 ABI 稳定。各语言的生成器可能给出更严格规则，因此每次插件升级都要同步检查语言 runtime、gRPC runtime、编译器和框架插件。

Go 生成后至少运行 go mod tidy 和 go test ./...，Java/Kotlin 运行依赖解析、编译和测试，C++ 重新构建全部链接目标。真正的失败证据常见为生成文件引用 runtime 中不存在的 symbol、启动时版本检查报错、重复类或多个 major runtime 冲突，而不是 buf generate 自身失败。依赖机器人应把 remote plugin 与 runtime 升级放在同一 PR，或明确记录允许的版本矩阵；只升级 buf CLI 通常不改变 runtime，但升级插件会改变 gencode。

发布作业和 PR 作业也要分权。PR 只读 Git/BSR 并执行检查，不需要 push token；主分支发布在受保护 environment 中取得写 token，先重复 lint、build、breaking 与生成编译，再 buf push。来自 fork 的不受信代码不能接触 BUF_TOKEN，更不能执行可由 PR 修改的本地生成插件后继续使用高权限凭证。

容量和费用从提交数量、生成次数与制品保留增长

Buf CLI 的本地 lint 和 build 主要消耗 CPU、内存与依赖缓存；schema 越多、import graph 越大，clean CI 的解析与下载时间越明显。远程插件增加上传 schema、排队执行和下载生成物的网络成本；多语言矩阵会把一次 schema 变更放大为多次插件执行和编译。BSR 还会保存模块 commit、文档、依赖关系和生成 SDK，私有仓库、用户席位、治理能力与保留策略可能受租户方案影响。采购和容量评估应从 Buf pricing与目标租户管理页读取实际能力，不把网页上的动态额度写进仓库策略。

可控的成本模型比一个固定数字更有用。记录每次 PR 的 .proto 文件数、descriptor image 大小、依赖下载字节、各插件耗时、生成文件数量与字节、语言编译耗时、远程失败率和 BSR commit 增长；观察这些指标随模块与语言数的趋势。大型组织可以按稳定 ownership 拆模块，让无关团队不必为一次局部变更重新生成全部 SDK，但过度拆分会增加依赖边、发布顺序和凭证授权。拆分点应同时满足独立版本节奏、清晰 owner 和可控 import 方向。

CI 缓存只保存可验证的下载物，不缓存带写权限的 home、.netrc 或临时 token。生成 SDK 和 descriptor artifact 设置与消费者升级周期匹配的保留策略；长期证据保存 schema commit、插件/runtime 版本和摘要即可，没必要无限保存每个 PR 的重复生成目录。remote plugin 或 BSR 不可用时，关键发布链应能选择已批准的本地插件镜像和 lockfile 缓存继续构建，但离线结果仍要在恢复后与发布权威对账。

升级、弃用和回退要围绕消费者状态设计

Buf v2 把 workspace modules、生成 inputs 与 managed mode 规则统一进新配置模型。旧仓库可能仍有 v1beta1、v1、旧字段名或把生成输入藏在 shell 参数里的模板；CLI 尚能识别旧版本不等于它们适合作为新基线。升级先执行配置迁移，在独立分支比较 buf build image、lint violations 和全部生成 diff，再切换 CI。不要在同一个变更里同时迁移 Buf 配置、切换 Protobuf edition、升级插件、修改 package 和删除字段，否则失败时无法判断是哪一层改变了行为。

proto3 optional 已是稳定语义，现代 protoc 不再需要早期的 --experimental_allow_proto3_optional。遗留脚本若仍携带实验 flag，应在升级编译器时验证并移除，避免团队误以为 presence 仍是实验能力。准备迁移 Protobuf Editions 时，先用 explicit presence 消除标量默认值歧义，再按目标语言生成器支持矩阵逐步转换；不能只改文件首行就假设所有插件和 runtime 已理解新 feature set。

schema 发布后，Git revert 只会恢复源码，不能让已经发布的客户端、消息和缓存回到旧状态。安全的恢复动作取决于变化类型：

尚未发布的 breaking change 直接回退 PR，并删除对应生成 diff。已发布但未被生产者使用的新增字段可以停止发布新 SDK，保留 field number，重新发布修正版。已有生产流量的字段先停止新写入、保留旧读路径、观测消费者版本，再弃用和 reserved。

package 或 RPC 身份迁移使用 v1/v2 双服务、流量与客户端分批切换，不能原地改名后依赖紧急回滚。错误插件生成的 SDK 应撤销或标记问题版本，恢复已验证插件/runtime 组合并重新生成；不能手工修补生成文件后继续发布。

长期治理需要把 schema 当成独立产品，而不是服务仓库里的附件。每个模块有 owner、消费者清单、稳定性级别和发布权威；每次变更有 lint、format、breaking、生成 diff、多语言编译和必要的 binary/JSON 回放；每个例外有到期条件；每个 token 有最小权限、轮换与撤销演练；每次插件和 runtime 升级保存版本矩阵与回退制品。这样，字段编号不再靠口头约定，gRPC 方法也不会等到线上旧客户端报错后才第一次接受兼容性检查。