الحاويات والنشر

طريقان إلى نفس الفكرة

قبل أن تبدأ

الفكرة الجوهرية

النشر حاوية تعمل بنفس الطريقة على أي خادم. تبني هنا الإعدادات من البيئة، ثم الصورة، ثم فصل الأوزان عنها، ثم الأرقام التي تجعل التراجع دقيقة واحدة.

1الإعدادات من البيئة

أول ما تفعله الخدمة عند البدء: تقرأ إعداداتها من متغيّرات البيئة، وتتأكّد أن كل المطلوب موجود. والأسرار مثل API_KEY تأتي من مدير الأسرار وقت التشغيل.

انظر إلى الرسم: خدمة ناقصة ترفض البدء برسالة واضحة. هذا أفضل بكثير من خدمة تبدأ ثم تفشل مع أول طلب.

def load_config(env):
    required = ["MODEL_PATH", "API_KEY"]
    missing = [k for k in required if not env.get(k)]
    if missing:
        raise SystemExit(f"cannot start: missing {', '.join(missing)}")
    return {
        "model_path": env["MODEL_PATH"],
        "api_key": env["API_KEY"],
        "max_input_chars": int(env.get("MAX_INPUT_CHARS", "2000")),
        "version": env.get("APP_VERSION", "dev"),
    }

def show(cfg):
    safe = {k: ("***" if k == "api_key" else v) for k, v in cfg.items()}
    print("starting with", safe)

show(load_config({"MODEL_PATH": "/models/sentiment-v3", "API_KEY": "sk-123", "APP_VERSION": "1.4.2"}))
try:
    load_config({"MODEL_PATH": "/models/sentiment-v3"})
except SystemExit as e:
    print(e)

الإعدادات المطلوبة تُفحص أولًا، والاختيارية لها قيم افتراضية، والسرّ يُخفى حتى في سجل البدء. في المرة الثانية نقص المفتاح فرفضت الخدمة البدء وقالت ماذا ينقص بالضبط. منصّة النشر سترى الفشل فورًا وتُبقي النسخة القديمة تعمل.

2الصورة: Dockerfile

الصورة حزمة فيها نظام صغير ومكتبات بإصدارات مثبّتة والكود. تُبنى مرة واحدة وتعمل بنفس الطريقة في كل مكان.

FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt   # pinned versions: fastapi==0.115.0, ...

COPY app/ app/
RUN useradd --create-home appuser
USER appuser                                          # do not run as root

ENV MAX_INPUT_CHARS=2000
EXPOSE 8000
HEALTHCHECK CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/ready')"
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

requirements.txt يُنسخ ويُثبَّت قبل الكود، فتغيير الكود لا يعيد تثبيت المكتبات ويبقى البناء سريعًا. والخدمة تعمل بمستخدم عادي لا root. ولا يوجد سرّ ولا أوزان في الملف: MODEL_PATH وAPI_KEY تأتيان وقت التشغيل.

3الأوزان خارج الصورة

صورة فيها نموذج بعشرة غيغابايت بطيئة البناء والسحب، وكل تعديل صغير في الكود يعيد رفعها كلها.

انظر إلى الرسم: الصورة فيها الكود فقط، والأوزان في تخزين ملفات بمسار يحمل نسختها. الخدمة تحمّلها عند البدء من MODEL_PATH.

هكذا تغيّر الكود والنموذج كلًّا على حدة، وتتراجع عن أيٍّ منهما وحده.

4الإصدارات والتراجع

كل صورة لها وسم ثابت مثل 1.4.2، والنموذج له نسخته أيضًا. الوسم latest ممنوع في الإنتاج.

انظر إلى الرسم: التراجع ليس إعادة بناء كود قديم، بل تشغيل صورة موجودة بوسمها.

docker build -t sentiment-api:1.4.2 .
docker run -d --name api -p 8000:8000 \
  -e MODEL_PATH=s3://models/sentiment/v3 \
  -e APP_VERSION=1.4.2 \
  --env-file /secure/api.env \
  sentiment-api:1.4.2

# 1.4.2 misbehaves in production: go back to the previous tag
docker rm -f api && docker run -d --name api -p 8000:8000 ... sentiment-api:1.4.1

الرقم في الصورة هو نفسه في APP_VERSION، فيظهر في كل رد وكل سطر سجل. والتراجع ليس إعادة بناء من كود قديم، بل تشغيل صورة موجودة. في منصّات النشر الحقيقية هذا زر واحد أو أمر واحد، بشرط أنك لم تحذف الصور القديمة.

كيف يعمل، خطوة بخطوة: كيف تنشر نسخة وتتراجع عنها

مثال محلول

أول ما تفعله الخدمة عند البدء: تقرأ إعداداتها من البيئة، وتتأكّد أن كل ما تحتاجه موجود، وترفض البدء برسالة واضحة إن نقص شيء. خدمة تبدأ ناقصة ثم تفشل مع أول طلب أسوأ بكثير من خدمة ترفض البدء.

جرّب بلا كود

خرافة مقابل حقيقة

جرّب بنفسك

بطاقات مراجعة سريعة

تحقق من فهمك