الاستضافة الذاتية

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

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

الأجزاء

الجزءما يفعلهمطلوب
البوابة (gateway)MCPG مع إضافاته الأصلية (first-party). تنهي اتصالات MCP، وتتحقق من الهوية، وتطبّق الحوكمة على كل أداة، وتستدعي Postgres أو imd-svc لكل أداة.نعم
PostgresPostgreSQL 17 مع pg_trgm و pgvector و pgcrypto، يديره CloudNativePG. الحالة المرجعية، وقواعد السجل في صورة دوال SQL.نعم
imd-svcخدمة الخادم الخاصة به إلى جانب البوابة: التوقيع، وبيانات اعتماد الوكلاء، والملفات، والمعالجة في الخلفية، وترحيلات المخطط.نعم
NATSJetStream: جلسات البوابة واشتراكاتها وإشعاراتها، مشتركة بين نسخها. لا يُحفظ هناك شيء دائم.عند وجود نسختين أو أكثر من البوابة
Keycloakتسجيل الدخول، مع realms مكتوبة ككود: الأشخاص، وبيانات الاعتماد الخاصة بالوكلاء، والمسؤولون.نعم
نموذج التضمينText Embeddings Inference مع BAAI/bge-base-en-v1.5، داخل العنقود: البحث بالمعنى. لا يخرج منه أي نص تعليمة.لا
الاستوديوالمحرر، وهو موقع ثابت يسجّل الدخول عبر Keycloak لديك ويحفظ مساحة عمله على خادمك.لا

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

أصغر نسخة تعمل

مخططات بيئة التشغيل الفعلية في عنقود k3d محلي، موصولة كما توصلها بيئة التشغيل الفعلية، على أصل واحد: الموقع على / والاستوديو على /editor/، وخادم MCP على /mcp، و Keycloak على /auth. تحتاج إلى Docker و k3d و kubectl و helm و Python 3 مع PyYAML و Node مع pnpm و rsync و openssl، ونحو 6 GB من مساحة القرص. وهي سجل حقيقي: الإصدارات، والمراجع، والمقترحات، والمؤسسات، والتوقيع، والتسليم عبر MCP، كلها تعمل.

Shell
# 1. build the site, the studio, the docs and Learn for the stack's origin, as one tree (dist/web)
PUBLIC_IMD_AUTH_ISSUER=http://localhost:18080/auth/realms/instruction-md PUBLIC_IMD_AUTH_CLIENT=platform-web \
  PUBLIC_IMD_MCP_URL=http://localhost:18080/mcp PUBLIC_IMD_STUDIO_SIGN_IN=on pnpm build:web

# 2. a k3d cluster, the operators, the secrets and every chart
deploy/k8s/stack/up.sh                  # http://localhost:18080

# the same, on MCPG's published release
IMD_GATEWAY_IMAGE=ghcr.io/mcpg-dev/mcpg:0.1.0-beta.68 deploy/k8s/stack/up.sh

إلى أن يُنشر MCPG 0.1.0-beta.68، البوابة الافتراضية في السكربت بناء محلي: صورة beta.67 المنشورة مع بوابة وإضافتَي الخلفية الخاصتين بها مبنية على الجهاز، من deploy/mcpg/data. ومع صدور ذلك الإصدار تستخدم الصيغة الثانية الصورة المنشورة وإضافاتها الموقّعة. سجّل الدخول على http://localhost:18080/ ووجّه وكيلًا إلى http://localhost:18080/mcp. في realm هذه البنية مستخدمون للتطوير؛ أما الخاص ببيئة التشغيل الفعلية فلا. والباقي في deploy/k8s/stack/README.md.

Postgres، والنسخ الاحتياطية المهمة

Postgres هو الحالة كلها. روابط SQL في البوابة تصل إليه عبر PgBouncer في وضع المعاملات، وهذا يحتاج إلى max_prepared_statements لأن MCPG يحضّر عباراته، بينما LISTEN وقارئ الأحداث يتصلان مباشرةً بالخادم الأساسي، لأن مجمِّع الاتصالات في وضع المعاملات لا يستطيع الإبقاء على LISTEN. كل عميل يتحقق من شهادة الخادم مقابل سلطة الشهادات (CA) الخاصة بالعنقود. والمخطط يهيّئ كل ذلك.

