Zipkin 发布流程深度解析：从 release 标签到 Maven Central、Docker Hub 与 Javadoc 的自动化发布指南

• 可观测性
• 后端
• 微服务

OpenZipkin 的 RELEASE.md 定义了 Zipkin 从代码提交到发布产物的完整自动化流程：基于语义化版本号，通过推送 git 标签触发 CI 流水线，最终把 jar 发布到 Maven Central、把镜像推送到 Docker Hub / GHCR、把 Javadoc 发布到站点。本文以该文档为主干，结合仓库中的 build-bin 发布脚本与 .github/workflows 工作流源码，逐环节拆解触发机制、脚本调用链、凭据配置与手动兜底方案，帮助读者掌握 Zipkin 的版本发布全貌，并可直接复用同一套思路管理自己的 Zipkin 系项目发布。

一、版本号约定：语义化版本是发布的前提

RELEASE.md 开宗明义：本仓库使用语义化版本（Semantic Versioning），选择版本号时必须遵守MAJOR.MINOR.PATCH三段式规则：

• MAJOR：不兼容的 API 变更；
• MINOR：向后兼容的功能新增；
• PATCH：向后兼容的缺陷修复。

这一约定不仅是版本号的命名规范，更是整个发布自动化的基础——CI 工作流正是通过正则匹配MAJOR.MINOR.PATCH格式的标签来判定“这是一次发布”。当前仓库根目录的 pom.xml 中的<version>即遵循该格式（含-SNAPSHOT后缀的开发版本）。

二、发布前检查与团队协作

正式动手发布前，RELEASE.md 要求完成两项准备：

1. 确认所有依赖已更新到最新，或者明确记录未更新的原因。重点检查 安全扫描工作流（security workflow），它应当干净通过，避免把已知漏洞带进发布版本。
2. 提前在团队沟通渠道（如 Gitter 的 openzipkin/zipkin 频道）告知“我要发布”。发布过程大约持续 10 分钟，期间master分支不应有任何新提交。一旦有人误合并代码导致构建失败，就必须重建下述的发布标签。

从源码看，这一警告并非空穴来风：build-bin/maven/maven_release 脚本在打版本标签前会做一次严格的一致性校验——比较本地master与远端origin/master的最新提交哈希：

commit_local_release_branch=$(git show --pretty='format:%H' ${release_branch}) commit_remote_release_branch=$(git show --pretty='format:%H' origin/${release_branch}) if [ "$commit_local_release_branch" != "$commit_remote_release_branch" ]; then >&2 echo "${release_branch} on remote 'origin' has commits since the version to release, aborting" exit 1 fi

也就是说，如果发布期间master出现了新提交，脚本会直接中止并报错“远端分支存在发布版本之后的新提交”，这正是要求在发布窗口内冻结提交的根本原因。

三、核心机制：双标签触发自动化

Zipkin 的发布自动化围绕两个 git 标签展开，二者分工明确、层层递进。

3.1 第一步：推送release-MAJOR.MINOR.PATCH触发标签

发布者在master上执行：

git tag release-1.18.1 && git push origin release-1.18.1

该标签的格式为release-前缀 + 目标版本号，例如release-1.18.1。它只负责“创建发布”，本身不会携带构建产物。

对应的触发工作流是 .github/workflows/create_release.yml，其标签过滤规则为：

on: push: tags: # e.g. release-1.2.3 - 'release-[0-9]+.[0-9]+.[0-9]+**'

工作流被触发后执行的核心命令是：

build-bin/git/login_git && build-bin/maven/maven_release $(echo ${GITHUB_REF} | cut -d/ -f 3)

其中 build-bin/maven/maven_release 脚本做三件事：

1. 通过 build-bin/git/version_from_trigger_tag 从触发标签中解析出版本号。该脚本用sed提取MAJOR.MINOR.PATCH，解析成功后还会顺手删除触发标签本身（git tag -d+git push origin :${trigger_tag}），避免触发标签残留在远端；
2. 校验本地与远端master一致（见上文）；
3. 调用 Maven 的release:prepare完成“打标动作”：

./mvnw --batch-mode -nsu -DreleaseVersion=${release_version} -Denforcer.fail=false \ -Darguments="-DskipTests -Denforcer.fail=false" release:prepare

release:prepare会创建发布提交、打上MAJOR.MINOR.PATCH版本标签，并将项目版本号递增为下一个-SNAPSHOT（即 maven-release-plugin 的完整流程）。脚本开头export MAVEN_OPTS="$($(dirname "$0")/maven_opts)"统一了构建期 JVM 参数。

3.2 第二步：MAJOR.MINOR.PATCH标签触发部署

release:prepare打出的MAJOR.MINOR.PATCH标签（如1.18.1）会触发 .github/workflows/deploy.yml 中的deploy工作流，进入真正的部署阶段。该工作流的触发条件设计得很精细：

on: push: branches: - master # Don't deploy tags because the same commit for MAJOR.MINOR.PATCH is also # on master: Redundant deployment of a release version will fail uploading. tags-ignore: - '*'

也就是说：master分支的每次推送都会部署（产出 SNAPSHOT），而发布版本标签MAJOR.MINOR.PATCH同样触发部署；普通标签（tags-ignore）不触发。注释点明了原因——发布版本的提交与master是同一个 commit，如果同时按分支和标签重复部署，上传会因版本重复而失败。

工作流最终执行：

build-bin/configure_deploy && build-bin/deploy $(echo ${GITHUB_REF} | cut -d/ -f 3)

3.3 deploy 脚本：一次发布，三路产出

build-bin/deploy 是整个发布落地的总调度脚本：

version=${1:-master} # 使用 master 时，从 pom.xml 隐式读取当前版本 if [ "${version}" = "master" ]; then version=$(sed -En 's/.*<version>(.*)<\/version>.*/\1/p' pom.xml| head -1) fi build-bin/maven/maven_deploy export RELEASE_FROM_MAVEN_BUILD=true build-bin/docker_push ${version} # openzipkin/zipkin 在发布时把 Javadoc 发布到 gh-pages (https://zipkin.io/zipkin/) case ${version} in *-SNAPSHOT ) ;; * ) build-bin/javadoc_to_gh_pages ${version} ;; esac

三路产出分别为：

1. jar 发布到 Sonatype（随后同步至 Maven Central）：核心脚本是 build-bin/maven/maven_deploy：

./mvnw --batch-mode -s ./.settings.xml -Prelease -nsu -DskipTests clean deploy $@

它使用-Prelease激活发布 profile，读取根目录.settings.xml（其中引用了 GPG 与 Sonatype 凭据，由 CI 注入）执行clean deploy。同一批 jar 稍后会自动同步到 Maven Central。文档特别提醒：search.maven.org 的索引更新会比 repo1.maven.org 的直接链接慢，因此发布后建议使用仓库直链验证。

2. Docker 镜像推送：build-bin/docker_push ${version}负责构建并推送镜像，最终产物以openzipkin/zipkin形式发布到 Docker Hub，并同步镜像到 GitHub Container Registry（ghcr.io/openzipkin/zipkin）。注意脚本设置了export RELEASE_FROM_MAVEN_BUILD=true，让镜像构建复用刚由 Maven 构建出的产物，保证镜像与 jar 来自同一份代码。

3. Javadoc 发布：对于非-SNAPSHOT的发布版本，build-bin/javadoc_to_gh_pages ${version}会把 Javadoc 推送到gh-pages分支，落到站点的版本化子目录中；而-SNAPSHOT版本跳过此步。这也对应 README 中所说“zipkin.io/zipkin 下每个（非 PR）构建与每次发布都有带版本的 Javadoc 文件夹”。

3.4 发布产物速查

关于 artifact 归属，README 的 Artifacts 一节也有明确划分：服务端产物在 Maven group idio.zipkin下，核心库产物在io.zipkin.zipkin2下；SNAPSHOT 则在每次 master 提交后上传至 Sonatype。

四、凭据管理：发布自动化的“钥匙”

4.1 所需的组织级 Secrets

发布流程依赖多种凭据。从 .github/workflows/deploy.yml 的env注入可以看到完整的凭据清单（这些通常配置在 openzipkin 组织级 Actions secrets 中）：

create_release.yml 中则特别强调：必须使用带写权限的GH_TOKEN而非 GitHub Actions 默认的只读GITHUB_TOKEN，因为 maven-release-plugin 需要向master推送 release 提交。此外，deploy 工作流刻意不缓存 Docker——fork 可能窃取敏感信息，且登录会话会残留在~/.docker；得益于DOCKER_PARENT_IMAGE发布到 ghcr.io（对 runner 而言是本地仓库），放弃缓存是可接受的代价。

4.2 排查无效凭据

RELEASE.md 给出了最常见的失败场景与排查路径：

