PR 37221 分析报告：Derive server address and accept signed env values

执行摘要

本 PR 是 rust-server-cleanup 系列（stack #37223）的第 2 步，核心动作是把嵌入式 Rust server 的监听地址从「Python 拼好字符串传入」改为「由 Rust 从类型化 ServerArgs 派生」，并将环境变量解析从无符号 env_u64 换成带符号 env_i64 以匹配 Python EnvInt 语义——负数 batch 上限视为不限制，负数 duration 钳制为 0。改动集中在启动边界与配置解析，覆盖 8 个文件、+119/-59 行，Rust 单元测试 248 个通过，CI 注册测试经多轮重跑后全绿。

功能与动机

PR body 的 Motivation 原文：

Make the embedded server launch boundary use the typed server configuration as its single address source, and match signed Python EnvInt values. This is PR 2 of 4 in stack #37223.

动机可拆为两点：

1. 地址单一事实来源：此前 Python 侧 RustServer.launch 自行拼接 {host}:{port + dp_rank} 字符串传入 http_addr，Rust 侧只是被动解析——地址逻辑双端各有一份，容易漂移（例如 IPv6 格式化、DP 偏移规则）。改为 port_offset 后，host 与基础 port 的唯一来源是 server_args。
2. 环境变量语义对齐：Python 的 EnvInt 接受负值（如 SGLANG_MAX_BATCH_REQS_PER_HTTP_REQ=-1 表示不设上限），而 Rust 的 env_u64 无法解析负数，导致同一配置在两种 server 模式下行为不一致。

实现拆解

1. 新增 utils/startup.rs 启动辅助模块：把 lib.rs 里的 value_error 迁入（保持 {context}: {err} 错误格式），新增核心函数 listen_addr(server_args, port_offset)——从 ServerArgs 读 host/port，用 checked_add 加 DP 偏移并对超过 65535 显式报错，再通过「先解析 server_args.bind() 字符串、后 set_port」的方式保留 IPv6 地址族。内置测试覆盖默认偏移、Some(7) 偏移、u16::MAX 溢出三个场景。
2. Server::start 签名收敛（lib.rs）：pyo3 构造器从 http_addr: Option<String> 改为 port_offset: Option<u16>，地址计算全部委托给 startup::listen_addr，错误统一走 value_error("bad listen address", e)；std::net::SocketAddr 的直接 import 随之删除。
3. 环境解析改带符号（utils/environ.rs）：env_u64 整体替换为 env_i64（类型 u64 → i64），-1、i64::MIN 等负值可正常解析；空格、下划线、非 ASCII 数字仍按「无效则 warn + 回退默认」处理。测试矩阵更新为 i64 的越界边界（±(i64::MAX+1)）。
4. 负数 batch 上限 = 不限（message/request.rs）：MAX_BATCH_REQS_PER_HTTP_REQ 从 LazyLock<usize> 改为 LazyLock<i64>，新增 batch_size_exceeds_limit(batch_size, limit)：负数恒返回 false（禁用上限），正数比较用 u128 拓宽避免类型转换溢出；原大 batch 测试先 usize::try_from(cap) 再构造数据，并新增 negative_batch_limit_disables_the_item_cap 验证哨兵语义。
5. duration 配置钳制：bootstrap.rs 的 cleanup_sweeper 与 native_api.rs 的 health timeout 均改为 env_i64(...).max(0) as u64，负值不再导致 Duration 构造异常。
6. Python 侧适配（rust_server/server.py）：RustServer.launch 不再拼 http_addr，仅保留 listen_port = get_serving().port + (dp_rank or 0) 用于日志展示，Server(...) 构造改为传 port_offset=dp_rank；DP 关闭时 None 保持原语义。
7. 测试配套：Rust 单元测试全部内联在各模块 #[cfg(test)] 中（共 248 个通过），无独立测试文件变更；CI 上 test_run_rust_tests.py、test_srt_endpoint.py、test_rust_native_mm_e2e.py、test_rust_native_mm_mmmu.py 经 4 轮 rerun 后全部通过。

rust/sglang-server/src/utils/startup.rs

新增的启动边界辅助模块，包含核心函数 listen_addr 与迁移来的 value_error，是本 PR 地址派生逻辑的主体。

//! startup.rs：Python 侧启动边界的辅助函数（从 lib.rs 拆出）。
//! value_error 统一启动期失败格式：" {context}: {err} "。
pub(crate) fn value_error(context: &str, err: impl std::fmt::Display) -> PyErr {
    PyValueError::new_err(format!("{context}: {err}"))
}
​
/// listen_addr：从类型化 server_args 派生监听地址。
/// host 与基础 port 的唯一来源是 ServerArgs；DP 各 rank 只提供偏移量。
/// checked_add 显式拒绝端口溢出，避免 u16 回绕导致监听端口与预期不符。
pub(crate) fn listen_addr(
    server_args: &ServerArgs,
    port_offset: Option<u16>,
) -> Result<SocketAddr, String> {
    let offset = port_offset.unwrap_or_default();
    // 端口溢出直接报错（u16 回绕会让监听端口与预期不符）
    let port = server_args
        .port
        .checked_add(offset)
        .ok_or_else(|| format!("port {} + offset {offset} exceeds 65535", server_args.port))?;
    // bind() 返回 "host:port" 字符串；先按原样解析以保留地址族（含 IPv6），
    // 再用 set_port 覆盖端口，host 的语义不被破坏。
    let mut addr: SocketAddr = server_args
        .bind()
        .parse()
        .map_err(|err| format!("invalid host {:?}: {err}", server_args.host))?;
    addr.set_port(port);
    Ok(addr)
}