النسخ الاحتياطية تمر عبر إضافة Barman Cloud في CloudNativePG إلى أي حاوية تخزين متوافقة مع S3: سجلات WAL باستمرار، ونسخة أساسية كل ليلة، ويُحتفظ بكليهما 30 يومًا، فتستطيع الاسترداد إلى لحظة زمنية محددة على خادم آخر.

YAML
# deploy/k8s/imd-postgres/values.yaml
backup:
  enabled: true
  destinationPath: s3://imd-postgres-backup/imd-postgres
  endpointURL: http://rgw.internal:7480
  credentialsSecret: imd-postgres-backup   # ACCESS_KEY_ID, ACCESS_SECRET_KEY
  retentionPolicy: "30d"
  schedule: "0 0 3 * * *"                  # a base backup nightly; WAL all the time

deploy/k8s/restore-drill.sh يستعيد عنقودًا ثانيًا من حاوية التخزين، ويقارن كل جدول بنظيره في العنقود الفعّال ثم يزيله. شغّله بعد أول نسخة احتياطية ليلية، وبعد أي تغيير في النسخ الاحتياطية. NATS لا يحتاج إلى نسخ احتياطي: إذا فُقد تعيد البوابة بناء ما كانت تحفظه فيه.

الهوية

تحتاج البوابة إلى ثلاثة أشياء من رمز الوصول (token): صاحب ثابت (subject)، وجمهور (audience) مرتبط بنقطة وصول MCP لديك، ومطالبة (claim) تبيّن هل الطالب شخص أم وكيل أم خدمة، لأن صلاحيات الوكلاء محدودة بما دون الإدارة الكاملة أيًّا كان من يتصرفون باسمه. ويعتمد الخادم على Keycloak في أكثر من تسجيل الدخول: فخدمة imd-svc تصدر بيانات الاعتماد الخاصة بكل وكيل في realm الوكلاء. ولذلك فمزوّد الهوية هو Keycloak، ومع ذلك يستطيع أشخاصك تسجيل الدخول بمزوّدك أنت عبر وساطة Keycloak (brokering).

تأتي realms ككود، مولَّدة لا محرَّرة يدويًّا (deploy/keycloak/gen-realms.py): واحد للأشخاص، وواحد للوكلاء، وواحد للمسؤولين. يستوردها Keycloak عند أول تشغيل له. وبعد كل تثبيت أو ترقية، تطبّق مهمة محتواها من جديد عبر واجهة API الإدارية: تضيف الجديد وتترك الموجود، لأن استبدال realm فعّال سيدمّر المؤسسات وروابط الهوية الموحّدة. ولا يُوجَّه من الخارج إلا realm الأشخاص و realm الوكلاء. أما الإدارة فتبقى داخل العنقود.

تحتفظ المولِّدات بملف تعريف لكل مكان يعمل فيه الخادم: جهاز المطوّر، والبنية المحلية، وبيئة التشغيل الفعلية على instruction.md. ونطاقك الخاص هو ملف تعريف خاص بك في deploy/mcpg/gen-config.py وdeploy/keycloak/gen-realms.py، بأصلك ومُصدِريك (issuers) وجمهورك (audience).

التوقيع

تشتق خدمة imd-svc مفتاح ناشر لكل مؤسسة من مفتاح رئيسي واحد، فلا يُخزَّن أي مفتاح خاص أبدًا: الأنصاف العامة تُقدَّم للتحقق، والأنصاف الخاصة لا توجد إلا داخل العملية وهي توقّع. ومفتاح ثانٍ يوقّع كل تسليم.

Secrets
# deploy/k8s/bootstrap-secrets.sh, in the Secret imd-keys
IMD_SIGNING_MASTER_KEY   # each organization's publisher key is derived from it
IMD_DELIVERY_KEY         # signs each delivery: one reader, one resolution

deploy/k8s/bootstrap-secrets.sh ينشئ المفتاحين عند أول تشغيل له ويحتفظ بهما بعد ذلك. احتفظ بنسخة حيث تحفظ مثل هذه الأشياء: إذا فُقد المفتاح الرئيسي تغيّر مفتاح الناشر لكل مؤسسة؛ وإذا فُقد مفتاح التسليم لم يعد التحقق من عمليات التسليم السابقة ممكنًا. ومن دون مفتاح رئيسي لا توقّع المنصة شيئًا، وهذا خيار مشروع. فالناشرون يستطيعون مع ذلك إحضار مفاتيحهم والتوقيع على أجهزتهم، والمستهلكون يتحققون بالطريقة نفسها تمامًا.

