DevOps والتشغيل الأدلة التقنية

Unleash على سيرفرك: الإطلاق التدريجي مع Kill Switch

نشغل Unleash لمتجر صغير ونطلق صفحة دفع جديدة للموظفين ثم لنصف العملاء، ونطفئها بالثواني، ونرى ماذا يحدث للتطبيق عندما يتوقف الخادم.

Unleash على سيرفرك: الإطلاق التدريجي مع Kill Switch

في مقال مفهوم Feature Flags والإطلاق التدريجي بنى فريق متجر إلكتروني صغير صفحة دفع جديدة، وأخفاها خلف Flag اسمه new_checkout، وأطلقها لموظفيه ثم لعشرة بالمئة من العملاء ثم لنصفهم. والفريق خمسة مطورين وشخص واحد في التشغيل، والمتجر يعمل على سيرفرين خلف Reverse Proxy، والآن جاء وقت القرار العملي: أي أداة يستضيفها الفريق لهذا العمل كل يوم، ومن يملك مفتاح الإطفاء، وماذا يحدث للمتجر في الليلة التي تتوقف فيها خدمة ال Flags نفسها؟ واختار الفريق أن يبدأ بأشهر أداة مفتوحة المصدر في هذا المجال، وهي Unleash، وأن يجربها بالتطبيق نفسه وال Flag نفسه قبل أن يقارنها بغيرها.

وهذا المقال هو الأول في سلسلة تطبيقية من مرحلة منصات للمطورين، نستخدم فيها مثال المتجر نفسه مع كل أداة، حتى تكون المقارنة في آخر السلسلة عادلة. ولن نعيد هنا شرح أنواع ال Flags أو فكرة الفصل بين النشر والإطلاق، فهي في مقال المفهوم، وإنما نركز على ما يخص Unleash: كيف يعمل من الداخل، وكيف تكتب قواعده، وماذا رأينا عندما شغلناه وأوقفناه وأعدنا تشغيله. وسوف نناقش في هذا المقال ما يلي:

  • لماذا اختار الفريق خدمة Flags مستقلة، وما الذي يقدمه Unleash تحديداً.
  • كيف يعمل Unleash من الداخل: الخادم وقاعدة البيانات وال SDK والتقييم المحلي والعدادات.
  • المشاريع والبيئات وأنواع التوكنات، ولماذا لا يعطى التطبيق توكن المدير.
  • استراتيجيات التفعيل Activation Strategies والقيود والمجموعات، والخانة الثابتة لكل مستخدم.
  • تجربة عملية كاملة: من التشغيل إلى نسبة 10% ثم 50%، والنسخ Variants، وال Kill Switch بالثواني.
  • ثلاث مشاكل حقيقية ظهرت لنا: تطبيق لا يبدأ، ونسخ اختفت، وملف نسخة احتياطية فارغ.
  • ماذا لو وضعنا Unleash Edge بين التطبيق والخادم، وما حدود النسخة المفتوحة اليوم.

لماذا خدمة Flags مستقلة؟ Why Unleash

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

وUnleash مشروع مفتوح المصدر تطوره شركة بالاسم نفسه، وتبيع فوقه نسخة تجارية وخدمة سحابية، والنسخة المفتوحة هي ما يستضيفه الفريق على سيرفره. والفكرة الأساسية فيه أن القواعد تكتب مرة واحدة في الخادم، وكل تطبيق يجلبها ويقيمها في ذاكرته، فلا يضيف Unleash أي اتصال شبكة إلى طلبات المستخدمين. وهذا ما جعل الفريق يبدأ به: المتجر لا يريد أن يصبح كل طلب دفع معلقاً بخادم آخر.

وقبل أن نبدأ، هناك أمر يجب أن تعرفه عن ترخيص المشروع، لأنه تغير في 2026. فمع الإصدار 8.0.0 في يونيو 2026 انتقل الكود المصدري في المستودع الرئيسي من Apache 2.0 إلى AGPLv3، ويقول إعلان الإصدار إن صور Docker الرسمية تبقى بترخيص Apache 2.0، وإن ال SDKs تبقى بتراخيصها المتساهلة، وإن التغيير يهمك إذا عدلت كود الخادم نفسه وقدمته لغيرك عبر الشبكة، وتفصيل ذلك في تدوينة الشركة عن التغيير. أما الفريق الذي يشغل الصورة الرسمية كما هي لمتجره، فلا يتغير عليه شيء.

كيف يعمل Unleash من الداخل؟ Architecture

يتكون Unleash من خادم واحد مكتوب ب Node.js، ومعه قاعدة بيانات PostgreSQL يحفظ فيها كل شيء: ال Flags والاستراتيجيات والمجموعات والتوكنات وسجل الأحداث والعدادات. والخادم نفسه يقدم لوحة الإدارة وواجهة الإدارة البرمجية Admin API وواجهة العملاء Client API التي تتصل بها ال SDKs. والصورة التالية تبين أين تعيش القواعد وأين يحدث التقييم:

فريق المتجر يغير القواعد من لوحة الإدارة أو Admin API في خادم Unleash 8.3.1 الذي يحفظها في PostgreSQL، وتطبيق المتجر shop-backend فيه unleash-client 6.12.2 يجلب القواعد من GET /api/client/features كل 15 ثانية بتوكن backend ويقيم محلياً في isEnabled، ويرسل عدد yes وno لكل Flag إلى POST /api/client/metrics، ويحفظ ملف نسخة احتياطية في /tmp، وفي الأعلى مربع متقطع لخيار Unleash Edge مع ملاحظة أن نسخته المفتوحة تنتهي صيانتها في 31 ديسمبر 2026
القواعد في الخادم، والتقييم داخل تطبيقك، والعدادات تعود إلى الخادم

وفي الصورة أعلاه لاحظ ثلاثة مسارات منفصلة. الأول من الفريق إلى الخادم، وهو مسار التغيير: تغيير نسبة أو إطفاء ميزة. والثاني من الخادم إلى التطبيق، وهو مسار الجلب Polling، حيث يطلب ال SDK كل القواعد التي يسمح بها توكنه كل 15 ثانية بشكل افتراضي، ويحفظها في الذاكرة، ثم يقيم كل استدعاء ل isEnabled محلياً دون أي اتصال. والثالث من التطبيق إلى الخادم، وهو مسار العدادات Metrics، حيث يرسل ال SDK كل دقيقة عدد المرات التي قيم فيها كل Flag ونتيجتها، فيعرف Unleash أن ال Flag مستخدم فعلاً في الإنتاج، وكم مستخدماً رأى الميزة.

وهذا التصميم له نتيجة مهمة يجب أن تتذكرها: تغيير القاعدة لا يصل فوراً، وإنما في دورة الجلب التالية لكل سيرفر، وكل سيرفر له دورته الخاصة. فإذا كان عندك سيرفران وأطفأت الميزة، فقد يرى عميل الصفحة الجديدة على سيرفر لبضع ثوان بعد أن اختفت من الآخر. وسوف نقيس هذه المدة في التجربة.

المشاريع والبيئات والتوكنات Projects, Environments, Tokens

كل Flag في Unleash يعيش داخل مشروع Project، وله حالة مستقلة في كل بيئة Environment، فيكون مفعلاً في development ومطفأ في production، ولكل بيئة استراتيجياتها. والنسخة المفتوحة تأتي بمشروع واحد اسمه default وبيئتين هما development وproduction، وهذا حد ثابت في النسخة المفتوحة كما سوف نرى.

ويتصل كل شيء بالخادم بتوكن API Token، والأنواع ثلاثة، والفرق بينها مهم للأمان، كما يشرح توثيق التوكنات:

  • توكن الإدارة Admin Token: يغير كل شيء، وهو ما استخدمناه لنكتب الإعداد بسكربت، ومكانه خط CI أو أداة الإدارة فقط، ولا يدخل تطبيقاً أبداً.
  • توكن الخلفية Backend Token: لتطبيقات السيرفر، مربوط ببيئة واحدة ومشاريع محددة، ويجلب القواعد كاملة حتى يقيمها ال SDK محلياً، لذلك هو سر يحفظ مع أسرار التطبيق كما شرحنا في إدارة الأسرار.
  • توكن الواجهة Frontend Token: للمتصفح والجوال، ولا يعطي القواعد وإنما النتائج المحسوبة لمستخدم واحد، لأن كل ما يصل إلى المتصفح يستطيع أي شخص أن يقرأه.

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

