پرش به مطلب اصلی

محیط اجرای Python

▶
ویدیو: استقرار اپلیکیشن Python روی ابرکلیکplaceholder — ویدیو را اینجا جایگزین کنید

ابرکلیک از استقرار و اجرای پروژه‌های Python پشتیبانی می‌کند. بیلدپکِ ابری به‌صورت خودکار نوع پکیج‌منیجر (pip, poetry, pipenv, uv, pdm) را تشخیص داده و برنامه شما را آماده می‌کند.

نسخه‌ها و ابزارهای پشتیبانی‌شده​

  • نسخه‌های فعال پایتون: پایتون از نسخه 3.8 تا آخرین نسخه پایدار 3.13.
  • تشخیص نسخه: نسخه مورد نظر شما از طریق فایل runtime.txt (توصیه‌شده) یا تنظیمات پروژه‌های Poetry خوانده می‌شود. در غیر این صورت، آخرین نسخه پایدار پیش‌فرض اعمال می‌شود.

منطق شناسایی پروژه (Project Detection)​

ابرکلیک پروژه‌های پایتونی را از طریق وجود یکی از فایل‌های زیر شناسایی می‌کند:

  • requirements.txt — مدیریت وابستگی با pip
  • Pipfile / Pipfile.lock — مدیریت وابستگی با Pipenv
  • poetry.lock / pyproject.toml — مدیریت وابستگی با Poetry
  • uv.lock — مدیریت وابستگی با uv
  • pdm.lock — مدیریت وابستگی با pdm

ترتیب اولویت بررسی فایل‌ها در صورت وجود چند گزینه: ۱. وجود Pipfile → استفاده از Pipenv ۲. وجود poetry.lock → استفاده از Poetry ۳. وجود pyproject.toml با بخش [tool.poetry] → استفاده از Poetry ۴. وجود uv.lock → استفاده از uv ۵. وجود pdm.lock → استفاده از pdm ۶. وجود requirements.txt → استفاده از pip (حالت پیش‌فرض)

تعیین دقیق نسخه پایتون​

روش اول — از طریق runtime.txt (ساده‌ترین روش)​

یک فایل متنی ساده با نام runtime.txt در ریشه پروژه خود بسازید و نسخه مورد نظر را به شکل زیر وارد کنید:

python-3.11.8

فرمت معتبر به‌صورت python-X.Y.Z است.

روش دوم — از طریق pyproject.toml (مخصوص پروژه‌های Poetry)​

اگر از ابزار Poetry استفاده می‌کنید، نسخه مورد نظر را در بخش وابستگی‌های داک بفرستید:

[tool.poetry]
name = "my-app"
version = "0.1.0"
description = "Fast Python App on Abrclick"

[tool.poetry.dependencies]
python = "^3.11"

مدیریت پکیج‌ها و نصب وابستگی‌ها​

۱. ابزار pip به همراه requirements.txt​

سیستم برای نصب وابستگی‌ها دستور زیر را اجرا می‌کند:

pip install -r requirements.txt

توصیه فنی: همیشه خروجی وابستگی‌ها را با ابزار قفل‌کننده نسخه تهیه کنید (مثلاً اجرای pip freeze > requirements.txt یا استفاده از pip-compile). این کار از ناسازگاری لایبرری‌ها در سرور نهایی جلوگیری می‌کند.

۲. ابزار Pipenv​

سیستم با اجرای متد زیر برنامه‌ها را سوار می‌کند (نیاز به حضور همزمان Pipfile و Pipfile.lock است):

pipenv install --deploy --ignore-pipfile

۳. ابزار Poetry​

در صورت تشخیص فایل poetry.lock لایسنس زیر اجرا می‌شود:

poetry install --no-interaction --no-dev

وب‌سرورهای پیشنهادی برای اجرای برنامه (Application Server)​

برای آنکه برنامه شما به درخواست‌های ورودی کاربران پاسخ دهد، باید از یک سرور مناسب زمان اجرا (WSGI یا ASGI) استفاده کنید:

۱. ابزار Gunicorn (توصیه‌شده برای وب‌سایت‌های WSGI مانند Flask یا Django)​

ابتدا پکیج را به وابستگی‌ها اضافه کنید:

pip install gunicorn

سپس در ریشه پروژه فایلی با نام Procfile (با P بزرگ و بدون هیچ پسوندی) بسازید و خط اجرای برنامه را وارد کنید:

web: gunicorn -w 4 -b 0.0.0.0:$PORT app:app

۲. ابزار Uvicorn (توصیه‌شده برای ساختارهای مدرن ASGI مانند FastAPI)​

ابتدا پکیج را نصب کنید:

pip install uvicorn

سپس در فایل Procfile دستور لود وب‌سرور را قرار دهید:

web: uvicorn main:app --host 0.0.0.0 --port $PORT

۳. فریم‌ورک جنگو (Django)​

پیشنهاد می‌شود پکیج‌های gunicorn و whitenoise (برای سرویس‌دهی فایل‌های استاتیک جنگو) را نصب کنید:

pip install gunicorn whitenoise

فایل Procfile جنگو را به این صورت تعریف کنید:

web: gunicorn config.wsgi:application --bind 0.0.0.0:$PORT

استفاده از فایل Procfile (Procfile Specification)​

