تشغيل Playground محليًا عبر Docker

شغّل Playground محليًا عندما تحتاج إلى التحقق من API Client الخاص بك، وصلاحيات حسابك، وأجهزتك الفعلية. تتضمن الصورة المنشورة واجهة الويب والخدمة الخلفية معًا، لذا لست بحاجة إلى Go أو Node.js أو نسخة من الكود المصدري.

إذا كنت تريد فقط استكشاف سير العمل، ابدأ بـ Playground عبر الإنترنت.

المتطلبات الأساسية

• Docker مثبَّت.
• لديك API Client مع clientId وclientSecret الخاصين به.
• لدى API Client صلاحية device:read على الأقل؛ يتطلب التحكم والإعداد صلاحيات إضافية.
• المنفذ المحلي 8090 متاح.

راجع نطاقات التفويض (بالإنجليزية) للاطلاع على القواعد الكاملة.

احمِ بيانات الاعتماد التجريبية

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

1. إنشاء ملف البيئة

أنشئ مجلدًا فارغًا وأضف ملف .env:

WLTE_BASE_URL=https://openapi.svnwi.com
WLTE_CLIENT_ID=replace-with-your-clientId
WLTE_CLIENT_SECRET=replace-with-your-clientSecret
WLTE_WS_ENABLED=true

قيّد الوصول إلى الملف:

chmod 600 .env

لا ترفع .env إلى Git ولا تضع clientSecret في كود المتصفح، أو تطبيق جوّال، أو سجلات عامة.

2. سحب أحدث صورة وتشغيلها

docker pull wlte/wlte-openapi-playground:latest

docker run -d \
  --name wlte-openapi-playground \
  --env-file .env \
  -p 127.0.0.1:8090:8090 \
  wlte/wlte-openapi-playground:latest

المنفذ مرتبط بواجهة loopback الخاصة بالمضيف ولا يُعرَض مباشرة على الشبكة المحلية أو الإنترنت.

3. التحقق من العملية

docker ps --filter name=wlte-openapi-playground
docker logs --tail=100 wlte-openapi-playground
curl --fail http://127.0.0.1:8090/healthz

بعد نجاح فحص السلامة، افتح:

http://127.0.0.1:8090

4. التحقق من تكاملك

1. تأكّد أن قائمة الأجهزة تطابق الأجهزة المتاحة للحساب.
2. افتح جهازًا وتحقّق أن لوحات ملحقاته تطابق قدراته.
3. اختر HTTP ثم WebSocket بالتناوب، ونفّذ تحديث حالة حيّ واحد مع كل وسيلة نقل.
4. استخدم الأجهزة التجريبية فقط لعمليات المرحّل أو RS-485.
5. قارن الطلبات والاستجابات ورسائل الأحداث في Protocol Inspector.

إذا أبلغت الواجهة عن خطأ صلاحيات، حدّث API Client في API Keys، ثم أعد تشغيل الحاوية ببيانات الاعتماد المحدَّثة.

إعداد اختياري

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

متغيّر البيئة	الافتراضي	الغرض
WLTE_REQUEST_TIMEOUT	15s	مهلة طلبات REST API
PLAYGROUND_WS_EVENT_BUFFER	256	حجم المخزن المؤقت لأحداث WebSocket
PLAYGROUND_WS_EVENT_HISTORY	200	الأحداث التي تحتفظ بها الصفحة
PLAYGROUND_WS_PING_INTERVAL	20s	فاصل Ping الخاص بـ WebSocket
PLAYGROUND_TRAFFIC_HISTORY	200	الرسائل التي يحتفظ بها Protocol Inspector
PLAYGROUND_LOG_FORMAT	json	تنسيق السجلات
PLAYGROUND_LOG_LEVEL	info	مستوى السجل

إيقاف الحاوية وإزالتها

docker rm -f wlte-openapi-playground

البناء من الكود المصدري

ابنِ من Dockerfile فقط عندما تحتاج إلى التحقق من كود غير منشور أو تعديل Playground نفسه:

docker build \
  --build-arg VERSION=local \
  -t wlte-openapi-playground:local \
  .

docker run -d \
  --name wlte-openapi-playground \
  --env-file .env \
  -p 127.0.0.1:8090:8090 \
  wlte-openapi-playground:local

يبني Dockerfile تطبيق Vue، ويضمّنه في خدمة Go، ويشغّل عملية واحدة بلا صلاحيات جذر (root) في الصورة النهائية. لا يُنسَخ .env أبدًا داخل الصورة.

حل المشكلات

الصفحة لا تُفتح

تأكّد أن الحاوية تعمل وأن .env لا يضبط PLAYGROUND_LISTEN_ADDR=127.0.0.1:8090. يجب أن تستمع العملية داخل الحاوية على 0.0.0.0:8090؛ تستخدم الصورة المنشورة هذه القيمة افتراضيًا بالفعل.

قائمة الأجهزة فارغة

تأكّد أن لدى API Client صلاحية device:read وأن حسابه يستطيع الوصول إلى الأجهزة. تابع إلى الأعطال الشائعة.

هل يمكنني عرضه علنًا؟

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

صفحات ذات صلة

• Playground عبر الإنترنت
• الحصول على API Key
• REST API أم WebSocket