Django使用celery multi启动worker报未注册任务错误排查

错误根因 #

报错Received unregistered task of type 'orders.tasks.order_created'的核心原因是：celery multi启动的worker进程没有正确加载Django项目的运行上下文，导致任务没有被扫描、注册到celery的任务注册表中。
该问题和手动执行celery -A speedrealm worker能正常运行的差异，全部来自multi启动时的工作目录、模块路径、环境变量配置不匹配，和代码本身的任务定义无关。

分步修复操作 #

• 第一，对齐项目绝对路径，解决模块找不到的问题
  当前配置存在多处路径不匹配的问题：
  • settings中CELERYD_CHIR="/home/bulofants/performancerealm.com"存在拼写错误（chdir错写为chir）
  • systemd服务配置的WorkingDirectory=/home/bulofants/sites/performancerealm.com，和你实际存放代码的根目录（包含manage.py、orders/、speedrealm/目录的路径）不一致
    修复要求：把所有和项目路径相关的配置，全部替换为代码实际存放的根目录绝对路径，杜绝路径错配、拼写错误。
• 第二，手动验证multi启动的正确命令
  非项目根目录下执行celery multi命令时，worker进程的Python模块搜索路径不会包含项目根目录，会导致找不到speedrealm、orders包，无法执行autodiscover_tasks()扫描任务。
  正确的手动启动流程：

  # 先cd到项目真实根目录
  cd /home/bulofants/performancerealm.com
  # 用项目虚拟环境内的celery可执行文件启动，避免全局celery版本/路径不匹配
  /home/bulofants/.local/share/virtualenvs/performancerealm.com-8nBM01mn/bin/celery multi start w1 -A speedrealm -l DEBUG
  

  按照这个流程启动后，如果任务能正常识别，就说明之前的multi启动失败是因为目录不对、用了非虚拟环境的celery导致的。
• 第三，修正无效的settings配置
  settings中以CELERYD_开头的配置项是旧版celery daemon的参数，在使用multi/systemd方式启动worker时，这些配置不会自动注入到进程中，属于无效配置：
  • 删除拼写错误的CELERYD_CHIR配置项
  • CELERY_IMPORTS不是必需配置：只要你在celery.py中启用了app.autodiscover_tasks()，且所有业务app都注册在settings的INSTALLED_APPS列表中，celery会自动扫描每个app下的tasks.py文件加载任务。你可以暂时保留CELERY_IMPORTS = ['orders.tasks']做兜底，待任务正常注册后可删除该配置。
• 第四，修正systemd服务的配置错误
  现有celery.service文件存在几处会导致进程启动异常的问题：
  1. ExecStart参数拼接错误：当前配置写了celery ${CELERY_BIN} multi ...，而CELERY_BIN本身是celery可执行文件的绝对路径，会导致命令执行时参数错乱，worker无法正常启动。
  2. EnvironmentFile指向的路径无效：当前配置把目录路径当成了env配置文件，没有注入必要的环境变量。
  3. 权限问题：没有提前创建celery日志、pid文件的存放目录，会因为权限不足导致进程加载失败。
     修正后的核心配置参考：

  [Unit]
  Description=Celery Service
  After=network.target
  
  [Service]
  Type=forking
  User=bulofants
  Group=bulofants
  # 替换为项目真实根目录
  WorkingDirectory=/home/bulofants/performancerealm.com
  # 注入虚拟环境路径，确保Python能找到项目模块、依赖包
  Environment="PATH=/home/bulofants/.local/share/virtualenvs/performancerealm.com-8nBM01mn/bin:/usr/bin:/bin"
  Environment="DJANGO_SETTINGS_MODULE=speedrealm.settings"
  ExecStart=/home/bulofants/.local/share/virtualenvs/performancerealm.com-8nBM01mn/bin/celery multi start w1 -A speedrealm -l INFO --pidfile=/var/run/celery/%n.pid --logfile=/var/log/celery/%n%I.log --time-limit=300 --concurrency=8
  ExecStop=/home/bulofants/.local/share/virtualenvs/performancerealm.com-8nBM01mn/bin/celery multi stopwait w1 --pidfile=/var/run/celery/%n.pid
  ExecReload=/home/bulofants/.local/share/virtualenvs/performancerealm.com-8nBM01mn/bin/celery multi restart w1 -A speedrealm -l INFO --pidfile=/var/run/celery/%n.pid --logfile=/var/log/celery/%n%I.log --time-limit=300 --concurrency=8
  
  [Install]
  WantedBy=multi-user.target
  

  启动前提前执行目录初始化操作：

  mkdir -p /var/log/celery /var/run/celery
  chown -R bulofants:bulofants /var/log/celery /var/run/celery
  

• 第五，校验任务注册状态
  启动worker后，查看日志文件中启动阶段打印的已注册任务列表，确认orders.tasks.order_created在列表内。如果列表中缺失该任务，做两项检查：
  • 确认orders app已经添加到settings的INSTALLED_APPS列表中
  • 在项目根目录执行python manage.py shell，运行from orders.tasks import order_created，检查是否存在导入报错（比如models导入失败、依赖包缺失等），有报错就先修复导入问题。

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