بيئات المعاينة لمراجعات الشيفرة، الجزء 3: إعداد الوكيل العكسي (Reverse-proxy)
وصل الجزء الثالث من سلسلة بيئة المعاينة لمراجعات الشيفرة! نركّز فيه على إعداد خادم الوكيل العكسي (Reverse-proxy) وتنفيذه، وهو الخادم الذي نحتاجه لتوجيه البيانات بين النطاقات الفرعية والمجلدات الفرعية في حاوية AWS S3.
قبل أن تبدأ
هذا المقال هو الجزء الثالث من سلسلة مقالات تصف كيفية بناء بيئة معاينة (Preview) مخصّصة لكل مراجعة شيفرة (Merge Request).
أنجزنا حتى الآن مسارات GitLab CI/CD التي تُنشئ بيئات المعاينة في السحابة وتغلقها.
في هذا المقال نسلّط الضوء على إعداد خادم الوكيل العكسي (Reverse-proxy) وتنفيذه، وهو الخادم الذي نحتاجه من أجل توجيه البيانات بين النطاقات الفرعية والمجلدات الفرعية في حاوية AWS S3.
تشغيل خادم الوكيل العكسي محليًا
هدفنا الأول هو تجربته محليًا داخل حاوية Docker، لأن ذلك ممكن دون أي تكامل معقّد مع عنقود K8S، وهو ما سنشرحه بالطبع في المقالات القادمة.
يتيح لنا هذا الأسلوب التركيز على إعداد الوكيل العكسي نفسه، والتأكد من حلّ أي مشكلة قبل النشر على العنقود، دون الحاجة إلى التفكير في ملفات K8S manifests الآن.