Kubernetes

ستة مخططات، في مساحة أسماء واحدة، تُثبَّت بهذا الترتيب، ويُنتظر كل منها. وهو الترتيب الذي يشغّلها به .github/workflows/deploy-server.yml، وسير العمل هذا يمرّر ملفات realms وسكربت مهمة التطبيق كاملةً. تسحب البوابة إضافاتها الأصلية عند بدء تشغيلها ولا تقبل إلا الموقّع منها.

Shell
# first, once per cluster: the CloudNativePG operator, cert-manager and the Barman Cloud plugin
# (docs/runbooks/server-deploy.md §1). Then the namespace's secrets:
deploy/k8s/bootstrap-secrets.sh instruction-md

helm upgrade --install imd-postgres   deploy/k8s/imd-postgres   -n instruction-md
kubectl -n instruction-md wait cluster/imd-postgres --for=condition=Ready --timeout=15m
helm upgrade --install imd-nats       deploy/k8s/imd-nats       -n instruction-md --wait
helm upgrade --install imd-keycloak   deploy/k8s/imd-keycloak   -n instruction-md --wait \
  --set-file realms.users=deploy/keycloak/realms/prod/instruction-md-realm.json …
helm upgrade --install imd-embeddings deploy/k8s/imd-embeddings -n instruction-md --wait
helm upgrade --install imd-svc        deploy/k8s/imd-svc        -n instruction-md --wait \
  --set image.tag=<tag>
helm upgrade --install imd-gateway    deploy/k8s/imd-gateway    -n instruction-md --wait \
  --set-file config=deploy/mcpg/prod.yaml

سكربت الأسرار ينشئ كل سر في مساحة الأسماء. يأخذ كل قيمة من البيئة (ما يسلّمه له مدير الأسرار لديك)، وإلا فمن كائن Secret الموجود أصلًا، وإلا ينشئ قيمة عشوائية جديدة، ثم يكتب كائنات Secret المشتقة التي تقرؤها المخططات. لا مكان لأي منها في ملفات القيم، والمخططات لا تقبلها هناك. أكثر من نسخة واحدة من البوابة، في عنقود على NATS، يحتاج إلى ترخيص MCPG. والبنية المحلية تعمل بمنحة MCPG المجانية لغير بيئات التشغيل الفعلية.

يتحدث الخادم بروتوكولًا واحدًا، MCP 2026-07-28، وليس فيه جلسة، فتجيب أي نسخة عن أي طلب. تشغّل المخططات حاليًّا نسخة واحدة، في وضع العنقود: فالبوابة ما زالت تقبل بروتوكول الجلسات الأقدم، وطلباته على نسختين قد تصل إلى نسخة لم ترَ بداية جلستها. وتعود النسخة الثانية حين يوقف MCPG ذلك البروتوكول.

الترقيات والتشغيل

أدلة التشغيل التي تستخدمها الخدمة المستضافة موجودة في المستودع تحت docs/runbooks: نشر الخادم، والتراجع، وتبديل المفاتيح، واسترداد Postgres، والمراقبة، وبوابة إصدارات MCPG، والاستجابة للحوادث، وإيقاف مؤسسة نهائيًّا. وهي مكتوبة لبيئتنا، لكن شكلها ينطبق على غيرها.

الترخيص

نص المواصفة مرخَّص برخصة Creative Commons Attribution 4.0. طبّقها، واقتبس منها، وتفرّع عنها، وبِعها. ومجموعة اختبارات المطابقة مرخَّصة برخصة Apache 2.0، لأن التطبيقات تنسخ تلك الملفات إلى أشجار مصادرها.

كود المنصة المصدري مرخَّص برخصة Business Source License 1.1. وعمليًّا: يحق لك تشغيله وتعديله واستخدامه لأغراضك، ومنها التجارية، والشيء الوحيد الذي لا يحق لك هو تقديمه لأطراف أخرى كخدمة مستضافة منافسة. يتحول كل إصدار إلى Apache 2.0 بعد أربع سنوات من نشره. وهو ليس ترخيصًا مفتوح المصدر اليوم، والإشعار في المستودع يقول ذلك بوضوح.

الدعم التجاري والتراخيص البديلة لم يُحسما بعد، فإذا احتجت إلى أي منهما فالجواب الآن محادثة لا صفحة.