RoadRunner 3 正式发布

很高兴地宣布，RoadRunner 3 已经发布。

RoadRunner 3 是可预见的未来里最后一个大版本，API 极其稳定。借着这次发布，我们清空了以往各个版本积压的 backlog，版本号也回归了清晰的规则：告别日历版本号（CalVer），重新采用 SemVer。RoadRunner 3 会继续获得 bug 修复和安全更新，不过团队今后的主要精力会放在 Rapira 上。

下面介绍服务端和 PHP 包各有哪些变化，以及如何升级。

主要变化

完整列表请查看发布说明，这里只挑重点：

默认构建内置的插件。 新增 NSQ 队列驱动、HTTP 限流（rate limiting）、Zstd 压缩和 protobuf 注册表（Protoreg）；移除了 TCP 插件。
HTTP。 支持 PROXY protocol v1 和 v2，需要显式配置受信任的代理列表。rate_limiter 中间件会返回 429 并带上 Retry-After 头。static 新增了缓存相关配置，以及 rr reset static 命令。
gRPC。 基于 Protoreg 实现 server reflection；错误日志中会输出 google.rpc.Status 的详细信息。
Jobs。 支持命名 worker 池：可以把某个 pipeline 绑定到单独的 PHP worker 池。AMQP 支持命名连接，可同时连接多个 broker。Kafka 可以只消费指定的分区。
Lock。 新增 Redis 后端，可以在多个 RoadRunner 实例之间加锁。
Logger。 日志改用 Go 的 log/slog 实现，写入输出不再阻塞。
Unix socket。 监听器和 worker relay 使用的 socket 可以设置权限、属主和属组。
Status。 /livez 和 /readyz 分别作为 /health 和 /ready 的别名。

破坏性变更

逐项说明请参考 v2025 升级到 v3 的迁移指南。影响最大的几项如下：

模块	变化
HTTP middleware	请求按从左到右的顺序经过 `http.middleware`。如需保持原来的执行顺序，请把列表倒过来。
HTTP/2	明文 HTTP/2（h2c）只支持 prior knowledge 方式，不再支持 `Upgrade: h2c`。
AMQP	broker 配置迁移到命名连接中，`config.version` 已移除。
Logger	移除了 `file_logger_options` 和内置的日志轮转，请改用 `output` 配合外部轮转工具。队列满时会丢弃新的日志。
链路追踪	移除了原生的 Zipkin exporter，请改用 OTLP。
RPC	Goridge v4 不再支持 MessagePack，可选 JSON、protobuf、Gob 和 raw。
Jobs	`pool` 头被保留，用于把任务路由到命名池。`pipeline_size` 的默认值改为 `100000`。
NATS	停止 pipeline 时默认保留 stream。
Centrifuge	移除了 `centrifuge.RateLimit` 方法。
`envfile`	根级 `envfile` 无需开启 experimental 模式即可加载，但指定的文件必须存在。
`server.on_init.env`	这里配置的值会覆盖继承来的环境变量。
TCP 插件	RoadRunner 3 不再支持。

.rr.yaml 根级仍然写 version: "3"。从源码构建需要 Go 1.27 及以上。Go 插件作者需要迁移到 api-go/v6、api-plugins/v6、pool/v2、goridge/v4 和 *slog.Logger。构建工具 Velox 改用新的模块配置格式，同时去掉了远程构建服务器和 Windows 构建目标。不过发布页仍然提供 Windows 的预编译二进制。

PHP 包

PHP 包也随服务端一起更新了，要点如下：

最低 PHP 版本为 8.2。
所有包统一使用新的 vendor 名 roadrunner/*（取代 spiral/* 和 roadrunner-php/*）。
为了保持向后兼容，类的命名空间没有变化。
每个新包都通过 replace 以 self.version 声明替代旧包名。元包是个例外，见下文。
元包 spiral/roadrunner 更名为 roadrunner/roadrunner，各个 roadrunner/* 包都依赖 roadrunner/roadrunner ^3.0。改名帮我们避开了几个麻烦：
- 2023.x–2025.x 这些不符合 SemVer 的日历版本号，总是被当成最新的稳定版本冒出来。CalVer 版本留在了 spiral/roadrunner 下。
- 安全公告 CVE-2025-22871 把 spiral/roadrunner < 2025.1.0 标记为存在漏洞，导致无法通过 Composer 安装 RoadRunner 3。换了新包名，这个包袱也就没有了。
所有包都要求 RoadRunner 3。旧版 RoadRunner 搭配新包能否正常工作，不作保证。
RoadRunner 3 彻底移除了 TCP 插件。用到 TCP 插件的应用，建议继续使用 RoadRunner v2025。注意这和 RPC 以及 worker relay 使用的 tcp:// 传输无关，后者照常可用。

其他打磨：

测试改用 Testo 重写。
Code Coverage、Mutation Testing 和 Static Analysis 各项指标都有提升。
RoadRunner CLI 3.0.0 改用 DLoad 下载二进制文件。

旧包名	新包名	状态
`spiral/roadrunner`	`roadrunner/roadrunner`
`spiral/roadrunner-worker`	`roadrunner/worker`
`spiral/roadrunner-http`	`roadrunner/http`
`spiral/roadrunner-grpc`	`roadrunner/grpc`
`spiral/roadrunner-jobs`	`roadrunner/jobs`
`spiral/roadrunner-kv`	`roadrunner/kv`
`spiral/roadrunner-metrics`	`roadrunner/metrics`
`spiral/roadrunner-services`	`roadrunner/services`
`spiral/goridge`	`roadrunner/goridge`
`spiral/roadrunner-cli`	`roadrunner/cli`
`roadrunner-php/app-logger`	`roadrunner/app-logger`
`roadrunner-php/centrifugo`	`roadrunner/centrifugo`
`roadrunner-php/lock`	`roadrunner/lock`
`roadrunner-php/symfony-lock-driver`	`roadrunner/symfony-lock-driver`
`roadrunner-php/version-checker`	`roadrunner/version-checker`
`roadrunner-php/roadrunner-api-dto`	`roadrunner/api-dto`