Django集成Celery任务触发'Not Registered'异常如何解决

开发环境配置 #

Django = 3.2.4
Celery = 5.2.3
Broker/Result Storage: Redis

项目基于Celery实现异步任务处理，承载两类业务逻辑：

• 邮件传输任务：通过@shared_task装饰器实现，全流程运行正常无报错
• AI推理任务：首次触发可执行成功，重复触发相同操作时，任务抛出Not Registered异常

该异常本质是Celery Worker接收到任务消息后，在自身已注册的任务列表中找不到对应名称的任务，结合两类任务的表现差异，具体原因通常有三类：

1. 任务注册时机异常
   邮件任务一般存放在对应业务app的tasks.py中，会在Celery启动执行autodiscover_tasks时被静态扫描、完成注册，因此全程可正常调用。AI推理任务如果存放在非标准路径、或者依赖运行时动态导入才会被加载，Worker启动时不会把该任务加入注册列表；首次触发任务时，触发请求所在的逻辑刚好动态导入了任务函数，会临时完成注册因此执行成功，当Worker进程池的子进程完成任务回收、重载后，临时注册的任务会丢失，后续请求再触发就会报未注册错误。
2. 任务名匹配不一致
   如果AI推理任务没有显式指定固定的name参数，重复触发时如果调用逻辑通过动态路径拼接调用任务，很容易出现调用时传入的任务名和Worker内注册的任务名不一致的问题，导致匹配失败。
3. 自动发现配置漏项
   如果AI推理任务所在的模块没有被纳入Celery自动扫描的范围，首次触发时的临时导入可以让当前进程识别到任务，Worker重启或子进程重载后，任务不会被重新加载，就会抛出异常。

按优先级依次排查调整即可：

1. 确保所有任务在Worker启动时被静态导入
   打开项目根目录的Celery初始化文件（通常为celery.py），调整自动发现配置，必要时手动导入AI任务模块，保证Worker启动时就能加载到所有任务：

import os
from celery import Celery

os.environ.setdefault('DJANGO_SETTINGS_MODULE', '你的项目配置路径.settings')
app = Celery('你的项目名')
app.config_from_object('django.conf:settings', namespace='CELERY')
# 开启自动任务发现
app.autodiscover_tasks()
# 如果AI任务不在app默认的tasks.py路径下，手动导入
from ai_module import tasks as ai_task_module

2. 给AI任务显式指定固定名称
   给AI推理任务的@shared_task装饰器传入固定的name参数，避免路径动态变化导致匹配失败：

@shared_task(name='ai.do_inference')
def do_inference(*args, **kwargs):
    # AI推理业务逻辑
    pass

调用任务时直接导入任务函数用delay/apply_async方法触发，不要通过send_task动态拼接任务名调用，减少名称匹配错误概率。
3. 调整Worker启动参数避免进程异常回收
如果使用默认的prefork进程池启动Worker，添加--max-tasks-per-child=0参数，禁止子进程处理完单任务后自动回收重启，避免动态加载的任务丢失：
celery -A 你的项目名 worker -l info --max-tasks-per-child=0
4. 验证任务注册结果
Worker启动后执行命令celery -A 你的项目名 inspect registered，查看输出的已注册任务列表，如果能看到你定义的AI推理任务名，说明注册正常，重复触发不会再报未注册错误。

内容的提问来源于stack exchange，提问作者bryantjo