Set up docs MCPيُوزَّع الموصل كملف ثنائي واحد باسم clicklink، وتوجد الأوامر التي تشغّلها ضمن clicklink clctl. تغطي هذه الصفحة الأوامر المستخدمة أثناء التثبيت والتشغيل اليومي. شغّل أي أمر باستخدام --help لعرض نص المساعدة الكامل. يمكن أيضًا تمرير العلامات ضمن التفرعات الفرعية troubleshoot وpreflight عبر متغيرات البيئة CLCTL_* (المذكورة في مخرجات المساعدة لكل علامة) أو عبر ~/.clicklink/clctl.yaml.
clicklink clctl init
يُهيّئ الموصل باستخدام رمز تسجيل، أو حزمة تسجيل محفوظة، أو شهادة موقّعة خارج النطاق. ينفّذ استدعاء واحد إعداد التكوين، ويوفّر الوصول إلى ClickHouse، ويحصل على شهادة عميل mTLS، وينشر المكوّنات (مخطط Helm أو وحدات systemd)، ويتحقق من سلامتها. إعادة التشغيل آمنة: يُحتفَظ بالتكوين ومعرّف UUID للمجموعة، وتُستبدل بيانات الاعتماد ذريًا، ويُعاد استخدام مفتاح العميل الحالي ما لم تمرّر --force. راجع الإعداد الأولي للاطلاع على التدفق الكامل.
نقاط الدخول
يلزم تحديد واحدة فقط من نقاط الدخول الثلاث؛ فهي متنافية فيما بينها.
| العلامة | الوصف |
|---|---|
--enroll <url> |
التدفق القياسي. يستخدم نقطة نهاية موصل مؤسستك (https://<subdomain>.<connector domain>)، ويستبدل رمز تسجيل أحادي الاستخدام (يُطلب دون عرضه في الطرفية، وإلا فيُقرأ من السطر الأول من stdin)، ويكتب الحزمة الناتجة إلى handoff.yaml (بالوضع 0600)، ثم يتابع باستخدام --handoff handoff.yaml. لا يصل الرمز مطلقًا إلى سطر الأوامر أو القرص أو السجلات. |
--handoff <path> |
يُجري Bootstrap من حزمة تسجيل محفوظة. تستخدم عمليات إعادة التشغيل والاسترداد هذا الخيار بعد إنشاء handoff.yaml. |
--signed-cert <path> |
المرحلة الثانية من تدفق البيئة المعزولة عن الشبكة: يثبّت شهادة عميل موقعة خارج النطاق ويكمل التثبيت المرحلي. ويمكن لـ --chain <path> استبدال سلسلة CA اختياريًا إلى جانبها. |
العلامات الشائعة
| العلامة | الوصف |
|---|---|
--target <shape> |
نمط النشر: systemd (الافتراضي؛ يُهيّئ الجهاز الافتراضي الذي تعمل عليه) أو helm (يُحضّر مخطط clicklink-connector من محطة عمل تتوفر فيها kubeconfig). |
--instance <spec> |
مثيل ClickHouse في صورة أزواج key=value مفصولة بفواصل (name، host، port، secure، database، namespace، cluster)؛ يمكن تكراره. يتجاوز المطالبات التفاعلية الخاصة بالمثيل. |
--operators <emails> |
عناوين البريد الإلكتروني للمشغّلين، مفصولة بفواصل، المسموح لهم بفتح جلسات الدعم؛ يفعّل بوابة الجلسات ويتجاوز المطالبة. |
--no-gateway |
يعطّل بوابة الجلسات (لا توجد جلسات مُدارة عبر OIDC)؛ ويتجاوز المطالبة. على جهاز افتراضي، يظل بإمكان المستخدم root على المضيف إدارة الجلسات عبر ملف الجلسات المحلي. |
--force |
يستبدل إعدادًا أو تراكبًا موجودًا ويعيد إنشاء مفتاح العميل؛ ويؤكد أيضًا استبدال شهادة موقّعة ذاتيًا لم تنته صلاحيتها. يُحفَظ معرّف UUID للعنقود حتى عند استخدام --force. |
--skip-provision |
للتحضير فقط: يتجاوز توفير صلاحيات الوصول إلى ClickHouse لكل دور (وكذلك تمكين الوحدة والتحقق منها عند استخدام هدف systemd). شغّل clicklink clctl {scraper,troubleshoot} access provision بشكل منفصل. |
--ch-user-suffix <suffix> |
لاحقة اختيارية لأسماء مستخدمي ClickHouse التي تم توفيرها (pcm_scraper يصبح pcm_scraper_<suffix>)، بحيث يمكن لنشر موصل ثانٍ مشاركة مثيل دون التعارض مع مستخدمي النشر الأول. |
--ch-admin-password-stdin |
يقرأ كلمة مرور مسؤول ClickHouse من stdin عندما يتطلب توفير SQL كلمة مرور؛ أما عند التشغيل من طرفية، فتظهر مطالبة بإدخالها. |
خيارات التوقيع (المرحلة 1 فقط)
| العلامة | الوصف |
|---|---|
--no-auto-sign |
للمرحلة فقط: يتخطى التوقيع التلقائي لـ CSR عبر نقطة نهاية التسجيل، لتدفقات التوقيع في البيئات المعزولة عن الشبكة أو خارج النطاق. |
--sign-endpoint <url> |
يتجاوز نقطة نهاية توقيع التسجيل (الافتراضي: تُشتق من نقطة نهاية الحزمة بإدراج تسمية DNS enroll). يجب أن يكون عنوان URL عبر HTTPS. |
العلامات الخاصة بـ Kubernetes
صالحة فقط مع --target helm.
| العلامة | الوصف |
|---|---|
--target-namespace <ns> |
مساحة الأسماء التي يُثبَّت فيها المخطط وتُنشأ فيها الأسرار (الافتراضي: clicklink؛ يُطلب إدخالها في الطرفية). |
--instance-namespace <ns> |
مساحة أسماء مثيل ClickHouse الهدف؛ تُستخدم لبدء اكتشاف الخدمة الأصلية وطلبات إدخال معلومات المثيل. |
--storage-class <name> |
StorageClass لوحدة تخزين حالة مستكشف الأخطاء (الافتراضي: StorageClass الافتراضي للمجموعة؛ يُطلب إدخاله أو يكون مطلوبًا عندما لا تعيّن المجموعة أيًّا منها). |
--values <path> |
مسار تراكب values المُرحَّل (الافتراضي: clicklink-values.yaml). |
--chart <ref> |
المخطط المراد نشره: اسم يُحلّ ضمن --chart-repo، أو مرجع مباشر من نوع oci:// أو URL أو مرجع محلي لعمليات التثبيت المُطابَقة (الافتراضي: clicklink-connector). |
--chart-repo <url> |
مستودع Helm الذي يُحلّ فيه اسم المخطط (الافتراضي: https://releases.clicklink.clickhouse.com/charts)؛ يُتجاهل عند استخدام مراجع --chart المباشرة. |
--chart-version <ver> |
إصدار المخطط المراد نشره (الافتراضي: إصدار هذا الملف الثنائي). |
--ch-pod <ref> |
كبسولة ClickHouse لخطوات التجهيز داخل الـ كبسولة، كاسم أو محدِّد label بصيغة k=v (الافتراضي: كبسولة بحالة Running يدعم Service لكل مثيل). |
--api-private-ca |
تعرض نقطة نهاية واجهة برمجة التطبيقات شهادة صادرة عن CA لحزمة التسجيل: تُجهِّز api.tls.caFile ليشير إلى سلسلة CA المُربطة بدلًا من جذور النظام. |
العلامات الخاصة بـ VM فقط
صالحة فقط مع --target systemd.
| العلامة | الوصف |
|---|---|
--server <url> |
عنوان URL لخادم API في Kubernetes الذي تشير إليه حزم الوصول (الافتراضي: kubeconfig الخاص بهذا المضيف، وإلا فستتم المطالبة بإدخاله). |
--ca-data <base64> |
قيمة certificate-authority-data بترميز Base64 لـ --server (الافتراضي: kubeconfig الخاص بهذا المضيف، وإلا فستتم المطالبة بإدخالها). |
تعارضات الخيارات
- الخيارات
--handoffو--enrollو--signed-certمتنافية؛ ويجب تحديد واحد منها فقط. - تُرفض الخيارات الخاصة بـ Kubernetes ما لم يُستخدم
--target helm؛ كما يُرفض--serverو--ca-dataعند استخدام--target helm(إذ يعتمد تدفق Helm على ملف kubeconfig لمحطة العمل). - يتنافى
--no-auto-signو--sign-endpointمع بعضهما، ويُرفض كلاهما (بالإضافة إلى--api-private-ca) مع--signed-cert. - يتنافى
--operatorsو--no-gateway. - يرفض
--skip-provisionالخيارات--ch-podو--ch-user-suffixو--serverو--ca-dataو--ch-admin-password-stdin(إذ لا يتم توفير أي شيء).
clicklink clctl preflight
يشغّل مجموعة فحوصات الموصل، المجمّعة حسب الفئات: الإعدادات، الملفات، الشبكة، ClickHouse، systemd، الوصول، القرص، وحجب المعلومات الحساسة. يُبلغ كل فحص عن إحدى الحالات التالية: نجاح أو تحذير أو فشل أو تخطٍّ. يشير رمز الخروج 0 إلى نجاح جميع الفحوصات (فالتحذيرات غير حاجبة)، بينما يشير رمز الخروج 2 إلى فشل فحص واحد أو أكثر.
يُشغَّل الأمر محليًا افتراضيًا. عند استخدام --k8s-namespace، يشغّل الملف الثنائي الخاص بكبسولة الموصل عبر kubectl exec ويعرض التقرير محليًا (تُتخطى فحوصات systemd دائمًا في الكبسولات). وعند استخدام علامات القناة البعيدة، يشغّل بدلًا من ذلك الملف الثنائي المثبّت على آلة افتراضية بعيدة.
| العلامة | الوصف |
|---|---|
--config <path> |
مسار ملف إعدادات الموصل؛ وعند استخدام هدف بعيد، يكون المسار على ذلك المضيف. |
--output <fmt>, -o |
تنسيق الإخراج: text (الافتراضي) أو json. |
--timeout <dur> |
المهلة الإجمالية لجميع الفحوصات (الافتراضي 30s). |
--skip-systemd |
يتخطى فحوصات حالة وحدة systemd (للمضيفين الذين لا يستخدمون systemd). |
--k8s-namespace <ns> |
مساحة الاسم الخاصة بمخطط الموصل؛ يشغّل فحص Preflight داخل كبسولة الموصل عبر kubectl exec. |
--k8s-component <name> |
كبسولة الموصل التي سيُشغَّل فيها: scraper (الافتراضي) أو troubleshooter. |
--k8s-pod <ref> |
تجاوز اسم الكبسولة أو محدد تسميات k=v (الافتراضي: تسميات المكوّن في المخطط). |
--k8s-container <name> |
الحاوية التي يُنفَّذ فيها الأمر (الافتراضي: اسم المكوّن). |
علامات --k8s-* وعلامات القناة البعيدة متنافية؛ اختر هدفًا واحدًا.
clicklink clctl troubleshoot session
يتيح تفعيل جلسة الدعم وتعطيلها وفحصها، وهي نافذة زمنية محددة يقبل خلالها troubleshooter الأوامر. عند عدم وجود جلسة نشطة، يرفض البرنامج الخفي جميع الأوامر حتى لو كان WebSocket متصلاً. راجع جلسات الدعم.
تعمل الأوامر بأحد الوضعين التاليين:
- ملف محلي (افتراضيًا): تقرأ ملف حالة الجلسة وتكتب إليه على المضيف الذي يعمل عليه troubleshooter (المسار الافتراضي:
/var/lib/clicklink/session.json). - بوابة: باستخدام
--gateway-url، يحصل على رمز مميز للهوية من OIDC ويستدعي بوابة جلسة troubleshooter بدلًا من ذلك من محطة العمل لديك.
| العلامة | الوصف |
|---|---|
--session-file <path> |
مسار ملف حالة الجلسة (القيمة الافتراضية /var/lib/clicklink/session.json). |
--config <path> |
ملف تهيئة الموصل؛ يُشتق منه مسار ملف الجلسة من قسم troubleshooter. |
--gateway-url <url> |
عنوان URL الأساسي لبوابة الجلسة. عند تعيينه، يحصل الأمر على رمز حامل OIDC ويستدعي البوابة بدلاً من التعامل مع ملف الحالة المحلي. لا يمكن استخدامه مع --session-file أو --config. |
--gateway-audience <aud> |
مطالبة الجمهور المرتبط بها رمز OIDC (القيمة الافتراضية clicklink-clctl، وهي مطابقة للقيمة الافتراضية للبوابة). عيّنه فقط إذا أُعيدت تهيئة جمهور البوابة. |
--gateway-issuer <url> |
جهة إصدار OIDC التي تتحقق البوابة منها. تؤدي القيمة الفارغة إلى اختيار مسار Google؛ عيّنه مع --oidc-client-id لتشغيل تدفق رمز الجهاز مع موفر هوية غير تابع لـ Google. |
--oidc-client-id <id> |
معرّف عميل OIDC العام لتدفق رمز الجهاز، والمسجّل لدى --gateway-issuer مع تفعيل منح الجهاز. |
--token-file <path> |
ملف يحتوي على رمز معرّف OIDC مُنشأ مسبقًا، يُستخدم كرمز حامل ويتجاوز موفري الرموز الآخرين. |
--gateway-ca <path> |
حزمة CA للتحقق من شهادة البوابة (شهادة توفرها بنفسك). عند عدم تعيينه، تُستخدم شهادة مثبّتة عبر gateway trust؛ وتفشل البوابة ذات الشهادة الموقعة ذاتيًا ومن دون تثبيت بشكل آمن. |
تفعيل الجلسة
| العلامة | الوصف |
|---|---|
--duration <dur> |
مدة بقاء الجلسة نشطة (المدة الافتراضية 4h، والحد الأقصى 24h). |
--reason <text> |
سبب اختياري بنص حر يُسجَّل مع الجلسة (بحد أقصى 256 حرفًا). |
--user <name> |
هوية المشغّل المراد تسجيلها في وضع الملف المحلي؛ تُستخدم قيمة $SUDO_USER أو $USER افتراضيًا. في وضع البوابة، يُعتمد البريد الإلكتروني الموثَّق بالرمز المميز. |
يفشل التفعيل إذا كانت هناك جلسة نشطة بالفعل؛ عطّلها أولًا أو انتظر انتهاء صلاحيتها.
تعطيل الجلسة
يعطّل الجلسة فورًا. ولا يكون له أي تأثير إذا لم تكن هناك جلسة نشطة.
حالة الجلسة
يوضح ما إذا كانت الجلسة نشطة، ومن فعّلها، ومتى تنتهي صلاحيتها. يحدد --output (-o) إما table (الخيار الافتراضي) أو json.
في Kubernetes، يمكنك الوصول إلى البوابة باستخدام إعادة توجيه المنفذ:
kubectl -n <connector-namespace> port-forward \
statefulset/clicklink-connector-troubleshooter 8443:8443
clicklink clctl troubleshoot session enable \
--gateway-url http://localhost:8443 \
--duration 1h --reason "support ticket 1234"clicklink clctl troubleshoot gateway trust
على جهاز افتراضي، تقدّم بوابة الجلسة شهادة TLS موقّعة ذاتيًا. يسجّل هذا الأمر بصمة SHA-256 للشهادة في ~/.clicklink/clctl.yaml كي تتمكن أوامر session من التحقق منها؛ وإذا لم تعد البصمة المثبّتة مطابقة، يُرفض الاتصال. تُنشأ الثقة خارج النطاق بإحدى طريقتين:
- باستخدام علامات القناة البعيدة، تُقرأ الشهادة مباشرةً من الجهاز الافتراضي عبر القناة التي تمت مصادقتها مسبقًا وتُثبّت.
- بدون قناة، مرّر
--gateway-fingerprintمع قيمة SHA-256 التي سجّلها الموصل عند إنشاء الشهادة؛ ولا تُثبّت الشهادة التي تم جلبها إلا إذا كانت مطابقة. يؤدي حذف العلامة إلى طباعة البصمة المقدَّمة دون تثبيت أي شيء.
| العلامة | الوصف |
|---|---|
--gateway-url <url> |
عنوان URL الأساسي للبوابة المطلوب الوثوق بها (مطلوب)، مثلًا: https://<vm-host>:8443. |
--gateway-fingerprint <sha256> |
بصمة SHA-256 المتوقعة من سجل الموصل، ويجري التحقق منها قبل التثبيت. تُتجاهل النقطتان وحالة الأحرف. |
--remote-cert-file <path> |
المسار إلى شهادة البوابة على الجهاز الافتراضي، وتُقرأ عبر القناة (القيمة الافتراضية: /var/lib/clicklink/gateway/tls/server.crt). |
clicklink clctl troubleshoot gateway trust \
--gateway-url https://<vm-host>:8443 \
--gateway-fingerprint <sha256-from-connector-log>في Kubernetes، لا يُستخدم التثبيت: اعرض البوابة عبر مورد Ingress باستخدام شهادة صادرة عن جهة إصدار شهادات موثوقة (CA)، أو استخدم إعادة توجيه المنفذ.
clicklink clctl troubleshoot audit tail
يطبع أحدث الإدخالات في سجل تدقيق مستكشف الأخطاء ومصلحها: JSON مفصول بأسطر جديدة، مع إدخال واحد لكل أمر قبله البرنامج الخفي أو حظره. يفتح الأمر السجل للقراءة فقط ولا يعدّله مطلقًا.
| العلامة | الوصف |
|---|---|
--lines <n>, -n |
عدد الإدخالات الأخيرة المطلوب طباعتها (الافتراضي 50). |
--path <path> |
مسار ملف سجل التدقيق (الافتراضي /var/log/clicklink/troubleshoot-audit.log). |
لا تتضمن صورة وقت تشغيل الموصل صدفة، لذا يُعد هذا الأمر القارئ المدعوم في Kubernetes:
kubectl -n <connector-namespace> exec <troubleshooter-pod> -- \
/clicklink clctl troubleshoot audit tailتهيئة الوصول
ينشئ الأمران clicklink clctl scraper access provision وclicklink clctl troubleshoot access provision حزمة وصول لكل مثيل من المكوّن، ويُدوّرانها عند استخدام --force. تشمل الحزمة مستخدم ClickHouse بصلاحية القراءة فقط وصلاحياته، بالإضافة إلى حساب خدمة Kubernetes وRBAC والرمز المميز الذي يستخدمه المكوّن. ينفّذ init ذلك مباشرةً أثناء التثبيت؛ أما الأوامر المستقلة فتُستخدم لإعادة التنفيذ وتدوير بيانات الاعتماد.
| العلامة | الوصف |
|---|---|
--instance <name> |
اسم المثيل من الإعدادات (مطلوب). |
--server <url> |
عنوان URL لخادم API في Kubernetes (مطلوب). |
--ca-data <base64> |
شهادة CA للمجموعة بترميز Base64 لملف kubeconfig المُنشأ. |
--config <path> |
ملف إعدادات الموصل لقراءة المثيل منه. |
--target <shape> |
systemd (الافتراضي: إرسال الحزمة إلى جهاز افتراضي عبر قناة بعيدة، أو إنشاؤها محليًا باستخدام --provider local) أو helm (دفع الحزمة بوصفها Kubernetes Secret للمخطط). |
--target-namespace <ns> |
مساحة الأسماء التي يُنشأ فيها Secret الحزمة (مطلوب مع --target helm). |
--instance-namespace <ns> |
(--target helm) مساحة أسماء مثيل ClickHouse الهدف. |
--force |
يستبدل حزمة موجودة؛ ويُستخدم لإعادة التنفيذ وتدوير بيانات الاعتماد. |
--secret-name <name> |
يتجاوز اسم Secret الحزمة (الافتراضي clicklink-connector-<component>-access-<instance>). |
--output-dir <path> |
(--target helm أو --provider local) الدليل الجذر الذي توضع فيه الحزمة. |
--ch-admin-user <name> |
مستخدم ClickHouse إداري لتطبيق الصلاحيات (الافتراضي default). |
--ch-admin-password-stdin |
يقرأ كلمة مرور مستخدم ClickHouse الإداري من stdin. |
--ch-user-suffix <suffix> |
لاحقة اختيارية لاسم مستخدم ClickHouse الذي تمت تهيئته. |
--ch-user-via <mode> |
كيفية تهيئة مستخدم ClickHouse: sql (الافتراضي؛ يطبّق الصلاحيات المُنشأة باستخدام --ch-admin-user) أو cr (يكتب المستخدم في المورد المخصص للمثيل، للمثيلات التي يديرها المشغّل ولا يتوفر لها مستخدم إداري قادر على تنفيذ SQL). |
--apply-ch-grants |
(--target helm) يطبّق الصلاحيات المُنشأة داخل كبسولة عبر kubectl exec بدلًا من تركها لتطبيقها بنفسك. |
--ch-pod <ref>, --ch-pod-namespace <ns>, --ch-container <name> |
(--target helm مع --apply-ch-grants أو --ch-user-via cr) حدّد كبسولة وحاوية ClickHouse لتنفيذ الأمر داخلهما. |
--token-duration <dur> |
مدة صلاحية رمز حساب الخدمة (الافتراضي 2160h، 90 يومًا؛ يقيّد EKS مدة الصلاحية بـ24 ساعة). |
--skip-restart |
يتخطى إعادة تشغيل المكوّن بعد التهيئة. |
--dry-run |
يطبع الخطة ثم ينهي التنفيذ؛ دون أي عمليات كتابة في Kubernetes أو عن بُعد أو في ClickHouse. |
دوّر بيانات اعتماد مثيل لمكوّن واحد:
clicklink clctl scraper access provision --target helm \
--target-namespace <connector-namespace> \
--instance <instance-name> --instance-namespace <clickhouse-namespace> \
--server <kubernetes-api-server-url> \
--apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace <clickhouse-namespace> \
--forceعلامات القناة البعيدة
تقبل preflight وgateway trust وaccess provision مجموعة مشتركة من العلامات التي تحدد كيفية الوصول إلى جهاز VM الهدف:
| العلامة | الوصف |
|---|---|
--provider <name> |
قناة التنفيذ: ssh أو aws (SSM) أو gcp (IAP) لأجهزة VM البعيدة، أو local عند التشغيل على جهاز VM الهدف نفسه. يُستنتج من الخيارات الخاصة بكل موفر عند عدم تعيينه صراحةً؛ ولا يُستنتج local مطلقًا. |
--ssh-host <host>, --ssh-user <user>, --ssh-port <port>, --ssh-identity-file <path> |
تفاصيل اتصال SSH (--provider ssh)؛ تُستخدم إعدادات SSH لديك افتراضيًا للمستخدم والمنفذ والمفتاح. |
--instance-id <id>, --region <region>, --profile <name> |
مثيل EC2 والمنطقة وملف تعريف الإعدادات المشتركة لـ SSM (--provider aws). |
--project <id>, --zone <zone>, --instance-name <name> |
المشروع والنطاق والمثيل لنفق IAP (--provider gcp). |