Dockerfile حرفه‌ای برای پایتون با uv و Multi-stage Build


چرا ایمیج‌های داکر پایتون این‌قدر بزرگ می‌شوند؟ #

اگر یک پروژهٔ پایتون یا جنگو را با یک Dockerfile ساده بسازید، معمولاً با ایمیجی چندصد مگابایتی روبه‌رو می‌شوید که کش pip، کامپایلرها، فایل‌های موقت و حتی ابزارهای توسعه را با خودش حمل می‌کند. هر بار هم که یک خط کد عوض شود، همهٔ وابستگی‌ها از اول نصب می‌شوند.

راه حل دو بخش دارد:

  • Multi-stage build: ساخت و نصب را در یک مرحله انجام می‌دهیم و فقط خروجی لازم را به ایمیج نهایی منتقل می‌کنیم.
  • uv: مدیر پکیج بسیار سریع پایتون که با فایل uv.lock نصب قابل‌تکرار را تضمین می‌کند. اگر با uv آشنا نیستید، اول مطلب ابزار uv چیست را بخوانید.

این راهنما بر اساس راهنمای رسمی استفاده از uv در Docker نوشته شده است.

نصب uv داخل ایمیج #

ساده‌ترین روش، کپی کردن باینری uv از ایمیج رسمی آن است؛ بدون نیاز به pip install uv یا اسکریپت نصب:

Dockerfiledockerfile
FROM python:3.14-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

نکته

در محیط production به‌جای latest نسخهٔ دقیق را pin کنید (مثلاً ghcr.io/astral-sh/uv:0.13.8) تا buildها قابل‌تکرار باشند.

سه ترفند کلیدی برای build سریع #

۱. لایهٔ جداگانه برای وابستگی‌ها #

وابستگی‌ها کمتر از کد تغییر می‌کنند. پس ابتدا فقط وابستگی‌ها را با --no-install-project نصب می‌کنیم تا داکر این لایه را کش کند و با تغییر کد دوباره اجرا نشود.

۲. Cache mount #

با --mount=type=cache کش uv بین buildها حفظ می‌شود ولی داخل ایمیج نهایی قرار نمی‌گیرد. چون کش و مقصد روی فایل‌سیستم‌های مختلف هستند، UV_LINK_MODE=copy را تنظیم می‌کنیم تا هشدار لینک نگیریم.

۳. کامپایل bytecode #

با UV_COMPILE_BYTECODE=1 فایل‌های .pyc هنگام build ساخته می‌شوند و زمان شروع کانتینر کمتر می‌شود.

Dockerfile کامل Multi-stage برای جنگو #

Dockerfiledockerfile
# ---------- مرحلهٔ build ----------
FROM python:3.14-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy \
    UV_PYTHON_DOWNLOADS=0 \
    UV_NO_DEV=1

WORKDIR /app

# فقط وابستگی‌ها (این لایه کش می‌شود)
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project

# ---------- مرحلهٔ نهایی ----------
FROM python:3.14-slim

RUN useradd --create-home --uid 1000 app
WORKDIR /app

# فقط محیط مجازی آماده و کد برنامه منتقل می‌شود
COPY --from=builder --chown=app:app /app/.venv /app/.venv
COPY --chown=app:app . /app

ENV PATH="/app/.venv/bin:$PATH" \
    PYTHONUNBUFFERED=1

USER app
EXPOSE 8000
CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000"]

چند نکته دربارهٔ این فایل:

  • UV_PYTHON_DOWNLOADS=0 باعث می‌شود uv از پایتون سیستمی ایمیج استفاده کند؛ چون هر دو مرحله روی یک ایمیج پایه هستند، محیط مجازی در مرحلهٔ نهایی هم سالم کار می‌کند.
  • UV_NO_DEV=1 وابستگی‌های توسعه (مثل pytest و ruff) را نصب نمی‌کند.
  • --locked اگر uv.lock با pyproject.toml هماهنگ نباشد، build را متوقف می‌کند.
  • اجرای برنامه با کاربر غیر root امنیت کانتینر را بالا می‌برد.

هشدار

فرض بر این است که gunicorn در وابستگی‌های پروژه (pyproject.toml) تعریف شده و ماژول تنظیمات جنگوی شما config نام دارد. این دو را با پروژهٔ خودتان تطبیق دهید.

فایل .dockerignore را فراموش نکنید #

محیط مجازی لوکال شما به سیستم‌عامل خودتان وابسته است و نباید وارد ایمیج شود:

.dockerignore
.venv
__pycache__/
*.pyc
.git
.env
node_modules

ساخت و اجرا #

bash
docker build -t myapp:latest .
docker run --rm -p 8000:8000 myapp:latest
docker images myapp
روش کش وابستگی‌ها ابزار build در ایمیج نهایی ابزار توسعه
Dockerfile تک‌مرحله‌ای با pip معمولاً ندارد دارد معمولاً دارد
Multi-stage با uv دارد (cache mount) ندارد ندارد
چرا از Alpine استفاده نکنیم؟

Alpine از musl به‌جای glibc استفاده می‌کند و بعضی پکیج‌های پایتون با wheel آماده برای آن عرضه نمی‌شوند؛ در نتیجه ممکن است نیاز به کامپایل از سورس پیدا کنید. برای بیشتر پروژه‌ها python:3.x-slim انتخاب امن‌تر و ساده‌تری است.

uv داخل ایمیج نهایی هست؟

خیر. uv فقط در مرحلهٔ builder کپی شده و ایمیج نهایی فقط پایتون، محیط مجازی و کد شما را دارد.

جمع‌بندی #

با ترکیب multi-stage build و uv، buildهای شما سریع‌تر، ایمیج‌ها سبک‌تر و نصب‌ها کاملاً قابل‌تکرار می‌شوند. قدم بعدی منطقی این است که این build را در pipeline خودکار قرار دهید؛ مطلب راهنمای سریع CI/CD با GitHub Actions دقیقاً برای همین کار است. برای گزینه‌های بیشتر، مستندات رسمی uv برای Docker را ببینید.

این پست چطور بود؟

پست‌های مرتبط