تمارين Kata في DevOps بثلاثة مستويات مع الحلول

السطر COPY . . ينسخ كل المشروع قبل تثبيت المكتبات، فأي تعديل في app.py يغير هذه الطبقة، وبالتالي يبطل كل ما بعدها ومنه pip install. وهذا ما رأيناه عند البناء بعد تعديل سطر واحد في الكود (اختصرنا المخرج إلى الخطوات):

#6 [2/4] WORKDIR /app
#6 CACHED
#7 [3/4] COPY . .
#7 DONE 0.6s
#8 [4/4] RUN pip install --no-cache-dir -r requirements.txt
#8 18.98 Successfully installed certifi-2026.7.22 charset_normalizer-3.5.2 idna-3.20 requests-2.32.5 urllib3-2.8.0
#8 DONE 19.9s

والحل أن تنسخ ملف المكتبات وحده أولاً وتثبتها، ثم تنسخ بقية الكود، لأن requirements.txt يتغير نادراً والكود يتغير في كل Commit:

FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]

وبعد تعديل الكود مرة أخرى وإعادة البناء، والمخرج سوف يكون كما يلي:

#6 [2/5] WORKDIR /app
#6 CACHED
#7 [3/5] COPY requirements.txt .
#7 CACHED
#8 [4/5] RUN pip install --no-cache-dir -r requirements.txt
#8 CACHED
#9 [5/5] COPY . .
#9 DONE 1.0s
$ docker run --rm lab-kata-ops-cache:good
app v3, requests 2.32.5

في الإعداد أعلاه لاحظ التالي:

• الطبقات الثلاث الأولى أصبحت CACHED، والخطوة الوحيدة التي تنفذ هي نسخ الكود، وهذه القاعدة نفسها في Node.js (package.json وpackage-lock.json ثم npm ci) وفي .NET (ملف .csproj ثم dotnet restore).
• الملف الإضافي هو .dockerignore، تضع فيه .git وnode_modules و.env والسجلات، فلا ترسل إلى البناء ولا تبطل الطبقة COPY . . عندما تتغير، ولا تدخل في ال Image أسرار من ملف .env.

للتفصيل: توثيق Docker عن ترتيب الطبقات وذاكرة البناء، وقسم نظافة ال Image في قائمة تحقق المطور.

كلامه غير صحيح، فال Container يعزل العمليات عن بعضها لكنه يشترك مع السيرفر في نفس النواة، والعملية التي تعمل بالرقم 0 تملك داخل ال Container كل شيء، فإذا استغل المخترق ثغرة في التطبيق فهو root في نظام ملفات ال Container، وأي خطأ في الإعداد مثل ربط مجلد من السيرفر أو ملف docker.sock يصبح طريقاً إلى السيرفر نفسه. والحل أن تنشئ مستخدماً عادياً وتنتقل إليه:

FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
RUN useradd --system --uid 10001 --no-create-home app
COPY --chown=app:app . .
USER app
CMD ["python", "app.py"]

والتحقق بأربعة أوامر، والمخرج سوف يكون كما يلي:

$ docker run --rm lab-kata-ops-user id
uid=10001(app) gid=999(app) groups=999(app)
$ docker run --rm lab-kata-ops-user
app v3, requests 2.32.5
$ docker image inspect lab-kata-ops-user --format '{{.Config.User}}'
app
$ docker run --rm lab-kata-ops-user sh -c 'touch /etc/x'
touch: cannot touch '/etc/x': Permission denied

في الإعداد أعلاه لاحظ التالي:

• التثبيت بالأمر pip install يبقى قبل USER لأنه يكتب في مجلدات النظام، وكل ما بعد USER يعمل بالمستخدم الجديد، ومنه الأمر CMD.
• --chown=app:app يجعل ملفات الكود ملكاً للمستخدم، وإذا كان التطبيق يقرأ فقط فيمكنك أن تتركها ملكاً ل root وهذا أفضل، لأن التطبيق عندها لا يستطيع تعديل كوده إذا اخترق.
• رقم المجموعة 999 جاء من الخيار --system الذي يختار رقماً من نطاق حسابات النظام، وإذا أردت رقماً ثابتاً فأنشئ المجموعة أولاً بالأمر groupadd --gid.

للتفصيل: التعليمة USER في مرجع Dockerfile، وقسم المستخدم والصلاحيات في قائمة تحقق المطور.

localhost داخل ال Container يعني ال Container نفسه، وليس السيرفر ولا ال Container الآخر، ولذلك جاء الرفض Connection refused من داخل app لأنه لا يوجد شيء يستمع فيه على المنفذ 5432. وCompose ينشئ شبكة افتراضية للمشروع ويسجل فيها كل خدمة باسمها، فالعنوان الصحيح هو اسم الخدمة db:

    environment:
      DB_HOST: db

وعند التشغيل مرة أخرى، والمخرج سوف يكون كما يلي:

lab-kata-ops-app  | db:5432 - accepting connections
lab-kata-ops-app  |  ok
lab-kata-ops-app  | ----
lab-kata-ops-app  |   1
lab-kata-ops-app  | (1 row)

ولاحظ أننا رفعنا الانتظار في هذا التشغيل إلى sleep 20، لأن المحاولة الأولى مع db وsleep 5 أعطت db:5432 - no response ثم connection to server at "db" (192.168.112.2), port 5432 failed: Connection refused، أي أن الاسم صحيح والقاعدة لم تجهز بعد، وهذه مشكلة مختلفة تماماً نحلها بالطريقة الصحيحة في التمرين 9، لأن الانتظار بعدد ثوان ثابت ليس حلاً. وطريقة التفريق بين المشكلتين في رسالة الخطأ نفسها: مع localhost ترى العنوان 127.0.0.1 و::1، ومع اسم الخدمة ترى عنوان ال Container الآخر في الشبكة.