استراتيجيات التفعيل Activation Strategies

عندما تفعل Flag في بيئة، فأنت لا تفتحه للجميع، وإنما تضيف له استراتيجية Strategy أو أكثر، وكل استراتيجية تقول «افتح الميزة لهؤلاء». والاستراتيجية الأساسية في Unleash اليوم هي الإطلاق التدريجي Gradual Rollout، واسمها الداخلي flexibleRollout، ولها ثلاثة معاملات: النسبة، والصفة التي يحسب عليها الالتصاق Stickiness، ومعرف المجموعة groupId. ويمكنك أن تضيف لكل استراتيجية قيوداً Constraints على صفات الطلب، مثل «الخطة تساوي pro»، أو أن تربطها بمجموعة Segment معرفة مسبقاً، وتفصيل ذلك في توثيق الاستراتيجيات. والصورة التالية تبين كيف قيم Unleash ال Flag في تجربتنا لثلاثة مستخدمين:

سياق الطلب لثلاثة مستخدمين: staff-1 بخطة staff وخانة 36، وuser-11 بخطة free وخانة 4، وuser-7 بخطة free وخانة 54، ثم الاستراتيجية الأولى staff first بمجموعة staff وشرط plan IN staff ونسبة 100%، ثم OR، ثم الاستراتيجية الثانية customers 50% التي تحسب murmur3 لنص new_checkout مع userId باقي القسمة على 100 زائد 1، وتفتح الميزة إذا كانت الخانة 50 أو أقل، وفيها نسختان one_page وtwo_steps بنسبة 50% لكل منهما، والنتائج: staff-1 مفعل بالاستراتيجية الأولى، وuser-11 مفعل لأن خانته 4، وuser-7 مطفأ لأن خانته 54
الاستراتيجيات بينها «أو»، والقيود داخل الاستراتيجية بينها «و»

وفي الصورة أعلاه لاحظ قاعدتين في القراءة. الأولى أن الاستراتيجيات في البيئة الواحدة بينها «أو»، فيكفي أن تطابق واحدة منها حتى تفتح الميزة، لذلك كتبنا استراتيجية للموظفين واستراتيجية للعملاء بدل استراتيجية واحدة معقدة. والثانية أن القيود والمجموعات داخل الاستراتيجية الواحدة بينها «و»، فالموظف يجب أن يكون في مجموعة staff وأن يقع ضمن النسبة، والنسبة هنا 100% فكل موظف يدخل.

لماذا لا يتبدل المستخدم بين الصفحتين؟ Stickiness

شرحنا في مقال المفهوم أن الإطلاق التدريجي يعتمد على دالة هاش Hash ثابتة لمعرف المستخدم، وفي Unleash رأينا الدالة نفسها في كود ال SDK: يحسب murmur3 على النص groupId:userId، ثم يأخذ باقي القسمة على 100 ويضيف 1، فيخرج رقم من 1 إلى 100 نسميه الخانة Bucket، وتفتح الميزة إذا كانت الخانة أقل من النسبة أو تساويها. وال groupId هو اسم ال Flag بشكل افتراضي، ولذلك يقع المستخدم نفسه في خانة مختلفة في كل Flag، فلا يتحمل المستخدمون أنفسهم كل التجارب في الوقت نفسه. وتفصيل اختيار الصفة في توثيق الالتصاق.

وقد يتساءل البعض: لماذا يكون الالتصاق على userId وليس على الجلسة؟ والإجابة أن الجلسة تتغير إذا فتح العميل المتجر من جواله بعد أن بدأ من حاسوبه، فيرى صفحة دفع مختلفة في منتصف الطلب. لذلك اختر صفة ثابتة للعميل نفسه، واستخدم الجلسة sessionId فقط للزوار الذين لم يسجلوا الدخول، وانتبه إلى أن الزائر الذي يسجل الدخول ينتقل من خانة الجلسة إلى خانة حسابه، وقد يرى الصفحة الأخرى مرة واحدة.

تجربة عملية Lab: Unleash مع PostgreSQL

الآن سوف نشغل Unleash 8.3.1 مع PostgreSQL 18، وننشئ ال Flag نفسه new_checkout لمتجرنا، ونكتب تطبيق Node.js يستخدم unleash-client 6.12.2، ثم نطلق الميزة للموظفين ثم ل 10% ثم 50%، ونضيف نسختين للصفحة، ونطفئها بال Kill Switch ونقيس المدة، ونوقف الخادم بطرق مختلفة لنرى ماذا يحدث للمتجر. وتحتاج التجربة إلى Docker فقط، والخادم على 127.0.0.1 فقط.

تشغيل الخادم Docker Compose

الملف التالي مبني على ملف Compose في مستودع المشروع، بعد تثبيت رقم الإصدار، وتغيير صورة قاعدة البيانات، وإضافة كلمة مرور لها بدل وضع trust الذي يستخدمه الملف الأصلي:

name: wr-ff-unleash

services:
  db:
    image: postgres:18-alpine
    container_name: wr-ff-unleash-db
    environment:
      POSTGRES_DB: unleash
      POSTGRES_USER: unleash
      POSTGRES_PASSWORD: lab-db-pass
    volumes:
      - pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d unleash -U unleash"]
      interval: 2s
      retries: 30

  unleash:
    image: unleashorg/unleash-server:8.3.1
    container_name: wr-ff-unleash-server
    environment:
      DATABASE_URL: postgres://unleash:lab-db-pass@db:5432/unleash
      DATABASE_SSL: "false"
      LOG_LEVEL: warn
      # one admin token to script the setup; create real tokens per app afterwards
      INIT_ADMIN_API_TOKENS: "*:*.lab-admin-token-change-me"
    ports:
      - "127.0.0.1:44242:4242"
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:
    name: wr-ff-unleash-pgdata

networks:
  default:
    name: wr-ff-unleash-net

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

  • ال Volume مربوط على /var/lib/postgresql وليس على data تحته، لأن صور PostgreSQL 18 غيرت مكان البيانات الافتراضي، وربطه على المسار القديم يجعل البيانات خارج ال Volume دون أن تنتبه.
  • INIT_ADMIN_API_TOKENS ينشئ توكن إدارة عند أول تشغيل، واستخدمناه لنكتب الإعداد كله بسكربت يمكن إعادته، وفي الإنتاج احذفه بعد الإعداد وأنشئ التوكنات من اللوحة.
  • المنفذ على 127.0.0.1 فقط، وفي الإنتاج تضع اللوحة خلف Reverse Proxy بشهادة TLS، أما التطبيقات فتتصل بالخادم من الشبكة الداخلية.

ثم نشغل الخدمتين ونتأكد من الخادم:

docker compose up -d
curl -s localhost:44242/health
curl -s -H "Authorization: *:*.lab-admin-token-change-me" localhost:44242/api/admin/instance-admin/statistics
{"health":"GOOD"}
{"timestamp":"2026-11-05T08:21:16.270Z","instanceId":"cdb808ff-…","versionOSS":"8.3.1","versionEnterprise":"","users":1,"serviceAccounts":0,"apiTokens":{"admin":1},…,"projects":1,"contextFields":5,"roles":6,…,"environments":2,"segments":0,"strategies":4,…}

والمخرج يؤكد ما قلناه عن النسخة المفتوحة: versionEnterprise فارغ، ومشروع واحد، وبيئتان، وخمسة حقول سياق Context Fields جاهزة منها userId وsessionId. واستهلك الخادم في التجربة نحو 82 ميجابايت من الذاكرة، وقاعدة البيانات نحو 86 ميجابايت، وحجم صورة الخادم 537 ميجابايت.

أول Flag مع Segment للموظفين

القيود في Unleash تكتب على حقول السياق، والحقل plan غير موجود، لذلك ننشئه أولاً مع قيمه المسموحة، ثم ننشئ مجموعة staff، ثم ال Flag نفسه من نوع release:

