التشغيل في الإنتاج

يغطي هذا الدليل v0.3.x. تتشارك أدوات Google التنفيذ نفسه عبر CLI وMCP stdio وStreamable HTTP.

TLS الأصلي وTLS المتبادل

يمكن لمستمع HTTP تقديم HTTPS مباشرة باستخدام rustls وTLS 1.2/1.3:

mcp-gmap-rs serve http --listen 0.0.0.0:3443 \
  --tls-cert /etc/mcp-gmap/tls/tls.crt \
  --tls-key /etc/mcp-gmap/tls/tls.key \
  --allowed-host maps.example.com:3443

وفّر MCP_HTTP_TOKEN بصورة مستقلة عبر البيئة أو Secret. يتصل العملاء بـ https://maps.example.com:3443/mcp، ويتحققون من شهادة الخادم ويرسلون Authorization: Bearer <token>. تتضمن ملفات الشهادات شهادة PEM للخادم ثم سلسلتها الوسيطة؛ ويجب أن يطابقها المفتاح الخاص. لا يُصدر الملف التنفيذي الشهادات ولا يطبق ACME. استخدم PKI لديك أو cert-manager أو بوابة TLS للإصدار والتجديد.

أضف --tls-client-ca /etc/mcp-gmap/tls/client-ca.pem لاشتراط شهادة عميل موقّعة من CA تلك. يطبق mTLS الأصلي على كل المسارات، بما فيها /health و/metrics، ولا يحل محل رمز HTTP. تُقبل أي هوية عميل صالحة تحت جذور الثقة المضبوطة في طبقة TLS؛ ولا توجد أذونات أدوات لكل شهادة أو فحوص قوائم إبطال.

على Linux/macOS، استبدل الملفات ذريًا ثم أرسل SIGHUP لإعادة تحميل الشهادة والمفتاح وCA العميل الاختيارية معًا. تحتفظ الاتصالات القائمة بحالة TLS الخاصة بها؛ وتستخدم المصافحات الجديدة البديل. إذا فشل التحميل، تبقى الإعدادات السابقة فعّالة ويُسجّل خطأ دون طباعة مواد المفاتيح. يمكن إعادة تحميل ملفات Kubernetes Secret المركّبة بهذه الطريقة بعد تحديث إسقاطها. وما زالت الإعدادات الأخرى تتطلب إعادة تشغيل العملية.

لهوية UID/GID 10001 في الحاوية، ركّب المفاتيح للقراءة فقط بأذونات تسمح لهذه الهوية بقراءتها؛ واستخدم مجموعة مناسبة وfsGroup لملفات Secret المُسقطة. مع TLS الأصلي، يجب أن تستخدم مجسات HTTP في Kubernetes القيمة scheme: HTTPS. لا تستطيع مجسات kubelet HTTP توفير شهادة عميل mTLS؛ استخدم مجس TCP لذلك النشر، مع العلم أنه يفحص المستمع لا TLS أو Google.

بوابة TLS في Kubernetes

يوفر ملف البوابة بوابة HTTPS وHTTPRoute للنشر الأساسي في ملف Kubernetes الأساسي. ثبّت أولًا CRDs الخاصة بـ Gateway API ووحدة تحكم متوافقة. استبدل your-gateway-class وmaps.example.com ووفّر Secret من نوع kubernetes.io/tls باسم mcp-gmap-tls في مساحة الأسماء نفسها. يستخدم المثال حقول Gateway/HTTPRoute v1 المستقرة ومهل HTTPRoute المدعومة منذ Gateway API v1.2. تحقّق من دعم وحدة التحكم للمهل.

kubectl create secret tls mcp-gmap-tls --cert=/secure/fullchain.pem --key=/secure/key.pem
kubectl set env deployment/mcp-gmap-rs \
  MCP_HTTP_ALLOWED_HOSTS='maps.example.com,mcp-gmap-rs:3000,localhost:3000,127.0.0.1:3000'
kubectl apply -f deploy/gateway.yaml
kubectl get gateway,httproute

احفظ إعداد المضيف المسموح المقابل أيضًا في ConfigMap أو مصدر النشر. أضف أصول المتصفح الفعلية باستخدام MCP_HTTP_ALLOWED_ORIGINS عند الحاجة. يعرض المسار /mcp فقط؛ وتبقى الصحة والمقاييس على الخدمة الخاصة. يجب تمرير ترويسات التفويض وجلسة MCP وبروتوكوله دون تغيير. عطّل تجميع الاستجابات قبل تمريرها (buffering) والتخزين المؤقت لإعادة استخدامها (caching) واضبط مهل البث والخمول في وحدة التحكم المختارة. يعطل المسار مهل الطلب وطلب الخلفية؛ اضبط حدود الاتصال والخمول المناسبة للعملاء عند البوابة.