للتفصيل: الشبكات في توثيق Compose، وقسم شبكات Compose في دليل شبكات Docker.

الطريقة الصحيحة هي git revert، فهو ينشئ Commit جديداً عكس ال Commit المحدد، والتاريخ القديم يبقى كما هو، فيسحبه زملاؤك كأي تغيير عادي. والمخرج الكامل للتجربة، بما فيها الطريقة الخاطئة أولاً، سوف يكون كما يلي:

$ git reset --hard HEAD~1 && git push origin main
To /work/origin.git
 ! [rejected]        main -> main (non-fast-forward)
error: failed to push some refs to '/work/origin.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. If you want to integrate the remote changes,
hint: use 'git pull' before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
$ git revert --no-edit HEAD
[main 3e23d1b] Revert "Set discount to 90 for testing"
 Date: Wed Oct 7 08:14:03 2026 +0000
 1 file changed, 1 insertion(+), 1 deletion(-)
$ git push origin main
To /work/origin.git
   085e333..3e23d1b  main -> main
$ git log --oneline
3e23d1b Revert "Set discount to 90 for testing"
085e333 Set discount to 90 for testing
7a6404b Add discount setting
8677838 Add pricing config
$ cat pricing.conf
price = 100
discount = 0

في الإعداد أعلاه لاحظ التالي:

• بعد reset أصبح فرعك المحلي خلف الفرع البعيد، فرفض الخادم ال Push لأنه ليس تقدماً مباشراً Fast-forward، والطريق الوحيد لإجباره هو --force، وهذا يعيد كتابة تاريخ سحبه زملاؤك، فيعود ال Commit المحذوف مع أول Push من أحدهم أو تضيع أعمالهم.
• git revert لا يحذف شيئاً، ولذلك يبقى ال Commit الخاطئ في التاريخ ويبقى معه سبب التراجع، وهذا ما تريده في الفرع المشترك.
• إذا كان ال Commit المراد عكسه هو Merge فتحتاج الخيار -m 1 لتحدد الطرف الذي تبقى عليه.

للتفصيل: قسم revert في دليل Git للمبتدئين، وتوثيق git revert.

الجزء بين <<<<<<< HEAD و======= هو نسخة الفرع الحالي main، والجزء بين ======= و>>>>>>> feature/longer-timeout هو نسخة الفرع المدموج، والأسطر خارج العلامات اتفق عليها الطرفان فدمجها Git وحده. وUU في git status تعني أن الملف معدل في الطرفين ولم يحل بعد. والحل أن تكتب الملف بالشكل النهائي دون علامات، ثم git add ثم git commit:

printf 'server_port = 8080\ntimeout = 60\nlog_level = info\n' > app.conf
git add app.conf
git commit --no-edit
git log --oneline --graph

والمخرج سوف يكون كما يلي:

*   34a1333 Merge branch 'feature/longer-timeout'
|\
| * c8aa02a Raise timeout to 60
* | 20f4850 Raise timeout to 45 for reports
|/
* 94a8de1 Initial config

في الإعداد أعلاه لاحظ التالي:

• القرار هنا قرار عمل وليس قرار Git، فلا تختر أحد الطرفين بالأمر git checkout --theirs أو --ours قبل أن تفهم لماذا غير كل طرف القيمة.
• لإلغاء الدمج كله والعودة إلى ما قبله استخدم git merge --abort.
• قبل ال Commit ابحث عن علامات نسيتها في كل المشروع بالأمر git diff --check أو grep -rn '^<<<<<<<'، فالعلامة المنسية في ملف إعداد تكسر التطبيق عند التشغيل وليس عند البناء.

للتفصيل: قسم التعارضات في دليل merge وrebase، وتوثيق git merge.

تحتاج أربعة أسطر proxy_set_header، تعيد اسم الموقع الأصلي وتخبر التطبيق بعنوان الزائر وبالبروتوكول الذي وصل به:

