1. 为什么使用 Celery？

💡 解决“阻塞请求”问题，提升系统响应速度与扩展性

场景 传统同步处理 使用 Celery 异步处理
发送邮件 用户等待 5~10 秒 立即返回“已提交”，后台异步发送
生成 Word 报告 请求超时失败 后台生成，完成后通知前端
调用第三方 API 高延迟拖垮服务 异步重试、限流、降级可控
定时清理缓存 需手动执行脚本 自动每天凌晨 2:00 执行

✅ 适用场景：

  • 文件/图片处理
  • 第三方接口调用（如 COS、短信、微信）
  • 数据统计、报表生成
  • 定时任务（每日对账、数据同步）

2. 核心组件说明

组件 作用 是否必需
Worker 执行任务的实际进程。可部署多台机器实现负载均衡 ✅ 必需
Beat 定时任务调度器，按计划触发周期性任务（如每天凌晨跑一次） ✅ 如需定时任务则必需
Broker（消息代理） 存储待执行任务的队列，相当于“任务信箱” ✅ 必需
Result Backend 存储任务执行结果（成功/失败、返回值） ⚠️ 推荐，用于状态监控

🔹 推荐组合：

  • 开发/轻量：Redis（同时做 Broker + Result Backend）
  • 生产：RabbitMQ（Broker） + Redis（Result Backend）

3. 平台差异：Windows VS Linux/macOS

维度 Linux / macOS Windows
默认并发池 prefork（基于 fork）✅ 推荐 prefork ❌ 禁止使用
是否支持 fork() ✅ 支持，高效稳定 ❌ 不支持，改用 spawn()
推荐并发池 prefork（CPU 密集）
eventlet（I/O 密集）		 ✅ threads（I/O 密集）
✅ solo（调试）
❌ 禁用 eventlet 和 prefork
eventlet 可用性 ✅ 高效，适合 HTTP 请求、下载 ❌ 严重 Bug：
DNS 解析失败、SSL 错误、连接超时
文件路径/权限 路径规范，权限可控 易因中文路径、杀毒软件、权限不足报 [WinError 5]
典型错误 无特殊问题 PermissionError: [WinError 5]
NameResolutionError: Lookup timed out

⚠️ 重要结论：
Windows 上使用 eventlet 是“自杀式配置”！

4. 启动命令规范（必读！）

✅ 所有成员必须严格遵守以下命令格式

平台 目标 推荐命令
Linux/macOS
（CPU 密集型）		 启动 Worker celery -A your_app worker -l info -P prefork -c 4
Linux/macOS
（I/O 密集型）		 启动 Worker celery -A your_app worker -l info -P eventlet -c 10
Windows
（I/O 密集型，如你正在做的 DOCX 生成）		 启动 Worker celery -A your_app worker -l info --pool=threads --concurrency=10
Windows
（调试模式）		 单进程运行 celery -A your_app worker -l info --pool=solo
所有平台
（定时任务）		 启动 Beat celery -A your_app beat -l info
所有平台
（开发合并）		 Worker + Beat celery -A your_app worker --beat -l info --pool=threads -c 10

🔍 参数说明：

  • -A your_app：指定包含 Celery 实例的模块名（如 celery_tasks）
  • -l info：日志级别，生产可用 warning
  • --pool=threads：Windows 唯一推荐方案
  • --concurrency=10：线程数，根据机器 CPU 核心数调整（建议 5~10）

5. 常见错误与解决方案

错误现象 原因 解决方案
PermissionError: [WinError 5] 拒绝访问 在模块顶层打开了文件/数据库连接 ✅ 移动到任务函数内；使用 --pool=threads
NameResolutionError: Lookup timed out 使用了 eventlet + Windows ✅ 禁用 -P eventlet，改用 --pool=threads
No module named 'your_app' 启动路径不对 ✅ 在项目根目录执行命令，确保 PYTHONPATH 正确
Beat not starting Redis 未运行 ✅ redis-server 必须先启动
Worker exits with code 1 代码语法错误、依赖缺失 ✅ 本地 python -m celery_tasks 测试导入

💡 调试技巧：
在 Windows 上，先用 --pool=solo 运行，确认功能正常，再切回 --pool=threads

6. 生产环境部署建议

项目 建议
部署方式 使用 supervisor（Linux）或 NSSM（Windows）管理 Celery 进程
日志轮转 配置 logrotate（Linux）或 LogRotate 工具，防止日志爆满
监控告警 集成 Prometheus + Grafana，监控任务队列长度、失败率
资源限制 Worker 设置内存上限（如 --max-tasks-per-child=100）避免内存泄漏
任务优先级 使用多个队列：high_priority, low_priority，避免大任务阻塞小任务
备份策略 定期备份 Redis 中的任务队列（如 redis-cli save）
CI/CD 集成 部署脚本中自动检查 redis-server 和 celery 是否运行

7. 快速启动命令对照表

场景 Linux/macOS 命令 Windows 命令
启动默认 Worker celery -A celery_tasks worker -l info -P prefork -c 4 celery -A celery_tasks worker -l info --pool=threads --concurrency=10
启动高并发 I/O Worker celery -A celery_tasks worker -l info -P eventlet -c 10 ❌ 不允许使用
启动 Beat 调度器 celery -A celery_tasks beat -l info celery -A celery_tasks beat -l info
Worker + Beat 合并启动 celery -A celery_tasks worker --beat -l info -P prefork -c 4 celery -A celery_tasks worker --beat -l info --pool=threads -c 10
调试模式（单进程） celery -A celery_tasks worker -l info -P solo celery -A celery_tasks worker -l info --pool=solo
查看任务队列状态 celery -A celery_tasks inspect active_queues 同左

✅ 记住口诀：
Linux 用 prefork，I/O 可选 eventlet；

Windows 只认 threads，别碰 eventlet！

作者：admin  创建时间：2025-10-20 17:36
最后编辑：admin  更新时间：2025-10-20 17:38