跳转至

服务节点优雅关闭方案

1. 核心目标

实现服务节点的优雅关闭，确保在停止服务时不丢失任何正在处理的用户请求，同时不影响整个集群的可用性。

2. 实现方案说明

该方案通过结合 Nginx 反向代理、Gunicorn 服务器、Uvicorn 服务器 和 FastAPI 协作来实现目标。

graceful_shutdown

3. 组件介绍

1. Nginx：流量入口与负载均衡器

  • 功能：
  • 作为反向代理，接收所有外部客户端请求并按负载均衡策略分发到上游（Upstream）的 Gunicorn 工作节点。
  • 通过健康检查机制主动监控后端节点的健康状态。
  • 通过配置管理，能够瞬时地将问题节点从服务池中摘除，实现流量切换。

2. Gunicorn：WSGI HTTP 服务器（进程管理器）

  • 功能：
  • 作为主进程（Master Process），负责管理多个 Uvicorn 工作子进程（Worker Process）。
  • 接收外部信号（如 SIGTERM），并协调所有子进程的优雅关闭流程。
  • 守护工作进程，在进程异常退出时自动重启，保证服务健壮性。

3. Uvicorn：ASGI 服务器（工作进程）

  • 功能：
  • 作为 Gunicorn 管理的 Worker，实际负责处理 HTTP 请求。
  • 运行 FastAPI 应用实例，处理具体的业务逻辑。
  • 实现 ASGI 协议，支持异步请求处理，高性能。

优势

  1. Nginx：
  2. 能够快速隔离故障节点，保证整体服务的可用性。

  3. 通过 nginx -s reload 可不停机更新配置，对用户无感知。

  4. Gunicorn（相比于 Uvicorn 原生的多 Worker）：

  5. 成熟的进程管理：内置了完善的进程生成、回收、管理逻辑，无需自己实现。
  6. 进程守护能力：Gunicorn Master 会在 Worker 异常退出后自动 fork 新 Worker，而 Uvicorn --workers 模式下任何进程崩溃都不会被重新拉起，需要外部守护进程。

  7. 配置丰富：提供大量参数用于调整超时、Worker 数量、重启策略等。

  8. Uvicorn：

  9. 基于 uvloop 和 httptools，速度极快。
  10. 原生支持优雅关闭：在收到关闭信号后，会停止接受新连接，并等待现有请求处理完成后再退出。

优雅关闭流程

当需要下线某个特定节点时，步骤如下：

  1. Nginx 监控节点状态是否健康：

  2. 通过向节点定时发送 health 请求，监控节点的健康状态。

  3. 从负载均衡中摘除：

  4. 修改 Nginx 配置，将该节点标记为 down 状态，并重载 Nginx 配置。

  5. 此后，所有新请求将不再被发送到目标节点。

  6. Gunicorn 服务器：

  7. 监控停止信号，收到停止信号（如 SIGTERM 信号）时，会把此信号向所有的 Uvicorn 子进程发送。

  8. 发送停止信号：

  9. 向目标节点的 Uvicorn 进程发送 SIGTERM 信号，触发 Uvicorn 的优雅关闭流程。

  10. 等待请求处理：

  11. 等待一段稍长于 timeout_graceful_shutdown 的时间后强制终止服务，让该节点有充足的时间完成所有已接收请求的处理。

  12. 关闭完成：

  13. 此时，该节点已经处理完所有存量请求并安全退出。