Celery chord头任务超2个时回调及剩余子任务无法启动问题

API 探路者

2026-8-29

问题描述

使用Celery chord实现“所有数据更新子任务完成后触发报表更新回调”的逻辑，核心实现代码如下：

@shared_task(autoretry_for=(Exception,), retry_backoff=True, retry_kwargs={'max_retries': 5})
def upload(df: pd.DataFrame, **kwargs):
    ed = EntityDataPoint(df, **kwargs)
    uploadtasks, source, subtype = ed.upload_database()
    chord(uploadtasks)(final_report.si(logger=ed.logger, 
                                       source=source, 
                                       subtype=subtype,
                                       index=ed.index))

其中uploadtasks是分组构造的批量上传任务，构造逻辑如下：

g = group(unwrap_upload_bulk.s(obj = self, data = self.data.iloc[i:i+chunk_size]) 
                                 for i in range(0, len(self.data), chunk_size))

异常表现

chord的header（传入的group任务）子任务数超过2个时，仅前2个子任务能成功执行，group内剩余子任务、chord绑定的回调任务均不会启动
全程无错误抛出，Celery worker日志无相关异常记录
执行celery inspect active、celery inspect scheduled排查，队列中不存在等待调度的任务
header子任务数≤2时功能完全正常：所有group子任务执行完成后，回调任务正常触发
问题和子任务处理的数据量无关：即使每个子任务仅处理100行数据，总数据量到1000行时仍会复现问题
单独执行group任务、不搭配chord回调时，所有任务都能正常执行无报错
尝试过chord的多种官方语法写法，异常表现没有变化
测试过group.link回调方案：group本身能正常执行完，但该机制无法保证所有子任务完成后再触发回调，不满足业务要求

运行环境

Celery 5.2.3
Redis 7.0.0 作为消息 broker
Django 3.2.13 + PostgreSQL 作为业务后端
Python 3.9
所有服务运行在独立Docker容器中

解决方案

这个问题是Redis作为broker时chord的已知适配问题，和当前配置强相关，按优先级依次修复即可：

修正chord调用写法
现有代码中chord(uploadtasks)(callback)的写法不会把chord整个任务拓扑正确提交到broker，子任务数少的时候碰巧能跑，子任务多了就会丢任务。换成标准调用方式：
```
chord(
    uploadtasks,
    final_report.si(
        logger=ed.logger, 
        source=source, 
        subtype=subtype,
        index=ed.index
    )
).apply_async()
```
调整worker预取配置
“刚好只有前2个任务执行”的现象，90%是worker预取配置导致的：如果worker启动时并发设为2，默认worker_prefetch_multiplier=4的配置会让worker提前把后续任务锁到本地但不调度，chord统计不到剩余任务的状态，就会直接卡住且不抛错。在Celery配置里添加这两个参数：
```
worker_prefetch_multiplier = 1
task_acks_late = True
```
改完重启所有worker，避免任务被提前锁定但不执行。
修正结果后端配置
用PostgreSQL+Django ORM当结果后端，和Redis broker搭配跑chord本身就不稳定：chord需要高频同步每个子任务的完成状态，数据库后端的延迟太高很容易丢状态。直接把结果后端换成同实例的Redis即可：
```
result_backend = 'redis://你的Redis服务地址:6379/1'
chord_unlock_retry_count = 10
```
检查worker并发数
如果启动worker的时候用了-c 2指定并发数为2，且上传任务是CPU/IO密集型，两个worker被占满后，chord自带的解锁调度任务没有空闲进程跑，就会卡在子任务执行完的状态，后续任务和回调都不会触发。把worker并发数调到至少3以上，或者单独开一个worker专门跑chord的内置调度任务即可。

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

Celery chord头任务超2个时回调及剩余子任务无法启动问题

异常表现 #

运行环境 #

异常表现

运行环境