
به اشتراک بگذارید

به اشتراک بگذارید
صفحه Design در مستندات Gunicorn برای تعداد Worker فرمول (۲ × تعداد هسته) + ۱ را پیشنهاد میکند. در استقرار FastAPI با Workerهای Uvicorn این عدد فقط حدس اول است. هر Worker یک نسخه کامل از برنامه را در رم نگه میدارد. پشته این راهنما Gunicorn با بسته uvicorn-worker است که systemd روی سوکت UNIX بالا میآورد و Nginx با SSL جلوی آن مینشیند.
| هسته | خروجی فرمول | سقفی که رم میگذارد | نقطه شروع (nproc) |
|---|---|---|---|
| ۱ | ۳ | با free -m بسنجید | ۱ |
| ۲ | ۵ | با free -m بسنجید | ۲ |
| ۴ | ۹ | با free -m بسنجید | ۴ |
| ۸ | ۱۷ | با free -m بسنجید | ۸ |
💡 هر Worker یک نسخه کامل برنامه در رم
منظور از Worker پردازهای مستقل است که درخواستها را جواب میدهد.
✅ با یک Worker برای هر هسته شروع کنید؛ سقف، کوچکترِ خروجی فرمول و حد رم است.
✅ ورودیها: nproc، ستون available در free -m و RSS یک Worker.
عددی که اینجا حساب میکنید از ماشین خودتان میآید و جلوی گزینه --workers در فایل سرویس قرار میگیرد. اگر کد را با اتصال VS Code Remote SSH به سرور روی همان ماشین ویرایش میکنید، دستورهای این صفحه را در ترمینال همان ویرایشگر اجرا کنید.
📌 از فرمول تا فایل سرویس
◀️ فرمول (۲ × هسته) + ۱ و معنای آن
◀️ تعداد Worker را روی سرور خودتان بسنجید
◀️ سرویس systemd و ساختار پروژه برای Production
◀️ پشت Nginx با SSL و عوامل جابهجایی عدد

(۲ × هسته) + ۱ فرمولی است که صفحه Design مستندات Gunicorn آورده و گفته با آن شروع کنید و زیر بار واقعی تنظیمش کنید. Gunicorn آن را بدون تفکیک نوع Worker میدهد، اما برای استقرار FastAPI نوع Worker مهم است، چون Worker ناهمگام Uvicorn چند درخواست را همزمان در یک پردازه جلو میبرد.
صفحه Design میگوید Gunicorn معمولاً با ۴ تا ۱۲ Worker ترافیک سنگین را جواب میدهد و Worker زیادی میتواند توان عملیاتی را پایین بیاورد. صفحه تنظیمات برای گزینه workers بازه ۲ تا ۴ برابر هسته را مینویسد. راهنمای ASGI همین پروژه هم مثال --workers $(nproc) را آورده است، یعنی یک Worker برای هر هسته. سه صفحه از یک پروژه و سه عدد؛ پس باید اندازه گرفت.
روی سرور ۸ هستهای فرمول ۱۷ میدهد، بیرون از بازه معمول همان صفحه. صفحه Server Workers در مستندات FastAPI اصلاً سراغ Gunicorn نمیرود و برای چند پردازه fastapi run --workers 4 یا uvicorn main:app --workers 4 را نشان میدهد.
در نانوایی سنگکی، شاطری که تا پخت یک نان چانه بعدی را پهن میکند، بی شاطر دوم نان بیشتری میدهد؛ Worker ناهمگام هم در انتظار یک درخواست سراغ بعدی میرود. در آزمایش ما روی ماشینی با ۲ هسته و ۸ گیگابایت رم (FastAPI 0.162.0 و Gunicorn 26.2.0)، یک Worker به ۲۰ درخواست همزمان با await asyncio.sleep(1) در حدود ۱ ثانیه جواب داد. عددهای اندازهگیریشده بعدی هم از همین ماشین است.
⚠️ کد مسدودکننده داخل async def (اندازهگیری ما)
با time.sleep(1) داخل async def همین ۲۰ درخواست حدود ۲۰ ثانیه طول کشید، چون حلقه رویداد Worker قفل ماند. چهار Worker در سه بار تکرار زمان را فقط به ۱۰ تا ۱۹ ثانیه رساند. طبق مستندات FastAPI تابع معمولی def در threadpool جدا اجرا میشود و همان کد با def حدود ۱ ثانیه تمام شد.
۴۷ مگابایت رم هر Worker در برنامه آزمایشی کوچک ما بود و سقف تعداد Worker از تقسیم رم در دسترس بر همین عدد به دست میآید. صفحه Deployment Concepts در مستندات FastAPI میگوید مدلی ۱ گیگابایتی با ۴ Worker دستکم ۴ گیگابایت رم میگیرد، چون پردازهها معمولاً حافظه مشترک ندارند. در استقرار FastAPI روی سرور کوچک، همین ضرب عدد نهایی را تعیین میکند.
nproc
free -m
sudo -u www-data curl --unix-socket /run/gunicorn.sock http://localhost/
ps -o pid,ppid,rss,cmd --ppid "$(systemctl show --value -p MainPID gunicorn.service)"
دستور nproc واحدهای پردازشی در دسترس را میشمارد و ستون available در free -m حافظهای را تخمین میزند که برنامه تازه بدون swap میگیرد. سرویس فعالشده با سوکت systemd تا اولین درخواست بالا نمیآید، برای همین دستور سوم یک درخواست میفرستد. ستون RSS در ps حافظه فیزیکی هر Worker به کیبیبایت است و بعد از گرم شدن برنامه معنا دارد.
برای رم کل سرور، راهنمای انتخاب رم سرور مجازی را ببینید.
| ورودی | محاسبه | نتیجه |
|---|---|---|
| نقطه شروع: خروجی nproc | یک Worker برای هر هسته | دو Worker |
| سقف فرمول | (۲ × ۲) + ۱ | پنج Worker |
| حد رم: available برابر ۷۵۸۵ مگابایت، هدف ۷۰ درصد | (۷۵۸۵ × ۰٫۷) ÷ ۴۷ | حدود ۱۱۲ Worker |
| عدد فایل سرویس | شروع ۲، سقف کوچکترِ ۵ و ۱۱۲ | دو، تا پنج با تست بار |
ضریب ۷۰ درصد انتخاب ماست، داخل بازه ۵۰ تا ۹۰ درصدی که FastAPI بهعنوان نمونهای اختیاری برای مصرف منابع آورده. برنامهای که مدل یا کش بزرگ بارگذاری میکند به مثال ۱ گیگابایتی FastAPI نزدیکتر است و آنجا حد رم زودتر از فرمول میرسد.