U=http://127.0.0.1:44242; A="Authorization: *:*.lab-admin-token-change-me"; J='Content-Type: application/json'
curl -s -X POST $U/api/admin/context -H "$A" -H "$J" -d '{"name":"plan","description":"customer plan","legalValues":[{"value":"free"},{"value":"pro"},{"value":"staff"}],"stickiness":false}'
curl -s -X POST $U/api/admin/segments -H "$A" -H "$J" -d '{"name":"staff","description":"shop employees","project":null,"constraints":[{"contextName":"plan","operator":"IN","values":["staff"],"inverted":false,"caseInsensitive":false}]}'
curl -s -X POST $U/api/admin/projects/default/features -H "$A" -H "$J" -d '{"name":"new_checkout","type":"release","description":"New checkout page. Release flag: remove after full rollout. Owner: payments team","impressionData":true}'
{"name":"plan","description":"customer plan","stickiness":false,"sortOrder":0,"legalValues":[{"value":"free"},{"value":"pro"},{"value":"staff"}],"createdAt":"2026-11-05T08:21:51.204Z"} HTTP 201
{"id":1,"name":"staff","description":"shop employees","constraints":[{"values":["staff"],"inverted":false,"operator":"IN","contextName":"plan","caseInsensitive":false}],"createdBy":"admin","createdAt":"2026-11-05T08:21:51.584Z"} HTTP 201
{"name":"new_checkout","description":"New checkout page. Release flag: remove after full rollout. Owner: payments team","type":"release","project":"default","stale":false,"createdAt":"2026-11-05T08:21:51.860Z","impressionData":true,"archived":false} HTTP 201

لاحظ أن الوصف يحمل نوع ال Flag ومالكه ومتى يحذف، وهي العادة التي اتفقنا عليها في مقال المفهوم ضد ال Flags المنسية. ولاحظ impressionData: true، وهو يجعل ال SDK يطلق حدثاً مع كل تقييم لهذا ال Flag، وسوف نستخدمه في السجلات. ثم نضيف الاستراتيجيتين في بيئة الإنتاج، ونفعل البيئة، وننشئ توكن الخلفية للمتجر:

P=$U/api/admin/projects/default/features/new_checkout/environments/production
curl -s -X POST $P/strategies -H "$A" -H "$J" -d '{"name":"flexibleRollout","title":"staff first","parameters":{"rollout":"100","stickiness":"default","groupId":"new_checkout"},"constraints":[],"segments":[1]}'
curl -s -X POST $P/strategies -H "$A" -H "$J" -d '{"name":"flexibleRollout","title":"customers 10%","parameters":{"rollout":"10","stickiness":"userId","groupId":"new_checkout"},"constraints":[]}'
curl -s -X POST $P/on -H "$A"
curl -s -X POST $U/api/admin/api-tokens -H "$A" -H "$J" -d '{"tokenName":"shop-backend","type":"backend","environment":"production","projects":["default"]}'
{"id":"01M6NCSY0KF9XK1YR9QAMTMGSY","name":"flexibleRollout","constraints":[],"parameters":{"groupId":"new_checkout","rollout":"100","stickiness":"default"},"variants":[],"segments":[1],"title":"staff first","disabled":false,"sortOrder":0} HTTP 200
{"id":"01M6NCSYAE0QSVJBNBZKMGTMGB","name":"flexibleRollout","constraints":[],"parameters":{"groupId":"new_checkout","rollout":"10","stickiness":"userId"},"variants":[],"segments":[],"title":"customers 10%","disabled":false,"sortOrder":1} HTTP 200
 HTTP 200
{"projects":["default"],"tokenName":"shop-backend","type":"backend","environment":"production",…,"secret":"default:production.v2_cQEe…","project":"default"} HTTP 201

والتوكن يبدأ باسم المشروع ثم البيئة، أي default:production، فتعرف من أول نظرة أين يعمل، وهذا مفيد عندما تجد توكناً منسياً في ملف إعداد. ولاحظ أن ترتيب الاستراتيجيات sortOrder محفوظ، والتقييم يمر عليها بالترتيب ويتوقف عند أول واحدة تطابق.

تطبيق المتجر مع Node SDK

نضع إنشاء عميل Unleash في ملف واحد، كما فعلنا مع Flagsmith في مقال المفهوم، حتى يبقى باقي الكود بعيداً عن تفاصيل الأداة. والملف unleash.mjs في نسخته الأولى كان كما يلي:

// One place that creates the Unleash client for the shop backend.
import { initialize } from 'unleash-client';

export const unleash = initialize({
  url: process.env.UNLEASH_URL,                 // http://unleash:4242/api/
  appName: 'shop-backend',
  instanceId: process.env.HOSTNAME,
  customHeaders: { Authorization: process.env.UNLEASH_TOKEN },   // backend token for production
  refreshInterval: Number(process.env.REFRESH_MS || 15000),       // SDK default is 15 s
  metricsInterval: 10000,                                          // send yes/no counts every 10 s (default 60 s)
});

// Wait until the SDK has rules, either from the server or from its backup file
export const ready = () => new Promise((resolve) => unleash.once('synchronized', resolve));

في الكود أعلاه لاحظ أن appName هو الاسم الذي يظهر في لوحة Unleash عند كل Flag يستخدمه هذا التطبيق، فاختر اسماً ثابتاً لكل خدمة، وأن instanceId يميز كل سيرفر عن الآخر. وجعلنا فترة إرسال العدادات 10 ثوان حتى نراها بسرعة في التجربة، أما الافتراضي فدقيقة، وهو مناسب للإنتاج. ثم نشغل التطبيق في Container على شبكة Unleash نفسها:

docker run -d --name wr-ff-unleash-app --network wr-ff-unleash-net -w /app \
  -e UNLEASH_URL=http://unleash:4242/api/ -e "UNLEASH_TOKEN=default:production.v2_cQEe…" \
  node:22-slim sleep infinity
docker cp . wr-ff-unleash-app:/app/ && docker exec wr-ff-unleash-app npm install --no-audit --no-fund

وسوف ترى بعد قليل أن السطر الأخير في unleash.mjs، أي انتظار الحدث synchronized، كان أول مشكلة حقيقية في هذه التجربة.

من 10% إلى 50%: Gradual Rollout

السكربت rollout.mjs يقيم ال Flag لألف عميل، ويحفظ من فتحت لهم الميزة، ويتحقق في المرة التالية هل بقوا:

// How many of 1000 customers get the new checkout? Run again after changing the percentage.
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { unleash, ready } from './unleash.mjs';

await ready();
const on = [];
for (let i = 1; i <= 1000; i++) {
  if (unleash.isEnabled('new_checkout', { userId: `user-${i}`, properties: { plan: 'free' } }, false)) on.push(i);
}
console.log(`new_checkout ON for ${on.length} of 1000 users, first: ${on.slice(0, 5).map(i => 'user-' + i).join(' ')}`);
const file = '/tmp/last-rollout.json';
if (existsSync(file)) {
  const before = JSON.parse(readFileSync(file, 'utf8'));
  console.log(`of the ${before.length} users who had it before, ${before.filter(i => on.includes(i)).length} still have it`);
}
writeFileSync(file, JSON.stringify(on));
console.log('staff-1 (plan=staff):', unleash.isEnabled('new_checkout', { userId: 'staff-1', properties: { plan: 'staff' } }, false));
unleash.destroy();

لاحظ أن الصفات المخصصة مثل plan تكتب داخل properties، أما userId وsessionId فحقول أساسية في السياق. ولاحظ المعامل الثالث false، وهو القيمة التي تعود إذا لم يجد ال SDK ال Flag أصلاً. والمخرج عند 10% كان كما يلي:

$ docker exec wr-ff-unleash-app node rollout.mjs
new_checkout ON for 103 of 1000 users, first: user-11 user-15 user-32 user-44 user-47
staff-1 (plan=staff): true

ثم نرفع النسبة إلى 50 بتعديل الاستراتيجية نفسها، وهو ما يعادل تحريك المؤشر في اللوحة، ونعيد تشغيل السكربت دون أي تغيير في الكود:

curl -s -X PUT $P/strategies/01M6NCSYAE0QSVJBNBZKMGTMGB -H "$A" -H "$J" \
  -d '{"name":"flexibleRollout","title":"customers 50%","parameters":{"rollout":"50","stickiness":"userId","groupId":"new_checkout"},"constraints":[]}'
new_checkout ON for 511 of 1000 users, first: user-2 user-3 user-4 user-5 user-8
of the 103 users who had it before, 103 still have it
staff-1 (plan=staff): true

في المخرج أعلاه لاحظ التالي:

  • 103 ثم 511 بدل 100 و500، والفرق طبيعي مع الهاش على ألف مستخدم فقط، وهي أرقام قريبة جداً مما رأيناه مع Flagsmith في مقال المفهوم (106 و481) رغم اختلاف الدالة.
  • كل ال 103 الذين رأوا الصفحة الجديدة عند 10% بقوا يرونها عند 50%، فلم يرجع أحد إلى الصفحة القديمة.
  • الموظف staff-1 مفعل في الحالتين، لأن استراتيجية الموظفين لا تعتمد على النسبة.