اختيار تنفيذ الخادم
أولًا، لنفكّر هل نحتاج إلى خادم مخصّص يُكتب من الصفر (مثلًا بلغة Scala أو Java)، أم أن الحل الجاهز هو الخيار الأفضل.
في حالة الاستخدام لدينا، مهمة خادم الوكيل العكسي نمطية إلى حد كبير (فهي تظهر باستمرار في مشاريع تطبيقات الويب)، لذلك لا جدوى من كتابة خادم خاص بنا. بدلًا من ذلك يمكننا الاعتماد على حل جاهز طوّره مجتمع المصادر المفتوحة وحسّنه لسنوات، وهو أيضًا محسَّن الأداء وسليم البناء من ناحية الأمان.
تشمل الخيارات المتاحة (استنادًا إلى تصنيف أفضل خوادم الويب في 2022):
- Apache httpd
- Nginx
- Lighttpd
- Caddy
- إضافة إلى كثير غيرها…
خلصنا إلى أن من المنطقي، لاحتياجاتنا، النظر في أكثر خادمين شعبية وانتشارًا: Apache httpd وNginx.
حالة الاستخدام لدينا بسيطة: نحتاج إلى وكيل عكسي يفلتر النطاقات الفرعية ذات الحرف البديل (wildcard). هنا يحتاج Apache httpd إلى ملفات إعداد أكثر من Nginx، الذي يتميّز بأنه أكثر اختصارًا في هذا الجانب (وأكثر متعة في الإعداد بكثير). إضافة إلى ذلك، يُعدّ Nginx معيارًا شبه قياسي في عناقيد Kubernetes، فالاتساق يصبّ في مصلحته أيضًا. وفي النهاية اخترنا Nginx.
إذا أردت معرفة الفروق بين الخادمين في الأداء بدقة، فاطّلع على أي من مقالات المدونات الكثيرة التي تقارن بينهما، مثل Apache vs. Nginx.
الإعداد الأولي (المحلي) للخادم
سيعمل خادم Nginx في النهاية داخل حاوية ضمن Pod في k8s، لذا نقطة انطلاقنا هي ملف Dockerfile الخاص بـ Docker:
FROM nginx:1.23.1
# custom configuration
COPY ./nginx.conf /etc/nginx/conf.d/default.conf
نأخذ هنا صورة Docker الرسمية لـ Nginx بالإصدار 1.23.1 ونوسّعها بـإعداد مخصّص يُعرَّف فيه الوكيل.
هكذا يبدو ملف الإعداد nginx.conf:
server_names_hash_bucket_size 64;
server {
listen 80;
server_name ~(.*)\.staging\.nice-app\.com$;
set $subdomain $1;
set $destination_domain 'nice-app-staging.s3-website.eu-central-1.amazonaws.com';
location / {
resolver 192.168.65.5; # docker localhost DNS resolver
proxy_pass http://$destination_domain/$subdomain$uri$is_args$args;
}
}
نبدأ بضبط server_names_hash_bucket_size 64;، لأن أسماء التجزئة (hash) الموضوعة في النطاق الفرعي قد تكون طويلة. القيمة الافتراضية مرتبطة بذاكرة المعالج المؤقتة (عادةً 32)، لكننا رفعناها احتياطًا كي لا تسبب النطاقات الفرعية الأطول مشكلات.
بعد ذلك نعلن خادمًا جديدًا يستمع على port 80، ويلتقط النطاقات الفرعية المطابقة لنمط التعبير النمطي (.*)staging.nice-app.com$. يُاستخرَج الـ hash نفسه من النطاق الفرعي ويُخزَّن في المتغير $subdomain.
إضافة إلى ذلك، ضبطنا مسبقًا النطاق الوجهة، وهو عنوان URL لحاوية staging في AWS S3 التي حصلنا عليها سابقًا.
لكل مسار location / تُوجَّه الحركة إلى عنوان URL يُركَّب من المتغيرات أعلاه مع المتغيرات المضمّنة في Nginx (مثل $uri، أي النص الذي يلي النطاق، بما فيه أي وسائط HTTP GET في العنوان).
والصيغة الناتجة هي: «http://$destination_domain/$subdomain$uri$is_args$args»، وهي تشير إلى مجلد فرعي في حاوية AWS S3.
نعرّف أيضًا محلّل DNS على عنوان IP 192.168.65.5، يمكن الوصول إليه داخل بيئة Docker daemon المحلية. لماذا نحتاج إليه؟ لأننا وضعنا متغيرات داخل تعليمة proxy_pass في Nginx. في هذه الحالة يعتمد Nginx آلية وكيل مختلفة تمامًا عن تلك المستخدمة مع عنوان URL غير ديناميكي (أي نص ثابت بسيط دون متغيرات). وتظهر هذه المشكلة في كثير من نقاشات StackOverflow.
تذكّر أن هذا العنوان قد يختلف بين الأجهزة وأنظمة التشغيل وإصدارات Docker. لذا من المفيد التحقق مسبقًا من عنوان IP المطبّق في بيئتك المحلية (لن نشرح كيف، فهناك طرق كثيرة لذلك وهي تختلف بين إصدارات Docker).
التحضير للاختبار محليًا
بعد أن يصبح ملف Dockerfile وملف nginx.conf بالإعداد المخصّص جاهزين، يمكننا البدء بالتحضير للاختبارات.
بادئ ذي بدء، يجب أن تكون ملفات التطبيق موجودة في حاوية staging. لذلك ننشئ فرعًا جديدًا في مستودع Git الخاص بالتطبيق، ثم نستخدمه لفتح Merge Request في GitLab، فيطلق النشر (عبر مسار CI/CD الذي بنيناه في المقال السابق).
$ git checkout -b feature/test-MR
Switched to a new branch 'feature/test-MR'
$ "test" > TEST.md
$ git add .
$ git commit -m "testing MR deployment"
[feature/test-MR (root-commit) 8266b1c] testing MR deployment
1 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 TEST.md
$ git push --set-upstream origin feature/test-MR
أُضيف الملف لأغراض الاختبار فقط، حتى إذا أُنشئ الـ MR أطلق GitLab المسار الذي يرفع النطاق الفرعي الجديد والملفات إلى AWS.
بعد ذلك فتحنا يدويًا Merge Request جديدًا في GitLab، مع الفرع feature/test-MR مصدرًا والفرع main هدفًا.
أنتجت المهمة build-and-deploy-staging-for-review في المسار (Pipeline) عنوان URL التالي: «http://a4f194667b4fa23.staging.nice-app.com/»، حيث a4f194667b4fa23 هو hash الإيداع (commit)، ويُستخدم نطاقًا فرعيًا ومجلدًا فرعيًا في حاوية AWS S3 الخاصة بـ staging في آنٍ واحد.
وبعد أن أصبحت الملفات والـ hash جاهزين، يمكننا الاستفادة من ميزة في نظام التشغيل تتيح ربط نطاق بعنوان IP في البيئة المحلية.

