Cloudflare CLI: دليل عملي للتثبيت والترحيل الآمن

المكسب العملي ليس اختصار الأمر، بل تقليل أعمال التكامل. يستطيع المؤسس فحص حسابه من دون التنقّل بين صفحات لوحة التحكم، ويمكن لفريق المنصة تزويد الوكيل بنتائج قابلة للقراءة آلياً، كما تستطيع الوكالة توحيد العمل على Cloudflare عبر حسابات عملائها من دون صيانة غلاف API مستقل لكل منتج.

لا توجد رخصة مستقلة يجب شراؤها لاستخدام cf. المستودع مفتوح المصدر، ويمكن بدء Worker صغير ضمن خطة Cloudflare المجانية، بينما يبلغ الحد الأدنى الشهري لخطة Workers Paid مبلغ $5. وفي الطرف الأعلى من الميزانية، تعرض منصة عامة لحوكمة البنية التحتية مثل Spacelift باقة Starter+ بسعر $20,000. تزيل cf قدراً كبيراً من أعمال ربط الـAPI بين هذين الطرفين، لكنها لا تلغي الحاجة إلى الموافقات أو سجلات التدقيق أو ضبط الصلاحيات بعناية.

ما هو Cloudflare CLI الجديد فعلاً؟

توفّر cf واجهة أوامر مولّدة تغطي Cloudflare API بالكامل، إلى جانب مسارات عمل مصمّمة يدوياً لمهام مثل إنشاء Workers وبنائها وترحيلها ونشرها. يمكن تشبيه Wrangler بمنضدة متخصصة ومتكاملة لأعمال Workers؛ أما cf فتضيف دليلاً ومكتب خدمات لمبنى Cloudflare بأكمله، ثم تعيد بعض مهام Workers إلى Wrangler عندما تظل هي الأداة الأوثق لها.

وهذا الفارق هو أيضاً ما يميز الإصدار الحالي عن المعاينة التقنية التي طرحتها Cloudflare في 13 أبريل. فقد اقتصرت نسخة أبريل على مجموعة صغيرة من المنتجات، بينما يقدّم الإصدار التجريبي المفتوح في سبتمبر تغطية كاملة للـAPI، ونتائج JSON افتراضية، والبحث عن الأوامر، وتهيئة Worker باستخدام TypeScript، واعتماد Vite مساراً افتراضياً للـWorker.

أبرز أربعة تغييرات في مسار العمل واضحة:

• تغطية كاملة للـAPI: تتبع الأوامر المولّدة النمط cf <product> [group…] <operation> عبر أكثر من 3,000 عملية.
• البحث عن الأوامر: يستقبل cf cli search وصفاً عادياً للمهمة ويعيد خمس نتائج JSON مرتبة حسب الصلة، فلا حاجة إلى حفظ شجرة الأوامر.
• JSON افتراضياً: تُرسل نتائج الـAPI المنظّمة إلى المخرج القياسي بصيغة JSON منسّقة، ما يتيح للشخص أو السكربت أو وكيل البرمجة تصفية الاستجابة نفسها.
• إعداد Worker بأنواع محددة: يمنح cloudflare.config.ts المحررات ووكلاء البرمجة ملاحظات TypeScript. يبدأ ذلك مع Workers اليوم؛ أما تهيئة الحساب بأكمله، بما يشمل DNS والمناطق والسياسات، فهي توجه مستقبلي وليست ميزة متاحة حالياً.

تثبيت Cloudflare CLI والمصادقة واختبار أول قراءة

ابدأ بعملية للقراءة فقط. بهذه الخطوة تتأكد من الحزمة وبيانات الاعتماد واختيار الحساب واكتشاف الأوامر ومسار JSON، قبل السماح لأي سكربت بإجراء تغييرات.

تتطلب الحزمة الرسمية Node.js 22 أو أحدث. عند الاستخدام البشري من الطرفية، يدير cf auth login ملف OAuth الافتراضي. أما في CI، فاضبط متغير CLOUDFLARE_API_TOKEN بصلاحيات محدودة؛ إذ تتحقق cf من هذا المتغير البيئي قبل أي ملف OAuth محفوظ. ويمكن إنشاء ملفات تعريف مسماة وربطها بأدلة مختلفة عند العمل على حسابات عدة لعملاء أو شركات.

اجعل النص المرسل إلى cf cli search عاماً. اذكر الإجراء ونوع المورد، ولا تضع فيه نطاقاً أو عنوان بريد إلكتروني أو معرّف حساب أو رمز وصول.

node --version
npm i -g cf
cf --version

cf auth login
cf auth whoami

cf cli search "list zones in an account"
cf zones list | jq -e 'type == "array" and all(.[]; has("name") and has("status"))'

يضع البحث حالياً cf zones list في المرتبة الأولى لهذه المهمة. والسطر الأخير هو الاختبار الفعلي: يجري طلب API للقراءة فقط، ولا ينتهي بنجاح إلا إذا كانت النتيجة مصفوفة JSON تحتوي عناصرها على name وstatus. إذا كنت تدير حسابات عدة، فاختر ملفاً مسمى عبر --profile أو قيّد الأمر باستخدام --account-id.

لا تلصق رمز الوصول في سجل أوامر الصدفة. ضعه بصلاحيات محدودة في بيئة العملية التي يستخدمها CI، ولا تمنحه سوى أذونات القراءة أو الكتابة اللازمة للمهمة. ويظل OAuth الخيار الأسهل لجلسة طرفية فردية، لأن cf تستطيع تحديث ملف التعريف المحدد.

ما الذي أثبته الاختبار المؤقت؟

أعاد تثبيت جديد ومعزول أُجري في 29 سبتمبر الإصدار cf v1.0.0-beta.5. وأرجع البحث عن الأوامر مصفوفة JSON صالحة من خمسة عناصر، وأنشأ cf init مشروع Worker بتهيئة ذات أنواع، كما اكتمل البناء المحلي لكل من المشروع الجديد ونموذج Vite جرى ترحيله. لم تتضمن البيئة بيانات اعتماد لحساب Cloudflare مخصص للاختبار، لذلك لم تُسجّل قراءة المناطق بعد المصادقة ولا عملية النشر ضمن الاختبارات المكتملة.

هذا الحد الفاصل مهم: نجاح البناء المحلي يثبت سلامة مسار المشروع، لكنه لا يثبت أن الرمز يملك صلاحيات الإنتاج المناسبة أو أن عملية النشر وصلت إلى Cloudflare.

أنشئ Worker صغيراً ثم افحص ما أنشأته cf

يقدّم cf init أسرع اختبار نظيف لمسار المشروع الجديد. عند تشغيله في دليل فارغ، ينشئ شيفرة TypeScript وملفي cloudflare.config.ts وvite.config.ts وسكربتات الحزمة وأنواع Worker مولّدة. بعد ذلك يفوّض cf build عملية البناء إلى Cloudflare Vite Plugin وينتج Build Output موحداً.

cf init hello-cf --package-manager npm
cd hello-cf
npm run build

# In a copied existing Vite Worker:
cf migrate --dry-run
cf migrate
npm run build

افتح cloudflare.config.ts بعد أي من المسارين. في Worker أساسي، ينبغي أن تجد كتلة worker وفيها الاسم وتاريخ التوافق ونقطة الدخول والارتباطات ذات الأنواع. ويُعرّف الارتباط النصي عبر API التهيئة بدلاً من نسخه بين عدة كتل بيئية. هنا تظهر قيمة TypeScript: قد يتحول الحقل المكتوب خطأ إلى تنبيه داخل المحرر قبل أن يصبح عملية نشر فاشلة.

إعداد Vite المولّد ليس إضافة شكلية؛ فقد أصبح Vite المسار الافتراضي للتطوير المحلي والبناء في cf، كما توصي Cloudflare بإضافتها الخاصة بـVite لكل من الواجهات الأمامية وواجهات API الخلفية. في المشروع المؤقت، فوّض npm run build المهمة إلى Vite واكتمل بنجاح. أما النشر فتُرك خارج الاختبار عمداً. وبعد اكتمال المراجعة واختبار الحساب، ينفّذ الأمر الموثق cf deploy البناء والرفع افتراضياً.

متى يبقى Wrangler ضرورياً؟

لا تزل Wrangler لمجرد أن تثبيت cf نجح. قرار الترحيل الصحيح يتوقف على مسار بناء المشروع.

في مشروع Worker قائم على Vite، يستطيع cf migrate تحويل إعدادات Wrangler المكتوبة بصيغ JSON أو JSONC أو TOML إلى cloudflare.config.ts. يكتشف الأمر Cloudflare Vite plugin بجوار إعداد Wrangler ويختار مسار Vite. وإذا لم تكن الإضافة معلنة، تختار الإصدارات التجريبية الحالية أداة تجميع Wrangler بدلاً منها. شغّل المعاينة الجافة، واقرأ كل بنود المتابعة، ونفّذ الترحيل على نسخة أو فرع نظيف قبل المساس بالمشروع الفعلي.

أما Workers المكتوبة بـJavaScript والتي ما زالت تعتمد على سلوك esbuild في Wrangler، فتفوّض cf إليها التطوير والنشر. وينطبق الأمر نفسه على Workers المكتوبة بـRust وPython. هذه آلية توافق وليست دليلاً على فشل الترحيل؛ إذ يحصل الفريق على cf بوصفها المدخل الموحد، مع إبقاء أداة البناء المجرّبة ضمن المسار.

ومن السهل أيضاً إساءة فهم جدول دعم Cloudflare. فالمخطط هو صيانة Wrangler مدة 18 شهراً بعد انتهاء الإصدار التجريبي المفتوح، لا 18 شهراً من إطلاق 28 سبتمبر. لذلك لا داعي لفرض التحول إلى Vite هذا الأسبوع على مشروع يستخدم Rust أو Python أو esbuild.

سبعة مسارات عمل تحقق قيمة سريعة

تشترك أفضل حالات البداية في سمة واحدة: فهي تستبدل أعمال البحث والتنسيق المتكررة، من دون منح صلاحيات كتابة واسعة منذ اليوم الأول.

1. وكالة توحّد عمليات فحص الحسابات

يستطيع مسؤول الوكالة ربط ملف OAuth مسمى بكل دليل عميل، والبحث عن أمر القراءة المناسب، ثم تمرير مخرجات JSON بالشكل نفسه إلى سكربت المراجعة. يحد ذلك من التفاوت الذي ينشأ عندما يتنقل مهندس بين لوحات التحكم بينما يصون آخر أمراً مخصصاً باستخدام curl. وتظهر الفائدة في قابلية تكرار العمل بين حسابات العملاء، ولا سيما في مراجعات DNS والمناطق وإعدادات الحساب والأمان.

2. فريق منصة يمنح وكلاء البرمجة واجهة آمنة إلى Cloudflare

يمكن لقائد المنصة وضع قاعدة في AGENTS.md تضبط استخدام cf cli search، وتسمح بأوامر القراءة افتراضياً، وتفرض موافقة بشرية على أي تغيير. يمنع البحث الوكيل من تخمين صياغة Wrangler قديمة، بينما تحافظ JSON على مخرجات موجزة قابلة للتصفية. وتفيد هذه الآلية خصوصاً عندما يستخدم الفريق الوكلاء بالفعل لفحص حالة البناء أو السجلات أو قوائم الانتظار أو موارد الحساب، ويريد واجهة واحدة يمكن توقع سلوكها.

3. مهندس المناوبة يجمع سياق الحادثة

أثناء الحوادث، يستطيع المسؤول البحث عن أمر قراءة السجلات أو المنطقة أو مجموعة القواعد أو التحليلات المناسبة، بدلاً من التنقل بين لوحات منتجات عدة. يظل اختيار الأمر الدقيق مهماً وتظل الصلاحيات سارية، لكن خطوة الاكتشاف أصبحت محلية والاستجابة جاهزة لـjq. وبالنسبة إلى الفرق التي تشغّل مهام مثل Cloudflare Browser Run، يختصر ذلك الطريق من المهمة الفاشلة إلى حالة الحساب المحيطة بها.

4. مؤسس يبدأ Worker واحداً من دون تصميم سلسلة أدوات

يمكن لمؤسس يبني webhook أو خدمة إعادة توجيه أو API داخلية صغيرة تشغيل cf init، وفحص Worker والارتباط المولّدين، ثم استخدام بناء Vite من دون اختيار كل حزمة على حدة. ويمكن بدء المشروع على Workers Free؛ وإذا احتاج إلى الخطة المدفوعة، فالحد الأدنى الحالي هو $5 لكل حساب شهرياً. الفائدة هنا هي الوصول سريعاً إلى ملف محلي قابل للمراجعة، لا وعداً بأن عمليات الإنتاج ستصبح مجانية.

5. فريق Vite يحوّل التهيئة من دون إعادة كتابة التطبيق

يستطيع فريق هندسي لديه Worker قائم على Vite تشغيل cf migrate --dry-run على نسخة، وفحص TypeScript المولّد، ثم إجراء البناء قبل تغيير النشر. ويكون ذلك مفيداً خصوصاً عندما تصبح كتل البيئات متكررة. يتيح التنسيق الجديد حساب التهيئة انطلاقاً من قاعدة مشتركة، لكن المطلوب ترحيل السلوك لا مجرد صيغة الملف.

6. فريق بيانات أو عمليات يمرر قراءات Cloudflare إلى التقارير

لأن النتائج المنظّمة تأتي بصيغة JSON افتراضياً، يستطيع المسؤول تمرير عملية قراءة إلى jq أو أداة تحميل مستودع بيانات أو تقرير مجدول، من دون استخراج البيانات من جدول Unicode. والفائدة التجارية عملية ببساطة: محولات مخرجات أقل وقواعد تحليل هشة أقل. استخدم رمز قراءة محدود الصلاحيات، ولا تعرض مخرجات الأوامر في سجلات CI العامة.

7. فريق Worker يفحص الموارد المحلية قبل الاقتراب من الإنتاج

تقبل الأوامر المدعومة الخيار --local وتتصل بنسخة Miniflare قصيرة العمر تستند إلى حالة محلية. ويشمل ذلك العمليات المعرّفة عبر KV وD1 وR2. إذا لم يتوفر بديل محلي، تعيد cf خطأ بدلاً من الانتقال بصمت إلى الإنتاج. ويمكن لفريق يبني Cloudflare AI Search Worker استغلال هذا الحد لاختبار البيانات المحلية المساندة، من دون تحويل أمر تطوير إلى عملية كتابة بعيدة.

منتجان يستحقان البناء بالاعتماد على cf

الفرصة التجارية ليست في أداة CLI نفسها، بل في طبقة التحكم التي لا تزال الفرق تحتاج إليها حول واجهة API واسعة بهذا الشكل.

أفضل فرصة: ضبط تغييرات Cloudflare للوكالات

يمكن بناء طبقة مركزة للموافقة وتوثيق الأدلة، موجهة إلى الوكالات أو فرق المنصات الصغيرة التي تدير حسابات Cloudflare عدة. يقترح المستخدم تغييراً في DNS أو منطقة أو WAF أو Worker؛ ثم يستخدم المنتج cf لجمع حالة JSON الحالية، ويعرض فرقاً مفهوماً للبشر، ويطلب الموافقة، وينفّذ التغيير بملف تعريف محدود الصلاحيات، ويحفظ النتيجة.

