معرفی کتابخانه Gunicorn در پایتون

Gunicorn (مخفف “Green Unicorn”) یک WSGI HTTP server سبک و محبوب برای اپلیکیشن‌های پایتون است. هدف اصلی آن فراهم کردن یک سرور تولیدی پایدار و ساده برای فریم‌ورک‌هایی مثل Flask و Django است. Gunicorn با معماری پردازشی (prefork) و پشتیبانی از انواع workerها می‌تواند به‌خوبی در محیط‌های چند‌هسته‌ای عملکرد مناسبی ارائه دهد.

چرا از Gunicorn استفاده کنیم؟

• پایدار و بالغ، مناسب برای محیط‌های تولیدی
• پیکربندی ساده و قابل گسترش با پلاگین‌ها
• پشتیبانی از انواع workerها: sync، async، threaded
• سازگاری گسترده با فریم‌ورک‌های WSGI محور
• قابلیت کار با reverse proxy مثل Nginx و مدیریت بار مناسب

نصب و اجرای ابتدایی

pip install gunicorn
# اجرا برای یک اپ Flask به نام app.py که اپ داخل متغیر app تعریف شده
gunicorn app:app
# اجرای با 4 worker و bind به پورت 8000
gunicorn -w 4 -b 0.0.0.0:8000 app:app

در مثال بالا ابتدا Gunicorn نصب می‌شود. سپس با فرمان اول اپ مشخص شده را اجرا می‌کنیم؛ فرمت عمومی “MODULE:VARIABLE” است (مثلاً app:app یعنی فایل app.py و متغیر app داخل آن). گزینه -w تعداد workerها و -b آدرس و پورت bind را مشخص می‌کند.

تنظیمات پیکربندی (فایل پیکربندی)

# gunicorn_config.py
bind = "0.0.0.0:8000"
workers = 3
worker_class = "gthread"
threads = 2
preload_app = True
timeout = 30
accesslog = "/var/log/gunicorn/access.log"
errorlog = "/var/log/gunicorn/error.log"

این فایل پیکربندی گانیکورن به‌صورت Python نوشته شده و هنگام اجرا با گزینه -c به آن ارجاع می‌دهیم: gunicorn -c gunicorn_config.py app:app. preload_app بارگذاری اپلیکیشن قبل از fork را فعال می‌کند که در استفاده از حافظه مشترک با COW مفید است. worker_class انواع مدل اجرایی worker را تعیین می‌کند.

مقایسه انواع Worker

انتخاب worker مناسب بر اساس نوع بار (CPU-bound یا I/O-bound)، کتابخانه‌های استفاده‌شده و نیاز به همزمانی تعیین می‌شود.

بهینه‌سازی تعداد Worker

قاعده‌ی تقریبی: workers = (2 x CPU) + 1 برای workerهای sync. برای workerهای async یا threaded، ممکن است کمتر یا بیشتر بسته به نیاز همزمانی مناسب باشد. آزمایش بار (load testing) بهترین راه تعیین دقیق است.

مثال استقرار با systemd

[Unit]
Description=Gunicorn instance to serve myapp
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/home/ubuntu/myapp
Environment="PATH=/home/ubuntu/myapp/venv/bin"
ExecStart=/home/ubuntu/myapp/venv/bin/gunicorn -c /home/ubuntu/myapp/gunicorn_config.py app:app

[Install]
WantedBy=multi-user.target

این فایل systemd را در /etc/systemd/system/myapp.service قرار دهید. سپس با systemctl daemon-reload و systemctl enable –now myapp سرویس را فعال و اجرا کنید. این روش مدیریت خودکار ریستارت، لاگینگ و دسترسی سرویس را ساده می‌کند.

نمونه پیکربندی Nginx به‌عنوان reverse proxy

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Nginx به‌عنوان reverse proxy جلوی Gunicorn قرار می‌گیرد تا TLS، Static file Serving و مدیریت اتصال را انجام دهد. این معماری در تولید استاندارد است و بار همزمان را بهتر کنترل می‌کند.

لاگ‌ها، مانیتورینگ و سلامت

• از accesslog و errorlog در فایل پیکربندی استفاده کنید.
• برای سلامت، مسیرهای health check ساده در اپ ایجاد و از load balancer یا Nginx برای چک استفاده کنید.
• ابزارهایی مثل prometheus + exporter یا Sentry برای مانیتورینگ و خطایابی مناسبند.

نکات امنیتی و بهترین شیوه‌ها

• Gunicorn را پشت یک reverse proxy (Nginx) قرار دهید تا TLS و محدودیت نرخ (rate limiting) مدیریت شود.
• اجازه ندهید Gunicorn به‌طور مستقیم به اینترنت وصل شود؛ فقط از localhost یا socket استفاده کنید.
• در محیط production از یک کاربر غیر ریشه (مثلاً www-data) استفاده کنید.
• timeout و max-requests را تنظیم کنید تا Workerهای حافظه‌نشده بازنشانی شوند:

# مثال: افزایش ایمنی با تنظیم max-requests
max_requests = 1000
max_requests_jitter = 100

این گزینه‌ها باعث می‌شوند هر Worker پس از تعداد مشخصی درخواست ری‌استارت شود تا لوک‌های حافظه‌ای یا افزایش تدریجی مصرف حافظه کنترل شود.

خطاها و رفع مشکلات متداول

• “Address already in use”: بررسی کنید پورت آزاد است یا از socket استفاده کنید.
• مصرف بالای حافظه: از preload_app=False یا تنظیم max_requests بهره ببرید؛ بررسی memory leaks در اپ لازم است.
• عدم پاسخ‌دهی: بررسی timeout، نوع worker و وابستگی‌های مسدود‌کننده (blocking) در کد.

نمونه کوچک: اجرای یک اپ Flask با Gunicorn و gevent

gunicorn -w 1 -k gevent -b 0.0.0.0:8000 app:app

در این مثال یک worker با worker_class از نوع gevent اجرا می‌شود که مناسب اپ‌هایی با I/O زیاد و تعداد کانکشن همزمان بالا است. اگر اپ شما از کتابخانه‌های blocking استفاده می‌کند، از نسخه‌های سازگار با gevent یا از gthread استفاده کنید.

جمع‌بندی و توصیه‌های حرفه‌ای

Gunicorn یک ابزار قدرتمند و ساده برای استقرار اپلیکیشن‌های WSGI در تولید است. با انتخاب صحیح worker، پیکربندی متناسب با حافظه و CPU و قرار دادن Gunicorn پشت Nginx، می‌توانید عملکرد و پایداری بالایی بدست آورید. همواره تست بار و مانیتورینگ را برای تنظیم دقیق پارامترها در محیط واقعی انجام دهید.

اگر نیاز به نمونه‌های بیشتر، اسکریپت‌های deployment یا تشخیص مشکلات خاص دارید، می‌توانم با اطلاعات دقیق‌تر محیط شما توصیه‌های تخصصی‌تری ارائه دهم.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال