Puma服务器重启机制详解：热重启与分阶段重启

Puma服务器重启机制详解：热重启与分阶段重启

puma A Ruby/Rack web server built for parallelism 项目地址: https://gitcode.com/gh_mirrors/pu/puma

前言

Puma作为一款高性能的Ruby应用服务器，提供了多种重启机制来满足不同场景下的需求。本文将深入解析Puma的两种核心重启方式：热重启(Hot Restart)和分阶段重启(Phased Restart)，帮助开发者根据实际需求选择最合适的重启策略。

热重启(Hot Restart)

基本概念

热重启是Puma提供的一种完全重启机制，它会通过exec系统调用启动新进程，新旧进程之间不共享任何内存空间。这种重启方式安全可靠，适用于大多数场景，包括Puma自身的版本升级。

操作方式

开发者可以通过以下三种方式触发热重启：

1. 向Puma进程发送SIGUSR2信号
2. 向Puma状态控制服务器发送GET /restart请求
3. 使用pumactl restart命令（优先使用控制服务器方式，不可用时回退到信号方式）

适用场景

• 适用于集群模式和单机模式
• 支持所有操作系统平台
• 特别适合需要升级Puma自身版本的情况

客户端体验

• 所有平台：正在处理的请求会正常完成响应，空闲的HTTP持久连接会被优雅关闭
• Linux/BSD上的MRI或TruffleRuby：重启期间新连接可能经历短暂延迟，但不会中断
• Windows和JRuby：重启期间新连接可能遇到"connection reset"错误

技术细节

1. 工作目录处理：新进程会将工作目录切换到directory选项指定的位置，如果该路径是符号链接，会自动重新解析，这为应用升级提供了便利
2. 版本控制：同一时间只有一个应用版本在运行
3. 资源清理：on_restart回调在服务器关闭前执行，可用于优雅释放资源（如数据库长连接）
4. 文件描述符：Ruby 2.0+会自动设置FD_CLOEXEC标志，确保文件描述符在exec时关闭

分阶段重启(Phased Restart)

基本概念

分阶段重启是Puma集群模式下特有的优雅重启机制，它会逐个替换工作进程，确保服务不中断。这种方式特别适合应用代码更新场景。

操作方式

触发分阶段重启的方法包括：

1. 向Puma进程发送SIGUSR1信号
2. 向Puma状态控制服务器发送GET /phased-restart请求
3. 使用pumactl phased-restart命令

适用场景

• 仅适用于集群模式
• 需要确保prune_bundler启用且preload_app!禁用
• 适用于所有支持集群模式的平台

客户端体验

• 正在处理的请求会正常完成
• 空闲持久连接会被优雅关闭
• 新连接不会丢失（工作进程数大于1时）
• 客户端不会感知到明显的延迟

技术细节

1. 工作目录处理：主进程会切换到directory指定目录，支持符号链接自动解析
2. 版本共存：重启过程中可能同时运行新旧两个版本的应用代码
3. 性能考量：工作进程较多时可能较慢，热重启通常更快但会有延迟
4. 限制条件：
   • 不能升级主进程加载的gem（包括Puma自身）
   • 移除旧版本gem时需特别注意原生扩展问题
   • 某些依赖原生扩展的gem可能导致工作进程启动失败

重启策略选择指南

选择热重启的场景

• 需要升级Puma服务器本身
• 单机模式下需要重启
• 需要确保完全清除旧版本代码
• 依赖了可能引发问题的原生扩展gem

选择分阶段重启的场景

• 仅需更新应用代码
• 要求服务不中断
• 可以接受短暂的新旧版本共存
• 工作进程数量适中

最佳实践建议

1. 生产环境：始终使用进程监控工具管理Puma
2. 部署策略：
   • 代码更新优先考虑分阶段重启
   • 服务器升级必须使用热重启
3. 配置检查：
   • 确保prune_bundler正确配置
   • 避免在extra_runtime_dependencies中包含问题gem
4. 监控指标：重启后检查工作进程状态和性能指标

常见问题解答

Q：为什么分阶段重启不能升级Puma自身？

A：因为分阶段重启只替换工作进程，主进程保持不变，而Puma核心代码由主进程加载。

Q：热重启会导致服务中断吗？

A：在Linux/BSD上，新连接会经历短暂延迟但不会中断；Windows/JRuby上可能有连接重置错误。

Q：如何确保重启后所有文件描述符正确关闭？

A：Ruby 2.0+自动处理大多数情况，特殊资源建议在on_restart回调中手动清理。

通过深入理解Puma的这两种重启机制，开发者可以根据实际需求选择最合适的策略，确保服务平稳运行的同时完成必要的更新和维护工作。

puma A Ruby/Rack web server built for parallelism 项目地址: https://gitcode.com/gh_mirrors/pu/puma