تنهي هذه الإعدادات TLS عند البوابة وتستخدم HTTP إلى خلفية ClusterIP. استخدم TLS الأصلي مع BackendTLSPolicy يدعمه المتحكم أو شبكة خدمات إذا وجب تشفير الاتصال من البوابة إلى الحجرة أيضًا. قيّد الوصول المباشر للحجرات والخدمات بسياسة شبكة العنقود. لا يوفر TLS تسجيل دخول MCP OAuth: يستخدم الملف التنفيذي رمز bearer مشتركًا وهوية Google واحدة لكل عملية.

راجع دليل TLS للبوابة ودليل مهل HTTPRoute.

الحدود والمحاولات والمواعيد النهائية

المتغير	القيمة الافتراضية	الخيار	المعنى والقيم المقبولة
GOOGLE_MAPS_MAX_REQUESTS	200	--max-requests	ميزانية محاولات Google HTTP لكل استدعاء أداة، عدد صحيح 1–10000. مشتركة بين فروع الأدوات المركبة؛ وتستهلك الإعادات محاولات.
GOOGLE_MAPS_MAX_RETRIES	2	--max-retries	محاولات إضافية للإخفاقات المؤقتة لكل طلب Google، عدد صحيح 0–5. الصفر يعني محاولة أولية واحدة. تبقى الإعادات ضمن المهلة والميزانية.
GOOGLE_MAPS_TOOL_TIMEOUT	120	--tool-timeout	المهلة الكلية للأداة بالثواني، عدد صحيح 1–3600. تشمل الحصول على بيانات الاعتماد والانتظار وطلبات API والإعادات.
MCP_HTTP_RATE_LIMIT	120	HTTP --rate-limit	طلبات /mcp المصادق عليها في الدقيقة لكل عملية، عدد صحيح 0–1000000. يعطّلها الصفر. سعة الاندفاع تساوي المعدل مع إعادة تعبئة مستمرة.
MCP_METRICS_ENABLED	false	HTTP --metrics [true|false]	تفعيل Prometheus على /metrics. الخيار المجرد --metrics يعني true. يستخدم رمز bearer نفسه عند ضبطه، ويطبق mTLS الأصلي أيضًا.
MCP_LOG_FORMAT	text	--log-format text|json	القيم text أو json. يذهب التشخيص دائمًا إلى stderr، ويبقى stdout لنتائج CLI JSON أو حركة MCP.
MCP_TLS_CERT	غير مضبوط	HTTP --tls-cert	شهادة خادم PEM مع سلسلة الشهادات الوسيطة. يجب توفيرها مع مفتاح خاص مطابق.
MCP_TLS_KEY	غير مضبوط	HTTP --tls-key	مسار مفتاح خادم PEM الخاص. أبقه قابلًا للقراءة بهوية التشغيل وخارج المصدر والصور.
MCP_TLS_CLIENT_CA	غير مضبوط	HTTP --tls-client-ca	حزمة CA للعملاء بصيغة PEM لتفعيل شهادات عميل إلزامية في كل مسارات المستمع. لا تحل محل رمز bearer.

تتبع هذه الإعدادات القيم الافتراضية ثم dotenv الاختياري ثم البيئة ثم الخيارات. يجب توفير شهادة TLS ومفتاحها معًا. تمسح مسارات TLS الفارغة في البيئة قيم الملف. يحدّ GOOGLE_MAPS_TIMEOUT كل طلب Google HTTP بما فيه انتظار الإشارة والمحاولات والتراجع وقراءة الاستجابة؛ وللحصول على OAuth حد مستقل بالقيمة نفسها. تشمل المهلة الكلية للأداة كليهما.

لكل استدعاء ميزانية طلبات جديدة مشتركة بين فروعه المتزامنة. يمكن تنفيذ خمسة طلبات Google API بالتوازي لكل عملية. عند نفاد الميزانية، تفشل المحاولات الإضافية محليًا. قد تعيد الأدوات المركبة مخرجات ناجحة تحتوي أخطاء أو نفاد ميزانية لكل عنصر؛ افحص تلك الحقول. يحد هذا عدد الطلبات لا التكلفة: لطلبات وحقول Google أسعار مختلفة، وقد يفوتر طلب مصفوفة واحد عدة عناصر.

تعيد طلبات Google للقراءة فقط المحاولة عند HTTP 429 و 500 و 502 و 503 و 504 وإخفاقات الشبكة. تحترم المحاولات Retry-After بالثواني أو تواريخ HTTP، وإلا تستخدم تراجعًا أسيًا مع عشوائية. تبقى ضمن مهلة الطلب وميزانية الاستدعاء. لا تُعاد أخطاء HTTP الأخرى، بما فيها 400/401/403. لا يحوّل أي فشل مصادقة الوضع بصمت إلى مفتاح API. اضبط المحاولات إلى صفر لمحاولة واحدة. تُبلّغ حالات الخطأ JSON الداخلية القديمة من Google دون إعادة محاولة.

