اگر کاربر فرم ثبت‌نام را می‌زند و سایت ۱۰ ثانیه روی «ارسال ایمیل تأیید» قفل می‌کند، یا پردازش فایل اکسل هزار ردیفی درخواست را Timeout می‌کند، مشکل شما نبود Celery است. در این آموزش Celery در پایتون یاد می‌گیرید چطور کارهای زمان‌بر را به صف پس‌زمینه بسپارید تا وب‌اپلیکیشن (مثلاً Django یا FastAPI) فوراً پاسخ بدهد و Workerها در پس‌زمینه با Redis کار را تمام کنند.

آموزش Celery در پایتون چیست و چرا باید از آن استفاده کنیم؟

Celery یک صف وظیفه توزیع‌شده برای پایتون است که تسک‌های سنگین مثل ارسال ایمیل، تولید PDF یا پردازش تصویر را از درخواست HTTP جدا می‌کند و با یک بروکر پیام مثل Redis یا RabbitMQ به Workerها می‌سپارد. نتیجه: پاسخ‌دهی آنی سایت، امکان زمان‌بندی (Periodic Tasks) و اجرای موازی. در ادامه، نصب، اولین تسک، اجرای Worker و Beat و مانیتورینگ را قدم‌به‌قدم می‌بینید.

فهرست مطالب

Celery چیست و چه مشکلی را حل می‌کند؟
پیش‌نیازها و نصب Celery با Redis و RabbitMQ
اولین پروژه Celery: ساخت و فراخوانی تسک ساده
اجرای Worker، Beat و مانیتورینگ با Flower
مقایسه Celery با جایگزین‌ها: کدام را انتخاب کنیم؟
اشتباهات رایج هنگام کار با Celery
سوالات متداول
جمع‌بندی

Celery چیست و چه مشکلی را حل می‌کند؟

Celery مثل یک آشپزخانه صنعتی برای کد شماست؛ به‌جای اینکه گارسون (وب‌سرور) خودش غذا را بپزد و مشتری معطل بماند، سفارش را روی نوار (Broker) می‌گذارد و آشپزها (Workerها) پشت صحنه کار را انجام می‌دهند. وقتی کاربر روی «ثبت سفارش» یا «آپلود ویدیو» کلیک می‌کند، درخواست شما فقط یک پیام سبک در Redis قرار می‌دهد و بلافاصله 202 Accepted برمی‌گرداند.

کاربردهای واقعی که هر روز در پروژه‌های ایرانی می‌بینید:

ارسال ایمیل و پیامک انبوه: بدون Celery هر ایمیل ۱ تا ۲ ثانیه طول می‌کشد و ۱۰۰۰ ایمیل یعنی مرگ سرور.
پردازش فایل و تصویر: تبدیل تصویر محصول، واترمارک، فشرده‌سازی ویدیو.
گزارش‌گیری و ETL: تولید اکسل سنگین، همگام‌سازی با API بانک یا پنل پیامک.
زمان‌بندی: اجرای تسک هر شب ساعت ۲ بامداد مثل پاک‌سازی سبدهای رها شده یا بکاپ دیتابیس.

تفاوت کلیدی Celery با threading یا asyncio این است که حتی اگر وب‌سرور ری‌استارت شد، تسک از بین نمی‌رود؛ چون در بروکر ذخیره شده و Worker دوباره آن را برمی‌دارد. برای تسک‌های درون یک فرآیند سبک، دموی تعاملی با Gradio یا AsyncIO کافی است، اما برای کارهای طولانی و نیاز به مقیاس‌پذیری، Celery انتخاب حرفه‌ای است.

پیش‌نیازها و نصب Celery با Redis و RabbitMQ

برای شروع فقط سه چیز لازم دارید: پایتون 3.9 به بالا، یک بروکر پیام و خود Celery. بیشتر تیم‌های ایرانی Redis را انتخاب می‌کنند چون هم ساده است و هم معمولاً برای کش قبلاً نصب شده.

