Celery 配置升级实战：用 `celery upgrade settings` 将 3.x 旧式设置迁移到 4.x 新命名规范

• 任务调度
• 后端
• 消息队列

本篇技术指南以 Celery 仓库中的celery upgrade命令（celery/bin/upgrade.py）为核心，讲解如何将 Celery 3.x 时代的旧式大写配置（如BROKER_URL、CELERY_ALWAYS_EAGER）一键迁移为 4.x 及以后版本的全小写新命名（如broker_url、task_always_eager），并覆盖 Django 项目的CELERY_命名空间改造。读完本文，你将掌握celery upgrade settings的完整用法、三个选项（--django/--compat/--no-backup）的适用场景、备份与回滚机制，以及新旧设置名背后的映射表与源码实现原理，从而安全、无痛地完成项目配置升级。

为什么需要升级设置名：4.0 起命名规范全面变更

Celery 4.0 对配置系统做了一次"为美而战"（in pursuit of beauty）的大规模改名：所有设置名改为全小写，并对前缀进行了系统性梳理。这一变更完全向后兼容——旧的大写名称仍然可用，但官方强烈建议尽快迁移。仓库文档 docs/history/whatsnew-4.0.rst 明确指出，迁移工作可以交给celery upgrade settings命令自动完成。

核心变更可归纳为三条规则：

1. 大小写规范化：所有设置名由全大写改为全小写，例如BROKER_URL→broker_url。
2. 前缀重构：
   • celerybeat_前缀更名为beat_（如CELERYBEAT_SCHEDULE→beat_schedule）；
   • celeryd_前缀更名为worker_（如CELERYD_CONCURRENCY→worker_concurrency）；
   • 去掉celery_前缀，任务相关设置改挂task_前缀，worker 相关设置改挂worker_前缀（如CELERY_ALWAYS_EAGER→task_always_eager、CELERY_TASK_SERIALIZER→task_serializer）。
3. 个别特殊改名：少量设置不仅改前缀还改了语义名称，例如CELERY_MAX_CACHED_RESULTS→result_cache_max、CELERY_RESULT_DBURI→ 直接改用result_backend（详见下文"特殊重命名"表）。

命令基本用法：一条命令完成就地迁移

celery upgrade是 Celery CLI 中用于"在版本之间执行升级"的命令组，目前包含settings一个子命令，其职责在源码 docstring 中写明为"Migrate settings from Celery 3.x to Celery 4.x"（celery/bin/upgrade.py）。

基本调用方式（针对普通 Python 项目的配置模块，例如proj/celeryconfig.py）：

$ celery upgrade settings proj/settings.py

执行过程分三步（对应 celery/bin/upgrade.py 的实现）：

1. 读取文件：_slurp以 UTF-8 编码逐行读入目标文件全部内容；
2. 逐行替换：对每一行调用_to_new_key做新旧键名映射替换，得到(did_change, line_contents)元组列表；
3. 写回与备份：只要有任何一行发生了变更，默认先在原文件旁生成备份文件（如proj/settings.py.orig），再把替换后的内容写回原文件。

命令结束时会在标准输出打印结果：有变更时输出Changes to your setting have been made!；无需变更时输出Does not seem to require any changes :-)。

备份机制：.orig文件与回滚

celery upgrade settings默认会进行"原地修改 + 备份"。备份逻辑位于_backup（celery/bin/upgrade.py）：它把原文件完整复制为追加.orig后缀的新文件（例如proj/settings.py→proj/settings.py.orig），并打印writing backup to proj/settings.py.orig...。settings命令文档（docs/history/whatsnew-4.0.rst）也明确承诺：命令会就地修改你的模块为新的小写名称，并保存一份.orig备份。这意味着升级后可随时用备份文件对比检查或回滚。

三个选项详解：--django、--compat、--no-backup

在 celery/bin/upgrade.py 中，settings子命令声明了三个互不冲突的选项：

这三个选项的生效逻辑非常简洁（celery/bin/upgrade.py）：

keyfilter = _compat_key if django or compat else pass1

• 默认（两者均不指定）时，keyfilter为恒等函数pass1，仅做大小写/前缀规范化，即BROKER_URL→broker_url；
• 指定--django或--compat时，keyfilter切换为_compat_key（celery/bin/upgrade.py），它会在原有基础上再给每个设置名补上CELERY_前缀（若本身不以CELERY开头），得到CELERY_BROKER_URL这种 Django 风格的大写命名。

因此三条命令产生三种结果风格：

# 普通模式：全小写新命名 $ celery upgrade settings proj/settings.py # BROKER_URL -> broker_url # Django/兼容模式：大写 + CELERY_ 前缀 $ celery upgrade settings proj/settings.py --django # BROKER_URL -> CELERY_BROKER_URL # 不备份直接覆盖 $ celery upgrade settings proj/settings.py --no-backup

Django 项目迁移：--django与CELERY_命名空间

对于从 Djangosettings.py加载 Celery 配置的项目，官方推荐使用CELERY_前缀，把 Celery 配置与 Django 自身及其他应用的配置隔离。仓库的 Django 示例项目即采用这一模式（见 examples/django/proj/celery.py 与 examples/django/proj/settings.py）：

# proj/celery.py app.config_from_object('django.conf:settings', namespace='CELERY')