محدد HTTP دلو رموز بسعة اندفاع تساوي المعدل في الدقيقة وإعادة تعبئة مستمرة. يشمل التهيئة وPOST وGET وDELETE على /mcp عبر جميع الجلسات. لا تستهلك الطلبات غير المخولة الدلو. يُرجع الرفض HTTP 429 مع Retry-After. تُستثنى فحوص الصحة وجمع المقاييس. المحدد عام للعملية وليس لكل مستخدم أو IP، ولا يثق بترويسات IP المُمرّرة. استخدم مصادقة البوابة وحدودًا لكل عميل للنشر المشترك.

المقاييس وأحداث التشخيص

mcp-gmap-rs --log-format json serve http --metrics --rate-limit 120

يستخدم GET /metrics رمز bearer نفسه المستخدم في /mcp عند ضبطه. وعلى مستمع loopback غير مصادق، يكون دون مصادقة أيضًا. وهو معطل افتراضيًا، ويطبق mTLS الأصلي عند تفعيله. اعرضه لجامعي المقاييس الموثوقين فقط. تصدّر نقطة Prometheus النصية:

• mcp_gmap_tool_calls_total{tool,outcome} للاستدعاءات المكتملة؛
• mcp_gmap_tool_duration_seconds{tool,outcome} كمخطط توزيع؛
• mcp_gmap_google_requests_total{api,status} لمحاولات Google HTTP، بما فيها الإعادات؛
• mcp_gmap_http_rate_limited_total لطلبات HTTP المرفوضة.

تتضمن التسميات أسماء الأدوات المدمجة ومضيفي API ورموز HTTP ونتائج ثابتة. ولا تحتوي مطلقًا عناوين أو إحداثيات أو بيانات اعتماد أو رموزًا أو معرّفات جلسات. قد يُحسب الاستدعاء المركب ذو أخطاء العناصر ناجحًا على المستوى الأعلى؛ افحص نتيجته ومقاييس حالة المنبع. تُصفّر المقاييس عند إعادة التشغيل.

اضبط RUST_LOG=info لرؤية أحداث اكتمال الأدوات مع الاسم والنجاح والمدة. لا تتضمن المعاملات أو أجسام استجابات Google. يُطبع عنوان بدء المستمع بصورة منفصلة على stderr. يبقى stdout لـ JSON الخاص بـ CLI أو حركة MCP.

Doctor

mcp-gmap-rs doctor
# Explicit opt-in: makes potentially billable requests.
mcp-gmap-rs doctor --live
# Check only the API dependencies of selected tools:
mcp-gmap-rs --enabled-tools maps_pollen,maps_area_insights doctor --live

دون --live، يفحص doctor إعداد بيانات الاعتماد المحلية وإعدادات HTTP وتطابق ملف TLS ومفتاحه دون طلبات شبكة. ولا يثبت صلاحية المفتاح أو IAM أو تفعيل API أو ثقة الشهادة واسم المضيف وانتهاءها أو الوصول إلى ADC. يُبلّغ اكتشاف ADC بالحالة not_tested حتى طلب حي. لا يطبع Doctor قيم بيانات الاعتماد أو JSON الخاص بها. يخرج تقرير JSON إلى stdout؛ ويؤدي فشل فحص إلى حالة خروج 1. حلّل checks[].status: القيم pass أو fail أو not_tested.

ينفذ الوضع الحي استدعاء أداة تمثيليًا واحدًا لكل Google API مميز تستخدمه الأدوات المفعّلة، مع إعدادات الإعادة والمهل والميزانية العادية. يتجنب الأدوات المركبة المكلفة. تستخدم Routes إحداثيات دقيقة؛ وتستخدم Roads البحث عن أقرب طريق. تستخدم المجسات معالم عامة في باريس، لا عناوين مقدمة من المستخدم. يعني النجاح قبول Google لذلك المجس، لا إتاحة كل عملية أو منطقة جغرافية.

الإيقاف وتغييرات الإعدادات

يوقف Ctrl-C وSIGTERM خادم HTTP وجلسات MCP النشطة. يمنح مثال Kubernetes العملية 30 ثانية. تتطلب إعدادات التطبيق الأخرى، بما فيها تغييرات Secret المحقونة بيئيًا، إعادة تشغيل؛ ولا تدعم إعادة تحميل SIGHUP إلا ملفات شهادة TLS الأصلية ومفتاحها وCA العميل. الجلسات والمقاييس في الذاكرة وتُفقد عند إعادة التشغيل. شغّل نسخة واحدة أو اضبط تثبيت الجلسات؛ ويجب أن يعيد العملاء الاتصال عند خروج العملية المالكة.

راجع النشر لأذونات الحاويات والمجسات وتركيب بيانات الاعتماد وقت التشغيل، ومرجع الإعدادات لكل إعداد وخيار.