# PR #22541 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[CI] Consolidate Docker release workflows into reusable workflow
- 合并时间：2026-04-24 05:06
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/22541

---

# 执行摘要

- 一句话：提取 Docker 构建逻辑为可复用工作流，简化 3 个发布工作流
- 推荐动作：值得精读，特别对于负责 CI/CD 的工程师。展示了如何通过 `workflow_call` 将重复的 Docker 构建逻辑抽取为可复用工作流，减少冗余代码并统一构建参数。关键设计决策包括：使用 job outputs 代替 artifact 传递 digest、通过 JSON tag_config 灵活生成多架构标签、暴露 `image_repo` 支持测试环境。建议合并前按 PR body 中的测试计划手动触发验证。

# 功能与动机

减少 Docker 发布工作流中的重复代码，降低维护成本，并修复遗漏的构建参数。PR body 指出原三个工作流共 815 行，大量重复；新方案通过 workflow_call 复用公共步骤，使每个调用工作流仅保留版本解析、标签配置等差异逻辑。同时修复了 runtime ARM64 CUDA 13 构建时缺少 INSTALL_FLASHINFER_JIT_CACHE=1 参数的问题。

# 实现拆解

### 1. 创建可复用构建工作流 `_docker-build-and-publish.yml`
- 文件新增，283 行。
- 定义 `workflow_call` 输入：`docker_target`, `sgl_version`, `extra_build_args`, `checkout_ref`, `tag_config`, `use_environment`, `image_repo`。
- 包含两个 job：`build-x86`（AMD64）和 `build-arm64`（ARM64）。
- 每个 job 执行：清理磁盘、checkout、设置 Docker Buildx、登录 Docker Hub、构建指定目标并推送 by-digest、输出 digest。
- 主 job `create-manifest`：根据 tag_config JSON 生成多架构 manifest 并推送。
- 关键改进：使用 job outputs 传递 digest，替代 upload-artifact/download-artifact。

### 2. 创建可复用清理工作流 `_docker-cleanup-nightly.yml`
- 文件新增，78 行。
- 接收 `tag_prefixes`, `keep_count`, `image_repo` 参数。
- 通过 Docker Hub API 获取标签列表，删除超出保留数量的旧标签。

### 3. 简化三个调用工作流
- `release-docker.yml`: 从 295 行减至 47 行，仅保留 `resolve-version` job 和调用可复用工作流的步骤。
- `release-docker-runtime.yml`: 同样从 310 行减至 47 行。
- `release-docker-dev.yml`: 从 210 行减至 96 行，新增 `prepare` job 用于计算 checkout_ref、extra_build_args 和 tag_config，然后调用可复用工作流。
- 所有调用工作流新增 `image_repo` 输入（默认 `lmsysorg/sglang`），便于测试时推到 staging 仓库。

### 4. 迁移运行时配置
- 所有工作流改用 `ubuntu-latest` 代替已弃用的 `ubuntu-22.04`。
- 原 `release-docker-dev.yml` 中的矩阵策略（4 个平台×CUDA 版本组合）被移到 `prepare` job 的 tag_config JSON 中，由可复用工作流统一处理。

关键文件：
- `.github/workflows/_docker-build-and-publish.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: 核心可复用构建工作流，封装了所有 Docker 构建、推送、清单创建逻辑，是整个重构的基础。
- `.github/workflows/release-docker.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: 框架 Docker 镜像发布工作流，从 295 行精简为 47 行，是重构的主要受益者之一。
- `.github/workflows/release-docker-runtime.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: 运行时 Docker 镜像发布工作流，同样从 310 行精简为 47 行，修复了 ARM64 CUDA 13 构建缺少 JIT 缓存参数的问题。
- `.github/workflows/release-docker-dev.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: 开发镜像发布工作流，从 210 行减至 96 行，新增 prepare job 计算配置，替代原矩阵策略。
- `.github/workflows/_docker-cleanup-nightly.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: 新增可复用清理工作流，用于定期清理旧的 nightly 标签，减少 Docker Hub 上的垃圾标签。

关键符号：未识别


# 评论区精华

该 PR 无人工 review 评论，仅有一条 Gemini 自动评论表示无法生成 review。无实质讨论。

- 暂无高价值评论线程

# 风险与影响

- 风险：
 1. **发布流程完整性风险**：重构后三个发布工作流的触发条件和最终推送行为可能因重构而偏离预期。例如，nightly workflow 的时间调度、workflow_dispatch 参数传递等需验证。
 2. **缺少端到端测试**：仅列出手动测试计划，无自动化 CI 验证。如果可复用工作流中某个步骤（如 manifest 创建）出错，可能导致镜像标签丢失或推送失败。
 3. **版本兼容性**：改用 `ubuntu-latest` 可能因 GitHub Actions 更新带来未知行为变化。
 4. **ARM64 构建**：原 release-docker-dev.yml 中 ARM64 构建使用 `arm-docker-build-node` runner，重构后由 `_docker-build-and-publish.yml` 的 `build-arm64` job 处理，需确保 runner 标签正确。
 5. **Docker Hub 凭据**：可复用工作流中直接使用 `secrets.DOCKERHUB_USERNAME` 和 `secrets.DOCKERHUB_TOKEN`，若调用工作流的仓库无这些 secrets 将失败。
 - 影响：**用户 / 开发者**：无直接影响，仅限于 CI/CD 维护者。
**系统**：减少了 Docker 构建工作流的重复代码，提高了可维护性和一致性。修复了 ARM64 CUDA 13 镜像缺失 FlashInfer JIT 缓存的问题，提高了潜在运行时性能。
**团队**：降低维护成本，新发布流程或镜像变体只需修改可复用工作流即可；测试时可通过 `image_repo` 参数推送到 staging 仓库，避免污染生产仓库。
**影响程度**：中等，因涉及发布流程变更，但回滚成本低（原工作流仍可通过 git 恢复）。

- 风险标记：发布流程变更 , 缺少端到端验证 , Docker Hub 凭据依赖 , ubuntu-latest 兼容性

# 关联脉络

- 暂无明显关联 PR