Все заметки
Программирование

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})

На первый взгляд всё нормально. На деле здесь четыре проблемы:

  1. Задача отправляется до коммита. Воркер может забрать сообщение раньше, чем транзакция закоммитится, и увидеть в базе старое состояние заказа. А если транзакция откатится, кешбэк начислится за неоплаченный заказ.
  2. В аргумент передан целый объект. JSON-сериализатор вообще не умеет сериализовать модель, а с pickle воркер работает с копией, устаревшей на секунды или минуты.
  3. balance += ... — это read-modify-write. Две параллельные задачи потеряют запись одной из них.
  4. Задача не идемпотентна. При повторе деньги добавятся ещё раз, и 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 час). Это спасает сообщение при падении воркера, но у этого есть два неожиданных последствия:

  1. Длинные задачи. Если задача с acks_late работает дольше visibility timeout, сообщение получит и другой воркер — задача выполнится дважды, хотя никто не падал.
  2. 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 во время деплоя не превратится в двойной кешбэк на счету клиента.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