server {
    listen 80;
    server_name shop.example.test;

    location / {
        proxy_pass http://lab-kata-ops-backend:8000;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

وبعد nginx -t وnginx -s reload ونفس الطلب، والمخرج سوف يكون كما يلي:

path=/orders?page=2
host=shop.example.test
client_ip=192.168.128.3
x-real-ip=192.168.128.1
x-forwarded-for=192.168.128.1
x-forwarded-proto=http

في الإعداد أعلاه لاحظ التالي:

• client_ip بقي عنوان Nginx، وهذا صحيح، لأن الاتصال فعلاً من Nginx، والعنوان الحقيقي يأتي في الترويستين، وعلى التطبيق أن يثق بهما فقط عندما يأتي الطلب من عنوان ال Proxy المعروف، وإلا فأي زائر يستطيع أن يكتب لنفسه X-Forwarded-For.
• العنوان 192.168.128.1 هو بوابة شبكة Docker، لأن الطلب في مختبرنا يمر عبر Docker Desktop، وعلى سيرفر Linux ترى عنوان الزائر الحقيقي.
• $proxy_add_x_forwarded_for يضيف عنوان الزائر إلى القائمة الموجودة بدل أن يستبدلها، وهذا مهم عندما يكون أمام Nginx طبقة أخرى مثل Cloudflare.

للتفصيل: قسم الترويسات في دليل تطبيقك خلف Reverse Proxy، وقسم انتحال العنوان Spoofing في نفس الدليل.

السران مكشوفان، والإثبات بأمرين. الأول docker history يظهر قيمة ARG في كل سطر RUN يأتي بعده:

$ docker history --no-trunc --format '{{.CreatedBy}}' lab-kata-ops-secret:bad | head -3
RUN |1 API_KEY=sk_live_FAKE_9f8e7d /bin/sh -c echo "calling the API with $API_KEY" > /dev/null # buildkit
RUN |1 API_KEY=sk_live_FAKE_9f8e7d /bin/sh -c echo "installing with the token..." && rm /root/.npmrc # buildkit
COPY .npmrc /root/.npmrc # buildkit

والثاني أن تحفظ ال Image في ملف tar وتفتح طبقاته، فتجد الملف كاملاً في طبقة COPY، وفي الطبقة التالية علامة الحذف فقط:

docker save lab-kata-ops-secret:bad -o img.tar && tar -xf img.tar
for b in blobs/sha256/*; do
  if tar -tf $b 2>/dev/null | grep -q npmrc; then echo "layer: $b"; tar -tvf $b | grep npmrc; tar -xOf $b root/.npmrc; fi
done

والمخرج سوف يكون كما يلي:

layer: blobs/sha256/055e4323d9b0d3f91c1004bd2b8aebcc09d072bd4a097e3f185caafc1d448fac
-rwxr-xr-x 0/0              58 2026-10-07 11:00 root/.npmrc
//registry.npmjs.org/:_authToken=npm_FAKE1234567890abcdef
layer: blobs/sha256/a7f9f0d94f6d16cfebfd8e1755cef7f4658950104f9b52d92877e5468e28ee96
---------- 0/0               0 1970-01-01 03:00 root/.wh..npmrc
tar: root/.npmrc: Not found in archive

والطريقة الصحيحة هي أسرار البناء Build Secrets في BuildKit، فالسر يركب في ملف أو متغير أثناء تنفيذ سطر RUN واحد فقط، ولا يكتب في أي طبقة ولا في التاريخ:

# syntax=docker/dockerfile:1
FROM alpine:3.22
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    echo "token file inside the build: $(wc -c < /root/.npmrc) bytes"
RUN --mount=type=secret,id=api_key,env=API_KEY \
    echo "API key length: ${#API_KEY}"

والبناء يمرر السرين من ملف ومن متغير بيئة:

API_KEY=sk_live_FAKE_9f8e7d docker build --progress=plain --no-cache \
  --secret id=npmrc,src=.npmrc --secret id=api_key,env=API_KEY -t lab-kata-ops-secret:good .
docker history --no-trunc --format '{{.CreatedBy}}' lab-kata-ops-secret:good | head -2
docker save lab-kata-ops-secret:good -o img.tar && tar -xf img.tar && (grep -rl "npm_FAKE\|sk_live_FAKE" . || echo "no secret found in any layer")

والمخرج سوف يكون كما يلي:

#9 3.296 token file inside the build: 58 bytes
#10 1.996 API key length: 19
RUN /bin/sh -c echo "API key length: ${#API_KEY}" # buildkit
RUN /bin/sh -c echo "token file inside the build: $(wc -c < /root/.npmrc) bytes" # buildkit
no secret found in any layer

في الإعداد أعلاه لاحظ التالي:

• البناء رأى الملف (58 بايت) ورأى المفتاح (19 حرفاً)، ولا يوجد أي أثر لهما في التاريخ أو في الطبقات.
• ARG وENV ليسا مكاناً للأسرار إطلاقاً، فالأول يظهر في التاريخ كما رأينا، والثاني يبقى في إعداد ال Image ويظهر بالأمر docker inspect.
• إذا رفعت Image فيه سر إلى أي سجل فاعتبر السر مسرباً وقم بتغييره Rotate، ولا يكفي أن تحذف ال Image من السجل لأن غيرك قد يكون سحبه.

للتفصيل: أسرار البناء في توثيق Docker، وقسم الأسرار داخل ال Images في دليل اكتشاف الأسرار المسربة.

الحجم كله تقريباً من ال Image الأساسي golang:1.27.1-bookworm، ففيه نظام Debian والمترجم وأدوات البناء، وطبقة البناء نفسها أضافت 101MB من ذاكرة المترجم كما يظهر docker history:

$ docker history lab-kata-ops-go:single --format '{{.Size}}\t{{.CreatedBy}}' | head -4
0B	CMD ["hello"]
0B	EXPOSE [8080/tcp]
101MB	RUN /bin/sh -c go build -o /usr/local/bin/he…
24.6kB	COPY . . # buildkit

والحل أن تبني في مرحلة أولى، ثم تنسخ الملف التنفيذي وحده إلى Image صغير لا يحتوي حتى على Shell:

FROM golang:1.27.1-bookworm AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/hello .

FROM gcr.io/distroless/static-debian13:nonroot
COPY --from=build /out/hello /hello
EXPOSE 8080
ENTRYPOINT ["/hello"]

والتحقق، والمخرج سوف يكون كما يلي:

$ docker images --format 'table {{.Repository}}:{{.Tag}}\t{{.Size}}' | grep -E "REPO|lab-kata-ops-go"
REPOSITORY:TAG                                        SIZE
lab-kata-ops-go:multi                                 15MB
lab-kata-ops-go:single                                1.38GB
$ docker run -d --name lab-kata-ops-go -p 127.0.0.1:21410:8080 lab-kata-ops-go:multi
$ curl -s http://127.0.0.1:21410/
hello from go
$ docker image inspect lab-kata-ops-go:multi --format 'user={{.Config.User}}'
user=65532
$ docker exec lab-kata-ops-go sh
OCI runtime exec failed: exec failed: unable to start container process: exec: "sh": executable file not found in $PATH

في الإعداد أعلاه لاحظ التالي:

• المرحلة الأولى AS build لا تصل إلى السيرفر أبداً، فالمترجم وذاكرته يبقيان على جهاز البناء.
• الوسم nonroot في distroless يجعل المستخدم 65532 دون أن تكتب USER، وعدم وجود Shell يعني أن المخترق الذي يجد ثغرة في البرنامج لا يجد أدوات يكمل بها، وأنت أيضاً لا تجدها، فاستخدم docker debug أو Container مؤقتاً للتشخيص.
• نفس الفكرة في Node.js وPython: مرحلة فيها أدوات البناء وتنزيل المكتبات، ومرحلة نهائية من Image بنسخة slim تنسخ إليها الناتج فقط.

للتفصيل: البناء متعدد المراحل في توثيق Docker، وقسم نظافة ال Images الأساسية في دليل أمن سلسلة التوريد.

depends_on بالصيغة القصيرة ينتظر أن يبدأ ال Container الخاص بالقاعدة فقط، وPostgreSQL يحتاج ثواني بعد ذلك لينشئ ملفاته عند أول تشغيل ثم يعيد التشغيل ليقبل الاتصالات، والتطبيق يحاول في هذه الثواني فيفشل. والحل أن تعرف Compose متى تكون القاعدة جاهزة بفحص صحة Healthcheck، وتجعل التطبيق ينتظر الحالة service_healthy:

services:
  db:
    image: postgres:18-alpine
    container_name: lab-kata-ops-db
    environment:
      POSTGRES_PASSWORD: example
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -h 127.0.0.1"]
      interval: 2s
      timeout: 3s
      retries: 30
      start_period: 5s
  app:
    image: postgres:18-alpine
    container_name: lab-kata-ops-app
    depends_on:
      db:
        condition: service_healthy
        restart: true
    command: psql "postgresql://postgres:example@db:5432/postgres" -c "select 1 as ok"

والمخرج سوف يكون كما يلي (اختصرنا سجلات القاعدة):

 Container lab-kata-ops-db Waiting
 Container lab-kata-ops-db Healthy
lab-kata-ops-app  |  ok
lab-kata-ops-app  | ----
lab-kata-ops-app  |   1
lab-kata-ops-app  | (1 row)
lab-kata-ops-app exited with code 0

في الإعداد أعلاه لاحظ التالي:

• الفحص يستخدم -h 127.0.0.1 وليس الاتصال المحلي عبر ال Socket، والسبب أن PostgreSQL في أول تشغيل يشغل نسخة مؤقتة لإنشاء القاعدة تستمع على ال Socket فقط، فالفحص عبر ال Socket قد ينجح قبل أن تجهز النسخة الحقيقية.
• restart: true يجعل Compose يعيد تشغيل التطبيق إذا أعيد تشغيل القاعدة بأمر من Compose.
• هذا يحل ترتيب التشغيل فقط، والقاعدة قد تتوقف لاحقاً أثناء العمل، لذلك يجب أن يعيد التطبيق محاولة الاتصال بنفسه، وهذا ما يفعله أي Connection Pool جيد.

للتفصيل: ترتيب التشغيل في توثيق Compose، وقسم ترتيب التشغيل في قائمة تحقق المطور.

المجلد /data غير موجود في ال Image، فأنشأه Docker عند التركيب بمالك root، والمستخدم 10001 لا يستطيع الكتابة فيه:

$ docker run --rm -v lab-kata-ops-data:/data alpine:3.22 ls -lnd /data
drwxr-xr-x    2 0        0             4096 Oct  7 07:58 /data

والحل أن تنشئ المجلد في ال Image وتعطيه للمستخدم قبل USER، فينسخ Docker المجلد بمالكه إلى ال Volume الجديد عند أول تركيب:

FROM alpine:3.22
RUN adduser -D -u 10001 app && mkdir /data && chown app:app /data
USER app
CMD ["sh", "-c", "echo hello > /data/out.txt && ls -ln /data"]

وبعد حذف ال Volume القديم بالأمر docker volume rm lab-kata-ops-data والتشغيل مرة أخرى، والمخرج سوف يكون كما يلي:

$ docker run --rm --name lab-kata-ops-vol -v lab-kata-ops-data:/data lab-kata-ops-vol:good
total 4
-rw-r--r--    1 10001    10001            6 Oct  7 07:58 out.txt
$ docker run --rm -v lab-kata-ops-data:/data alpine:3.22 ls -lnd /data
drwxr-xr-x    2 10001    10001         4096 Oct  7 07:58 /data

في الإعداد أعلاه لاحظ التالي:

• النسخ من ال Image يحدث فقط عندما يكون ال Volume فارغاً، فإذا كان فيه بيانات بمالك root من تشغيل قديم فأصلح ملكيتها مرة واحدة بأمر chown من Container يعمل بالمستخدم root، ولا تغير الخدمة نفسها.
• ربط مجلد من السيرفر Bind Mount لا ينسخ شيئاً، والمجلد يبقى بمالكه على السيرفر، فهناك تعطي المجلد للرقم 10001 على السيرفر بالأمر chown 10001:10001.
• Linux يقارن الأرقام وليس الأسماء، ولذلك نستخدم ls -n، فالمستخدم app في ال Container قد يكون اسمه شيئاً آخر على السيرفر وله نفس الرقم.

للتفصيل: ال Volumes في توثيق Docker، وقسم ال Volumes والصلاحيات في قائمة تحقق المطور.

بدون URI يرسل Nginx المسار كما جاء من الزائر، فيصل إلى التطبيق /api/users/7 وهو لا يعرفه. والإصلاح أن تضيف شرطة في آخر العنوان، فيستبدل Nginx الجزء /api/ بالشرطة /. والتطبيق في المختبر يطبع سطر الطلب كما وصله حرفياً، والمخرج سوف يكون كما يلي:

--- without slash
path=/api/users/7
--- with slash
path=/users/7
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:21411/api
301

ومع location /api بدون شرطة وproxy_pass بشرطة يحدث أمران خاطئان، والمخرج سوف يكون كما يلي:

$ curl -s http://127.0.0.1:21411/api/users/7 | head -1
path=//users/7
$ curl -s http://127.0.0.1:21411/apiusers | head -1
path=/users

في الإعداد أعلاه لاحظ التالي:

• الاستبدال نصي بحت: /api استبدلت ب / فأصبح المسار //users/7، وبعض أطر العمل تصلح الشرطتين بصمت وبعضها يعطي 404، ولذلك لا ترى المشكلة دائماً في كل التطبيقات.
• الأخطر أن location /api يطابق أيضاً /apiusers و/api-admin، فيصل إلى التطبيق مسار لم تقصد نشره، لذلك اجعل الشرطة في آخر ال location وفي آخر ال proxy_pass معاً.
• الطلب /api بدون شرطة أعطى 301 إلى /api/، وهذا سلوك Nginx المعروف عندما ينتهي ال location بشرطة ويمرر إلى proxy_pass.

للتفصيل: التعليمة proxy_pass في توثيق Nginx، وقسم التطبيق تحت مسار فرعي في دليل تطبيقك خلف Reverse Proxy.

Nginx لا يمرر الترويستين Upgrade وConnection لأنهما Hop-by-hop، فوصل الطلب إلى التطبيق كطلب HTTP عادي ورفضه. والحل أن تمررهما صراحة، مع map يضع close عندما لا يطلب الزائر ترقية:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;

    location /ws/ {
        proxy_pass http://lab-kata-ops-backend:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 1h;
    }
}

وبعد إعادة التحميل ونفس الطلب، والمخرج سوف يكون كما يلي:

HTTP/1.1 101 Switching Protocols
Server: nginx/1.29.8
Date: Wed, 07 Oct 2026 08:11:28 GMT
Connection: upgrade
Upgrade: websocket
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

curl exit=28

في الإعداد أعلاه لاحظ التالي:

• الرمز curl exit=28 هو انتهاء المهلة التي حددناها بالخيار --max-time 2، وهو هنا علامة نجاح، لأن الاتصال بعد 101 يبقى مفتوحاً للرسائل.
• القيمة s3pPLMBiTxaQ9kYGzzhZRbK+xOo= هي نفس المثال في RFC 6455 للمفتاح الذي أرسلناه، أي أن التطبيق أكمل المصافحة Handshake فعلاً.
• السطر proxy_http_version 1.1 أصبح القيمة الافتراضية منذ Nginx 1.29.7 حسب التوثيق، ونتركه لأن كثيراً من السيرفرات تعمل بنسخ أقدم، وبدونه فيها ترسل الطلبات بالإصدار 1.0 الذي لا يعرف الترقية.
• بدون proxy_read_timeout يغلق Nginx الاتصال إذا لم يرسل التطبيق شيئاً خلال 60 ثانية، والبديل أن يرسل التطبيق رسائل Ping دورية.

للتفصيل: صفحة WebSocket proxying في توثيق Nginx، وقسم WebSocket في دليل تطبيقك خلف Reverse Proxy.

في التشغيل الثاني يفشل سطران ويتكرر الثالث بصمت، ثم يطبع السكربت done كأن شيئاً لم يحدث:

$ sh setup-bad.sh   # run 1
done
$ sh setup-bad.sh   # run 2
adduser: user 'deploy' in use
mkdir: can't create directory '/srv/app': File exists
done
$ cat /etc/sysctl.d/99-app.conf
net.core.somaxconn = 1024
net.core.somaxconn = 1024

والنسخة المتكررة بأمان:

set -e
id deploy >/dev/null 2>&1 || adduser -D deploy
mkdir -p /srv/app
LINE="net.core.somaxconn = 1024"
grep -qxF "$LINE" /etc/sysctl.d/99-app.conf 2>/dev/null || echo "$LINE" >> /etc/sysctl.d/99-app.conf
echo "done"

وفي Container جديد بعد ثلاث مرات، والمخرج سوف يكون كما يلي:

$ sh setup-good.sh   # run 1
done
$ sh setup-good.sh   # run 2
done
$ sh setup-good.sh   # run 3
done
$ cat /etc/sysctl.d/99-app.conf
net.core.somaxconn = 1024
$ grep -c ^deploy: /etc/passwd
1

في الإعداد أعلاه لاحظ التالي:

• كل أمر يصف حالة نهائية وليس خطوة، وهذا هو الفرق بين الأسلوب الأمري Imperative والتصريحي Declarative الذي تبنى عليه أدوات مثل Ansible وTerraform.
• set -e يوقف السكربت عند أول أمر يفشل، فلا يطبع done وخط النشر يرى الفشل، والسطر المكرر في ملف الإعداد أخطر من الخطأ الظاهر لأن لا أحد يراه حتى يتعارض سطران بقيمتين مختلفتين.
• grep -x يطابق السطر كاملاً و-F يعامل النص كما هو، فلا تفسر النقاط في القيمة كتعبير نمطي.

للتفصيل: قسم التكرار الآمن في دليل البنية كشيفرة IaC.

السجل اسمه reflog، وفيه كل حركة ل HEAD على جهازك، ومنه تأخذ المكان الذي كنت فيه قبل ال reset وتعطيه فرعاً باسم، والمخرج سوف يكون كما يلي:

$ git reflog
f5191e6 HEAD@{0}: reset: moving to HEAD~2
6d00124 HEAD@{1}: commit: Add feature B (two days of work)
69afd84 HEAD@{2}: commit: Add feature A
f5191e6 HEAD@{3}: commit (initial): Initial version
$ git branch rescue HEAD@{1}
$ git log --oneline rescue
6d00124 Add feature B (two days of work)
69afd84 Add feature A
f5191e6 Initial version
$ git reset --hard rescue
HEAD is now at 6d00124 Add feature B (two days of work)
$ cat app.txt
v1
feature A
feature B

في الإعداد أعلاه لاحظ التالي:

• أنشأنا الفرع rescue أولاً قبل أي أمر آخر، لأن الفرع يحمي ال Commits من التنظيف، ثم انتقلنا إليه.
• حسب توثيق Git فإن السجلات التي لا يصل إليها أي فرع تنتهي افتراضياً بعد 30 يوماً، والباقية بعد 90 يوماً، ثم يحذف git gc ال Commits التي لا يشير إليها شيء، فالإنقاذ ممكن لأيام وليس للأبد.
• ال reflog محلي فقط، فلا يوجد على الخادم ولا في نسخة زميلك، والتعديلات التي لم تدخل Commit أصلاً لا يحفظها شيء، لذلك اعمل Commit مبكراً ولو مؤقتاً.

للتفصيل: قسم reflog في دليل merge وrebase، وتوثيق git reflog.

الأمر git cherry-pick -x يطبق تغيير Commit واحد فوق الفرع الحالي، ويضيف إلى الرسالة رقم ال Commit الأصلي:

$ git switch release/1.4 && git cherry-pick -x bb9cca6
[release/1.4 855a304] Fix: total ignores quantity
 Date: Wed Oct 7 08:15:16 2026 +0000
 1 file changed, 1 insertion(+), 1 deletion(-)
$ git log --oneline release/1.4
855a304 Fix: total ignores quantity
3081b8e Cart total
$ git log -1 --format=%B
Fix: total ignores quantity

(cherry picked from commit bb9cca6a57171757b0fa40904e78e4a367e2c9b3)

$ ls
cart.py

في الإعداد أعلاه لاحظ التالي:

• ال Commit الجديد له رقم مختلف 855a304 لأنه بني فوق أب مختلف، والسطر الذي أضافه -x هو الرابط الوحيد بين النسختين، وتحتاجه عندما تسأل بعد شهر «هل الإصلاح موجود في 1.4؟».
• الأمر ls لا يظهر checkout.py، أي أن صفحة الدفع بقيت في main.
• الترتيب الأفضل في الفرق أن يدخل الإصلاح أولاً إلى main ثم ينقل إلى فروع النسخ، حتى لا يعود الخطأ في النسخة القادمة.

للتفصيل: قسم cherry-pick في دليل merge وrebase، وتوثيق git cherry-pick.

الاختبار سطران، ونضعه خارج المستودع حتى لا يتغير مع كل Checkout:

cat > /work/test.sh <<'T'
#!/bin/sh
[ "$(sh price.sh 100)" = "115" ]
T
chmod +x /work/test.sh
git bisect start HEAD $(git rev-list --max-parents=0 HEAD)
git bisect run /work/test.sh
git bisect reset

والمخرج سوف يكون كما يلي:

$ git bisect start HEAD 71f3f9d
Bisecting: 19 revisions left to test after this (roughly 4 steps)
[68503c0a10a1fdbbeb2a599d8a55876ce4391cd3] Update changelog 20
$ git bisect run /work/test.sh
running '/work/test.sh'
Bisecting: 9 revisions left to test after this (roughly 3 steps)
[239d86a3319d1c8776e6b504cb4be512698f11d8] Update changelog 30
running '/work/test.sh'
Bisecting: 4 revisions left to test after this (roughly 2 steps)
[4dd794f374bcf489a8116c6e34422133ec6e2e99] Update changelog 25
running '/work/test.sh'
Bisecting: 2 revisions left to test after this (roughly 1 step)
[98ff2e4499f117ee2b4561695787ad53b8924866] Update changelog 22
running '/work/test.sh'
Bisecting: 0 revisions left to test after this (roughly 1 step)
[57ab4f6f5b82508892408e28a28f2c4376979763] Update changelog 24
running '/work/test.sh'
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[f4c458d346246cc674fc2b81ef40bd073bfcbc15] Read VAT from environment (refactor)
running '/work/test.sh'
f4c458d346246cc674fc2b81ef40bd073bfcbc15 is the first bad commit
commit f4c458d346246cc674fc2b81ef40bd073bfcbc15
Author: Lab <[email protected]>
Date:   Wed Oct 7 08:15:42 2026 +0000

    Read VAT from environment (refactor)

 CHANGELOG | 1 +
 price.sh  | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
bisect found first bad commit
$ git bisect reset
Previous HEAD position was f4c458d Read VAT from environment (refactor)
Switched to branch 'main'

في الإعداد أعلاه لاحظ التالي:

• ست تشغيلات للاختبار بدل أربعين، وال Commit المسؤول عنوانه «refactor» أي أن صاحبه لم يقصد تغيير السلوك، فقد غير السطر VAT=15 إلى VAT=${VAT_RATE:-0}، والقيمة الافتراضية صفر.
• الأمر git rev-list --max-parents=0 HEAD يعطي أول Commit في المستودع، وفي العمل الحقيقي تعطي bisect آخر وسم Tag تعرف أنه سليم.
• bisect يعمل جيداً عندما تكون ال Commits صغيرة وكل واحد منها يبنى ويعمل، وهذا سبب آخر لصغر ال Commits.

للتفصيل: قسم bisect في دليل merge وrebase، وتوثيق git bisect.

ملاحظات المراجعة من الأخطر:

1. السطر echo ... | base64 يطبع السر بشكل آخر، والإخفاء التلقائي يبحث عن القيمة كما هي فقط، وتوثيق GitHub نفسه يقول إن الإخفاء غير مضمون لأن السر قد يتحول بطرق كثيرة، فأي شخص يقرأ السجل يفك ال Base64 في ثانية. واحذف سطري Debug بالكامل، فلا يوجد سبب لطباعة سر.
2. actions/checkout@main وdocker/login-action@v3 مراجع متحركة، فالفرع والوسم يمكن نقلهما إلى كود آخر في أي لحظة، والكود الجديد يعمل بأسرارك. والحل هو التثبيت Pinning برقم ال Commit الكامل، وهو حسب توثيق GitHub الطريقة الوحيدة لاستخدام Action كإصدار لا يتغير، وهذا ما استغله المهاجمون في حادثة tj-actions/changed-files في مارس 2025 التي رويناها في دليل Gitea Actions، وشرحنا التثبيت بالتفصيل في دليل أمن سلسلة التوريد.
3. كتابة ${{ secrets.X }} داخل run تضع القيمة في نص السكربت قبل تشغيله، فإذا احتوت على علامات تنصيص أو $(...) تنفذ كأوامر، والطريقة الصحيحة أن تمررها في env ويقرأها السكربت من متغير البيئة.
4. لا يوجد قسم permissions، فالتوكن الافتراضي للمهمة يأخذ صلاحيات المستودع الافتراضية، والصحيح أن تبدأ من contents: read.
5. actions/checkout يحفظ التوكن في إعداد Git داخل مجلد العمل افتراضياً، وأي خطوة لاحقة أو ملف يرفع كناتج Artifact قد يحمله، فاستخدم persist-credentials: false.
6. النشر إلى الإنتاج بلا environment يعني أن أسرار الإنتاج متاحة لأي مهمة في المستودع، وبلا concurrency قد يعمل نشران في نفس الوقت.

وللحصول على الأرقام الكاملة للوسوم استخدمنا git ls-remote، والمخرج سوف يكون كما يلي:

$ git ls-remote https://github.com/actions/checkout "refs/tags/v7.0.1*"
3d3c42e5aac5ba805825da76410c181273ba90b1	refs/tags/v7.0.1
$ git ls-remote https://github.com/docker/login-action "refs/tags/v4.6.0*"
dbcb813823bdd20940b903addbd779551569679f	refs/tags/v4.6.0

والنسخة المصححة:

name: deploy
on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  deploy:
    name: Deploy to production
    runs-on: ubuntu-latest
    environment: production
    concurrency:
      group: deploy-production
      cancel-in-progress: false
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: registry.example.com
          username: ci
          password: ${{ secrets.REGISTRY_TOKEN }}
      - name: Deploy
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: ./deploy.sh

وللتحقق دون الاعتماد على عينك فقط شغلنا أداة فحص ملفات Workflow المسماة zizmor (الإصدار 1.30.1) على الملفين بالأمر docker run --rm -v "$PWD:/repo:ro" ghcr.io/zizmorcore/zizmor:latest --offline --persona=auditor --format plain /repo، والمخرج على الملف الأصلي سوف يكون كما يلي (اختصرنا كل ملاحظة إلى سطرها الأول):

warning[artipacked]: credential persistence through GitHub Actions artifacts
warning[excessive-permissions]: overly broad permissions
warning[excessive-permissions]: overly broad permissions
help[template-injection]: code injection via template expansion
help[template-injection]: code injection via template expansion
help[template-injection]: code injection via template expansion
error[unpinned-uses]: unpinned action reference
error[unpinned-uses]: unpinned action reference
info[anonymous-definition]: workflow or action definition without a name
help[concurrency-limits]: insufficient job-level concurrency limits
warning[secrets-outside-env]: secrets referenced without a dedicated environment
warning[secrets-outside-env]: secrets referenced without a dedicated environment
warning[secrets-outside-env]: secrets referenced without a dedicated environment
warning[secrets-outside-env]: secrets referenced without a dedicated environment
14 findings (1 unsafe fixes): 1 informational, 4 low, 7 medium, 2 high

وعلى الملف المصحح بنفس الأمر دون --format plain:

 INFO zizmor: 🌈 zizmor v1.30.1
 INFO audit: zizmor: 🌈 completed /repo/.github/workflows/deploy.yml
No findings to report. Good job!

في الإعداد أعلاه لاحظ التالي:

• الأداة لا تعرف أن base64 يكشف السر، فهي اعترضت على السطر لأنه يضع السر في نص السكربت، وفهم سبب الخطر عليك أنت، ولهذا هذا التمرين بلا أدوات أولاً.
• التعليق # v7.0.1 بجانب الرقم يجعل المراجعة مقروءة، وأدوات التحديث مثل Renovate وDependabot تحدث الرقم والتعليق معاً.
• في Gitea Actions تحمل ال Actions من github.com افتراضياً، فنفس القاعدة تنطبق، والفروق بين الصيغتين في صفحة المقارنة في توثيق Gitea.

للتفصيل: الاستخدام الآمن في توثيق GitHub Actions، وقسم الأسرار في دليل Gitea Actions.

غير صحيح، فبناءان من نفس الكود يعطيان نسختين مختلفتين من ال Image، والمخرج سوف يكون كما يلي:

$ docker build -q --no-cache -t lab-kata-ops-shop:staging .
sha256:d136fd58542dc65716556c27d0701f97bb96be3e68344cb8a6c2c12df446c865
$ docker build -q --no-cache -t lab-kata-ops-shop:prod .
sha256:d481ebea59763ec7282efdbb77a2563d3aeee275dacbb15f3d46fbb37fed7c89

والطريقة الصحيحة أن تبني مرة واحدة باسم يحمل رقم ال Commit، ثم تعطي نفس ال Image وسم كل بيئة:

$ docker build -q --no-cache -t lab-kata-ops-shop:git-3f2a9c1 .
$ docker tag lab-kata-ops-shop:git-3f2a9c1 lab-kata-ops-shop:staging
$ docker tag lab-kata-ops-shop:git-3f2a9c1 lab-kata-ops-shop:prod
$ docker images --no-trunc --format '{{.Repository}}:{{.Tag}} {{.ID}}' | grep lab-kata-ops-shop
lab-kata-ops-shop:git-3f2a9c1 sha256:625257182ab894d2b572090ceaa38507281c39d753555f207ed35277d5e1bb72
lab-kata-ops-shop:prod sha256:625257182ab894d2b572090ceaa38507281c39d753555f207ed35277d5e1bb72
lab-kata-ops-shop:staging sha256:625257182ab894d2b572090ceaa38507281c39d753555f207ed35277d5e1bb72

في الإعداد أعلاه لاحظ التالي:

• الاختلاف هنا من وقت الإنشاء على الأقل، ولكن في الواقع قد يكون أخطر: requirements.txt يثبت requests فقط، والمكتبات التي يعتمد عليها مثل urllib3 وcertifi قد تنزل بنسخة أحدث في البناء الثاني، فالذي اختبرته في Staging ليس ما ينشر في الإنتاج.
• الفروق بين البيئات (عنوان القاعدة، والأسرار، ومستوى السجلات) مكانها متغيرات البيئة والأسرار عند التشغيل، وليس داخل ال Image.
• في السجل Registry يكون المرجع الأدق هو الهاش Digest وليس الوسم، لأن الوسم يمكن نقله، فاكتب في ملف النشر image@sha256:... عندما تريد أن تضمن أن الإنتاج يشغل ما اختبرته بالضبط.

للتفصيل: قسم ابن مرة واحدة في دليل البيئات وGitOps.

الخيار الأسرع والأقل خطراً في العادة هو (ب)، أي أن تشغل ال Image السابق الموجود في السجل كما هو، لأنه نفس ما كان يعمل أمس ولا يحتاج بناء، والخيار (أ) يعيد مشكلة التمرين السابق، والخيار (ج) يحذف كل طلبات العملاء منذ الصباح. والتراجع بتغيير الوسم يعمل في المختبر كما يلي:

$ APP_TAG=1.8 docker compose up -d
 Container lab-kata-ops-web Started
$ curl -s http://127.0.0.1:21412/
shop version 1.8
$ APP_TAG=1.7 docker compose up -d
 Container lab-kata-ops-web Starting
 Container lab-kata-ops-web Started
$ curl -s http://127.0.0.1:21412/
shop version 1.7
$ docker compose up -d   (APP_TAG not set)
error while interpolating services.web.image: required variable APP_TAG is missing a value: set APP_TAG

لكن في هذه الحالة تحديداً الترحيل غير اسم العمود، والكود القديم لا يجده، فالتراجع بالكود وحده يعطي أخطاء أكثر من النسخة الجديدة:

alter table products rename column price to unit_price;
--- v1.7 code after rollback
select id, name, price from products;
ERROR:  column "price" does not exist
LINE 1: select id, name, price from products;
                         ^

ولذلك يصبح الخيار المتاح الآن هو (د) إذا كان الإصلاح صغيراً وواضحاً، أو أن تعيد تسمية العمود يدوياً ثم تتراجع ب (ب). والدرس للمرة القادمة أن الترحيل يجب أن يكون متوافقاً مع النسخة السابقة: في النسخة 1.8 تضيف العمود الجديد وتنسخ البيانات إليه وتبقي القديم (التوسيع Expand)، وبعد أن تستقر النسخة وتتأكد أنك لن تتراجع تحذف القديم في نسخة لاحقة (الانكماش Contract):

alter table products add column unit_price numeric;
update products set unit_price = price;
--- v1.7 code after rollback
select id, name, price from products;
 id |   name   | price
----+----------+-------
  1 | keyboard |   120
  2 | mouse    |    45
(2 rows)

--- v1.8 code
select id, name, unit_price from products;
 id |   name   | unit_price
----+----------+------------
  1 | keyboard |        120
  2 | mouse    |         45
(2 rows)

في الإعداد أعلاه لاحظ التالي:

• الصيغة ${APP_TAG:?set APP_TAG} تجعل Compose يرفض التشغيل إذا نسيت الوسم، بدل أن ينشر وسماً فارغاً أو latest.
• بين التوسيع والانكماش يكتب الكود الجديد في العمودين أو تزامنهما بطريقة أخرى، حتى تبقى البيانات صحيحة إذا تراجعت.
• خطة التراجع تكتب وتجرب قبل النشر وليس بعد ارتفاع الأخطاء، وهذا ما يجعل النشر في يوم عمل عادي ممكناً.

للتفصيل: دليل طرق نشر التطبيقات من FTP إلى GitOps، وقسم الترحيلات في دليل البيئات وGitOps، وقسم أوقف الضرر أولاً في دليل استكشاف الأخطاء.