读懂 Moby 中 vendored 的 cloud.google.com/go：CHANGES.md 变更史及其在 Docker 守护进程中的角色

本文以 Moby（Docker 引擎仓库）中 vendored 依赖 vendor/cloud.google.com/go/CHANGES.md 为切入点，完整讲解这份 Google Cloud Go 客户端库变更日志的结构、版本约定与关键演进节点，并结合 go.mod 与 GCP 日志驱动 的源码，说明该库在 Moby 中实际的消费位置与维护含义。读完后，你将能够独立解读这类 vendored 依赖的 changelog、定位其在宿主仓库中的依赖版本，并判断一次依赖升级对 Moby 构建的实际影响。

文档定位：Moby 仓库里的第三方变更史

CHANGES.md 是 Go 模块 cloud.google.com/go（Google Cloud 官方 Go 客户端库，项目内部称 google-cloud-go）的完整变更历史，共 2808 行，记录了从最早的 v0.2.0 预览版到 2025-09-18 发布的 0.123.0 的全部版本条目。在 Moby 仓库中，它以 vendor 目录的形式被完整落盘——这是 Go 模块 vendoring 的常规产物：为了让 Moby 的构建在离线、可复现的环境下进行，第三方依赖的源码连同文档一起被拷贝进 vendor/cloud.google.com/go 目录。

从 vendor/cloud.google.com/go 的目录结构可以看到，vendor 下来的并不只是这份变更史，还有 README.md、RELEASING.md、go.work 以及子模块 auth/、compute/metadata、logging/、longrunning/ 等——它们对应下文 go.mod 依赖清单中列出的各个独立 Go 模块。

消费方：Moby 到底用了 cloud.google.com/go 的什么

理解这份 changelog 的现实意义，先要弄清 Moby 在哪些代码路径上依赖了它。

根目录 go.mod 中的依赖声明（第 129～132 行附近）为：

cloud.google.com/go v0.123.0 // indirect
cloud.google.com/go/auth v0.20.0 // indirect
cloud.google.com/go/auth/oauth2adapt v0.2.8 // indirect
cloud.google.com/go/longrunning v1.2.0 // indirect
cloud.google.com/go/compute/metadata v0.9.0
cloud.google.com/go/logging v1.19.1

可以看到 cloud.google.com/go v0.123.0 与 vendor 目录中这份 CHANGES.md 的末位版本号完全一致，即当前快照对应的正是 2025-09-18 这一版。真正直接使用的入口在 daemon/logger/gcplogs/gcplogging.go：该文件第 13～14 行导入了 cloud.google.com/go/compute/metadata 与 cloud.google.com/go/logging，并在第 108 行调用 logging.NewClient(context.Background(), project) 创建日志客户端——这就是 Moby 的 GCP Stackdriver 日志驱动（GCP logging driver）：容器日志会被写入 Google Cloud Logging。此外，compute/metadata 包负责检测 GCE 元数据服务、解析项目 ID，是日志驱动自动识别 project 参数的前置能力。

因此，当你在这份 CHANGES.md 中看到 logging:、compute/metadata: 开头的条目时，它们直接关系到 Moby GCP 日志驱动的可用性；而 internal/gapicgen、internal/postprocessor、godocfx 这类条目属于上游的客户端代码生成工具链，对 Moby 的运行时没有直接影响，只影响库自身的演进方式。

changelog 的结构与版本约定

这份文档的排版遵循 release-please 工具自动生成的格式，读懂它需要掌握以下几点约定。

条目格式：Features / Bug Fixes / Documentation / Reverts

0.66.0 之后的每个版本块形如：

## [0.123.0](https://github.com/googleapis/google-cloud-go/compare/v0.122.0...v0.123.0) (2025-09-18)

### Features

* **internal/stategen:** Populate the latest googleapis commit (...)
* **librariangen:** Implement the build command (...)

### Bug Fixes

* **internal/librariangen:** Add link to source commit in release notes (...)

条目以 **scope:** 描述 的形式书写，scope 即受影响的子模块或子包（如 civil、transport、internal/trace）。### ⚠ BREAKING CHANGES 小节用于标注破坏性变更，例如 0.90.0（2021-08-03）中 compute: add pagination and an Operation wrapper，0.88.0 中 cloudbuild 对 WorkerPool 资源定义的替换。升级依赖时，这类小节是必须优先阅读的。

0.65.0 中的"默认超时"公告：对调用方有实际行为的变更

0.65.0（2020-08-27）包含一段 Announcements 说明：非流式方法（如 Create、Get）默认会对调用时的 context 施加默认 deadline，而流式方法不设默认 deadline；如需关闭该行为，可在初始化客户端前设置环境变量：

export GOOGLE_API_GO_EXPERIMENTAL_DISABLE_DEFAULT_DEADLINE=true

这是一个典型的"行为层面"的变更——API 签名未变，但超时语义改变，对 Moby 中 logging.NewClient 之后的所有 RPC 都有潜在影响，值得在依赖升级评审中单独关注。

"空发布"：模块拆分的技术痕迹