پیش‌نیازها

پایتون 3.10 یا 3.11 (توصیه شده)، pip و venv
Redis 6+ (یا RabbitMQ 3.9+) روی لوکال یا سرور
یک پروژه پایتون؛ اگر هنوز محیط را استاندارد نکرده‌اید، آموزش Poetry برای مدیریت وابستگی و آموزش انتشار پکیج در PyPI به نظم پروژه کمک می‌کند.

نصب

python -m venv venv
source venv/bin/activate  # ویندوز: venv\Scripts\activate
pip install celery redis

# اگر RabbitMQ می‌خواهید:
pip install celery[redis,librabbitmq]

برای تست سریع Redis را با Docker بالا بیاورید:

docker run -d --name redis-celery -p 6379:6379 redis:7-alpine
redis-cli ping  # باید PONG برگرداند

Redis یا RabbitMQ؛ کدام بروکر؟

Redis: نصب یک‌خطی، عالی برای شروع، مناسب وقتی دیتای تسک مهم اما نه حیاتی است و می‌توانید از دست‌رفتن تسک در خاموشی ناگهانی را تحمل کنید. RabbitMQ: قابل‌اعتمادتر، پیام‌ها را روی دیسک می‌نویسد، برای تسک مالی/سفارش که نباید گم شود بهتر است. در این آموزش با Redis جلو می‌رویم؛ تغییر به RabbitMQ فقط تغییر یک URL است.

اولین پروژه Celery: ساخت و فراخوانی تسک ساده

یک پوشه به نام celery_demo بسازید و دو فایل ایجاد کنید. هدف: یک تسک که ایمیل جعلی می‌فرستد و ۵ ثانیه طول می‌کشد تا ببینید چطور درخواست قفل نمی‌شود.

فایل 1: celery_app.py

from celery import Celery

app = Celery(
    "celery_demo",
    broker="redis://localhost:6379/0",
    backend="redis://localhost:6379/1",  # برای ذخیره نتیجه
)

app.conf.update(
    task_serializer="json",
    result_serializer="json",
    accept_content=["json"],
    timezone="Asia/Tehran",
    enable_utc=True,
    task_acks_late=True,  # تسک فقط بعد از موفقیت تایید شود
    worker_prefetch_multiplier=1,
)

@app.task(bind=True, max_retries=3, default_retry_delay=10)
def send_welcome_email(self, email):
    try:
        print(f"ارسال ایمیل به {email} ...")
        import time; time.sleep(5)  # شبیه‌سازی کار سنگین
        return f"ایمیل {email} ارسال شد"
    except Exception as exc:
        raise self.retry(exc=exc)

فایل 2: tasks.py یا فراخوانی از FastAPI/Django

from celery_app import send_welcome_email

# اجرای معمولی (سینک) - برای تست فقط:
# send_welcome_email("test@example.com")

# اجرای غیرهمزمان - همین را در ویو صدا بزنید:
result = send_welcome_email.delay("user@example.com")
print(result.id)  # شناسه تسک برای پیگیری

# بررسی نتیجه بعداً:
print(result.status)  # PENDING, STARTED, SUCCESS, FAILURE
print(result.get(timeout=10))

نکته مهم: .delay() و .apply_async() تسک را به صف می‌فرستند، نه اینکه همان‌جا اجرا کنند. در ویو FastAPI/Django شما فقط همین یک خط را صدا می‌زنید و فوراً Response برمی‌گردانید. برای تسک‌های زمان‌بندی شده از apply_async(countdown=60, eta=...) یا retry استفاده کنید.

ساختار پیشنهادی پروژه برای تیم:

celery_demo/
  celery_app.py
  tasks/
    emails.py
    reports.py
  config.py

هر ماژول تسک‌ها را جدا نگه دارید تا Worker سبک بماند و فقط ماژول لازم را لود کند.

اجرای Worker، Beat و مانیتورینگ با Flower