الخانة Bucket لكل مستخدم

حتى لا نأخذ كلام التوثيق كما هو، استدعينا الدالة التي يستخدمها ال SDK نفسه لنرى خانة كل مستخدم في Flag المتجر وفي Flag آخر:

// Which bucket (1..100) does each user fall in for the flag new_checkout?
const { normalizedStrategyValue } = require('unleash-client/lib/strategy/util');
for (const u of ['user-11', 'user-2', 'user-7', 'staff-1']) console.log(u, normalizedStrategyValue(u, 'new_checkout'));
for (const u of ['user-11', 'user-2', 'user-7']) console.log(u, 'in group other_flag:', normalizedStrategyValue(u, 'other_flag'));
user-11 4
user-2 25
user-7 54
staff-1 36
user-11 in group other_flag: 76
user-2 in group other_flag: 97
user-7 in group other_flag: 47

والمخرج يفسر كل ما رأيناه: user-11 في الخانة 4، لذلك كان من أول من رأوا الميزة عند 10%، وuser-2 في الخانة 25 فدخل عند 50% فقط، وuser-7 في الخانة 54 فلن يرى الميزة حتى تتجاوز النسبة 54%. ولاحظ السطور الثلاثة الأخيرة: المستخدمون أنفسهم في خانات مختلفة تماماً عندما يتغير groupId، فمن كان من أول عشرة بالمئة في ميزة الدفع يكون في آخر الصف في ميزة أخرى. وهذا يعني أيضاً أنك إذا أردت أن تطلق ميزتين مرتبطتين للمستخدمين أنفسهم، كصفحة الدفع الجديدة وصفحة تأكيد الطلب الجديدة، فاجعل لهما groupId واحداً.

النسخ داخل الاستراتيجية Strategy Variants

ثم أراد فريق المنتج أن يجرب شكلين للصفحة الجديدة: صفحة واحدة، أو خطوتين. وفي Unleash تضيف النسخ Variants إلى الاستراتيجية نفسها، فيحصل كل من فتحت له الميزة على نسخة ثابتة مع قيمة Payload يقرؤها الكود، كما في توثيق النسخ:

curl -s -X PUT $P/strategies/01M6NCSYAE0QSVJBNBZKMGTMGB -H "$A" -H "$J" -d '{"name":"flexibleRollout","title":"customers 50%",
  "parameters":{"rollout":"50","stickiness":"userId","groupId":"new_checkout"},"constraints":[],
  "variants":[{"name":"one_page","weight":500,"weightType":"variable","stickiness":"userId","payload":{"type":"json","value":"{\"steps\":1}"}},
              {"name":"two_steps","weight":500,"weightType":"variable","stickiness":"userId","payload":{"type":"json","value":"{\"steps\":2}"}}]}'

والأوزان من 1000، فكل نسخة 500 أي النصف. ثم كتبنا سكربتاً يعد النسخ لألف عميل عبر getVariant:

// Strategy variants: inside the 50% who get the new checkout, which layout does each user get?
import { unleash, ready } from './unleash.mjs';
await ready();
const count = {};
for (let i = 1; i <= 1000; i++) {
  const v = unleash.getVariant('new_checkout', { userId: `user-${i}` });
  const key = v.feature_enabled ? v.name : `flag off (${v.name})`;
  count[key] = (count[key] || 0) + 1;
}
console.log(count);
const v = unleash.getVariant('new_checkout', { userId: 'user-2' });
console.log('user-2 ->', JSON.stringify(v));
unleash.destroy(); process.exit(0);

وكان المخرج الأول مفاجئاً:

{ 'flag off (disabled)': 489, disabled: 511 }
user-2 -> {"name":"disabled","enabled":false,"feature_enabled":true,"featureEnabled":true}

ال 511 المفعلة لهم الميزة حصلوا كلهم على نسخة اسمها disabled، أي لا نسخة. وكنا في تلك اللحظة قد غيرنا ready() لتنتظر الحدث ready بدل synchronized لأسباب سوف نشرحها في القسم التالي، والفرق بين الحدثين هو سبب هذه النتيجة. فالحدث ready يطلق عندما يجد ال SDK قواعد يعمل بها، ومنها ملف النسخة الاحتياطية الذي حفظه في التشغيل السابق، وذلك الملف كتب قبل أن نضيف النسخ. أي أن السكربت قيم ألف مستخدم بقواعد قديمة من القرص قبل أن يصل الجلب الأول من الخادم. وعندما جعلناه ينتظر حتى ثلاث ثوان للحدث synchronized أولاً، ظهرت النتيجة الصحيحة:

ready: ready
synchronized: true
{ 'flag off': 489, two_steps: 253, one_page: 258 }
user-2 -> {"name":"two_steps","enabled":true,"payload":{"type":"json","value":"{\"steps\":2}"},"feature_enabled":true,"featureEnabled":true}

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

ولاحظ أن الأرقام 253 و258 داخل ال 511 قريبة من النصف، وأن ال SDK يحسب خانة النسخة ببذرة Seed مختلفة عن خانة الإطلاق، فلا تكون كل الخانات الصغيرة في نسخة واحدة. وإذا أردت أن تعرف أي النسختين أفضل للمبيعات، فهذا عمل أداة تجارب تقيس النتيجة وتحسب الفرق، وهو موضوع مقال GrowthBook في هذه السلسلة.

ال Kill Switch أثناء عمل المتجر

السكربت watch.mjs يتصرف كسيرفر يعمل، فيطبع كل ثانية ما يراه user-11، وبعد ست ثوان أطفأنا البيئة كلها من ال API، وهو ما يعادل مفتاح البيئة في اللوحة:

// Behaves like a running server: what does user-11 (bucket 4) see, every second?
import { unleash, ready } from './unleash.mjs';
await ready();
const t0 = Date.now();
const timer = setInterval(() => {
  const s = Math.round((Date.now() - t0) / 1000);
  const v = unleash.isEnabled('new_checkout', { userId: 'user-11' }, false);
  console.log(`${new Date().toISOString().slice(11, 19)} t=${String(s).padStart(2)}s user-11=${v}`);
  if (s >= Number(process.env.SECONDS || 30)) { clearInterval(timer); unleash.destroy(); }
}, 1000);
08:24:17 kill switch: production off
08:24:14 t= 1s user-11=true
08:24:15 t= 2s user-11=true
…
08:24:27 t=14s user-11=true
08:24:28 t=15s user-11=true
08:24:29 t=16s user-11=false
08:24:30 t=17s user-11=false
…
08:24:41 t=28s user-11=false

أطفأنا الميزة في 08:24:17، ورأى التطبيق ذلك في 08:24:29، أي بعد 12 ثانية، والسبب أن ال SDK يجلب القواعد كل 15 ثانية، فالإطفاء يصل في الدورة التالية، وأسوأ حالة 15 ثانية لكل سيرفر. والصورة التالية تلخص ما حدث:

خط زمني من 08:24:14 إلى 08:24:41، الجزء الأول أخضر فيه user-11 = true وصفحة الدفع الجديدة، والإطفاء production off في 08:24:17، ثم سهم 12 ثانية إلى next fetch في 08:24:29 حيث يبدأ الجزء الأحمر user-11 = false والصفحة القديمة، وتحته ثلاث بطاقات: refreshInterval 15000 الافتراضي حتى 15 ثانية لكل سيرفر، وrefreshInterval 2000 أسرع ولكن الطلبات أكثر بنحو سبع مرات، ودون بناء أو نشر أو إعادة تشغيل والمسار القديم يجب أن يبقى صالحاً
ال Kill Switch يصل مع دورة الجلب التالية

وماذا لو كانت 15 ثانية كثيرة على متجر في يوم تخفيضات؟ أعدنا التجربة نفسها بفترة جلب ثانيتين:

$ docker exec -e REFRESH_MS=2000 wr-ff-unleash-app node watch.mjs
08:56:38 kill switch: production off
08:56:38 t= 5s user-11=true
08:56:39 t= 6s user-11=true
08:56:40 t= 7s user-11=false

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

ماذا لو توقف Unleash؟ What If

