برای نوشتن یک Dockerfile برای پایتون به شکل پایدار و قابل استقرار، این گام‌ها کافی است: یک image پایه مثل python:3.12-slim انتخاب کنید، متغیرهای محیطی پایه را تنظیم کنید، دایرکتوری کاری بسازید، ابتدا requirements.txt را کپی و وابستگی‌ها را نصب کنید، سپس کد را کپی کرده و اپلیکیشن را با یک دستور شفاف (CMD) اجرا کنید. در ادامه همین الگو را گام‌به‌گام با مثال واقعی و نکات بهینه‌سازی پیش می‌بریم.

ساختار کلی یک Dockerfile پایدار

این Dockerfile مینیمال برای اغلب سرویس‌های پایتون مناسب است. از image slim استفاده می‌کند، لایه‌ها را درست می‌چیند و کاربر غیرریشه را فعال می‌کند.

# 1) تصویر پایه
FROM python:3.12-slim

# 2) تنظیم محیط برای رفتار قابل پیش‌بینی‌تر
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

# 3) دایرکتوری کاری
WORKDIR /app

# 4) نصب وابستگی‌های سیستمی موردنیاز (در صورت نیاز پکیج‌های باینری)
# RUN apt-get update && apt-get install -y --no-install-recommends build-essential && rm -rf /var/lib/apt/lists/*

# 5) ابتدا فقط فایل وابستگی‌ها را کپی کنید تا کش لایه‌ها بهتر عمل کند
COPY requirements.txt .

# 6) نصب کتابخانه‌های پایتون
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

# 7) سپس بقیه کد را کپی کنید
COPY . .

# 8) ایجاد کاربر غیرریشه
RUN useradd -m appuser
USER appuser

# 9) فرمان اجرا (برای مثال اپ ساده یا سرور وب)
# با توجه به اپ خود تغییر دهید
CMD ["python", "main.py"]

نکته ساختاری مهم این است که ابتدا requirements.txt را کپی کنیم و نصب کنیم؛ تا زمانی که وابستگی‌ها تغییر نکرده، کش این لایه‌ها تکرار شود و build سریع‌تر بماند.

مثال عملی: اجرای یک سرویس FastAPI با Uvicorn

در این مثال یک سرویس کوچک FastAPI می‌سازیم و آن را در کانتینر اجرا می‌کنیم.

# app/main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}
# requirements.txt
fastapi==0.112.2
uvicorn[standard]==0.30.5
# Dockerfile
FROM python:3.12-slim

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

COPY . .

# ایجاد کاربر غیرریشه و دادن مالکیت به پوشه کاری
RUN useradd -m appuser && chown -R appuser /app
USER appuser

EXPOSE 8000
# اجرای سرور Uvicorn برای FastAPI
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

فایل .dockerignore را هم اضافه کنید تا build سریع‌تر شود و فایل‌های بی‌ربط وارد image نشوند:

.git
__pycache__/
*.pyc
*.pyo
*.pyd
.env
.venv/
venv/
build/
dist/
*.log

دستورهای ساخت و اجرا:

docker build -t my-fastapi .
docker run --rm -p 8000:8000 my-fastapi
# تست:
curl http://localhost:8000/health

برای نوشتن مدل‌های داده تمیز در همین سرویس، مطالعه آموزش dataclass در پایتون می‌تواند مفید باشد.

بهینه‌سازی اندازه و سرعت ساخت

چینش لایه‌ها و کش

  • requirements.txt را زودتر کپی کنید تا کش نصب pip حفظ شود.
  • .dockerignore بنویسید تا فایل‌های غیرضروری وارد context نشوند.
  • از تگ نسخه‌دار مثل python:3.12-slim استفاده کنید تا buildها تکرارپذیر باشند.

Multi-stage برای پکیج‌های باینری

اگر برخی کتابخانه‌ها به build-essential یا هدرهای سیستمی نیاز دارند، آن‌ها را در مرحله builder نصب و در مرحله نهایی فقط محیط اجرا را نگه دارید.

# مرحله ساخت
FROM python:3.12-slim AS builder
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
WORKDIR /app

# وابستگی‌های سیستمی موقتی برای ساخت wheelها
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential gcc && \
    rm -rf /var/lib/apt/lists/*

# ساخت یک venv مجزا و نصب وابستگی‌ها در آن
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

COPY . .

# مرحله نهایی
FROM python:3.12-slim AS runtime
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
WORKDIR /app

# فقط venv آماده و کد را کپی کن؛ ابزارهای ساخت وارد image نهایی نمی‌شوند
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY --from=builder /app /app

RUN useradd -m appuser && chown -R appuser /app
USER appuser

EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

این الگو مخصوصا وقتی اندازه image و حمل‌ونقل سریع اهمیت دارد مفید است.

slim یا alpine؟

تصاویر alpine کوچک‌اند اما برای پکیج‌های نیازمند glibc یا build پیچیده، دردسرساز می‌شوند. برای اکثر پروژه‌ها python:3.x-slim تعادل بهتری بین اندازه و سازگاری دارد.

ساخت برای معماری‌های مختلف

# اگر لازم است خروجی amd64 بسازید (مثلا روی مک ARM)
docker buildx build --platform linux/amd64 -t my-fastapi:amd64 .

امنیت و تکرارپذیری

  • از USER غیرریشه استفاده کنید تا سطح دسترسی محدود شود.
  • نسخه پایتون و کتابخانه‌ها را پین کنید (مثلا ==) تا build امروز و فردا یکسان بماند.
  • Secretها را وارد image نکنید؛ از متغیر محیطی و Secretهای runtime استفاده کنید.
  • اگر حساسیت بالاست، از فایل قفل (مثل pip-tools یا Poetry) و گزینه‌های تایید هش‌ها استفاده کنید.

خطاهای رایج و روش رفع

  • ModuleNotFoundError: معمولا به خاطر نصب نشدن وابستگی‌ها یا کپی نکردن requirements.txt قبل از کد است. ترتیب COPY را اصلاح کنید.
  • Permission denied: اگر کاربر غیرریشه است، مالکیت پوشه کاری را به او بدهید (chown) یا مسیرهای نوشتنی را مشخص کنید.
  • کندی build به خاطر context بزرگ: .dockerignore را کامل کنید.
  • خرابی build در alpine: پکیج‌های نیازمند glibc یا کامپایلر روی alpine شکست می‌خورند؛ به slim مهاجرت کنید یا وابستگی‌های لازم را اضافه کنید.
  • نسخه‌های شناور: استفاده از :latest یا عدم پین نسخه‌ها باعث نتایج غیرقابل پیش‌بینی می‌شود.

بررسی نتیجه و دیباگ سریع

  1. ورود به کانتینر برای بررسی محیط:
docker run --rm -it my-fastapi sh
python -V
pip list
  1. دیدن لاگ‌ها:
docker logs -f <container_id_or_name>
  1. تست سلامت Endpoints با curl یا ابزارهای مشابه و بررسی کد وضعیت.

نکات ویژه برای علم داده و پردازش متن

  • برای کتابخانه‌های علمی (numpy, pandas, scikit-learn) معمولا slim کافی است؛ در صورت نیاز build-essential اضافه و سپس در مرحله نهایی حذف کنید (با الگوی multi-stage).
  • اگر با متن فارسی کار می‌کنید، دقت به کدگذاری و نرمال‌سازی اهمیت دارد. برای ایده‌ها و ابزارهای مرتبط می‌توانید استانداردسازی متن فارسی در پایتون را ببینید.
  • اگر سرویس شما با مدل‌های زبانی محلی تعامل دارد، مطالعه آموزش Ollama مسیر خوبی برای اجرای مدل در کنار سرویس پایتون است.

گام بعدی چیست؟

Dockerfile پایه خود را همین حالا بسازید: image slim، ترتیب درست COPY و نصب وابستگی‌ها، کاربر غیرریشه و فرمان اجرای شفاف. سپس با multi-stage و .dockerignore اندازه را کاهش دهید و با پین کردن نسخه‌ها build پایدار بسازید. در صورت نیاز به لایه‌های بیشتر، از Compose یا CI/CD برای خودکارسازی build و استقرار استفاده کنید.