۵ ثانیه در برابر ۳۰ ثانیه: فایل سرویس نمونه در مستندات استقرار Gunicorn مقدار TimeoutStopSec=5 دارد، اما graceful_timeout پیشفرض خود Gunicorn ۳۰ ثانیه است. با کپی همان نمونه، systemd پنج ثانیه بعد از فرمان توقف پردازه را با SIGKILL میبندد و درخواستهای نیمهکاره در استقرار FastAPI فرصت تمام شدن پیدا نمیکنند.
sudo apt install python3-venv
sudo mkdir -p /srv/fastapi-app
sudo chown someuser:someuser /srv/fastapi-app
cd /srv/fastapi-app
python3 -m venv .venv
.venv/bin/pip install "fastapi[standard]" gunicorn uvicorn-worker
دستور apt مخصوص Debian و Ubuntu است و بسته python3-venv ماژول venv را نصب میکند. به جای someuser کاربری را بگذارید که صاحب پروژه است و main.py را در همین پوشه قرار دهید.
# /etc/systemd/system/gunicorn.socket
[Unit]
Description=gunicorn socket
[Socket]
ListenStream=/run/gunicorn.sock
SocketUser=www-data
SocketGroup=www-data
SocketMode=0660
[Install]
WantedBy=sockets.target
# /etc/systemd/system/gunicorn.service
[Unit]
Description=gunicorn daemon for FastAPI
Requires=gunicorn.socket
After=network.target
[Service]
Type=notify
NotifyAccess=main
User=someuser
Group=someuser
WorkingDirectory=/srv/fastapi-app
ExecStart=/srv/fastapi-app/.venv/bin/gunicorn main:app -k uvicorn_worker.UvicornWorker --workers 2 --forwarded-allow-ips=*
ExecReload=/bin/kill -s HUP $MAINPID
KillMode=mixed
TimeoutStopSec=35
PrivateTmp=true
[Install]
WantedBy=multi-user.target
/etc/systemd/system بسازید و someuser را با همان کاربر صاحب پروژه عوض کنید.sudo systemctl daemon-reload بارگذاری و سوکت را با sudo systemctl enable --now gunicorn.socket فعال کنید.daemon-reload و بعد sudo systemctl restart gunicorn.service را اجرا کنید.ساختار هر دو فایل از نمونه رسمی Gunicorn است؛ مسیر، کلاس Worker، عدد ۲ جدول قبل، --forwarded-allow-ips و عدد پیشنهادی ۳۵ برای TimeoutStopSec تغییر ما هستند. به گفته مستندات Gunicorn، کاربر Nginx در Debian بهطور پیشفرض www-data است؛ در توزیع دیگر SocketUser و SocketGroup را با کاربر Nginx عوض کنید. این ترکیب را با systemd-socket-activate امتحان کردیم و دو Worker پاسخ دادند.
🔸 سه راه اجرای Worker و فرقشان
◀️ روش -k uvicorn_worker.UvicornWorker: مدیر پردازه Gunicorn و پردازش با Uvicorn؛ ماژول قدیمی uvicorn.workers طبق مستندات Uvicorn منسوخ است.
◀️ روش fastapi run --workers N: مدیر پردازه Uvicorn با spawn به جای pre-fork؛ حدود ۶۴ مگابایت برای هر Worker در اندازهگیری ما.
◀️ گزینه --worker-class asgi: Worker داخلی Gunicorn، بتا در 24.0.0 و پایدار از 25.1.0. یادداشتهای انتشار سری 26 هنوز برایش اصلاحیه دارند و ما فعلاً uvicorn-worker را نگه داشتیم.