• 若 Sonatype 返回401 unauthorized，多半是SONATYPE_USER或SONATYPE_PASSWORD失效，或关联账号没有上传权限（即对io.zipkin命名空间无权限）。
• 破坏性最小的验证手段：手动发布一次 SNAPSHOT。用 CI 会传入的同一组值，在本地发起快照部署，即可验证未加密凭据是否被授权。

官方示例命令如下（注意：原文档中此处路径写作build-bin/build-bin/maven/maven_deploy，从仓库目录结构看应为build-bin/maven/maven_deploy，即原文疑为笔误，实际执行请使用单层build-bin）：

$ export GPG_TTY=$(tty) && GPG_PASSPHRASE=whackamole SONATYPE_USER=adrianmole SONATYPE_PASSWORD=ed6f20bde9123bbb2312b221 build-bin/maven/maven_deploy

export GPG_TTY=$(tty)保证 GPG 能正确读取当前终端的口令输入，在无头环境中尤为关键。

五、手动发布：脱离 CI 的完整兜底方案

如果丢失了 CI 访问权或自动化不可用，RELEASE.md 明确指出：Zipkin 本质是一个普通 Maven 项目，完全可以按 Maven 常规方式手动发布。

前置说明：

• 手动发布前先按第一节设置好个人凭据环境变量——这些值在 CI 中通常作为组织级 secrets 注入；
• 如果 Sonatype 服务宕机，下述流程将无法完成（jar 发布是整条链路的必经环节）。

完整命令序列：

# 首先，按你的个人凭据设置变量。这些值在 CI 中通常作为 org secrets 注入 export GPG_TTY=$(tty) export GPG_PASSPHRASE=your_gpg_passphrase export SONATYPE_USER=your_sonatype_account export SONATYPE_PASSWORD=your_sonatype_password release_version=xx-version-to-release-xx # 从最新 master 开始创建发布。这会创建并推送 MAJOR.MINOR.PATCH 标签 ./build-bin/maven/maven_release release-${release_version} # 一旦上一步成功，检出该版本并执行部署 git checkout ${release_version} ./build-bin/deploy # 最后，清理 release 产生的中间状态 ./mvnw release:clean git checkout master git reset HEAD --hard

几点实战提示：

• maven_release的第一个参数必须是release-前缀的完整触发标签，脚本内部会解析出版本号并校验远端master无新提交；
• ./build-bin/deploy不带参数时默认部署master，而检出release_version后再执行则会按版本标签部署，两者在 build-bin/deploy 中通过version=${1:-master}与从 pom.xml 隐式读取版本两段逻辑区分；
• 收尾的./mvnw release:clean会清理 maven-release-plugin 的临时状态，git checkout master+git reset HEAD --hard则让工作区回到干净的master状态。

六、发布中的常见坑与应对

综合文档与源码，把发布过程中的高频风险点梳理如下：

1. 发布窗口期master被推送：maven_release的哈希一致性校验会直接 abort，需要删除重建触发标签后重试。因此务必先告知团队、再打标签。
2. 重复部署导致上传失败：deploy 工作流对 master 与版本标签共用同一 commit，已通过tags-ignore: '*'避免对普通标签重复触发。
3. Sonatype 401：优先检查SONATYPE_USER/SONATYPE_PASSWORD是否过期、账号是否有io.zipkin上传权限；用“手动 SNAPSHOT 部署”这一最小破坏手段验证。
4. Maven Central 索引延迟：发布成功后不要依赖 search.maven.org 的即时可见性，直接访问 repo1.maven.org 的坐标路径验证更可靠。
5. 凭据泄漏面控制：CI 中不缓存 Docker、使用专用发布 token 而非只读 token，都是降低凭据风险的设计，手动发布时也应遵循同样的最小权限原则。

七、结语

Zipkin 的发布流程是一套“标签驱动 + 脚本复用”的工程范本：release-MAJOR.MINOR.PATCH只负责触发创建版本，MAJOR.MINOR.PATCH负责触发真实部署，而 build-bin/deploy 作为总调度把 Maven、Docker、Javadoc 三路产物串成一条流水线。无论是 CI 正常运转时的“推标签即发布”，还是 CI 失效时的“环境变量 + 手动脚本”兜底，其核心都建立在清晰的语义化版本约定与可复用的 build-bin 脚本体系之上。理解这套机制，不仅能让 Zipkin 的发布者少踩坑，也能为自建发布流水线提供直接的参考实现。

• 可观测性
• 后端
• 微服务