واجهة برمجة تطبيقات التصحيح Debug API

تم الالتقاط في 2026-07-28 من إحدى عقد CE في هذا النشر. يسجّل الملف sitecli/capture-manifest.json أي عقدة تم استخدامها، ويقوم scripts/capture-sitecli.sh --check بإعادة التحقق من سطح الأوامر مقابل عقدة CE حيّة.

تقوم واجهة vpm/debug بتشغيل أوامر Site CLI على عقدة مُسجّلة وإرجاع مخرجاتها. كل ما يلي تم إثباته مقابل عقدة حيّة؛ ولا شيء منه منشور من المصدر الرسمي.

كتالوج الأوامر يصف نفسه

اسأل العقدة عمّا تدعمه عن طريق إرسال طلب POST إلى exec-user مع حذف المفتاح command:

curl -sS -X POST \
  -H "Authorization: APIToken $XCSH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"system","site":"<site>","node":"<node>"}' \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/<node>/exec-user" \
  | jq -r .output | jq .

الاستجابة هي كائن JSON مُفتَّح باسم الأمر:

{
  "crictl-inspect": ["System Troubleshooting", "ExecUser", " container-id"],
  "diagnosis":      ["System Troubleshooting", "ExecUser", "no argument needed", "GLOBAL"],
  "ip-link-set":    ["Network Troubleshooting", "Exec", " (<device>||<group>) (up||down)"]
}

كل مدخل هو [category, tier, exampleArgument?, scope?]، وهذه الحقول ليست توثيقًا — بل هي التي تحدد كيف يجب استدعاء الأمر.

احذف المفتاح؛ لا ترسل قيمة خاطئة

يعمل الاستكشاف من خلال حذف command. أما إرسال قيمة غير معروفة بدلًا من ذلك فيُرجع خطأً، وليس الكتالوج:

{"code":3,"details":[],"message":"exec command failed: command not supported"}

هذه الرسالة نفسها هي ما تحصل عليه لأمر حقيقي أُرسل إلى نقطة النهاية الخاطئة، ولذلك يسهل قراءتها خطأً بمعنى “هذا الأمر غير موجود”.

ثلاث وسائل نقل، يحددها مدخل الكتالوج

الشرط	الطريقة والمسار	الجسم	الناتج
scope يساوي GLOBAL	GET .../vpm/debug/global/<cmd>	لا شيء	JSON
tier يساوي ExecUser	POST .../vpm/debug/<node>/exec-user	مصفوفة command	نص
tier يساوي Exec	POST .../vpm/debug/<node>/exec	مصفوفة command	نص

ExecUser — الطبقة للقراءة فقط 31 أمرًا

الحالة الشائعة. مرِّر الأمر ووسائطه كمصفوفة، مع اسم الأمر أولًا:

curl -sS -X POST \
  -H "Authorization: APIToken $XCSH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"system","site":"<site>","node":"<node>","command":["crictl-ps"]}' \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/<node>/exec-user"

{ "return_code": 0, "output": "CONTAINER    IMAGE    CREATED    STATE ..." }

الوسائط هي عناصر مصفوفة منفصلة، وليست سلسلة نصية واحدة:

{ "command": ["journalctl", "-u", "vpm", "-n", "200"] }

GLOBAL — على نطاق الموقع، ووسيلة نقل مختلفة تمامًا أمران

health وdiagnosis هما الأمران الوحيدان. وهما طلبا GET إلى مسار global، لا يأخذان أي وسائط، ويُرجعان JSON مُهيكلًا بدلًا من نص طرفية.

curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/global/health" | jq .

أمر GLOBAL لا يمكن الوصول إليه عبر exec-user

هذا هو الفخ الذي يستهلك أكبر قدر من الوقت. إرسال health أو diagnosis إلى exec-user يُرجع command not supported، وهو ما يُقرأ كأن الأمر غير موجود على العقدة — في حين أنه موجود بالفعل وأنت استخدمت وسيلة النقل الخاطئة.

