不能直接用 time.sleep() 在 Django 启动时跑定时任务,因为其会阻塞主线程导致 HTTP 请求无法响应,且 Gunicorn/Uvicorn 的 worker 进程可能随时重启或扩缩容,不可靠;应改用 Django 自定义命令配合系统 cron 或 Celery Beat。

为什么不能直接用 time.sleep() 在 Django 启动时跑定时任务
因为 Django 的 runserver 或 WSGI 进程不是长期运行的守护进程,time.sleep() 会阻塞主线程,导致 HTTP 请求无法响应;生产环境用 Gunicorn/Uvicorn 时,worker 进程可能随时重启或扩缩容,根本不可靠。真正可行的路径只有一条:把维护逻辑写成 Django 自定义命令,再交给系统级调度器(如 cron)或专用任务队列(如 Celery Beat)触发。
如何编写一个可被 cron 安全调用的 Custom Command
关键不是“怎么写命令”,而是“怎么写才不会在并发或异常时出问题”。比如清理过期日志、归档旧订单、刷新缓存等操作,必须自带幂等性和排他锁机制。
- 继承
BaseCommand,重写handle(self, *args, **options),所有逻辑放在这里 - 加
requires_system_checks = False避免每次执行都校验数据库连接(尤其在 DB 临时不可用时) - 用
django.core.cache.cache.add()尝试设置一个带 TTL 的锁键(如"maintenance_lock_cleanup_orders"),失败则直接return—— 防止多个cron实例同时进入 - 捕获
DatabaseError和OperationalError,记录警告但不抛出,避免cron邮件轰炸 - 所有数据库操作尽量用
.filter().delete()或.update(),避免先.all()再循环,否则内存爆掉
class Command(BaseCommand):
requires_system_checks = False
<pre class="brush:php;toolbar:false;">def handle(self, *args, **options):
lock_key = "maintenance_lock_cleanup_orders"
if not cache.add(lock_key, "1", timeout=3600): # 1小时锁
self.stdout.write("Another instance is running.")
return
try:
Order.objects.filter(created_at__lt=timezone.now() - timedelta(days=90)).delete()
except (DatabaseError, OperationalError) as e:
logger.warning(f"Cleanup failed: {e}")
finally:
cache.delete(lock_key)
cron 调用时必须指定 DJANGO_SETTINGS_MODULE 和 Python 路径
很多脚本本地能跑,一丢进 cron 就报 ModuleNotFoundError 或 django.core.exceptions.ImproperlyConfigured,本质是环境变量没对齐。
立即学习“Python免费学习笔记(深入)”;
-
cron默认PWD是用户 home 目录,不是项目根目录,所以不能只写python manage.py cleanup_orders - 必须用绝对路径:比如
/opt/myproject/venv/bin/python /opt/myproject/manage.py cleanup_orders - 必须显式设置
DJANGO_SETTINGS_MODULE,例如DJANGO_SETTINGS_MODULE="myproject.settings.production" - 建议在
cron条目里重定向 stdout/stderr 到日志文件,方便排查:> /var/log/django-maintenance.log 2>&1
什么时候该换 Celery Beat 而不是硬扛 cron
当你的维护任务开始依赖 Django 模型状态、需要与其他异步任务协调、或者要求秒级精度(比如每 30 秒检查一次支付回调结果),cron 就撑不住了——它最小粒度是分钟,且和 Django 进程完全隔离。
- Celery Beat 本身不执行任务,只是按配置发消息到 broker(如 Redis),由 worker 拿到后走完整 Django 上下文,能安全调用
select_for_update()、事务、信号等 - 注意 Celery worker 必须和 Web 进程共用同一份
settings.py,尤其是TIME_ZONE和数据库配置,否则时间判断错乱 - Beat 的调度配置写在
CELERY_BEAT_SCHEDULE字典里,key 是任意字符串,value 必须含'task'和'schedule',后者推荐用crontab(minute='*/5')而非数字秒数,更易读
复杂点永远在锁和超时:哪怕用了 Celery Beat,也要给每个周期性任务加唯一锁 + 最大执行时长限制,不然一个卡住的任务会拖垮整个 beat 调度器。


















