Craft Agents 凭据安全设计：AES-256-GCM 加密存储全流程解析
2026/9/2 11:28:05
0. 上一章思考题参考答案
思考题 1：线程池里的「任务」只是进程内存里的一个函数调用记录，进程一崩全部蒸发；而 Celery 的任务是一条被 Broker 持久化的消息，生产者（Web）与执行者（Worker）是隔离的进程、甚至可以跨机器，任务在消息确认之前都不会因为执行方崩溃而消失。Worker 不是被「拉起来执行函数」，而是被消息驱动（Actor 模型），因此是「分布式 Actor + 消息中间件」。
思考题 2：分两段看——① 任务消息尚未成功写入 Broker（比如连接池满了）时 Broker 挂掉，发送失败，任务丢失；但消息一旦写入且被持久化，Broker 恢复后任务仍在。② Worker 默认早确认（acks_late=False），取到消息即 Ack，此时 Worker 崩溃，消息已被确认，任务丢失；若开启acks_late=True，未确认的消息会在 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/ | 应用内核：base（App）、task（Task）、amqp（消息）、registry（注册表）、defaults（默认配置） | 配置不生效？看 defaults；任务没注册？看 registry |
celery/worker/ | 消费运行时：worker、consumer 管线、request（请求上下文）、strategy（投递策略） | 任务不执行？看 consumer；状态不对？看 request |
celery/concurrency/ | 并发池：prefork、gevent、eventlet、thread、solo | 并发压不上去？看 prefork |
celery/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 并发的基础）、vine（promise 风格回调，Canvas 编排的基础）、click（CLI 解析）。-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# Windows；Linux/Mac 用 source .venv/bin/activatepipinstall-e".[celery]"# 3) 验证版本与安装方式celery--version# 5.6.2 (kombu 5.x ...)python-c"import 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 app=Celery('tasks',broker='redis://localhost:6379/0')# 原来 amqp://@app.task()defadd(x,y):returnx+yif__name__=='__main__':app.start()坑提醒：改
examples/下的文件只在本地学习用，别提交；生产代码应把 broker 写进配置（第 4 章）。
步骤 2：启动第一个 Worker
目标：让一个进程持续从 Redis 拉消息执行add任务。
cdexamples/tutorial celery-Atasks worker--loglevel=info运行结果（节选）：
[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] celery@DESKTOP ready.Windows 提示：若报
ValueError: not enough values to unpack之类的进程池错误，在命令末尾加--pool=solo（Windows 下 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运行结果（文字描述）：
-> celery@DESKTOP: 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 -y |
Windows 启动 Worker 报OSError: [WinError 6]或进程池错误 | 常见于 prefork | 加--pool=solo或升级到 Python 3.11+；第 17 章详细对比并发模型 |
celery -A tasks worker报ModuleNotFoundError: tasks | 命令在examples/tutorial之外执行 | 先cd examples/tutorial，或PYTHONPATH=examples/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.main=='tasks'deftest_add_task_registered():assert'tasks.add'inapp.tasksdeftest_broker_points_to_redis():assertapp.conf.broker_url=='redis://localhost:6379/0'cdexamples/tutorial&&python-mpytest../../tests/test_env_smoke.py-v# 3 passed附：五个必读源码文件（本仓库，后文各章主线）
| 文件 | 为什么必读 |
|---|---|
celery/app/base.py | App 的初始化与配置装配，第 4 章的主战场 |
celery/app/task.py | Task 类定义，delay/apply_async/retry 全在这 1287 行里 |
celery/bin/celery.py | CLI 入口，celery -A全部子命令的分发逻辑 |
celery/app/defaults.py | 全部默认配置的唯一权威字典（小写命名空间出处） |
celery/worker/consumer/tasks.py | Worker 如何声明队列、预取与消费消息 |
3.5 源码调试三件套（本章收官技能）
- 日志：
celery worker --loglevel=debug能看到消息收发、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 支持受限，学习阶段统一
--pool=solo，避免被环境问题劝退。 - 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固定celery==5.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 实战修炼与源码剖析