کد به تنهایی اجرا نمی‌شود؛ باید Worker را روشن کنید.

۱. اجرای Worker

celery -A celery_app worker --loglevel=info --concurrency=4 --pool=prefork

روی ویندوز به‌جای prefork از --pool=solo استفاده کنید. هر Worker یک فرآیند جدا است؛ با --concurrency=4 چهار تسک همزمان اجرا می‌شود.

۲. اجرای Beat برای تسک‌های دوره‌ای

برای «هر روز ۸ صبح گزارش بفرست» به Beat نیاز دارید:

from celery.schedules import crontab

app.conf.beat_schedule = {
    "daily-report": {
        "task": "celery_app.send_welcome_email",
        "schedule": crontab(hour=8, minute=0),
        "args": ("report@example.com",)
    },
}
# ترمینال دوم:
celery -A celery_app beat --loglevel=info

برای پایداری در پروداکشن، Beat را با celery beat --pidfile=... و با سوپروایزر یا systemd اجرا کنید یا از django-celery-beat برای مدیریت از دیتابیس استفاده کنید.

۳. مانیتورینگ با Flower

pip install flower
celery -A celery_app flower --port=5555
# مرورگر: http://localhost:5555

Flower به شما صف‌ها، تسک‌های موفق/ناموفق، زمان اجرا و Workerهای فعال را زنده نشان می‌دهد. آلارم قرمز یعنی تسک‌ها در صف مانده‌اند و باید concurrency را زیاد یا Worker جدید اضافه کنید.

در پروداکشن حتماً این موارد را رعایت کنید: result_expires را روی ۳۶۰۰ ثانیه بگذارید تا Redis پر نشود، تسک‌ها را idempotent بنویسید (اگر دو بار اجرا شد مشکلی پیش نیاید)، و برای تسک‌های حساس از acks_late=True و retry استفاده کنید.

مقایسه Celery با جایگزین‌ها: کدام را انتخاب کنیم؟

انتخاب ابزار به جنس تسک بستگی دارد. اگر تسک شما ۵۰ میلی‌ثانیه طول می‌کشد، Celery شلیک به مگس با توپ است.

ابزار	بهترین برای	بروکر	مزیت اصلی	محدودیت
Celery	تسک سنگین، زمان‌بندی، مقیاس بزرگ	Redis / RabbitMQ	پایدار، retry، Beat، Flower	پیچیدگی اولیه بیشتر
RQ (Redis Queue)	پروژه کوچک، شروع سریع	فقط Redis	ساده، کد کم	بدون Beat داخلی، مقیاس محدود
Dramatiq	کارایی بالا با RabbitMQ	RabbitMQ / Redis	سریع، API تمیز	اکوسیستم کوچک‌تر
APScheduler	زمان‌بندی درون‌برنامه‌ای	بدون بروکر	سبک، بدون سرویس جدا	اگر اپ خاموش شود تسک می‌پرد
asyncio / FastAPI BackgroundTasks	تسک سبک زیر ۱ ثانیه	ندارد	بدون وابستگی	تسک با ری‌استارت از بین می‌رود

قانون سرانگشتی: اگر تسک بیشتر از ۲ ثانیه است، باید بعد از دیپلوی هم بماند، یا نیاز به retry و زمان‌بندی دارید → Celery. اگر فقط یک اسکریپت کوتاه می‌خواهید → RQ یا BackgroundTasks کافی است.

اشتباهات رایج هنگام کار با Celery

اجرای تسک بدون Worker روشن: پیام در Redis می‌ماند و فکر می‌کنید کد باگ دارد. همیشه اول celery worker --loglevel=info را چک کنید.
ارسال آبجکت بزرگ در آرگومان تسک: به‌جای پاس دادن DataFrame یا فایل ۲۰ مگابایتی، فقط id یا مسیر فایل را بفرستید و داخل Worker از دیتابیس/استوریج بخوانید.
فراموشی idempotency: تسک ایمیل را طوری بنویسید که اگر دو بار اجرا شد، دو ایمیل نرود (مثلاً با کلید یکتا در دیتابیس).
تنظیم نادرست timezone و crontab: اختلاف Asia/Tehran و UTC باعث می‌شود Beat یک ساعت زودتر/دیرتر بزند؛ همیشه timezone را ست کنید.
پر شدن Redis از نتایج: اگر backend دارید و result_expires را ست نکنید، بعد از یک ماه Redis چند گیگابایت نتیجه قدیمی نگه می‌دارد.

