执行摘要

此PR引入了--strict-ports选项，使服务器在HTTP、scheduler和master端口被占用时立即失败，而非自动选择其他端口，解决了端口分配不确定性问题，是一个向后兼容的功能增强，提升了配置可预测性。

功能与动机

当前，当请求端口被占用时，settle_port方法会自动选择可用端口，这导致用户无法预知服务器最终使用哪个端口，客户端配置不可靠，且多个服务器实例间易产生端口冲突。引用PR body中描述：“users who need to know exactly which ports will be used”，此PR旨在通过添加--strict-ports选项，确保端口分配的确定性，满足需要精确端口配置的使用场景。

实现拆解

主要改动集中在python/sglang/multimodal_gen/runtime/server_args.py文件中：

• 添加字段：在ServerArgs类中添加strict_ports: bool = False字段，作为默认关闭的严格端口模式开关。
• 修改逻辑：在_adjust_network_ports方法中，根据strict_ports值分支处理：
  • 启用时：使用is_port_available检查端口可用性，若不可用则抛出RuntimeError，包含明确的错误提示。
    

    if not is_port_available(self.port):
        raise RuntimeError(f"Port {self.port} is unavailable and --strict-ports is enabled...")
    

• 禁用时：保持原有自动端口选择逻辑（调用settle_port）。
• CLI集成：在add_cli_args方法中添加--strict-ports参数，使用StoreBoolean action，便于命令行使用。

另一个文件python/sglang/multimodal_gen/registry.py的改动最初是为了优化错误处理，但根据review讨论，为避免隐藏配置问题，最终被revert回抛出RuntimeError，与strict-ports功能无关。

评论区精华

review中，gemini-code-assist[bot]提出了两个关键讨论点：

1. 正确性担忧：关于registry.py的错误处理变更，评论指出“Changing RuntimeError to logger.debug and returning None can hide potential configuration issues”，建议回退到异常以快速失败。这被采纳，在后续commit中revert。
2. 设计改进：关于strict-ports错误消息，评论建议“The error messages for unavailable scheduler_port and master_port are not as helpful”，要求统一所有端口错误消息，包含解决建议。这导致错误消息被一致化，提升了用户体验。

风险与影响

风险分析：

• 启用--strict-ports后，端口被占用时服务器启动失败率增加，但这正是功能设计目标，无额外性能或安全风险。
• 错误处理逻辑需确保错误消息清晰准确，避免用户混淆；审查显示已通过改进消息解决。
• 兼容性：默认行为不变，现有用户不受影响，新增选项可选使用。

影响评估：

• 用户：获得更可控的端口配置能力，便于部署和调试，尤其适用于多实例环境。
• 系统：新增选项轻量级，不干扰核心功能，测试计划覆盖正常和失败场景，确保可靠性。
• 团队：需了解新选项以有效利用，代码变更集中在单个文件，维护成本低。

关联脉络

• 此PR在body中提及“Related to #21284”，但未在提供的历史PR列表中，具体关联未知。
• 与近期其他PR（如#21435安全绑定端口）无直接功能关联，但同属基础设施改进范畴，体现了仓库对网络配置的持续优化趋势。
• 独立性强，作为独立功能添加，不影响其他模块。