هذا هو السؤال الذي يجب أن تجيب عنه قبل أن تضع أي خدمة Flags في طريق المتجر. شغلنا watch.mjs أربعين ثانية، وأوقفنا Container الخادم بعد خمس ثوان:

08:26:12 docker stop wr-ff-unleash-server
08:26:09 t= 1s user-11=true
…
08:26:41 t=33s user-11=true
FetchError: Unleash Repository error: request to http://unleash:4242/api/client/features failed, reason: getaddrinfo ENOTFOUND unleash
08:26:42 t=34s user-11=true
…
08:26:48 t=40s user-11=true
exit code 0

العملية التي كانت تعمل لم تتأثر، فبقيت على آخر قواعد في الذاكرة، وهذه ميزة التقييم المحلي. ولكن لاحظ أن أول خطأ ظهر في السجل بعد نحو عشرين ثانية من التوقف، أي أن تطبيقك لن يخبرك فوراً أن خدمة ال Flags متوقفة، لذلك راقب الخادم نفسه بنقطة /health كما شرحنا في التنبيهات، ولا تنتظر أن تشتكي التطبيقات.

والسؤال الأصعب هو العملية الجديدة: Container يعاد تشغيله أثناء العطل، أو نشر جديد في تلك الليلة. وهنا ظهرت المشكلة الأولى.

مشكلة حقيقية: التطبيق لا يبدأ Synchronized

شغلنا rollout.mjs بنسخته الأولى والخادم متوقف، ووضعنا عليه حداً أقصى ستين ثانية:

$ time timeout 60 node rollout.mjs   # Unleash is down, backup file present
FetchError: Unleash Repository error: request to http://unleash:4242/api/client/features failed, reason: getaddrinfo ENOTFOUND unleash
    at ClientRequest.<anonymous> (/app/node_modules/minipass-fetch/lib/index.js:130:14)
    …
Warning: Detected unsettled top-level await at file:///app/rollout.mjs:5
await ready();
^

real	0m27.201s
exit code: 13

السكربت لم يقيم مستخدماً واحداً. والسبب في السطر الذي كتبناه في unleash.mjs: انتظار الحدث synchronized، وهذا الحدث لا يطلق إلا بعد جلب ناجح من الخادم، والخادم متوقف، فبقي الانتظار معلقاً حتى فرغت حلقة الأحداث وأنهى Node العملية بالرمز 13. وفي سيرفر حقيقي لن تنتهي العملية، لأن سيرفر HTTP يبقيها حية، وإنما سوف يبقى المتجر معلقاً لا يستقبل أي طلب حتى يعود Unleash. وهذا هو بالضبط ما تفعله الدالة startUnleash الموجودة في أمثلة ال SDK، فهي بحسب توثيق Node SDK تنتظر حتى «يتزامن ال SDK بالكامل مع Unleash API».

والإصلاح هو ما يجب أن تكتبه في كل تطبيق: انتظر القواعد الطازجة مدة قصيرة، فإذا لم تصل فاعمل بما عندك، سواء كان ملف النسخة الاحتياطية أو القيم الافتراضية في الكود. والنسخة النهائية من unleash.mjs كما يلي:

unleash.on('error', (err) => console.error(`[unleash] ${err.message}`));   // log, never crash

// Start serving with fresh rules from the server. If Unleash does not answer within 3 s, fall back to the
// backup file (rules from the last good fetch), and with no backup file, to the safe defaults in the code.
let hasRules = false;
unleash.on('ready', () => { hasRules = true; });   // fired by the backup file or the first fetch

export const ready = (ms = 3000) => new Promise((resolve) => {
  if (unleash.isSynchronized()) return resolve('synchronized: fresh rules from Unleash');
  unleash.once('synchronized', () => resolve('synchronized: fresh rules from Unleash'));
  setTimeout(() => resolve(hasRules ? 'timeout: rules from the backup file' : 'timeout: code defaults'), ms);
});

في الكود أعلاه لاحظ أن الدالة تعيد سبب البدء، فتكتبه في سجل التشغيل، وعندما يسألك أحد لماذا رأى العملاء الصفحة القديمة صباح ذلك اليوم تجد الجواب في سطر واحد. ولاحظ مستمع error، فال SDK يكتب الأخطاء بنفسه إذا لم تضف مستمعاً، ولكن إضافته تجعلها سطراً واحداً بصيغة سجلاتك بدل تتبع طويل لكل محاولة فاشلة.

ملف النسخة الاحتياطية الفارغ Backup File

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

--- Unleash down, backup file present
ready: timeout: code defaults
new_checkout ON for 0 of 1000 users, first:
staff-1 (plan=staff): false

«القيم الافتراضية» والملف موجود؟ فتحنا المجلد، فوجدنا الملف بحجم صفر:

-rw-r--r-- 1 root root    0 Nov  5 08:33 unleash-backup-shop-backend.json

وعندما قرأنا كود ال SDK وجدنا السبب: الملف يكتب بالدالة writeFile بعد كل جلب فيه تغيير، وهذه الدالة تفرغ الملف أولاً ثم تكتب فيه، وسكربتاتنا القصيرة كانت تنهي العملية ب process.exit بعد الجلب مباشرة، فتنتهي في منتصف الكتابة ويبقى الملف فارغاً. وأعدنا ذلك ثلاث مرات فكان الحجم صفراً كل مرة، أما العملية التي بقيت تعمل خمس ثوان فترك ملفها 850 بايت:

0 bytes  /tmp/unleash-backup-shop-backend.json
0 bytes  /tmp/unleash-backup-shop-backend.json
0 bytes  /tmp/unleash-backup-shop-backend.json
850 bytes after a long-running process  /tmp/unleash-backup-shop-backend.json

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

  • مكانه الافتراضي مجلد الملفات المؤقتة: أي /tmp داخل ال Container، فإذا أعيد إنشاء ال Container في نشر جديد ضاع الملف، ولا يفيدك إلا عند إعادة تشغيل ال Container نفسه. فإذا أردته فعلاً فاجعل backupPath على Volume.
  • الكتابة ليست ذرية Atomic: إنهاء العملية بقوة أثناء الكتابة يترك ملفاً فارغاً، وال SDK يتعامل مع الملف الفارغ كأنه غير موجود، فتعمل بالقيم الافتراضية دون أي رسالة.
  • قواعده قديمة بطبيعتها: كما رأينا في قسم النسخ، فهو صورة لآخر جلب ناجح، وقد يعيد ميزة أطفأتها.

لذلك لا تعتمد في خطة الطوارئ على ملف في /tmp، واعتمد على أمرين: قيمة افتراضية آمنة في الكود لكل Flag، ونسخة من القواعد تعيش خارج التطبيق، وهو ما يقدمه Unleash Edge كما سوف نرى. ويدعم ال SDK أيضاً خيار bootstrap الذي يحمل القواعد من ملف أو رابط تحدده أنت قبل الجلب الأول.

مشكلة ثالثة عند الإيقاف Graceful Shutdown

بقي أمر صغير ظهر لنا أكثر من مرة: عملية تنهي نفسها بإيقاف منظم أثناء عطل الخادم. حاكينا ذلك بسكربت يستدعي unleash.destroy() بعد ثانيتين من البدء، وعنوان الخادم عنوان لا يرد أبداً حتى يبقى الطلب معلقاً:

08:27:25 ready from backup, new_checkout for user-11 = true
08:27:27 SIGTERM: unleash.destroy()
08:27:58 process exit code 1
FetchError: network timeout at: http://10.255.255.1:4242/api/client/features
…
Emitted 'error' event on Repository instance at:
    at AdaptiveFetcher.<anonymous> (/app/node_modules/unleash-client/lib/repository/index.js:59:69)

طلبنا الإيقاف في الثانية 27، فبقيت العملية حتى الثانية 58 ثم انتهت بالرمز 1 بخطأ غير معالج. والسبب في كود ال SDK: الدالة destroy() تزيل كل المستمعين من مستودع القواعد، والطلب الذي كان معلقاً ينتهي بعد ذلك بخطأ، فيطلق حدث error لا يستمع له أحد، وفي Node.js هذا ينهي العملية. والنتيجة في الإنتاج أن كل إيقاف أثناء عطل Unleash يأخذ نصف دقيقة وينتهي بخطأ، وقد يقتل Docker أو Kubernetes العملية قبل أن تنهي طلبات عملائك. والإصلاح أن تنهي العملية بنفسك بعد أن تغلق سيرفر HTTP وتستدعي destroy():

