دليل تشغيل Gateway

استخدم هذه الصفحة للبدء في اليوم الأول وعمليات اليوم الثاني لخدمة Gateway.

📌

استكشاف الأخطاء وإصلاحها العميق

تشخيصات تبدأ بالأعراض مع سلالم أوامر دقيقة وتوقيعات السجل.

📌

التكوين

دليل إعداد موجه بالمهام + مرجع تكوين كامل.

بدء محلي لمدة 5 دقائق

1

ابدأ Gateway

bash
mayros gateway --port 18789
# debug/trace معكوس إلى stdio
mayros gateway --port 18789 --verbose
# إيقاف قسري للمستمع على المنفذ المحدد، ثم البدء
mayros gateway --force
2

تحقق من صحة الخدمة

bash
mayros gateway status
mayros status
mayros logs --follow

خط أساس صحي: Runtime: running و RPC probe: ok.

3

التحقق من جاهزية القناة

bash
mayros channels status --probe

تراقب إعادة تحميل تكوين Gateway مسار ملف التكوين النشط (محلول من ملف التعريف/افتراضيات الحالة، أو MAYROS_CONFIG_PATH عند التعيين). الوضع الافتراضي هو gateway.reload.mode="hybrid".

نموذج وقت التشغيل

  • عملية واحدة دائمًا نشطة للتوجيه ومستوى التحكم واتصالات القنوات.
  • منفذ واحد متعدد الإرسال لـ:
    • WebSocket control/RPC
    • HTTP APIs (متوافق مع OpenAI، Responses، tools invoke)
    • واجهة التحكم و hooks
  • وضع الربط الافتراضي: loopback.
  • المصادقة مطلوبة افتراضيًا (gateway.auth.token / gateway.auth.password، أو MAYROS_GATEWAY_TOKEN / MAYROS_GATEWAY_PASSWORD).

أسبقية المنفذ والربط

الإعدادترتيب الحل
منفذ Gateway--port → MAYROS_GATEWAY_PORT → gateway.port → 18789
وضع الربطCLI/override → gateway.bind → loopback

أوضاع إعادة التحميل الساخن

gateway.reload.modeالسلوك
offلا إعادة تحميل للتكوين
hotتطبيق التغييرات الآمنة للتسخين فقط
restartإعادة التشغيل عند التغييرات المطلوبة للتحميل
hybrid (افتراضي)تطبيق ساخن عند الأمان، إعادة التشغيل عند الحاجة

مجموعة أوامر المشغل

bash
mayros gateway status
mayros gateway status --deep
mayros gateway status --json
mayros gateway install
mayros gateway restart
mayros gateway stop
mayros logs --follow
mayros doctor

الوصول عن بُعد

المفضل: Tailscale/VPN. احتياطي: نفق SSH.

bash
ssh -N -L 18789:127.0.0.1:18789 user@host

ثم قم بتوصيل العملاء بـ ws://127.0.0.1:18789 محليًا.

إذا تم تكوين مصادقة البوابة، يجب على العملاء لا يزال إرسال المصادقة (token/password) حتى عبر أنفاق SSH.

راجع: Gateway عن بُعد، المصادقة، Tailscale.

الإشراف ودورة حياة الخدمة

استخدم عمليات التشغيل الخاضعة للإشراف للموثوقية الشبيهة بالإنتاج.

bash
mayros gateway install
mayros gateway status
mayros gateway restart
mayros gateway stop

تسميات LaunchAgent هي ai.mayros.gateway (افتراضي) أو ai.mayros.<profile> (ملف تعريف مسمى). يقوم mayros doctor بتدقيق وإصلاح انحراف تكوين الخدمة.

عدة بوابات على مضيف واحد

يجب أن تشغل معظم الإعدادات بوابة واحدة. استخدم عدة فقط للعزل الصارم/التكرار (على سبيل المثال ملف تعريف إنقاذ).

قائمة تحقق لكل مثيل:

  • فريد gateway.port
  • فريد MAYROS_CONFIG_PATH
  • فريد MAYROS_STATE_DIR
  • فريد agents.defaults.workspace

مثال:

bash
MAYROS_CONFIG_PATH=~/.mayros/a.json MAYROS_STATE_DIR=~/.mayros-a mayros gateway --port 19001
MAYROS_CONFIG_PATH=~/.mayros/b.json MAYROS_STATE_DIR=~/.mayros-b mayros gateway --port 19002

راجع: بوابات متعددة.

مسار سريع لملف تعريف التطوير

bash
mayros --dev setup
mayros --dev gateway --allow-unconfigured
mayros --dev status

تتضمن الافتراضيات حالة/تكوين معزول ومنفذ بوابة أساسي 19001.

مرجع سريع للبروتوكول (عرض المشغل)

  • يجب أن يكون الإطار الأول للعميل connect.
  • يعيد Gateway لقطة hello-ok (presence، health، stateVersion، uptimeMs، limits/policy).
  • الطلبات: req(method, params) → res(ok/payload|error).
  • الأحداث الشائعة: connect.challenge، agent، chat، presence، tick، health، heartbeat، shutdown.

عمليات تشغيل الوكيل من مرحلتين:

  1. إقرار قبول فوري (status:"accepted")
  2. استجابة إكمال نهائية (status:"ok"|"error")، مع أحداث agent مُبثة بينهما.

راجع وثائق البروتوكول الكاملة: بروتوكول Gateway.

الفحوصات التشغيلية

Liveness

  • افتح WS وأرسل connect.
  • توقع استجابة hello-ok مع لقطة.

Readiness

bash
mayros gateway status
mayros channels status --probe
mayros health

استرداد الفجوات

الأحداث لا يتم إعادة تشغيلها. عند فجوات التسلسل، قم بتحديث الحالة (health، system-presence) قبل الاستمرار.

توقيعات الفشل الشائعة

التوقيعالمشكلة المحتملة
refusing to bind gateway ... without authربط غير loopback بدون token/password
another gateway instance is already listening / EADDRINUSEتعارض المنفذ
Gateway start blocked: set gateway.mode=localالتكوين معين على الوضع عن بُعد
unauthorized أثناء الاتصالعدم تطابق المصادقة بين العميل والبوابة

للحصول على سلالم تشخيص كاملة، استخدم استكشاف أخطاء Gateway وإصلاحها.

ضمانات الأمان

  • عملاء بروتوكول Gateway يفشلون بسرعة عندما يكون Gateway غير متاح (لا يوجد احتياطي قناة مباشر ضمني).
  • الإطارات الأولى غير الصالحة/غير المتصلة مُرفوضة ومُغلقة.
  • الإيقاف الرشيق يصدر حدث shutdown قبل إغلاق المقبس.

ذات صلة: