0. 上一章思考题参考答案思考题 1线程池里的「任务」只是进程内存里的一个函数调用记录进程一崩全部蒸发而 Celery 的任务是一条被 Broker 持久化的消息生产者Web与执行者Worker是隔离的进程、甚至可以跨机器任务在消息确认之前都不会因为执行方崩溃而消失。Worker 不是被「拉起来执行函数」而是被消息驱动Actor 模型因此是「分布式 Actor 消息中间件」。思考题 2分两段看——① 任务消息尚未成功写入 Broker比如连接池满了时 Broker 挂掉发送失败任务丢失但消息一旦写入且被持久化Broker 恢复后任务仍在。② Worker 默认早确认acks_lateFalse取到消息即 Ack此时 Worker 崩溃消息已被确认任务丢失若开启acks_lateTrue未确认的消息会在 Worker 崩溃后由 Broker 重新投递给其他 Worker代价是可能重复执行必须幂等。1. 项目背景新人小周入职第三周被安排接管「订单短信」异步任务。leader 丢给他一句话「代码在 gitlab 上环境你自己搭明天给我跑起来。」小周 clone 下来发现是个叫celery-main的仓库里面躺着 3000 多个 Python 文件——他慌了我该看哪我该装什么这个仓库是官方源码还是业务代码怎么才能「边读源码边调试」而不是对着黑盒瞎猜这其实是每个 Celery 使用者的必经之路Celery 是个框架不是业务库。你在网上看到的celery -A proj worker命令背后是celery/bin/celery.py里几千行 CLI 逻辑你调用的app.task装饰器背后是celery/app/task.py一千多行的类定义。如果不认识目录结构出了问题就只能「重启大法」——而分布式任务最怕的就是靠运气。同时环境搭建也有讲究业务代码里pip install celery用的是 PyPI 发布的轮子但我们要读源码、加断点、看内部变量就必须用pip install -e .可编辑模式从源码安装。装错模式你打印出的对象是「关过壳的」断点断不进源码内部读源码成了纸上谈兵。业务代码视角 源码开发视角 pip install celery ────────► pip install -e . site-packages/celery/ 成品 celery-main/celery/ 源码 ▲ 能用但不能看内脏 ▲ 可断点、可改、可看本章目标把 Celery 源码目录变成一张「导航地图」并用 Docker Compose 拉起 Redis Broker从源码安装 Celery 5.6.2跑通官方examples/tutorial/tasks.py完成第一个「源码级」最小闭环。2. 项目设计场景小周拿着源码仓库找大师求助小胖在旁边啃鸡腿看热闹。小胖我不理解啊大师pip install celery一行命令就装好了小周非要自己编译源码这不是脱裤子放屁——多此一举吗鸡腿都不香了。小白翻着仓库目录我看了下这仓库里不只有celery/还有examples/、t/测试、docs/、helm-chart/、docker/。业务代码一般就一两个包这仓库至少五六个层次。而且我注意到celery/app/和celery/worker/这种「按组件分目录」的结构好像和 Nginx 那种 src/core、src/http 的布局思路差不多大师小周的问题问对了。先回答小胖能用和能修是两码事。业务代码出 bug我们查自己的代码Celery 出 bug你得查 Celery 的代码。用轮子安装你看到的celery/app/base.py在 site-packages 里pycharm 断点能进去但你改不了它、也看不到完整的仓库配套examples、t 测试、docker 编排。用pip install -e .源码和仓库活在一起你改完不用重装改完就生效。这是源码调试的最低门槛。小周那目录结构我该怎么记3000 个文件总不能靠背吧大师记住一句口诀「应用管配置worker 管消费并发管执行backends 管结果bin 管命令。」再展开就是一张地图目录/文件职责你会在这调试什么celery/app/应用内核baseApp、taskTask、amqp消息、registry注册表、defaults默认配置配置不生效看 defaults任务没注册看 registrycelery/worker/消费运行时worker、consumer 管线、request请求上下文、strategy投递策略任务不执行看 consumer状态不对看 requestcelery/concurrency/并发池prefork、gevent、eventlet、thread、solo并发压不上去看 preforkcelery/backends/结果后端redis、rpc、database、cache 等结果查不到看这里celery/bin/CLI 全家桶celery.py、worker.py、control.py 等celery -A命令行为异常看这里celery/canvas.py工作流原语chain/group/chord/signature编排不按预期看这里celery/beat.py定时调度器定时任务不触发看这里celery/events/监控事件总线Flower 没数据看这里celery/signals.py信号机制横切逻辑想在任务前后插逻辑看这里小白那「源码安装」装的到底是个啥我pip install -e .会不会把 Celery 官方的依赖搞乱影响我们线上大师.指的是仓库根目录Celery 的元信息在pyproject.toml和setup.py里它声明的核心依赖就四个kombu消息层Broker 适配全靠它、billiard进程池prefork 并发的基础、vinepromise 风格回调Canvas 编排的基础、clickCLI 解析。-e模式只是把仓库目录软链进 site-packages不会污染线上——你机器上的环境本来就是隔离的。装完跑celery --version看到 5.6.2 就对了。技术映射目录地图 医院的科室分布图心内、神内、外科kombu/billiard/vine 医院的水电煤管道——你不直接见它们但它们断了全院瘫痪。小胖抹了抹嘴那咋验证装对了总得有活儿干吧光看目录多无聊。大师仓库里有examples/tutorial/tasks.py就 12 行定义了一个add任务。我们把它的 broker 指到本地 Redis跑一个 Worker再用命令行发任务、查结果。跑通之后你用celery report把环境信息导出来团队 wiki 留档。能跑通最小例子环境就算验收了——后面所有章节的实战都在这套环境上跑。3. 项目实战3.1 环境准备Python 3.11、Docker可选但推荐、Git本仓库celery-main已 clone 到本地Redis 6本步用 Docker Compose 拉起# 1) 拉起 Redis开发环境用生产 Broker 选型第 7 章细聊dockercompose-fdocker/docker-compose.yml up-dredis# 2) 创建虚拟环境并从源码可编辑安装python-mvenv .venv .venv\Scripts\activate# WindowsLinux/Mac 用 source .venv/bin/activatepipinstall-e.[celery]# 3) 验证版本与安装方式celery--version# 5.6.2 (kombu 5.x ...)python-cimport celery, os; print(os.path.dirname(celery.__file__))# 应指向仓库 celery-main\celery验证「可编辑安装」生效最后一个命令打印的路径是仓库里的celery目录而不是site-packages说明改动源码立即生效。3.2 分步实现步骤 1给官方示例任务接上 Redis Broker目标让examples/tutorial/tasks.py从默认的amqp://RabbitMQ切到本地 Redis便于我们先跑通。# examples/tutorial/tasks.py改为fromceleryimportCelery appCelery(tasks,brokerredis://localhost:6379/0)# 原来 amqp://app.task()defadd(x,y):returnxyif__name____main__:app.start()坑提醒改examples/下的文件只在本地学习用别提交生产代码应把 broker 写进配置第 4 章。步骤 2启动第一个 Worker目标让一个进程持续从 Redis 拉消息执行add任务。cdexamples/tutorial celery-Atasks worker--loglevelinfo运行结果节选[tasks] . tasks.add [2026-08-23 10:00:01,001: INFO/MainProcess] Connected to redis://localhost:6379/0 [2026-08-23 10:00:01,002: WARNING/MainProcess] celeryDESKTOP ready.Windows 提示若报ValueError: not enough values to unpack之类的进程池错误在命令末尾加--poolsoloWindows 下 prefork 进程池受限第 17 章解释。步骤 3发任务并查结果目标命令行验证「生产者发消息 → Worker 执行 → Backend 无本步未配」。另开一个终端cdexamples/tutorial celery-Atasks call tasks.add--args[1, 2]# 发送任务得到任务 IDcelery-Atasks result上一步的任务ID运行结果文字描述发送成功返回形如 9a2f3c4d-...-e1f2a3b4c5d6 的任务 ID Worker 日志同步打印: Task tasks.add[9a2f3c4d] succeeded in 0.000s: 3注意result命令查不到结果时会提示结果后端未配置——本步 Broker 与 Backend 分离正是第 1 章讲的「传菜口不记账」的直观体验第 8 章补上 Backend 后即可查到返回值。步骤 4用celery report采集环境指纹目标产出可留档的环境信息出问题时有据可查。celery report输出节选software → celery:5.6.2 / kombu:5.x / billiard:4.x / python:3.11.x / platform:windows ...configuration → task_serializer: json, result_backend: (None)...。步骤 5验证可编辑安装的调试效果目标确认断点能进源码。在celery/app/base.py的__init__里临时加一行print( app 正在初始化)再执行python -c from tasks import app会看到该行打印——这就是源码调试的入场券。验证完删除该行。步骤 6用inspect registered验证 Worker 侧注册表目标从运维侧确认 Worker 到底注册了哪些任务任务名契约一目了然。celery-Aorder_tasks inspect registered运行结果文字描述- celeryDESKTOP: OK celery.backend_cleanup celery.chain celery.chord orders.send_order_sms生产排障第一步就是它任务一直 PENDING 时先inspect registered确认 Worker 有没有注册这个任务——没有的话多半是模块没被 import 或任务名不匹配第 15 章故障排查会反复用到。3.3 可能遇到的坑及解决方法坑现象解决pip install -e .装的是旧版celery --version显示 4.x确认工作目录在仓库根目录且虚拟环境是新建的先pip uninstall celery -yWindows 启动 Worker 报OSError: [WinError 6]或进程池错误常见于 prefork加--poolsolo或升级到 Python 3.11第 17 章详细对比并发模型celery -A tasks worker报ModuleNotFoundError: tasks命令在examples/tutorial之外执行先cd examples/tutorial或PYTHONPATHexamples/tutorial启动Docker 拉不起 Redis端口 6379 被占 / Docker 未启动docker compose -f docker/docker-compose.yml down后重试或本机直接跑redis-server任务发出去但 Worker 没反应任务名写错或 Worker 没重启确认celery -A tasks call tasks.add的任务名与注册表一致Worker 重启再试3.4 完整代码清单与测试验证本步不新增业务代码清单即官方examples/tutorial/tasks.py已改 broker 上文 5 个命令。仓库结构速览命令tree celery-L1--dirsfirst# 一屏看完全局测试验证为「环境就绪」写一个冒烟测试放进团队仓库tests/smoke# tests/test_env_smoke.pyfromtasksimportappdeftest_app_can_create_app():assertapp.maintasksdeftest_add_task_registered():asserttasks.addinapp.tasksdeftest_broker_points_to_redis():assertapp.conf.broker_urlredis://localhost:6379/0cdexamples/tutorialpython-mpytest../../tests/test_env_smoke.py-v# 3 passed附五个必读源码文件本仓库后文各章主线文件为什么必读celery/app/base.pyApp 的初始化与配置装配第 4 章的主战场celery/app/task.pyTask 类定义delay/apply_async/retry 全在这 1287 行里celery/bin/celery.pyCLI 入口celery -A全部子命令的分发逻辑celery/app/defaults.py全部默认配置的唯一权威字典小写命名空间出处celery/worker/consumer/tasks.pyWorker 如何声明队列、预取与消费消息3.5 源码调试三件套本章收官技能日志celery worker --logleveldebug能看到消息收发、ack 全过程的明细生产建议 info避免刷屏。断点PyCharm/VSCode 直接断在仓库源码里——可编辑安装保证断点命中的是「真实源码」改完无需重装。pdb / rdb任务函数里临时加import pdb; pdb.set_trace()或使用celery.contrib.rdb远程调试第 38 章展开。三件套配合「五个必读源码文件」表就是后续 35 章源码阅读的通用姿势先看行为、再断关键路径、最后读源码验证假设。4. 项目总结4.1 优点 缺点维度源码可编辑安装pip install -e .轮子安装pip install celery可调试性断点直达框架内部改码即生效源码在 site-packages改动需重装学习素材自带 examples、t/、docs、docker 编排只有包本体版本风险跟着仓库基线走可控装到什么版本看镜像/索引缺点 1需要 clone 仓库体积大安装快、体积小缺点 2误改源码可能引入隐性行为差异无此风险缺点 3新手面对 3000 文件容易迷失本章地图解决——4.2 适用场景适用① 需要读源码/断点调试的框架级开发② 线上问题需要对比框架行为差异时③ 研究依赖联动kombu/billiard 版本升级影响。不适用① 业务交付环境直接依赖固定版本发布即可② 公司安全规范禁止源码装配的机器。4.3 注意事项examples/目录属于示例不要在其中提交业务改动要改就复制到自己项目。Windows 上 prefork 支持受限学习阶段统一--poolsolo避免被环境问题劝退。Redis 0 号库做开发没问题生产建议独立实例或独立 DB 编号避免与缓存数据互相覆盖第 7 章展开。4.4 常见踩坑经验3 个生产故障故障升级 Celery 后任务全部 PENDING。根因Kombu 版本未同步升级消息协议不兼容Worker 拒收但消息已入队。对策依赖锁 pin 版本升级走灰度。教训Celery 与 Kombu 必须同批次升级。故障celery -A命令找不到任务报错 No module named ‘proj’。根因在错误的目录启动 Worker。对策启动脚本里显式cd到项目根目录。教训Worker 的启动目录 任务模块的可见范围。故障开发机跑通、测试机跑挂报 ImportError。根因开发机是源码安装的旧版本测试机从 pip 装了新版本。对策统一用requirements.txt固定celery5.6.2全量锁依赖。教训环境指纹celery report要纳入变更发布单。4.5 思考题celery/app/、celery/worker/、celery/backends/三个目录的边界是什么为什么「配置归属」「消费归属」「结果归属」要拆开提示分别对应 App、Worker、Backend 三个生命周期pip install -e .的-e到底做了什么它如何做到「改源码不重装」提示site-packages 里找到 celery 目录看看它是指向仓库的什么答案见第 3 章开头的「上一章思考题参考答案」。延伸阅读与资源Java 工程师进阶从 JVM 生产排障到OpenJDK原理NumPy 从入门到生产落地全链路实战指南科学计算/向量化Redis 8 实战精讲从 CRUD 到源码构建高可用缓存系统Redis 实战修炼与原理进阶Python 3实战精进从脚本到高并发订单引擎python入门Rquests从菜鸟脚本到企业级SDK的网络实战圣经Milvus向量数据库实战修炼从 0 到 1精通向量检索与生产落地MongoDB 实战进阶与内核修炼后端工程师的 AI 转型第一课Ollama 与私有化大模型实战10倍开发者的 Dify 魔法书从零构建全栈 AI 应用后端工程师转型AI第一课-Ollama 与私有化大模型实战大型语言模型(LLM) vLLM 高性能推理落地实战Agent开发之LlamaIndex 实战修炼与源码进阶大语言模型Transformers 实战修炼与源码剖析