# proj/settings.py —— 升级后的目标形态 CELERY_BROKER_URL = 'redis://localhost:6379/0' CELERY_TASK_ALWAYS_EAGER = True CELERY_WORKER_CONCURRENCY = 4

迁移旧 Django 项目分两步（docs/userguide/configuration.rst 与 docs/history/whatsnew-4.0.rst）：

第一步：升级设置文件。对旧的 Django 配置执行：

$ celery upgrade settings proj/settings.py --django

--django会为原本没有前缀的设置补上CELERY_。例如旧的BROKER_URL应写成CELERY_BROKER_URL——这一转换完全由命令自动完成，无需手工改动。

第二步：在celery.py中显式声明命名空间。在proj/celery.py里通过app.config_from_object('django.conf:settings', namespace='CELERY')让应用从带前缀的 Django 设置中读取配置。完整的 Django 集成示例可参考 docs/django/first-steps-with-django.rst。

新旧设置名对照表

常见设置对照（旧 → 新）

下表完整摘录自 docs/userguide/configuration.rst 的官方对照表，覆盖 broker、result backend、任务与 worker 等核心配置域：

特殊重命名（语义变化）

除前缀统一外，个别设置在改名时还调整了语义或归属，摘录自 docs/history/whatsnew-4.0.rst：

源码原理：_TO_NEW_KEY映射表如何驱动替换

celery upgrade settings之所以能自动完成新旧键名替换，底层依赖一张由celery/app/defaults.py在模块加载时生成的映射表_TO_NEW_KEY。

映射表的生成链路如下（celery/app/defaults.py）：

1. NAMESPACES以嵌套字典定义全部配置项，每个配置项是Option对象；带旧名的选项通过old={...}参数声明其历史名称，例如send_task_events声明了old={'celery_send_events'}（celery/app/defaults.py）；
2. _to_compat遍历所有配置项：若选项声明了opt.old，则把旧键映射到新键；否则把同名键大写后映射到自身，从而保证新旧名称一一对应；
3. flatten(NAMESPACES, keyfilter=_to_compat)生成(old_key, new_key, opt)三元组列表，最终产出三个字典：
   • _TO_NEW_KEY：旧键 → 新键（upgrade settings命令正是消费这张表）；
   • _TO_OLD_KEY：新键 → 旧键（用于反向兼容）；
   • _OLD_DEFAULTS：旧键 → 默认值。

替换逻辑位于_to_new_key（celery/bin/upgrade.py），它有一个值得注意的细节——按旧键名长度降序匹配：

for old_key in reversed(sorted(source, key=lambda x: len(x))): new_line = line.replace(old_key, keyfilter(source[old_key])) if line != new_line and 'CELERY_CELERY' not in new_line: return 1, new_line # only one match per line. return 0, line

源码注释解释了原因：避免broker_transport抢先匹配并覆盖broker_transport_options这类前缀包含关系。长键先替换可保证子键不被父键误伤；同时每行只做一次替换即返回，并且用'CELERY_CELERY' not in new_line防止重复加前缀产生CELERY_CELERY_...这类错误键名。

单元测试 t/unit/app/test_defaults.py 对映射表的自洽性做了严格校验：

• DEFAULTS中不含任何大写键，_OLD_DEFAULTS中不含任何小写键（新旧两套命名互不混杂）；
• _TO_NEW_KEY的每个键都属于_OLD_SETTING_KEYS，_TO_OLD_KEY的每个键都属于SETTING_KEYS，且映射后的值大小写方向正确。

这套测试保证了两张映射表始终闭合、可双向查找，是celery upgrade settings可靠性的根基。

注意事项与限制

1. 新旧命名不可混用：loader 会自动检测配置使用的是新格式还是旧格式并据此解析，但这意味着你不允许在同一个配置里混用新旧设置名——除非你为两个替代名都提供了值（docs/history/whatsnew-4.0.rst）。迁移时应一次性完成。
2. --django会补前缀：该选项会给原本没有前缀的设置统一加上CELERY_，例如BROKER_URL变为CELERY_BROKER_URL。如果目标项目本就不打算走 Djangonamespace='CELERY'路线，应使用默认模式而非--django。
3. --compat与--django行为等价：从源码看，两者都只是把keyfilter切换为_compat_key，区别在于语义场景——--compat面向希望保留大写风格的非 Django 项目。
4. 备份是默认行为：除非显式传入--no-backup，命令总会生成.orig备份；若对替换结果不满意，可用备份文件恢复。
5. 文件必须可写且存在：命令以 UTF-8 读写文件；源码中_slurp留有 TODO 注释，尚未专门处理文件不存在的情况（celery/bin/upgrade.py），因此请确认目标文件路径正确。

小结

celery upgrade settings是 Celery 从 3.x 走向 4.x 命名体系时提供的自动化迁移工具，它的核心价值在于：以 celery/app/defaults.py 中的_TO_NEW_KEY映射表为唯一事实来源，逐行扫描并就地重写配置文件，同时默认保留.orig备份，兼顾了正确性与安全性。对普通项目使用默认模式即可获得全小写新命名；对 Django 项目，则配合--django与namespace='CELERY'两步走，即可平滑过渡到官方推荐的前缀化配置风格。如需完整的设置项语义说明，可继续查阅 docs/userguide/configuration.rst 中的 Configuration Directives 章节；该命令的 API 文档位于 docs/reference/celery.bin.upgrade.rst。

• 任务调度
• 后端
• 消息队列