# PR #27997 完整报告

- 仓库：`sgl-project/sglang`
- 标题：fix(gateway): make sgl-model-gateway a cargo workspace so maturin 1.14 accepts the parent README
- 合并时间：2026-06-12 14:37
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/27997

---

# 执行摘要

- 一句话：修复 maturin 1.14 下 gateway 构建失败
- 推荐动作：值得合并，修复构建阻塞问题。变更简洁明了，逻辑清晰。建议读者关注其中的工作区设计模式——通过声明工作区解决 maturin 路径校验问题，而非逐个脚本固定 maturin 版本，是一种更优雅的解决方案。

# 功能与动机

PR body 指出 dev docker 镜像构建因 maturin 1.14 的变更而失败，错误信息为 `project.readme` path `../../README.md` resolves outside allowed metadata root。该问题影响所有使用 `sgl-model-gateway/bindings/python/pyproject.toml` 的构建路径，包括 dev Docker、gateway Docker、ROCm Docker、CI 和 PyPI 发布。

# 实现拆解

1. 在 `sgl-model-gateway/Cargo.toml` 中新增 `[workspace]` 声明，将 `bindings/python` 列为成员，`bindings/golang` 和 `examples` 排除在外。这样 `cargo metadata` 从 `bindings/python` 运行时会报告 `sgl-model-gateway/` 作为工作区根，包含 `README.md`，使得 `../../README.md` 路径解析合法。
2. 移除 `bindings/python/Cargo.toml` 中的 `[profile.ci]` 段，因为该配置与工作区根目录的 `[profile.ci]` 完全相同，且 cargo 会忽略工作区成员中的 profile 表。
3. `bindings/python/src/lib.rs` 中的改动仅为格式化调整：由于 `bindings/python` 成为工作区成员，`cargo +nightly fmt` 现在会作用于该目录，导致 import 顺序（按 `StdExternalCrate` 分组）和部分换行风格变化，无逻辑变更。

关键文件：
- `sgl-model-gateway/Cargo.toml`（模块 sgl-model-gateway；类别 config；类型 configuration）: 核心修复：新增 `[workspace]` 声明，将 bindings/python 纳入工作区，使 maturin 能够正确解析父目录 README.md。
- `sgl-model-gateway/bindings/python/Cargo.toml`（模块 sgl-model-gateway；类别 config；类型 configuration）: 移除多余的 `[profile.ci]` 段，因为根目录已有相同配置，且 cargo 会忽略工作区成员中的 profile 表。
- `sgl-model-gateway/bindings/python/src/lib.rs`（模块 sgl-model-gateway；类别 source；类型 data-contract；符号 new）: 格式化变更：由于成为工作区成员，cargo fmt 规则（`group_imports = "StdExternalCrate"`）开始作用，导致 import 顺序调整和部分换行变化，无逻辑改动。

关键符号：new

## 关键源码片段

### `sgl-model-gateway/Cargo.toml`

核心修复：新增 `[workspace]` 声明，将 bindings/python 纳入工作区，使 maturin 能够正确解析父目录 README.md。

```toml
# sgl-model-gateway/Cargo.toml 头部新增 workspace 声明
[workspace]
members = ["bindings/python"]   # 将 bindings/python 纳入工作区
                                 # maturin 1.14 要求 parent-relative readme
                                 # 路径必须位于工作区根目录下
                                 # 此配置使得 sgl-model-gateway 成为
                                 # 工作区根，从而允许 "../../README.md"
exclude = ["bindings/golang", "examples"]  # 这些保持独立

[package]
name = "sgl-model-gateway"
# ... 其余配置保持不变

```

# 评论区精华

Reviewer dougyster 批准了 PR，并确认 CI 运行通过（https://github.com/sgl-project/sglang/actions/runs/27394688617/job/80959410404）。未发现其他讨论或争议。

- PR 批准与 CI 结果 (other): PR 被批准通过。

# 风险与影响

- 风险：本 PR 主要涉及构建配置调整，不修改运行时逻辑。风险较低，但需注意：
 - 工作区声明可能影响其他工具（如 `cargo test` 或 IDE 解析），但通过 `exclude` 排除了 golang 和 wasm 绑定，影响可控。
 - `[profile.ci]` 的移除对 CI 构建无影响，因为根目录的相同配置仍然有效。
 - 格式化变更仅涉及 import 顺序和换行，不存在功能风险。
 - 影响：直接影响所有依赖 maturin 构建 sgl-model-gateway Python 绑定的路径，包括 Docker 镜像构建、CI 测试、PyPI 发布和本地开发环境。修复后这些路径不再因 maturin 版本升级而中断。用户无感知，内部团队无需额外操作。
 - 风险标记：构建配置变更 , 格式化变更无功能风险

# 关联脉络

- PR #27999 [AMD] Pin maturin<1.14 to fix ROCm image build failure: 两者都处理 maturin 1.14 引起的构建失败问题，PR#27999 采用固定版本方式，而本 PR 采用工作区方式，是更彻底的修复。