يوجد هذا الإعداد في ملف مسارُه /etc/hosts (Linux/Mac) أو c:\Windows\System32\Drivers\etc\hosts (Windows). افتحه بصلاحيات المسؤول، وأضف السطر أدناه، ثم احفظ التغييرات:
127.0.0.1 a4f194667b4fa23.staging.nice-app.com
نتيجة لذلك، سيوجّهنا نظام التشغيل، عند طلب العنوان «http://a4f194667b4fa23.staging.nice-app.com»، إلى عنوان IP 127.0.0.1، أي localhost، حيث سيعمل Docker daemon مع صورة Nginx docker التي عرّفناها قبل بضع فقرات.
بفضل هذه الحيلة، يمكننا اختبار خادم الوكيل العكسي وتنقيحه محليًا دون الاعتماد على AWS Route 53 لمنطقة DNS الخاصة بـ «nice-app.com».
تشغيل الاختبارات محليًا
بعد ذلك، انتقل إلى مجلد المشروع المنفصل الذي يحتوي ملفات خادم الوكيل العكسي (نعرض قائمتها هنا لبيان الملفات التي نُسخت إليه).
$ cd /home/nice-app-developer/projects/staging-reverse-proxy
$ ls
Dockerfile nginx.conf
يمكننا الآن تشغيل حاوية Docker من الصورة المبنية من هذه الملفات (تأكد من تثبيت Docker ومن أن Docker daemon يعمل).
$ docker build -t reverse-proxy .
$ docker run -it --rm -d -p 80:80 --name reverse-proxy-server reverse-proxy
يفترض الآن أن نستطيع إرسال طلب إلى الخادم عبر النطاق الفرعي المعلن سابقًا. وفي الرد ينبغي أن نحصل على شيفرة HTML للتطبيق الذي رُفعت ملفاته (ومنها index.html) إلى AWS S3. المحتوى أدناه مجرد عينة أُعدّت كي لا نتوقف عند التطبيق نفسه هنا، بل لتوضيح شكل رد الخادم في مثل هذه الحالة.
$ curl http://a4f194667b4fa23.staging.nice-app.com/
<html>
<head><title>Nice-app application</title></head>
<body>
<center>Hello!</center>
</body>
</html>
مشكلات الاستضافة من حاوية AWS S3
أحسنتم! اجتازت آلية الوكيل العكسي في خادم Nginx اختباراتنا. لكن لا تنسوا أن هذه مجرد بداية الطريق، لأن عناوين URL في حاويات AWS S3 لها أنماط سلوك خاصة بها، وتأتي بـمشكلات خاصة بها، نصفها فيما يلي.
المشكلة 1: طريقة تعامل الاستضافة مع عناوين URL التي تنتهي بشرطة مائلة
تعمل استضافة الملفات المخزّنة في حاوية AWS S3 على النحو التالي: عندما ينتهي عنوان URL بشرطة مائلة / (ما يُسمّى «trailing slash»)، يبحث خادم الاستضافة أولًا عن مجلد في ذلك المسار، ثم عن ملف index.html بداخله، ويعيد محتواه في الرد.
فمثلًا، للعنوان «nice-app-staging.s3-website.eu-central-1.amazonaws.com/some-directory/» تحصل على محتوى الملف الموجود في some-directory/index.html. وإن لم يوجد هذا الملف تظهر صفحة خطأ 404 (انظر الصورة أدناه).
يختلف الأمر عندما يخلو العنوان من الشرطة المائلة الأخيرة. في هذه الحالة تتحقق استضافة AWS S3 من وجود ملف باسم some-directory (دون امتداد)، متجاهلةً تمامًا احتمال أن يكون مجلدًا لا ملفًا. وهكذا، حتى لو كان المجلد الفرعي some-directory يحتوي ملف index.html، فلن تُعرض الصفحة بالشكل الصحيح (مثال أدناه).
مع إعداد Nginx الحالي، تمرّر الدالة proxy_pass كل عنوان URL (سواء كان بشرطة مائلة أخيرة أم بدونها) إلى استضافة AWS S3، لذا قد نحصل مع عناوين URL الخالية من الشرطة المائلة الأخيرة على صفحات خطأ 404 بدلًا من صفحة التطبيق الفعلية (محتوى ملف HTML).
الحل
يمكننا إصلاح ذلك بالدالة rewrite، التي تعيد توجيه كل عنوان URL يخلو من الشرطة المائلة الأخيرة إلى العنوان نفسه مع إلحاق شرطة مائلة.
rewrite (.*[^\/])$ $1/ break;
المشكلة 2: إعادة توجيه عناوين URL الخاصة بالأصول (assets) بلا شرطة مائلة (مثل jpg وpng وcss وjs وغيرها).
حُلّت مشكلة الشرطة المائلة الأخيرة، لكننا في المقابل لم نعد قادرين على الوصول إلى ملفات الأصول. فتعليمة rewrite المضافة حديثًا تُلحق شرطة مائلة بملفات مثل *.jpg، فيبحث AWS S3 عن ملف index.html داخل مجلد ينتهي اسمه بـ .jpg/.
الحل
أبسط طريقة للالتفاف على ذلك هي تقسيم توجيه مسارات URL إلى نمطين: نمط يتعامل مع الملفات بلا شرطة مائلة أخيرة، وآخر يتعامل مع عناوين الصفحات الفرعية التي تنتهي بشرطة مائلة.
location ~* (.*\.[A-Za-z]+)$ { # all files with extension
resolver 192.168.65.5;
proxy_pass http://$destination_domain/$subdomain$uri$is_args$args;
}
location / {
resolver 192.168.65.5; # docker localhost DNS resolver
# adding a trailing slash to the end of URL if it does not exist (needed for proxy_pass to open AWS S3 directory, then to search for index.html inside)
rewrite (.*[^\/])$ $1/ break;
proxy_pass http://$destination_domain/$subdomain$uri$is_args$args;
}
كما يُظهر الكود أعلاه، فإن النمط الإضافي location ~* (.*[A-Za-z]+)$ يطابق عناوين URL التي تشير إلى ملفات ذات امتداد ولا تنتهي بشرطة مائلة، ويمرّرها دون أي تعليمة rewrite.
المشكلة 3: يمرّر Nginx عناوين URL بصيغة مفكوكة الترميز
تجلب الملفات مشكلة أخرى: يمكن أن تتضمن أسماؤها مسافات ورموزًا خاصة أخرى. للأسف، عند استخدام المتغير $uri يحوّل Nginx افتراضيًا عناوين URL المشفّرة سابقًا إلى صيغة مفكوكة الترميز، وهذا ما يُسلَّم إلى الدالة proxy_pass.
كان هذا الإعداد سيعمل على ما يرام لو قبلت AWS S3 عناوين URL المفكوكة هذه. وكما قد تتوقع، فإن الخدمة لا تقبلها.
بالنسبة إلى ملف يتضمن اسمه مسافات، مثل file with space.png، ستعرض استضافة AWS S3 خطأً يفيد بأنها لم تجد الملف.
في المقابل، ستُعثر على الصورة المطلوبة عند استخدام عنوان URL مشفّر، مثل file%20with%20space.png (حيث يمثّل %20 مسافة مشفّرة).
الحل
الحل هو إعادة ترميز جزء العنوان الذي فكّ Nginx ترميزه لأغراض معالجته. ولأن الدالة نفسها معقّدة نسبيًا، اخترنا امتدادًا لخادم Nginx يوفّرها. اسم الامتداد «OpenResty»، والدالة التي نحتاجها هي set_escape_uri.
ولتوفير وقت تثبيت الامتداد عبر أسطر إضافية في Dockerfile، اخترنا في هذا العرض التوضيحي صورة Nginx docker مُجهَّزة مسبقًا بالامتداد المطلوب.
أصبح Dockerfile الآن هكذا:
FROM openresty/openresty:1.21.4.1-3-buster-fat
# custom configuration
COPY ./nginx.conf /etc/nginx/conf.d/default.conf
وهذا هو ملف الإعداد nginx.conf الكامل:
server_names_hash_bucket_size 64;
server {
listen 80;
server_name ~(.*)\.staging\.nice-app\.com$;
set $subdomain $1;
set $destination_domain 'nice-app-staging.s3-website.eu-central-1.amazonaws.com';
location ~* (.*\.[A-Za-z]+)$ {
resolver 192.168.65.5;
set_escape_uri $escaped_uri $uri; # OpenResty Nginx module https://github.com/openresty/set-misc-nginx-module#set_escape_uri
proxy_pass http://$destination_domain/$subdomain$escaped_uri$is_args$args;
}
location / {
resolver 192.168.65.5; # docker localhost DNS resolver
# adding a trailing slash to the end of URL if it does not exist (needed for proxy_pass to open AWS S3 directory, then to search for index.html inside)
rewrite (.*[^\/])$ $1/ break;
proxy_pass http://$destination_domain/$subdomain$uri$is_args$args;
}
}
ملخص سريع
اخترنا تنفيذًا للخادم، وأعددنا (الوكيل العكسي) Reverse-proxy، وعالجنا المشكلات الناجمة عن طريقة عمل عناوين URL في استضافة AWS S3. كما اختبرنا كل شيء في بيئة محلية باستخدام Docker. لكن ما ينقصنا بعد هو نشر في السحابة يجعل الخادم متاحًا لعنقود Kubernetes الخاص بشركة العميل.