08:28:11 ready from backup, new_checkout for user-11 = true
08:28:13 SIGTERM: close the HTTP server, then unleash.destroy() and exit
08:28:13 process exit code 0

ماذا لو أضفنا Unleash Edge؟ What If

Unleash Edge خدمة صغيرة مكتوبة ب Rust تقف بين تطبيقاتك وخادم Unleash، وتعمل كنسخة قراءة: تجلب القواعد من الخادم، والتطبيقات تجلبها منها. ويستخدمها الناس لسببين: تقليل الطلبات على الخادم عندما يكثر عدد التطبيقات، والصمود عندما يتوقف الخادم. وقبل أن تبني عليها، اقرأ هذا التحذير في المستودع نفسه: النسخة المفتوحة من Edge في وضع صيانة طويلة، ونهاية دعمها في 31 ديسمبر 2026، والشركة توصي بالانتقال إلى Enterprise Edge. فهذا القسم تجربة لما تقدمه الفكرة، وليس توصية بأن تبني عليها اليوم.

شغلنا Edge 20.6.4 بتوكن المتجر نفسه، وصورتها 88 ميجابايت فقط، واستهلكت أقل من 7 ميجابايت من الذاكرة، ثم وجهنا التطبيق إليها، وأوقفنا خادم Unleash، وشغلنا عملية جديدة دون ملف نسخة احتياطية:

docker run -d --name wr-ff-unleash-edge --network wr-ff-unleash-net unleashorg/unleash-edge:v20.6.4 \
  edge --upstream-url http://unleash:4242 --tokens "default:production.v2_cQEe…"
--- app -> Edge -> Unleash, all up
ready: synchronized: fresh rules from Unleash
new_checkout ON for 511 of 1000 users, first: user-2 user-3 user-4 user-5 user-8
08:35:45 docker stop wr-ff-unleash-server
--- Unleash down, new app process (no backup file) through Edge
ready: synchronized: fresh rules from Unleash
new_checkout ON for 511 of 1000 users, first: user-2 user-3 user-4 user-5 user-8
--- Edge restarted while Unleash is still down
ready: timeout: code defaults
new_checkout ON for 0 of 1000 users, first: 

والنص fresh rules from Unleash هنا يعني أن الرد جاء من Edge، لأن ال SDK لا يفرق بينهما. والمخرج يبين أن Edge حمت العملية الجديدة ما دامت هي نفسها تعمل، ولكن عندما أعدنا تشغيل Edge والخادم متوقف، رفضت أن تبدأ أصلاً، وسجلها يقول:

ERROR unleash_edge::edge_builder: Edge was not able to validate any of the tokens configured at startup
Error: No valid tokens provided on startup. At least one valid token must be specified at startup

أي أن Edge تحتاج إلى الخادم لتتحقق من التوكنات عند البدء، إلا إذا حفظت بياناتها على القرص بالخيار --backup-folder. فأضفنا Volume وهذا الخيار، وهنا ظهرت مشكلة صغيرة أخرى، فقد امتلأ السجل بهذه الرسالة كل دقيقة:

WARN unleash_edge_persistence: Could not persist tokens: PersistenceError("Cannot write tokens to backup. Opening backup file for writing failed")

والسبب أن Edge تعمل بمستخدم غير root اسمه edgeuser ورقمه 10001، والمجلد في ال Volume الجديد ملك root. ولاحظ أن Edge بدأت وعملت بشكل طبيعي رغم ذلك، فلو لم تقرأ السجل لظننت أن النسخ يعمل حتى يوم العطل. وبعد تغيير مالك المجلد ظهرت الملفات خلال دقيقة:

docker run --rm -v wr-ff-unleash-edge-data:/data alpine:3.24 chown 10001:10001 /data
-rw-r--r--    1 10001    10001          950 Nov  5 08:41 unleash_features.json
-rw-r--r--    1 10001    10001            2 Nov  5 08:41 unleash_last_event_ids.json
-rw-r--r--    1 10001    10001          190 Nov  5 08:41 unleash_tokens.json

ثم أعدنا الاختبار الصعب: أوقفنا الخادم، وأعدنا تشغيل Edge، وشغلنا عملية جديدة:

08:41:49 docker stop wr-ff-unleash-server
08:41:50 docker restart wr-ff-unleash-edge   (Unleash still down)
ready: timeout: code defaults
new_checkout ON for 0 of 1000 users, first:
08:42:28 app again, Edge now listening (Unleash still down)
ready: synchronized: fresh rules from Unleash
new_checkout ON for 511 of 1000 users, first: user-2 user-3 user-4 user-5 user-8

نجحت Edge في البدء من ملفاتها والخادم متوقف، ولكن لاحظ السطر الثالث: العملية التي بدأت بعد إعادة التشغيل مباشرة لم تجد Edge، لأن Edge لم تستقبل الطلبات إلا في 08:42:09، أي بعد 19 ثانية من طلب إعادة تشغيلها، قضت أغلبها في محاولة التحقق من التوكنات مع الخادم المتوقف. وتطبيقنا ينتظر ثلاث ثوان فقط، فبدأ بالقيم الافتراضية، وهو السلوك الآمن الذي صممناه. والصورة التالية تجمع كل الحالات التي جربناها:

جدول من خمس حالات عند توقف Unleash: عملية تعمل منذ قبل التوقف بقيت user-11 = true أربعين ثانية والخطأ ظهر في السجل بعد نحو 20 ثانية والنتيجة آخر قواعد في الذاكرة، وعملية جديدة مع ملف النسخة تعمل بقواعد آخر جلب وقد تكون قديمة، وعملية جديدة دون ملف النسخة ON for 0 of 1000 users أي المسار القديم الآمن، وتطبيق ينتظر synchronized أو startUnleash ينتهي ب unsettled top-level await exit 13 ولا يبدأ أبداً فالمتجر كله متوقف، وعبر Unleash Edge مع backup-folder ON for 511 of 1000 users وبعد إعادة تشغيله احتاج 19 ثانية ليستقبل الطلبات
العملية التي تعمل لا تتأثر، والعملية الجديدة هي الاختبار الحقيقي

بيانات التقييم Impression Data في السجلات

فعلنا impressionData عند إنشاء ال Flag، فصار ال SDK يطلق حدث impression مع كل تقييم، ونستطيع أن نحوله إلى سطر في السجلات المنظمة، كما يشرح توثيق بيانات التقييم:

// Impression data: every evaluation of new_checkout becomes an event the app can log or count.
import { unleash, ready } from './unleash.mjs';
unleash.on('impression', (e) => console.log(JSON.stringify({ flag: e.featureName, enabled: e.enabled, user: e.context.userId, plan: e.context.properties?.plan, event: e.eventType })));
await ready();
for (let i = 1; i <= 300; i++) unleash.isEnabled('new_checkout', { userId: `user-${i}`, properties: { plan: i % 10 === 0 ? 'pro' : 'free' } }, false);
unleash.isEnabled('new_checkout', { userId: 'staff-1', properties: { plan: 'staff' } }, false);
await new Promise((r) => setTimeout(r, 12000));   // let one metrics batch reach Unleash
unleash.destroy(); process.exit(0);
{"flag":"new_checkout","enabled":false,"user":"user-1","plan":"free","event":"isEnabled"}
{"flag":"new_checkout","enabled":true,"user":"user-2","plan":"free","event":"isEnabled"}
{"flag":"new_checkout","enabled":true,"user":"user-3","plan":"free","event":"isEnabled"}
…
{"flag":"new_checkout","enabled":true,"user":"staff-1","plan":"staff","event":"isEnabled"}

من 301 تقييم كانت 147 مفعلة و154 مطفأة. وهذه الأسطر هي ما يربط ال Flag بمشكلة في الإنتاج: إذا ارتفعت أخطاء الدفع، فأول سؤال هو هل الأخطاء عند من يرون الصفحة الجديدة فقط، والجواب يأتي من ضم هذه الحقول إلى سجل الطلب. ولكن انتبه إلى أمرين: لا تكتب سطراً لكل تقييم في متجر يقيم ال Flag آلاف المرات في الدقيقة، وإنما أضف القيمة كحقل في سطر الطلب نفسه، ولا تضع في السياق بيانات شخصية لا تحتاج إليها، لأنها سوف تصل إلى سجلاتك.

ما يعرفه Unleash عن ال Flag Metrics