سوالات متداول

آیا بدون Redis یا RabbitMQ می‌توان Celery اجرا کرد؟

خیر، Celery حتماً به یک بروکر نیاز دارد. برای تست سریع می‌توانید از memory:// استفاده کنید اما فقط در یک فرآیند کار می‌کند و با بستن برنامه همه تسک‌ها پاک می‌شود؛ برای لوکال همان Redis داکری بهترین گزینه است.

تفاوت delay و apply_async چیست؟

delay(args) میانبر ساده است، apply_async(args, countdown, eta, queue, priority) کنترل کامل می‌دهد؛ مثلاً send_welcome_email.apply_async(args=[email], countdown=60, queue="emails") تسک را ۶۰ ثانیه بعد و در صف مخصوص ایمیل اجرا می‌کند.

Celery با Django و FastAPI چطور کار می‌کند؟

منطق یکسان است؛ در Django فایل celery.py کنار settings.py می‌سازید و app.autodiscover_tasks() را صدا می‌زنید، در FastAPI کافی است همان celery_app را ایمپورت و در endpoint از .delay() استفاده کنید. هر دو فریم‌ورک از Worker مشترک استفاده می‌کنند.

چرا تسک من همیشه در حالت PENDING می‌ماند؟

سه دلیل شایع: Worker خاموش است، نام صف اشتباه است (تسک به queue=emails رفته ولی Worker فقط celery را گوش می‌دهد)، یا بروکر URL اشتباه است. با Flower یا celery -A celery_app inspect active صف‌ها را چک کنید.

چطور تسک را امن و قابل retry کنیم؟

تسک را با bind=True, max_retries=3 تعریف کنید و خطاهای موقت مثل قطعی SMTP یا API را با raise self.retry(exc=exc, countdown=30) دوباره تلاش کنید؛ برای خطای منطقی مثل ایمیل نامعتبر، retry نکنید و مستقیم لاگ کنید.

آیا Celery برای پروژه کوچک هم لازم است؟

اگر سایت شما زیر ۱۰۰ کاربر همزمان دارد و فقط یک ایمیل خوش‌آمدگویی می‌فرستید، RQ یا حتی FastAPI BackgroundTasks ساده‌تر است. وقتی تسک‌ها زیاد، زمان‌بر یا نیازمند زمان‌بندی دقیق شدند، مهاجرت به Celery منطقی می‌شود.

جمع‌بندی

Celery به شما اجازه می‌دهد وب‌اپلیکیشن سبک و سریع بماند و کارهای سنگین را با اطمینان در پس‌زمینه انجام دهید. برای شروع همین امروز:

Redis را با Docker بالا بیاورید و Celery را نصب کنید.
یک تسک ساده مثل send_welcome_email بسازید و با .delay() تست کنید.
Worker و Flower را اجرا کنید و وضعیت تسک را در پنل ببینید.
برای تسک دوره‌ای، Beat و crontab را اضافه کنید.
نتایج را با result_expires مدیریت و تسک‌ها را idempotent بنویسید.

وقتی این چرخه را یک بار بچرخانید، اضافه کردن تسک جدید مثل تولید PDF یا همگام‌سازی API فقط کپی یک تابع است. از همین امروز صف پس‌زمینه را جدی بگیرید تا تجربه کاربری سایت‌تان از «لطفاً صبر کنید» به «انجام شد» تبدیل شود.

آموزش Celery در پایتون؛ اجرای تسک‌های پس‌زمینه با Redis