Django优雅停机怎么实现

wen python案例 2026-07-12 2

Django优雅停机实现指南：从理论到实战的完整攻略

目录导读

什么是优雅停机？为什么Django需要它？
Django默认停机机制的问题
优雅停机的核心实现策略
实战：使用Gunicorn + Django实现优雅停机
进阶：自定义信号处理与连接池管理
常见问题问答（FAQ）
最佳实践与性能调优

什么是优雅停机？为什么Django需要它？

优雅停机（Graceful Shutdown） 是指服务器在收到停止信号后，不再接受新请求，同时等待正在处理的请求完成，再释放资源并退出进程的过程，对于Django应用而言，当我们需要部署新代码、扩缩容或重启服务时，如果没有优雅停机机制，会直接杀死正在处理请求的进程，导致：

Django优雅停机怎么实现

用户收到502/504错误响应
数据库连接、缓存连接等资源泄漏
事务中断导致数据不一致

核心价值：保障生产环境的零停机部署（Zero-Downtime Deployment）体验。

Django默认停机机制的问题

Django本身作为一个WSGI框架,其内置的runserver开发服务器不支持优雅停机，而在生产环境中，我们通常使用 Gunicorn/uWSGI + Django 的组合，它们的默认行为是：

Gunicorn：收到SIGTERM信号后，默认会立即终止所有worker进程
UWSGI：收到SIGTERM后，会等待worker完成当前请求，但默认超时时间较短

关键缺陷：Django应用中的长连接（如WebSocket、SSE）、耗时数据库事务、外部API调用不会自动中断或补偿，一个耗时30秒的报表查询，在停机信号发出后3秒就被强制杀死，导致数据库锁未释放。

优雅停机的核心实现策略

要实现一个健壮的优雅停机,需要覆盖四个层面：

层面	策略	关键参数/配置
WSGI服务器	设置超时后强制终止	`timeout`、`graceful_timeout`
Django应用	处理`SIGTERM`信号，停止接受新请求	`atexit`、`signal`模块
连接池	关闭空闲连接，等待活跃连接完成	数据库连接池（如`psycopg2.pool`）
中间件	返回503状态码给新请求	自定义`GracefulShutdownMiddleware`

核心思想：先挡新流量，再处理旧流量，最后杀进程。

实战：使用Gunicorn + Django实现优雅停机

1 配置文件（`gunicorn_config.py`）

import multiprocessing
import os
bind = "0.0.0.0:8000"
workers = multiprocessing.cpu_count() * 2 + 1
worker_class = "sync"  # 或 "gevent"
timeout = 30  # 单个请求最大处理秒数
graceful_timeout = 30  # 优雅停机等待秒数
keepalive = 5  # 保活连接超时
# 关键设置：防止worker被立刻杀死
proc_name = "django_app"

2 Django端的信号处理（`wsgi.py`）

import os
import signal
import sys
import time
from django.core.wsgi import get_wsgi_application
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "your_project.settings")
# 标志位：是否正在关闭
shutting_down = False
def graceful_shutdown(signum, frame):
    global shutting_down
    shutting_down = True
    print(f"收到信号 {signum}，开始优雅关闭...")
    # 标记所有新请求返回503
    # 实际工作中可通过全局变量或Redis缓存flag实现
    # 等待3秒让现有请求完成（可按需调整）
    time.sleep(3)
    sys.exit(0)
# 注册信号处理器
signal.signal(signal.SIGTERM, graceful_shutdown)
signal.signal(signal.SIGINT, graceful_shutdown)
application = get_wsgi_application()

3 中间件拦截新请求

# middleware.py
from django.http import JsonResponse
class GracefulShutdownMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response
        from .wsgi import shutting_down
        self.shutting_down = shutting_down  # 注意：实际需通过线程安全方式访问
    def __call__(self, request):
        # 如果正在关闭，返回503
        if self.shutting_down:
            return JsonResponse({"error": "服务器正在维护"}, status=503)
        response = self.get_response(request)
        return response

4 启动命令示例

gunicorn your_project.wsgi:application \
  -c gunicorn_config.py \
  --reload  # 开发用，生产去掉

验证方法：压测过程中发送kill -TERM <pid>，观察日志中是否有延迟退出。

进阶：自定义信号处理与连接池管理

1 数据库连接池优雅关闭

如果使用psycopg2.pool或SQLAlchemy连接池，需要在graceful_shutdown函数中显式关闭：

def graceful_shutdown(signum, frame):
    # 关闭数据库连接池
    from django.db import connections
    for conn in connections.all():
        conn.close()
    # 关闭Redis连接池
    from django_redis import get_redis_connection
    redis_conn = get_redis_connection("default")
    redis_conn.connection_pool.disconnect()
    # ... 其他资源清理
    sys.exit(0)

2 使用`atexit`模块（不支持信号场景）

如果你的应用被kill -9强制杀死，atexit不会执行，但对于正常停止，可以额外注册：

import atexit
@atexit.register
def cleanup():
    print("执行atexit清理...")

3 分布式环境下的优雅停机

当Django后面有 Nginx/Load Balancer 时，停机流程应为：

先让Nginx将当前服务器从负载均衡中移除（通过健康检查返回503）
等待一段时间（如10秒）让现有请求完成
发送SIGTERM给Gunicorn主进程

健康检查配置（Nginx）：

location /healthz {
    proxy_pass http://backend;
    health_check interval=5s fails=3 passes=2;
}

常见问题问答（FAQ）

Q1：优雅停机后，为什么还有请求超时？
A：可能因为graceful_timeout设置过短，或请求本身处理时间超过超时值，建议将timeout设为最大期望处理时间，并确保请求幂等性。

Q2：Gunicorn的preload_app配置会不会影响优雅停机？
A：如果开启preload_app=True，Django应用会在启动时加载一次，优雅停机时只能等待当前请求完成，无法加载新的中间件状态，建议生产环境关闭。

Q3：如何测试优雅停机是否有效？
A：使用ab或wrk进行压测，同时在一个终端发送kill -TERM，观察压测结果的错误率是否增加，理想状态下，错误率应为0%。

Q4：Django Channels（WebSocket）如何实现优雅停机？
A：需要自定义ASGI shutdown handler，向所有活跃WebSocket连接发送关闭帧，等待客户端确认，具体实现需参考channels.layers的flush_channel_layer。

Q5：优雅停机过程中，定时任务（Celery）如何处理？
A：Django进程与Celery worker通常是独立的，建议Celery worker也配置优雅停止（停止接收新任务，等待当前任务完成），并设置task_acks_late=True防止任务丢失。

最佳实践与性能调优

超时值的黄金法则：Gunicorn的timeout应设为Django视图层最大处理时间的1.5倍，graceful_timeout设为2倍。
避免在主进程中持有大对象：如果使用preload_app，主进程会保留所有内存快照，导致优雅停机内存释放缓慢。
监控与告警：监控优雅停机过程中503响应的比例，若超过0.1%需要排查。
Kubernetes环境：使用preStop hook发送SIGTERM，并设置terminationGracePeriodSeconds大于graceful_timeout。
日志记录：在优雅停机函数中添加日志，记录当前活跃请求数和资源释放状态。