بعد التجربة سألنا الخادم عن عدادات ال Flag، وهي ما يرسله ال SDK كل فترة:

curl -s -H "$A" "$U/api/admin/client-metrics/features/new_checkout/raw?hoursBack=1"
{ "version": 1, "maturity": "stable",
  "data": [ { "featureName": "new_checkout", "appName": "shop-backend", "environment": "production",
              "timestamp": "2026-11-05T08:00:00.000Z", "yes": 162, "no": 159, "variants": {} } ] }

العدادات مجمعة بالساعة، لذلك فيها تقييمات السكربت السابق مع تقييمات watch.mjs في الساعة نفسها، وليست كل التقييمات، لأن السكربتات التي أنهت نفسها قبل موعد الإرسال لم ترسل عداداتها. ثم قرأنا حالة ال Flag نفسه:

{'name': 'new_checkout', 'type': 'release', 'stale': False, 'lifecycle': {'stage': 'live', 'enteredStageAt': '2026-11-05T08:32:13.153Z'}, …}
production True 2026-11-05T08:32:09.556Z [('staff first', '100', [1]), ('customers 50%', '50', [])]

لاحظ lifecycle: انتقل ال Flag وحده إلى مرحلة live عندما وصلت أول عدادات من بيئة الإنتاج، دون أن يغير أحد شيئاً. وUnleash يعرف لكل نوع Flag مدة حياة متوقعة، وقرأناها من الخادم:

release 40
experiment 40
operational 7
kill-switch None
permission None
sunset 90

فال Release Flag يتوقع أن يعيش 40 يوماً، وبعدها يعلمه Unleash بأنه قد يكون منسياً، أما Kill Switch وPermission فليس لهما مدة، لأنهما يعيشان طويلاً بطبيعتهما. والنوع الجديد sunset الذي أضافه الإصدار 8 لحالة معاكسة: ميزة قديمة تريد أن تزيلها تدريجياً. وهذا يغنيك عن جزء من سكربت ال Flags المنسية الذي كتبناه في مقال المفهوم، ولكنه لا يغني عن الجزء الذي يقارن ال Flags بالكود، لأن Unleash لا يعرف أين تقرأ ال Flag في الكود. والصورة التالية من لوحة Unleash بعد التجربة، وفيها البيئتان والاستراتيجيتان والنسختان:

صفحة ال Flag new_checkout في Unleash: بيئة development مطفأة دون استراتيجيات، وبيئة production مفعلة بنسبة تعرض 53% وفيها استراتيجيتان: Gradual rollout staff first بمجموعة staff وAND ونسبة 100%، ثم OR، ثم Gradual rollout customers 50% بنسبة 50% من userId ونسختان one_page وtwo_steps بنصف لكل منهما، وفي الجانب تفاصيل ال Flag: الوصف ونوعه Release flag ومرحلة حياته، وفي الأسفل إعلان عن Change Requests في النسخة التجارية
البيئتان والاستراتيجيتان والنسختان، وإعلان Change Requests التجارية في الأسفل

وكل تغيير قمنا به مسجل في سجل الأحداث Event Log مع من قام به ومتى وما الذي تغير بالضبط، والصورة التالية تبين تغيير إضافة النسختين:

تبويب Event log لل Flag new_checkout وفيه 8 أحداث، وأحدثها الحدث 17 من نوع feature-strategy-update بتاريخ 11/05/2026 من المستخدم admin في المشروع default وبيئة production، وفي الجانب الآخر الفرق بالأسطر المضافة: variants فيها one_page بوزن 500 وPayload steps 1 وtwo_steps بوزن 500 وPayload steps 2 والالتصاق على userId
سجل الأحداث يجيب عن «من غير هذا ومتى» بالفرق نفسه

كلمة مرور المدير الافتراضية Default Admin

عند أول تشغيل ينشئ Unleash مستخدماً اسمه admin وكلمة مروره unleash4all، وهي مكتوبة في توثيق الإعداد مع المتغيرين UNLEASH_DEFAULT_ADMIN_USERNAME وUNLEASH_DEFAULT_ADMIN_PASSWORD لتغييرها قبل أول تشغيل. وتأكدنا أنها تعمل على خادمنا، ثم غيرناها من ال API وأعدنا المحاولة:

$ login with the default admin / unleash4all, after changing the password
{"name":"PasswordMismatch","message":"The combination of password and username you provided is invalid. …"} HTTP 401

والدرس أن تضع المتغير في ملف Compose من البداية بكلمة مرور قوية من ملف أسرار، أو تغيرها قبل أن تفتح المنفذ لأي شبكة، والسبب أن كلمة المرور الافتراضية لأداة مشهورة هي أول ما يجربه أي شخص يجد اللوحة.

التنظيف Cleanup

docker rm -f wr-ff-unleash-app wr-ff-unleash-edge
docker compose -p wr-ff-unleash down -v
docker volume rm wr-ff-unleash-edge-data

ما لا تعطيه النسخة المفتوحة Open Source Limits

راجعنا صفحة الأسعار في 5 نوفمبر 2026، وجربنا ما يمكن تجربته على خادمنا، والصورة التالية تلخص النتيجة:

عمودان: في النسخة المفتوحة 8.3.1 مشروع واحد وبيئتان development وproduction، والنسب والقيود Constraints والمجموعات Segments، والنسخ Variants مع Payload، وسجل الأحداث Event log، وعدادات التعرض Exposure metrics، وبيانات التقييم Impression data، وال SDKs بتراخيصها المتساهلة، وصورة Docker الرسمية بترخيص Apache 2.0، والكود المصدري AGPLv3 منذ الإصدار 8، وفي Enterprise فقط طلبات التغيير Change Requests بموافقة شخص ثان، ومشاريع وبيئات أكثر مثل staging، والدخول الموحد SSO عبر SAML أو OIDC، وأدوار مخصصة RBAC لكل مشروع، ومقاييس الأثر Impact metrics والإيقاف التلقائي، وال Edge بالبث Streaming بدل الجلب، وسجل تدقيق يحفظ حتى سنتين، وتحتها POST /api/admin/projects و POST /api/admin/environments ترد 404
النسخة المفتوحة تكفي فريقاً صغيراً ببيئتين، وتنقصها الحوكمة

والحد الذي يهم فريق المتجر أكثر من غيره هو البيئتان. فالفريق عنده بيئة staging كما شرحنا في البيئات وGitOps، وعندما حاولنا إنشاء بيئة ثالثة أو مشروع ثان عبر ال API ردت النقطتان ب 404، لأنهما غير موجودتين في النسخة المفتوحة أصلاً:

$ create a second project
{"name":"NotFoundError","message":"The path you were looking for (/api/admin/projects) is not available.",…} HTTP 404
$ create a third environment (staging)
{"name":"NotFoundError","message":"The path you were looking for (/api/admin/environments) is not available.",…} HTTP 404

والحلول التي يستخدمها الناس مع هذا الحد ثلاثة: أن تستخدم بيئة development لل staging وتجعل المطورين يعملون بالقيم الافتراضية محلياً، أو أن تشغل خادماً ثانياً لل staging بقاعدة بيانات أخرى، وهذا يعني أن تنقل كل تغيير بيدك بين الخادمين، أو أن تشتري الخطة التجارية. واختار فريق المتجر الحل الأول، لأن staging عندهم نسخة من الإنتاج، والمطور يختبر المسارين باختبارات بمزود في الذاكرة كما شرحنا في مقال المفهوم.

والحد الثاني هو طلبات التغيير Change Requests، أي أن يحتاج تغيير الإنتاج إلى موافقة شخص ثان كما في طلب الدمج، ويشرحها توثيق طلبات التغيير، وهي في النسخة التجارية فقط، وتظهر في اللوحة كإعلان كما رأيت في الصورة. وفي النسخة المفتوحة كل من له صلاحية على المشروع يستطيع أن يغير الإنتاج مباشرة، وسجل الأحداث يسجل ما فعله، لكنه لا يمنعه. لذلك قلل عدد من لهم صلاحية التعديل، وأرسل أحداث الإنتاج إلى قناة الفريق عبر Webhook أو تكامل، حتى يرى الجميع كل تغيير لحظة حدوثه.

Unleash في فريق حقيقي: من يغير ماذا؟ Workflow