۶۰ ثانیه پیشفرض proxy_read_timeout در Nginx است؛ اگر سرور پشتی در این فاصله چیزی نفرستد، Nginx اتصال را میبندد و با Nginx 1.24 روی همان ماشین، کاربر خطای 504 Gateway Timeout گرفت. در استقرار FastAPI این 504ها را زیاد به حساب کمبود Worker میگذارند، اما اغلب یک مسیر کند پشت آنهاست.
upstream fastapi_app {
server unix:/run/gunicorn.sock fail_timeout=0;
}
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/cert.key;
location / {
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_redirect off;
proxy_pass http://fastapi_app;
}
}
sudo nginx -t && sudo nginx -s reload
هدرها از نمونه استقرار Gunicorn آمده و دو خط ssl_certificate فایل گواهی و کلید PEM را میخواهند. گرفتن گواهی و ریدایرکت پورت 80 به ابزار ACME شما بستگی دارد و اینجا نیامده؛ مستندات استقرار Uvicorn گواهی Let’s Encrypt و اتصال Nginx از راه سوکت UNIX را توصیه میکند. خط آخر پیکربندی را بررسی و بارگذاری میکند.
گزینه --forwarded-allow-ips=* در فایل سرویس لازم است. یادداشت Gunicorn که این گزینه را روی سوکت UNIX بیاثر میداند برای uvicorn-worker صدق نمیکند، چون Uvicorn کلاینت بیآدرس سوکت را معتبر نمیشمارد. بدون آن، روی همان ماشین آزمایشی، با هدر X-Forwarded-Proto: https ریدایرکت 307 به نشانی http رفت. مقدار * اینجا امن است، چون سوکت با SocketMode=0660 فقط در دسترس www-data یعنی Nginx است؛ روی bind از نوع TCP به کارش نبرید.
🔸 مهلتهایی که با کمبود Worker اشتباه گرفته میشوند
◀️ گزینه timeout در Gunicorn پیشفرض ۳۰ ثانیه دارد و برای Worker غیرهمگام فقط یعنی پردازه هنوز با مدیر در تماس است. مسیری async با time.sleep(15) و --timeout 5 پیغام WORKER TIMEOUT داد، Worker عوض شد و کلاینت پاسخی نگرفت.
هر Worker اتصالهای پایگاه داده خودش را باز میکند، پس با دو برابر کردن Worker سقف اتصال پایگاه داده را هم دوباره حساب کنید.
بعد از اولین تست بار، معمولاً این عددها دوباره زیر سؤال میروند:
فقط حدسی اولیه برای سقف است؛ خود Gunicorn یک Worker برای هر هسته را هم آورده و عدد درست را تست بار و رم سرور شما میدهد.
فرمول ۳ میدهد و راهنمای ASGI یک. Worker دوم بیشتر برای جدا ماندن خرابیهاست، چون به گفته Gunicorn، Workerها خرابیها را از هم جدا میکنند.
با Uvicorn 0.54.0 هنوز اجرا میشود، اما مستندات Uvicorn آن را منسوخ میداند؛ uvicorn_worker.UvicornWorker را به -k بدهید.
بله. مستندات FastAPI دستور fastapi run –workers را نشان میدهد و مدیر پردازه Uvicorn Worker ازکارافتاده را دوباره بالا میآورد.
بله، موقت: systemctl kill -s TTIN gunicorn.service یک Worker اضافه میکند و TTOU یکی کم. برای ماندگاری، فایل سرویس را عوض کنید و daemon-reload و restart بزنید.
اغلب کد مسدودکننده داخل async def یا گلوگاه پایگاه داده علت است؛ Worker بیشتر هیچکدام را درمان نمیکند.
از ستون RSS در ps، به کیبیبایت؛ مستندات FastAPI ابزار htop را هم پیشنهاد میکند.
جمعبندی؛ عدد Worker را خودتان حساب کنید. فرمول (۲ × هسته) + ۱ یکی از سه توصیه مستندات Gunicorn است و هیچکدام روی برنامه شما سنجیده نشدهاند. در استقرار FastAPI با Worker ناهمگام، همزمانی داخل هر پردازه حل میشود و هر Worker اضافه یک نسخه دیگر از برنامه در رم است. پس از یک Worker برای هر هسته شروع کنید و سقف را کوچکترِ خروجی فرمول و حد رم بگیرید. در فایل سرویس، uvicorn-worker را به جای ماژول منسوخ بگذارید، --forwarded-allow-ips=* را پشت سوکت UNIX فراموش نکنید و TimeoutStopSec را کمی بیشتر از graceful_timeout نگه دارید تا خاموشی آرام نیمهکاره نماند.
🚀 ویرایش فایلهای سرویس روی خود سرور
ویرایش فایل سرویس و پیکربندی Nginx با ویرایشگری که مستقیم به سرور وصل است راحتتر است.
سرور شما چند هسته دارد و روی چند Worker ماندید؟ جواب را با RSS هر Worker در دیدگاهها بگذارید تا خط محاسبه با سرورهای دیگر هم سنجیده شود.