# Wrong. Returns: exec command failed: command not supported
-d '{"namespace":"system","site":"…","node":"…","command":["health"]}'   # POST exec-user

# Right.
GET .../vpm/debug/global/health

Exec — الطبقة المُتميّزة أمر واحد في هذه النسخة

نقطة نهاية منفصلة، والطبقة مُفرَضة وليست إرشادية: فـ exec يرفض أمرًا من ExecUser بنفس رسالة command not supported. وكل عضو فيها إمّا يُغيّر العقدة أو يقرأ علامة حالة.

في النسخة التي يشغّلها هذا المستأجر، تحتوي الطبقة على ip-link-set فقط. أما النسخ الأحدث فتضيف systemctl-restart-NetworkManager وsystemctl-restart-crio وsystemctl-restart-kubelet وsystemctl-start-crio-prune وثلاثة أوامر marker-exists-*.

لا شيء هنا يُشغّل أمر Exec

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

إيجاد أسماء الموقع والعقدة

اسم العقدة هو اسم جهاز Azure الافتراضي، وlist-service طريقة رخيصة لتأكيده جنبًا إلى جنب مع الخدمات العاملة عليه:

curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/global/list-service" \
  | jq -r '[.service[].node] | unique'

["", "f5-xc-ce-vm-01"]

تُبلّغ بعض الخدمات عن اسم عقدة فارغ، لذا فإن السلسلة الفارغة في تلك القائمة هي أثر من آثار الاستجابة وليست عقدة ثانية. كما أن list-service ليس ضمن كتالوج الأوامر الـ 34: فهو نقطة نهاية global لا يعلن عنها الكتالوج، ولذلك يُوثَّق هنا وليس في مرجع الأوامر.

إعادة إنتاج عمليات الالتقاط في هذا المستودع

كل صفحة أمر تُضمّن مخرجات تم التقاطها بواسطة scripts/capture-sitecli.sh، الذي يُنفّذ القواعد الثلاث المذكورة أعلاه.

1. وجّهه إلى مستأجر. يقرأ XCSH_API_URL وXCSH_API_TOKEN، أو يعود إلى سياق xcsh النشط.

2. حدّث الكتالوج وتأكّد من أن العقدة لم تتغيّر من تحت التوثيق:

   bash scripts/capture-sitecli.sh --check

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

3. أعِد الالتقاط عندما تريد أدلّة حديثة:

   bash scripts/capture-sitecli.sh

عمليات الالتقاط أدلّة، وليست مُخرجات قابلة لإعادة الإنتاج

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

الالتقاط من عقدة عميل: تحقّق من ملف تعريف الحجب

تحمل مخرجات الأوامر هوية البنية التحتية — العنونة الداخلية وعناوين MAC وأرقام AS وأسماء المضيفين — وبالنسبة لعميل فإن ذلك يُعدّ معلومات تُعرِّف بالمؤسسة.

لذلك يستخدم مُرشِّح التنقية افتراضيًا ملف تعريف صارم يزيل كل ذلك. يعلن هذا المستودع lab في sitecli/capture-manifest.json، وهو ما يُبقي تلك التفاصيل، وهذا صحيح هنا فقط لأن عمليات الالتقاط هذه تأتي من بنية عرض توضيحي مملوكة لشركة F5.

لا تنقل هذا الإعداد إلى عملية التقاط لدى عميل. تُزال الرموز والمفاتيح الخاصة ومعرّف المستأجر ومعرّفات UUID للكائنات وعناوين البريد الإلكتروني ومسارات الأدلة الرئيسية في كلا ملفي التعريف.

هناك قيد واحد يجدر معرفته: يطبع جدول جوار BGP رقم AS كعمود مجرّد دون أي تسمية يمكن أن يرتكز عليها النمط، لذا تُطابَق أرقام ASN بالقيمة مقابل النطاقات الخاصة. لذا فإن رقم ASN عامًّا هناك يبقى حتى مع الملف الصارم، ويتطلّب مراجعة يدوية لمخرجات show-ip-bgp* قبل نشرها.