Celery выполнил задачу дважды: acks_late, ретраи и идемпотентные задачи
Во время деплоя воркер умер, и клиент получил кешбэк два раза. Когда Celery отправляет ack, как работают ретраи и что нужно, чтобы задача пережила повтор.
Представьте: пользователь оплатил заказ, а view отправила в Celery задачу «начисли кешбэк и пришли SMS». В этот момент идёт деплой: Kubernetes шлёт старому поду воркера SIGTERM, ждёт 30 секунд, потом SIGKILL. Задача оборвалась на середине. Дальше возможны два исхода, и оба плохие: либо задача пропадёт целиком (клиент никогда не получит кешбэк), либо выполнится повторно, и кешбэк придёт дважды.
Какой из них случится, зависит от настроек Celery. В этой статье разберём, когда Celery считает задачу «выполненной», как работают ретраи и как сделать задачу безвредной при повторном выполнении (идемпотентной). В прошлой статье мы говорили о ключах идемпотентности для HTTP-запросов; здесь применим ту же идею к фоновым задачам.
Наивный код и четыре ошибки в нём
Во многих проектах первая версия выглядит примерно так:
# orders/tasks.py — the naive version
from decimal import Decimal
from celery import shared_task
from notifications.sms import send_sms
@shared_task
def credit_cashback(order):
user = order.user
user.balance += order.total * Decimal("0.01")
user.save()
send_sms(user.phone, f"Cashback for order #{order.pk} credited")
# orders/views.py — the naive call site
from django.db import transaction
from django.http import JsonResponse
from .models import Order
from .tasks import credit_cashback
def pay_order(request, order_id):
with transaction.atomic():
order = Order.objects.select_for_update().get(pk=order_id, user=request.user)
order.status = Order.Status.PAID
order.save(update_fields=["status"])
credit_cashback.delay(order) # sent BEFORE commit, with a whole object
return JsonResponse({"ok": True})
На первый взгляд всё нормально. На деле здесь четыре проблемы:
- Задача отправляется до коммита. Воркер может забрать сообщение раньше, чем транзакция закоммитится, и увидеть в базе старое состояние заказа. А если транзакция откатится, кешбэк начислится за неоплаченный заказ.
- В аргумент передан целый объект. JSON-сериализатор вообще не умеет сериализовать модель, а с pickle воркер работает с копией, устаревшей на секунды или минуты.
balance += ...— это read-modify-write. Две параллельные задачи потеряют запись одной из них.- Задача не идемпотентна. При повторе деньги добавятся ещё раз, и SMS уйдёт ещё раз.
Почему четвёртая проблема, самая важная, неизбежна, становится понятно, только когда разберёшься с гарантиями доставки в Celery.
Когда уходит ack: at-most-once и at-least-once
Брокер (Redis или RabbitMQ) отдаёт сообщение воркеру, а воркер должен его подтвердить — отправить ack: «получил, можно удалять». Вопрос только в том, когда этот ack уходит.
По умолчанию Celery подтверждает сообщение до выполнения задачи. Если воркер умер посередине, сообщения в брокере уже нет — задача потеряна. Это at-most-once: не больше одного раза, иногда ноль.
С acks_late=True ack отправляется после завершения задачи. Если у воркера оборвалось соединение с брокером или сервер выключился, неподтверждённое сообщение будет доставлено снова. Это at-least-once: как минимум один раз, иногда два и больше.
Но есть тонкость. Задачу в Celery выполняет не главный процесс воркера, а дочерний процесс пула. Если убит именно он (OOM killer или SIGKILL), главный процесс подтверждает сообщение даже при acks_late и помечает задачу как FAILURE. Чтобы вернуть сообщение в очередь, нужен отдельный флаг task_reject_on_worker_lost=True.
| Настройка | Когда ack | Убит процесс пула | Упал весь воркер/соединение | Гарантия |
|---|---|---|---|---|
| По умолчанию | До выполнения | Задача теряется | Задача теряется | at-most-once |
acks_late=True |
После выполнения | Ack, задача теряется | Повторная доставка | частично at-least-once |
acks_late + reject_on_worker_lost |
После выполнения | Возврат в очередь | Повторная доставка | at-least-once |
Обратите внимание: даже с acks_late, если задача упала с обычным исключением, сообщение подтверждается (по умолчанию task_acks_on_failure_or_timeout=True). Повторять попытку — работа ретраев, а не ack.
Никакого «exactly-once» нет. Вы выбираете между потерей задачи и её повтором. Когда речь о деньгах, почти всегда выбирают повтор и делают задачу устойчивой к нему.
Для задач, связанных с деньгами, я начинаю с такой конфигурации:
# config/celery.py
import os
from celery import Celery
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
app = Celery("config")
app.config_from_object("django.conf:settings", namespace="CELERY")
app.autodiscover_tasks()
# config/settings.py
CELERY_BROKER_URL = "redis://localhost:6379/0"
CELERY_TASK_SERIALIZER = "json"
CELERY_ACCEPT_CONTENT = ["json"]
CELERY_TASK_ACKS_LATE = True # ack after the task finishes
CELERY_TASK_REJECT_ON_WORKER_LOST = True # requeue if the pool process dies
CELERY_WORKER_PREFETCH_MULTIPLIER = 1 # do not hoard unacked messages
# Redis: must exceed your longest task AND your longest countdown/ETA
CELERY_BROKER_TRANSPORT_OPTIONS = {"visibility_timeout": 6 * 60 * 60}
Зачем worker_prefetch_multiplier = 1? Воркер забирает сообщения заранее (prefetch), и с acks_late они висят неподтверждёнными. На длинных задачах это значит, что один воркер «держит» много сообщений, и при его падении все они будут доставлены заново.
Ретраи: exponential backoff, jitter и max_retries
Если внешний API временно не отвечает, повторять сразу — плохая идея: сотни воркеров одновременно добивают и без того перегруженный сервис. Правильно — удваивать паузу с каждой попыткой (exponential backoff) и добавлять случайную составляющую (jitter), чтобы повторы размазывались во времени.
# notifications/tasks.py
import requests
from celery import shared_task
from .models import Notification
SMS_URL = "https://sms.example.com/v1/messages"
@shared_task(
bind=True,
autoretry_for=(requests.ConnectionError, requests.Timeout),
retry_backoff=True, # 1, 2, 4, 8 ... seconds
retry_backoff_max=600, # never wait more than 10 minutes
retry_jitter=True, # random delay in [0, backoff]
max_retries=8,
)
def send_sms_notification(self, notification_id: int) -> None:
n = Notification.objects.get(pk=notification_id)
if n.status == Notification.Status.SENT:
return # a previous delivery already did the job
resp = requests.post(
SMS_URL,
json={"phone": n.phone, "text": n.text},
headers={"Idempotency-Key": str(n.uuid)},
timeout=(3, 10),
)
if resp.status_code == 429 or resp.status_code >= 500:
# temporary problem on their side: retry manually with a delay
raise self.retry(countdown=min(60 * 2 ** self.request.retries, 900))
resp.raise_for_status() # other 4xx: a bug in our request, retrying won't help
Notification.objects.filter(pk=n.pk).update(status=Notification.Status.SENT)
Что здесь происходит:
autoretry_for— автоматический ретрай только для перечисленных исключений. Не пишитеautoretry_for=(Exception,): повторять восемь разDoesNotExistилиKeyErrorбессмысленно.retry_backoff=Trueсчитает задержку как1 * 2 ** retriesсекунд и ограничивает еёretry_backoff_max(по умолчанию 600).retry_jitter=True(включён по умолчанию) выбирает реальную задержку случайно от 0 до этого значения.max_retriesпо умолчанию равен 3;Noneозначает бесконечно. Когда лимит исчерпан,self.retry(exc=exc)пробрасывает исходное исключение, а безexc—MaxRetriesExceededError.self.retry()бросает исключение, поэтому принято писатьraise self.retry(...): сразу видно, что код ниже не выполнится.timeout=(3, 10)обязателен. Без таймаутаrequestsможет зависнуть навсегда, и ретрай так и не начнётся.
Важно: ретрай — это повторная отправка той же задачи новым сообщением с countdown. То есть он тоже часть механизма at-least-once, и задача всё равно должна быть готова к повтору. Для этого и нужен заголовок Idempotency-Key: если SMS-провайдер принял запрос, а ответ до нас не дошёл, повторный запрос не превратится во второе SMS — конечно, если провайдер этот заголовок поддерживает.
Как сделать задачу идемпотентной
Идемпотентная задача даёт один и тот же результат, выполнили её один раз или пять. Самый надёжный способ сделать это в базе — оформить «захват» одним атомарным UPDATE:
# orders/tasks.py — the fixed version
from decimal import ROUND_HALF_UP, Decimal
from celery import shared_task
from django.db import transaction
from django.db.models import F
from wallets.models import Wallet
from .models import Order
@shared_task(acks_late=True)
def credit_cashback(order_id: int) -> None:
with transaction.atomic():
# Atomic "claim": only one execution can flip the flag.
claimed = Order.objects.filter(
pk=order_id,
status=Order.Status.PAID,
cashback_credited=False,
).update(cashback_credited=True)
if not claimed:
return # already credited, or the order is not paid
order = Order.objects.only("total", "user_id").get(pk=order_id)
amount = (order.total * Decimal("0.01")).quantize(
Decimal("0.01"), rounding=ROUND_HALF_UP
)
Wallet.objects.filter(user_id=order.user_id).update(
balance=F("balance") + amount
)
Здесь проверка и запись — не два отдельных шага. Если написать if order.cashback_credited: return, а потом save(), две параллельные задачи обе увидят False и обе начислят деньги. Условный UPDATE в PostgreSQL работает иначе:
-- What the "claim" compiles to (simplified)
UPDATE orders_order
SET cashback_credited = true
WHERE id = 42
AND status = 'paid'
AND cashback_credited = false;
-- First transaction: UPDATE 1
-- Second, concurrent: waits for the row lock, re-checks WHERE
-- after the first commits -> UPDATE 0
На уровне READ COMMITTED вторая транзакция ждёт блокировку строки, взятую первой, после коммита перепроверяет условие WHERE на новой версии строки и ничего не обновляет. .update() возвращает число обновлённых строк — на этом и строится проверка. Баланс тоже обновляем через F("balance") + amount: атомарное сложение на стороне базы, а не чтение-запись в Python.
Ещё более надёжный вариант — записывать каждую операцию отдельной строкой в леджер и поручить отсев дублей самой базе:
# wallets/models.py — a ledger row makes duplicates impossible at the DB level
from django.db import models
class CashbackEntry(models.Model):
order = models.ForeignKey("orders.Order", on_delete=models.PROTECT)
amount = models.DecimalField(max_digits=14, decimal_places=2)
created_at = models.DateTimeField(auto_now_add=True)
class Meta:
constraints = [
models.UniqueConstraint(fields=["order"], name="uniq_cashback_per_order"),
]
Второй CashbackEntry.objects.create(order_id=...) получит IntegrityError, и транзакция откатится. Как бы ни ошибся код, constraint второй записи не пропустит.
С внешними сайд-эффектами (SMS, email, платёж через провайдера) сложнее: их не включишь в транзакцию базы. Тут два инструмента: ключ идемпотентности, если провайдер его поддерживает, а если нет — запись состояния (pending → sent) и принятие редких дублей. Поэтому я и выношу SMS из задачи, которая двигает деньги, в отдельную задачу: ретрай одной не должен перезапускать другую.
Передавайте id, а не объект
Вместо credit_cashback.delay(order) — credit_cashback.delay(order.pk). Почему:
- JSON (стандартный сериализатор Celery) не умеет сериализовать модель. А включать pickle плохо с точки зрения безопасности: он открывает путь к выполнению кода через сообщение.
- Задача выполнится через секунды, а с ретраями — через минуты. За это время строка могла измениться. С id воркер читает из базы текущее состояние.
- Сообщение маленькое, и его легко прочитать в брокере.
По той же причине осторожнее с передачей значений вроде суммы: пусть задача сама возьмёт её из базы. Иначе устаревшее значение будет «вечно» жить в ретраях.
transaction.on_commit: отправлять задачу после коммита
Самая коварная ошибка наивной версии — вызов delay() внутри atomic(). Сообщение уходит в Redis сразу, а коммит происходит позже. Быстрый воркер увидит заказ ещё не в статусе PAID, а при откате транзакции задача отработает для платежа, которого не существует.
# orders/views.py — the fixed call site
from functools import partial
from django.db import transaction
from django.http import JsonResponse
from .models import Order
from .tasks import credit_cashback
def pay_order(request, order_id):
with transaction.atomic():
order = Order.objects.select_for_update().get(pk=order_id, user=request.user)
order.status = Order.Status.PAID
order.save(update_fields=["status"])
transaction.on_commit(partial(credit_cashback.delay, order.pk))
# Celery 5.4+ with Django: credit_cashback.delay_on_commit(order.pk)
return JsonResponse({"ok": True})
transaction.on_commit() вызывает колбэк после успешного коммита внешней транзакции, а при откате не вызывает вовсе. Начиная с Celery 5.4, при работе с Django базовым классом задач становится DjangoTask, и у него есть методы delay_on_commit() и apply_async_on_commit(), которые делают ровно это.
В тестах TestCase оборачивает каждый тест в транзакцию и никогда её не коммитит, поэтому on_commit-колбэки сами не срабатывают. Запускайте их через captureOnCommitCallbacks:
# orders/tests.py
from unittest import mock
from django.test import TestCase
from .models import Order
class PayOrderTests(TestCase):
def test_task_is_sent_after_commit(self):
order = Order.objects.create(...) # fixture of your choice
with mock.patch("orders.views.credit_cashback.delay") as delay:
with self.captureOnCommitCallbacks(execute=True):
self.client.post(f"/orders/{order.pk}/pay/")
delay.assert_called_once_with(order.pk)
Но и on_commit не даёт полной гарантии. Коммит прошёл, а колбэк не смог подключиться к Redis или процесс умер ровно в эту секунду — задача потеряна. Для денег простое средство — периодическая задача-«дворник» (через Celery beat), которая находит недоделанное и отправляет повторно. Это безопасно, потому что задача идемпотентна:
# orders/tasks.py — a safety net for messages lost between commit and broker
from datetime import timedelta
from celery import shared_task
from django.utils import timezone
from .models import Order
@shared_task
def resend_missing_cashback() -> int:
cutoff = timezone.now() - timedelta(minutes=10)
ids = list(
Order.objects.filter(
status=Order.Status.PAID,
cashback_credited=False,
paid_at__lt=cutoff,
).values_list("pk", flat=True)[:500]
)
for pk in ids:
credit_cashback.delay(pk) # safe: the task is idempotent
return len(ids)
В системах побольше обобщённая версия этого — паттерн outbox: сообщение пишется в таблицу в той же транзакции, что и бизнес-данные, а отдельный процесс доставляет его в брокер.
Ловушка visibility timeout
В Redis нет механизма, как в RabbitMQ, «соединение оборвалось — верни неподтверждённые сообщения». Поэтому Redis-транспорт Celery хранит выданные сообщения в отдельной структуре unacked и возвращает сообщение в очередь, если ack не пришёл в течение visibility timeout (по умолчанию 1 час). Это спасает сообщение при падении воркера, но у этого есть два неожиданных последствия:
- Длинные задачи. Если задача с
acks_lateработает дольше visibility timeout, сообщение получит и другой воркер — задача выполнится дважды, хотя никто не падал. - countdown и ETA. Сообщения с
apply_async(countdown=...),eta=...иself.retry(countdown=...)воркер забирает сразу и держит в памяти до наступления срока. Если задержка больше visibility timeout, сообщение доставляется повторно, и каждый новый воркер тоже начинает его ждать — в итоге одна задача выполняется в нескольких копиях.
Решение: ставьте visibility_timeout больше самой длинной задачи и самого большого countdown (в настройках выше — 6 часов). Для работы «через сутки» используйте не countdown, а колонку run_at в базе и периодическую задачу. В ретраях задержку ограничивает retry_backoff_max, и это тоже важно.
В RabbitMQ visibility timeout нет, но есть похожее ограничение — consumer_timeout, срок ожидания ack. Если он превышен, брокер закрывает канал, и сообщение доставляется заново. Для длинных задач проверьте и его.
Состояние можно посмотреть в Redis:
# Messages taken by workers but not yet acked (Redis transport)
redis-cli HLEN unacked
# Messages waiting in the default queue
redis-cli LLEN celery
Грабли в продакшене
- Не хватает времени на graceful shutdown. После SIGTERM Celery перестаёт брать новые задачи и пытается доделать текущие. В Kubernetes
terminationGracePeriodSecondsпо умолчанию 30 секунд; если задача дольше, под получит SIGKILL. Увеличьте этот срок сверх самой длинной задачи или режьте задачи на короткие куски. - «Ядовитое» сообщение. С
reject_on_worker_lost=Trueзадача, которая каждый раз убивает воркер по OOM, будет возвращаться в очередь бесконечно. Следите за памятью и ставьтеtime_limit. - Полусделанная работа при ретрае. Если задача сначала пишет в базу, потом вызывает API и падает, ретрай повторит и первую часть. Либо делайте всё в одной транзакции, либо делайте каждый шаг идемпотентным отдельно.
- Тесты в eager-режиме. С
task_always_eager=Trueтесты обходят брокер, сериализацию и ack. Код, передающий объект в аргументе, пройдёт тест и упадёт в продакшене. - Ожидание результата. Не вызывайте
result.get()внутри другой задачи: воркеры начинают ждать друг друга, вплоть до дедлока.
Чеклист
- Задачи, меняющие деньги или состояние:
acks_late=Trueиtask_reject_on_worker_lost=True. - Каждая задача устойчива к повтору: условный
UPDATE,UniqueConstraintили поле статуса. - Ключ идемпотентности для внешних API и всегда
timeout. autoretry_forтолько для временных ошибок, сretry_backoff,retry_jitterи явнымmax_retries.- В аргументах только id и простые значения, JSON-сериализатор.
delay()только черезtransaction.on_commit()илиdelay_on_commit().- Периодическая задача-проверка для потерянных сообщений.
visibility_timeout> самой длинной задачи и самого большого countdown.- Срок shutdown > самой длинной задачи.
Итог
Celery не даёт «ровно один раз»: по умолчанию задача может потеряться, а с acks_late — повториться. В системе, где ходят деньги, правильный выбор — доставка at-least-once плюс идемпотентная задача. Отправляйте задачу после коммита, передавайте id, пусть дубли отсекает сама база, и помните про visibility timeout — тогда SIGKILL во время деплоя не превратится в двойной кешбэк на счету клиента.
// комментарии
Загружаем комментарии...