إشارة الطلب محدودة لكنها تجارية: يستقبل استعلام cloudflare dns management نحو 170 عملية بحث شهرياً في الولايات المتحدة، وتبلغ كلفة النقرة فيه $6، فيما تتراوح عروض أعلى الصفحة بين $3.85 و$36.64. كما أن الحوكمة العامة للبنية التحتية تستقطب ميزانيات فعلية؛ إذ تعرض Spacelift باقة Starter+ بسعر $20,000. ويمكن لمنتج متخصص في Cloudflare أن يكون أقل كلفة وأسهل اعتماداً، لأنه غير مضطر إلى حوكمة كل الخدمات السحابية.

أصغر إصدار قابل للبيع هو تطبيق GitHub أو قائمة مراجعة مستضافة لتغييرات DNS وWorker، تتضمن عزل ملفات التعريف، وقائمة أوامر مسموح بها، وحالة JSON قبل التنفيذ وبعده، وتراجعاً بنقرة واحدة عندما تدعمه الـAPI الأساسية. لكن التحدي يكمن في الميزة الدفاعية: توفر cf تغطية الأوامر بالفعل، لذا تتركز القيمة التي يصعب تقليدها في السياسات والأدلة والصلاحيات ومسار عمل الوكالة. أما الغلاف الرسومي البسيط فسيسهل نسخه سريعاً.

ميزة مفيدة: قياس جاهزية ترحيل Worker

يمكن بناء أداة فحص تصنّف المستودع إلى Vite أصلي، أو esbuild يعمل عبر Wrangler، أو Python، أو Rust؛ ثم تشغّل معاينة الترحيل الآمنة وتحول بنود المتابعة إلى قائمة تحقق لطلب السحب. المشترون هنا فرق تملك مجموعة من Workers، لا مطوراً منفرداً يرحّل مشروعاً صغيراً واحداً.

الطلب أقل من أن يدعم شركة كاملة بمفرده. يستقبل استعلام cloudflare worker deployment نحو 10 عمليات بحث شهرياً في الولايات المتحدة، رغم أن نيته شرائية. لذلك يكون المنتج الأولي المنطقي ميزة مدفوعة داخل منتج لعمليات Cloudflare أو خدمة ترحيل، وتشمل فحص المستودع وتشغيل cf migrate --dry-run والتحقق من البناء وتقريراً واضحاً للعودة إلى Wrangler. والتحدي هو سرعة تغير الإصدارات خلال المرحلة التجريبية؛ إذ يجب أن تتابع الأداة إصدارات cf وCloudflare Vite Plugin بدقة، وإلا ستتقادم توصياتها أسرع من المشاريع التي تفحصها.

الحدود والقرار العملي الصريح

استخدم cf الآن لاكتشاف الأوامر، وقراءة الحساب بصيغة JSON أولاً، وإنشاء Workers جديدة على Vite، وتجارب الترحيل المدروسة. وأبقِ Wrangler مثبتة حيث تفوّض cf العمل إليها، مع إبقاء عمليات الكتابة إلى الإنتاج خلف صلاحيات صريحة ومراجعة واضحة.

لا يجعل الإصدار التجريبي المفتوح cloudflare.config.ts بعدُ مصدراً للحقيقة على مستوى الحساب كله؛ فهو يبدأ مع Workers. كما أنه لا يحوّل كل عملية في Cloudflare API إلى مسار عمل تجاري آمن. تزيد التغطية الكاملة للـAPI نطاق ما يستطيع الرمز الوصول إليه، ما يجعل مبدأ أقل الصلاحيات ومراجعة الأوامر أكثر أهمية لا أقل.

والخيار المحلي محدود عن قصد. يمكن لعمليات KV وD1 وR2 وDurable Object وWorkflow المدعومة استخدام الحالة المحلية، لكن أي عملية بلا نظير في المستكشف المحلي تعيد خطأ. هذه خاصية أمان جيدة، لكنها تعني أن --local ليس نسخة شاملة تعمل بلا اتصال من Cloudflare.

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

إذا أردت مساراً آمناً لأتمتة Cloudflare مصمماً ومبنياً لفريقك، فتعرّف إلى أنظمة AI للإنتاج.