ابرکلیک فرآیند وب را مستقیماً از روی فایل Procfile شما در ریشه پروژه می‌خواند. اگر فایل Procfile را نساخته باشید، بیلدپک تلاش می‌کند یکی از موارد زیر را به‌طور هوشمند حدس بزند:

  • وجود فایل manage.py → پروژه Django تشخیص داده شده و وب‌سرور gunicorn را به‌طور خودکار فراخوانی می‌کند.
  • وجود فایل wsgi.py → پروژه WSGI خام تشخیص داده شده و دستور gunicorn wsgi:app را اجرا می‌کند.
  • وجود فایل app.py با لایبرری اکسپورت‌شده فلاسک → وب‌سرور Flask را راه‌اندازی می‌کند.
توصیه مهم

برای پایداری فرآیند بیلد و جلوگیری از حدس‌های اشتباه، همیشه یک فایل Procfile صریح در ریشه پروژه خود اضافه کنید.

متغیرهای محیطی و پورت (PORT)​

برنامه شما حتماً باید بر روی پورت مشخص‌شده در متغیر محیطی PORT اجرا شود. این مقدار به‌صورت خودکار توسط ابرکلیک تنظیم می‌گردد و سیستم کوبرنتیز ترافیک کاربران را به این پورت هدایت می‌کند.

در برنامه خود برای خواندن متغیرهای محیطی از کتابخانه استاندارد پایتون استفاده کنید:

import os

port = int(os.environ.get("PORT", 8000))

مشاهده لاگ‌ها​

برای بررسی لاگ‌های برنامه Python خود، از دستور زیر استفاده کنید:

abrclick logs <app>

این دستور لاگ‌های زمان اجرا را به‌صورت زنده نمایش می‌دهد. لاگ‌های بیلد نیز در حین اجرای abrclick deploy استریم می‌شوند.

از طریق داشبورد نیز می‌توانید لاگ‌ها را مشاهده کنید: وارد صفحه برنامه شوید و بر روی تب لاگ‌ها کلیک کنید.

نکته فنی

در برنامه‌های سالم Python که از gunicorn استفاده می‌کنند، پیام‌هایی مانند Booting worker with pid: 123 و Listening at: http://0.0.0.0:8000 را خواهید دید. اگر این پیام‌ها ظاهر نشوند، احتمالاً مشکلی در راه‌اندازی برنامه وجود دارد.

برای اطلاعات بیشتر، راهنمای کامل لاگ‌ها را مطالعه کنید.

رفع خطاهای رایج​

اپ بالا نمی‌آید / پورت اشتباه​

علت: برنامه شما بر روی پورت ثابت یا آدرس 127.0.0.1 گوش می‌دهد. پلتفرم ترافیک را به پورت موجود در متغیر محیطی PORT هدایت می‌کند و اگر برنامه روی پورت دیگری اجرا شود یا فقط روی localhost بالا بیاید، درخواست‌ها دریافت نمی‌شوند.

راه‌حل: مطمئن شوید وب‌سرور شما (gunicorn، uvicorn و غیره) بر روی متغیر $PORT و آدرس 0.0.0.0 گوش می‌دهد. در Procfile:

web: gunicorn -w 4 -b 0.0.0.0:$PORT app:app

یا برای uvicorn:

web: uvicorn main:app --host 0.0.0.0 --port $PORT

فایل Procfile پیدا نشد یا نقطه ورود اشتباه​

علت: بیلدپک نمی‌داند چطور برنامه شما را اجرا کند. ممکن است فایل Procfile وجود نداشته باشد یا ماژول WSGI/ASGI به درستی مشخص نشده باشد.

راه‌حل: یک فایل Procfile در ریشه پروژه ایجاد کنید و دستور اجرای برنامه را مشخص کنید:

web: gunicorn config.wsgi:application --bind 0.0.0.0:$PORT

برای FastAPI:

web: uvicorn main:app --host 0.0.0.0 --port $PORT

فایل requirements.txt پیدا نشد / بیلد ناموفق​

علت: وابستگی‌های پروژه شما به درستی مشخص نشده‌اند یا فایل مربوطه (مثلاً requirements.txt) وجود ندارد. در محیط بیلد ابرکلیک، اینترنت عمومی در دسترس نیست و آینه داخلی به‌صورت خودکار استفاده می‌شود.

راه‌حل: مطمئن شوید فایل requirements.txt (برای pip) یا Pipfile.lock (برای Pipenv) یا poetry.lock (برای Poetry) در ریشه پروژه موجود است و آن را کامیت کرده‌اید. سپس دوباره deploy کنید.

OOMKilled / خطای حافظه​

علت: برنامه شما از حافظه بیشتر از محدودیت تعریف‌شده (پیش‌فرض ۵۱۲Mi) استفاده کرده است.

راه‌حل: محدودیت حافظه برنامه را از طریق داشبورد یا تغییر پلن افزایش دهید.

تایم‌اوت worker در gunicorn (درخواست‌های طولانی)​

علت: درخواست‌های طولانی (مثلاً پردازش تصاویر، فراخوانی APIهای خارجی) بیشتر از تایم‌اوت پیش‌فرض worker (۳۰ ثانیه) طول می‌کشند و gunicorn آن‌ها را می‌کشد.

راه‌حل: تایم‌اوت worker را با افزایش آن در تنظیمات برنامه خود بالا ببرید. می‌توانید این کار را از طریق آرگومان --timeout در Procfile انجام دهید:

web: gunicorn -w 4 -b 0.0.0.0:$PORT --timeout 120 app:app