文中多次出现这样的版本，例如 v0.46.3、v0.46.2、v0.45.1：

This is an empty release that was created solely to aid in storage's module
carve-out.

这类版本不包含任何代码变更，唯一目的是配合 Go 多模块仓库的"模块拆分"（carve-out）：storage、spanner、firestore、pubsub、bigtable、bigquery、datastore、logging 等曾经共享同一版本号的包，被逐个拆成独立模块（各自拥有 go.mod 与独立版本号）。这也解释了为何 Moby 的 go.mod 里 cloud.google.com/go/logging 已是 v1.19.1，而主模块停留在 0.123.0——拆分之后的模块按自己的节奏演进，CHANGES.md 只继续为主模块记史，各子模块拥有自己的变更文件（如 vendor/cloud.google.com/go/logging/CHANGES.md）。

双轨排版的过渡痕迹

0.62.0 之前的条目采用传统手工排版的 ## vX.Y.Z + 项目符号 格式（如 v0.53.0 记录"多数客户端从 transport/grpc.Dial 迁移到 DialPool 以启用连接池"），0.62.0 起逐步切换为 release-please 的自动格式。文档末尾还能看到 v0.2.0 时代对 preview/logging（gRPC 传输、支持日志读取/sinks/metrics）的描述——这正是后来独立成 cloud.google.com/go/logging 模块的前身，也是 Moby GCP 日志驱动所依赖的那个包。

演进主线：从这份变更史里读出的四条脉络

1. 客户端生成工具链的持续重构。 0.82.0 引入 internal/gensnippets 自动生成示例代码与 region tag，0.89.0 引入 internal/carver 工具辅助模块拆分，0.92.0 加入 internal/detect 辅助从环境探测项目 ID，0.110.0 让 postprocessor 能检测并初始化新模块，直到 0.121.0/0.122.0/0.123.0 的 librariangen（release-init、build 命令）。这条线说明该库自身是一套高度自动化的"客户端工厂"，升级它通常意味着大批 gapic 客户端被重新生成。
2. 遥测从 OpenCensus 迁移到 OpenTelemetry。 0.111.0（2023-11-29）internal/trace 加入 OpenTelemetry 支持，0.115.0 弃用 OpenCensus，0.117.0 移除 OpenCensus 支持，0.118.1 彻底移除 OpenCensus 依赖。若上游代码曾依赖 OpenCensus 采集 GCP RPC 链路，则必须同步迁移。
3. REST（REGAPIC）与 gRPC 双通道并存。 0.108.0 启用 REGAPIC 与 REST 数字枚举，0.107.0 起 routing 包开始生成 apiv2。部分客户端因此同时提供 gRPC 与 REST 实现，升级时需留意所选通道。
4. civil 包的持续增强。 civil.Date/Time/DateTime 陆续获得 IsEmpty（0.96.0）、Compare（0.113.0/0.114.0）、AddMonths/AddYears/Weekday（0.118.0）、database/sql 的 Scanner/Valuer 实现（0.120.0）以及 Scan 方法对 civil 类型的支持（0.121.1）。该包被多个 GCP 客户端用于时间类型，属于纯增量增强。

版本核对与维护要点

结合 Moby 仓库现状，这份 changelog 的实用读法可以归纳为：

• 版本对齐核对：go.mod 中 cloud.google.com/go v0.123.0 与 vendor 目录中 CHANGES.md 的最高版本号一致，说明 vendored 快照与声明的依赖版本同步，未出现 go.mod 与 vendor 目录漂移。
• 升级路径评估：若未来升级 cloud.google.com/go/logging（GCP 日志驱动直接依赖），应交叉阅读 vendor/cloud.google.com/go/CHANGES.md 中 logging: 相关条目与 vendor/cloud.google.com/go/logging/CHANGES.md 的独立历史，特别关注 BREAKING CHANGES 小节与超时/重试语义类公告（如 0.65.0 的默认 deadline 机制）。
• 传递依赖风险：go.mod 中标注 // indirect 的 auth、longrunning、oauth2adapt 属于 logging/metadata 的传递依赖。changelog 中 0.118.2/0.118.3 一类"依赖版本提升"（如 grpc 升级）条目，正是评估传递依赖安全性的信息来源。
• 只读视角：本仓库为只读分析对象，上述核对均通过阅读 go.mod、vendor/cloud.google.com/go/CHANGES.md 与 daemon/logger/gcplogs/gcplogging.go 完成，不涉及任何仓库修改。

小结

vendor/cloud.google.com/go/CHANGES.md 表面是第三方库的变更流水账，实则是 Moby 维护者理解 GCP 日志驱动依赖行为演进的权威索引：release-please 条目格式、BREAKING CHANGES 标记、模块 carve-out 空发布、默认 deadline 公告等约定共同构成了它的阅读语法；而 logging 与 compute/metadata 两个包则把它与 Moby 的 GCP 日志驱动 直接挂钩。掌握这份文档，就能在依赖升级时准确判断哪些条目会波及 Moby 的构建与运行时行为。