rust/sglang-server/src/utils/environ.rs

环境变量解析核心，env_u64 整体替换为 env_i64，是本 PR 与 Python EnvInt 语义对齐的关键文件。

/// env_i64：与 Python EnvInt 对齐的带符号环境变量解析。
/// 接受 i64::from_str 的完整语法（含负值）；非法或越界值告警并回退默认，
/// 与 Python EnvField.get 的 warn-and-default 行为一致。
pub fn env_i64(name: &str, default: i64) -> i64 {
    read(name, default, |raw| raw.parse().ok())
}
​
/// read：共享的"读环境变量或回退默认"逻辑。
/// 未设置 → 默认值；设置但无法解析 → tracing::warn + 默认值（绝不报错）。
fn read<T: Copy + std::fmt::Debug>(name: &str, default: T, parse: impl Fn(&str) -> Option<T>) -> T {
    let Ok(raw) = std::env::var(name) else {
        return default;
    };
    match parse(&raw) {
        Some(v) => v,
        None => {
            tracing::warn!(name, value = %raw, ?default, "invalid env value; using default");
            default
        }
    }
}

rust/sglang-server/src/message/request.rs

/generate 请求路径，batch 上限从 usize 改为 i64，引入负数哨兵语义，影响请求扇出保护逻辑。

/// 单次 /generate HTTP 请求可展开的最大调度请求数。
/// 进程静态，用 LazyLock 记忆化，避免热路径上每次 env::var 加锁；
/// 默认值 4096 由 Python 侧 environ.py 拥有。
static MAX_BATCH_REQS_PER_HTTP_REQ: LazyLock<i64> =
    LazyLock::new(|| env_i64("SGLANG_MAX_BATCH_REQS_PER_HTTP_REQ", 4096));
​
/// 负数 limit 是"禁用上限"哨兵（与 Python 语义一致）：
/// limit < 0 时恒为 false（不限制 batch 大小）；
/// 正常比较用 u128 拓宽，避免 usize 与 i64 混用时的类型转换问题。
fn batch_size_exceeds_limit(batch_size: usize, limit: i64) -> bool {
    limit >= 0 && batch_size as u128 > limit as u128
}

评论区精华

review 仅两条评论，均来自作者自己的自我审查，聚焦命名：

merrymercy（对初始文件名 server.rs）："do not name this file server.rs. give it an another name."

merrymercy（回复）："Renamed the helper module to utils/startup.rs and updated the import; the file now describes its startup-only role."

要点：server.rs 这种名称过于宽泛，会与主模块、Server 类概念混淆；startup.rs 精准表达其「仅服务启动边界」的定位。除此之外 rainj-me 直接批准，无功能争议。

风险与影响

• 启动签名破坏：Server 构造器的 http_addr 参数被移除，任何仍按旧签名调用的外部脚本或嵌入方会直接 TypeError。仓库内唯一调用方 python/sglang/srt/rust_server/server.py 已同步，但独立使用者需要迁移。
• env 语义反转：SGLANG_MAX_BATCH_REQS_PER_HTTP_REQ 的负值从「回退默认 4096」变为「禁用上限」；若用户此前误设负值并依赖保护，现在会失去 batch 上限防护。同时大于 i64::MAX 的合法 u64 值（如 18446744073709551616）现在会回退默认。
• 负数 duration 钳制 0 的忙等风险：cleanup_sweeper 若被设为负值会变成 Duration::from_secs(0)，tokio::time::sleep(0) 立即返回导致 sweep 忙等；比 panic 安全，但值得在文档中提示。
• 行为等价性：默认偏移 0 时 listen_addr 与原 http_addr 默认路径等价；DP 场景端口计算逻辑从 Python 侧移到 Rust 侧，当前 server.py 仍自行计算 listen_port 仅用于日志，若后续与 Rust 实际绑定不一致需留意。

影响范围集中在 SGLANG_RUST_SERVER=1 模式的启动路径与 DP 多 rank 端口分配；对用户行为基本不变，主要收益是地址单一事实来源与 env 语义对齐。

关联脉络

本 PR 是 rust-server-cleanup 4-PR stack（#37223）的第 2 层：

• 1/4 #37220：结构层，为后续拆分做模块组织准备；
• 2/4 本 PR：配置层，统一地址来源 + env 语义对齐；
• 3/4 #37222：将 Rust 采样与线上结构对齐 Python，新增双语言 lockstep 测试；
• 4/4 #37226：精简 GenerateBody 反序列化注解并文档化 batch header ABI，涉及与本 PR 同文件的 message/request.rs 区域。

与历史 PR #37195（保留引擎预解析声明）、#36897（解耦投机草稿容量）同属「Python↔Rust 边界一致性」工作线；#37222 的 lockstep 测试思路与本 PR 的 EnvInt 对齐一脉相承，整体方向是让 Rust server 与 Python 参考实现共享语义、减少双端行为漂移。