بعد التجربة كتب فريق المتجر قواعد استخدام Unleash في صفحة واحدة، ونضعها هنا لأنها ما يحول الأداة إلى عادة:

  • إنشاء ال Flag مع الكود: المطور ينشئ ال Flag في نفس طلب الدمج الذي يضيف الشرط في الكود، ويكتب في وصفه النوع والمالك وتذكرة الحذف، وبيئة الإنتاج تبقى مطفأة.
  • الإطلاق مسؤولية مالك الميزة: هو من يرفع النسبة، خطوة كل يوم أو يومين، بعد أن يقارن الأخطاء وزمن الرد بين من يرون الصفحة الجديدة ومن لا يرونها، كما شرحنا في مفاهيم المراقبة.
  • الإطفاء حق لكل من في المناوبة: مهندس المناوبة يستطيع أن يطفئ أي Flag في الإنتاج دون أن يسأل، ويكتب السبب في قناة الفريق، لأن ثانية التردد في الحادثة أغلى من خطأ إطفاء ميزة سليمة.
  • الحذف بعد أسبوعين من 100%: عندما تبقى الميزة مفتوحة للجميع أسبوعين دون مشاكل، يحذف المطور الشرط والمسار القديم من الكود، ثم يؤرشف ال Flag في Unleash، بهذا الترتيب، لأن أرشفة ال Flag قبل حذف الكود تجعل الكود يعود إلى القيمة الافتراضية، أي الصفحة القديمة.
  • التوكنات بأقل صلاحية: توكن خلفية لكل خدمة ولكل بيئة، وتوكن إدارة واحد لخط CI فقط، وكلها في أسرار الخط وليس في المستودع، كما في خط CI/CD آمن.

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

أخطاء شائعة Common Mistakes

  • انتظار synchronized أو startUnleash دون مهلة: المتجر كله لا يبدأ ما دام Unleash متوقفاً.
  • الاعتماد على ملف النسخة الاحتياطية في /tmp: يضيع مع كل Container جديد، وقد يكون فارغاً، وقواعده قديمة.
  • توكن الإدارة داخل التطبيق: من يصل إلى التطبيق يستطيع أن يغير كل ال Flags، فأعط التطبيق توكن خلفية لبيئته فقط.
  • توكن الخلفية في كود المتصفح: يكشف كل القواعد والمجموعات، والمتصفح يأخذ توكن الواجهة فقط.
  • الالتصاق على الجلسة لعملاء مسجلين: يرى العميل صفحتين مختلفتين على جهازين.
  • ظن أن الإطفاء فوري: يصل مع دورة الجلب التالية، أي حتى 15 ثانية، فلا تعد تشغيل السيرفرات بعد الضغط على الزر.
  • ترك كلمة المرور unleash4all: غيرها بالمتغير قبل أول تشغيل.
  • Volume لا يستطيع Edge الكتابة فيه: تعمل Edge وتكتب تحذيراً كل دقيقة، ولا تحفظ شيئاً حتى يوم العطل.
  • أرشفة ال Flag قبل حذف الكود: تعود الميزة إلى القيمة الافتراضية بصمت.

قائمة تحقق قبل الإنتاج Checklist

البندكيف تتحقق
التطبيق يبدأ والخادم متوقفأوقف Unleash وأعد إنشاء Container التطبيق، ويجب أن يبدأ خلال ثوان بالقيم الافتراضية
سبب البدء مسجلسطر في سجل التشغيل: قواعد طازجة، أو ملف نسخة، أو قيم افتراضية
القيمة الافتراضية لكل Flag هي المسار القديممراجعة الكود: المعامل الثالث في isEnabled
الإيقاف المنظم لا يتعلقأرسل SIGTERM والخادم لا يرد، ويجب أن تنتهي العملية بالرمز 0 خلال ثوان
كل خدمة لها توكن خلفية لبيئتهاقائمة التوكنات في اللوحة، ولا يوجد توكن إدارة خارج CI
كلمة مرور المدير ليست الافتراضيةمحاولة الدخول ب unleash4all ترد 401
الخادم مراقبتنبيه على /health، ولا تنتظر أخطاء التطبيقات
نسخة احتياطية لقاعدة البياناتاستعادة مجربة كما في قاعدة 3-2-1
تغييرات الإنتاج مرئية للفريقكل تغيير في بيئة الإنتاج يصل إلى قناة الفريق
Flags منسيةمراجعة شهرية لل Flags التي تجاوزت مدة نوعها

الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • Unleash خادم واحد مع PostgreSQL، والتطبيقات تجلب القواعد كل 15 ثانية وتقيمها في ذاكرتها، وترسل العدادات كل دقيقة.
  • الاستراتيجيات بينها «أو» والقيود داخلها بينها «و»، والإطلاق التدريجي يضع كل مستخدم في خانة ثابتة من 1 إلى 100 بحسب اسم ال Flag ومعرفه، فرفع النسبة من 10% إلى 50% أبقى كل ال 103 مستخدمين.
  • ال Kill Switch وصل بعد 12 ثانية بالإعداد الافتراضي، وبعد ثانيتين بفترة جلب ثانيتين، مع طلبات أكثر بسبع مرات ونصف.
  • انتظار synchronized دون مهلة يمنع التطبيق من البدء عندما يتوقف Unleash، والحل مهلة قصيرة ثم القيم الافتراضية.
  • ملف النسخة الاحتياطية في /tmp قديم بطبيعته، ويضيع مع ال Container، وقد يكون فارغاً، فلا تجعله خطة الطوارئ.
  • Unleash Edge مع حفظ البيانات حمت المتجر من توقف الخادم، ولكن نسختها المفتوحة تنتهي صيانتها في 31 ديسمبر 2026.
  • النسخة المفتوحة تعطي مشروعاً واحداً وبيئتين وسجل أحداث، ولا تعطي طلبات التغيير ولا SSO ولا بيئة ثالثة.

وفي المقال القادم من هذه السلسلة بإذن الله نأخذ المتجر نفسه إلى Flagsmith، ونركز على ما يميزه، وهو الإعدادات عن بعد Remote Config. والمقالات المرتبطة بهذا المقال:

دليلFeature Flags: انشر الكود وفعل الميزة لاحقاًكيف يفصل ال Feature Flag بين نشر الكود وإطلاق الميزة، وكيف تطلقها لجزء من المستخدمين أولاً وتوقفها فوراً إذا تعطلت.دليلمفهوم CI/CD للمبتدئين: من كل Push إلى سيرفر يعملما الذي يعنيه التكامل المستمر والتسليم المستمر فعلاً، وكيف تبني خطاً صغيراً يختبر كل Push وينشر إلى staging ويتحقق منه، مع الأخطاء الحقيقية التي يكشفها وتلك التي لا يكشفها.دليلمفاهيم المراقبة Observability: من الإشارة إلى التنبيهما الذي تجيب عنه المقاييس والسجلات والتتبع، وكيف تبني تنبيهاً على ما يشعر به المستخدم وعلى ميزانية الأخطاء بدل كل رقم.دليلإدارة الأسرار Secrets Manager: OpenBao أم Infisical؟نشغل OpenBao ثم Infisical على المسار نفسه، من هوية التطبيق إلى كلمات مرور تنتهي وحدها وسجل يقول من قرأ السر، ونرى ما تعطيه كل أداة دون رخصة.

تدريب عملي Practice

  1. شغل Unleash بملف Compose أعلاه، وأنشئ Flag باستراتيجية 30%، ثم احسب بنفسك خانة خمسة مستخدمين بالدالة normalizedStrategyValue، وتوقع من منهم سوف يرى الميزة قبل أن تقيمها.
  2. اكتب سيرفر HTTP صغيراً يستخدم دالة ready() النهائية، ثم أوقف Unleash وأعد إنشاء Container السيرفر، وقس كم ثانية يحتاج إلى أن يستقبل أول طلب، وما القيمة التي يراها العميل.
  3. غير backupPath إلى Volume، ثم أعد إنشاء ال Container والخادم متوقف، وتأكد أن السيرفر يبدأ بقواعد الملف، وقارن ذلك بما يحدث إذا أطفأت ميزة قبل التوقف بدقيقة.

سجل التحديثات Changelog

  • نوفمبر 2026: كتابة المقال وتنفيذ التجربة على Unleash 8.3.1 مع PostgreSQL 18 وunleash-client 6.12.2 على Node.js 22.23.4، وUnleash Edge 20.6.4، على Docker Engine 29.8.0، ومراجعة صفحة الأسعار وحدود النسخة المفتوحة في 5 نوفمبر 2026.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.