لماذا التخلي عن خدمات CI السحابية لصالح خط أنابيب على خادم VPS
تفوتر خدمات CI السحابية بالدقيقة وتفرض قوائم انتظار مشتركة تطول مع الحجم. حين تكبر المستودعات أو تتضاعف الاختبارات، تتجاوز الفاتورة بسرعة تكلفة VPS مخصص. استضافة Forgejo وWoodpecker CI على الخادم ذاته تُلغي هذا الزمن الضائع في الشبكة: يقرأ المشغّل الكود محلياً دون المرور عبر بنية تحتية خارجية. تتحكم أيضاً في دورة التحديث — لا يُطبَّق أي تغيير في التسعير أو سياسة الاحتفاظ بالسجلات دون موافقتك. بالنسبة للفرق الخاضعة لمتطلبات تنظيمية أو سرية، هذه ميزة حاسمة: أسرار التكامل (مفاتيح SSH للنشر، رموز الوصول إلى السجل) لا تتجاوز حدود شبكتك. وأخيراً، يكفل ترخيص Apache 2.0 أن يظل الكود المصدري قابلاً للتدقيق.
ما يوفره Woodpecker CI على خادم VPS
- عزل Docker لكل خطوة — تعمل كل خطوة في حاويتها الخاصة دون حالة مشتركة بين المهام؛ فشل خطوة لا يُفسد ما يليها.
- بصمة ذاكرة خفيفة — يبدأ الخادم والوكيل معاً بأقل من 50 ميغابايت من الذاكرة، مما يُبقي معظم الموارد لعمليات البناء.
- صياغة YAML بسيطة — يكفي ملف
.woodpecker.yamlفي جذر المستودع لوصف خط الأنابيب بالكامل؛ الصياغة أوضح من GitHub Actions. - تكامل أصيل مع Forgejo — بروتوكول OAuth2 الخاص بـForgejo هو الآلية الوحيدة للمصادقة المطلوبة؛ يُسجَّل الـwebhook تلقائياً.
- دعم متعدد المعماريات بدون إضافات — مفتاح
platform: linux/arm64يوجّه المهمة إلى وكيل ARM64 دون أي تجريد إضافي. - أسرار مركزية لكل مستودع أو عالمية — تُحقَن المتغيرات الحساسة وقت البناء ولا تظهر في ملف YAML الخاضع للإصدار.
- ترخيص Apache 2.0 — كود مصدري قابل للتدقيق، مجتمع تفرع نشط، بلا اعتماد على موفر خاص.
المتطلبات المحددة: خادم VPS وForgejo والشبكة
يمكن تثبيت Woodpecker CI على الخادم ذاته الذي يضم Forgejo أو على خادم مخصص. للخدمتين معاً، خصص 1 غيغابايت من الذاكرة كحد أدنى، و2 غيغابايت للاستخدام المريح مع عدة مستودعات نشطة بالتوازي. على صعيد البرمجيات: Docker Engine 24 أو أحدث، Docker Compose v2 (أمر docker compose)، نطاق فرعي مخصص لـWoodpecker — مثلاً ci.votre-domaine.com — يشير إلى IP الخادم، والمنفذ 443 مفتوحاً لـHTTPS، وصول SSH. يجب أن يكون Forgejo متاحاً من حاوية Woodpecker: عبر شبكة Docker الداخلية إذا كانا على الخادم ذاته، أو عبر عنوان URL العام لـHTTPS إذا كان Woodpecker على خادم منفصل. Woodpecker CI v3 متوافق مع Forgejo v1.20 وما فوق.
Woodpecker CI مقابل Forgejo Actions: متى تستخدم أيهما
Forgejo Actions — متاح منذ Forgejo v1.19 بصورة تجريبية، ومستقر تدريجياً — يُكرر صياغة GitHub Actions: إذا كانت فرقك تمتلك بالفعل سير عمل .github/workflows/ في الإنتاج، فالانتقال يكاد يكون شفافاً. Forgejo Actions هو الخيار الطبيعي لأسطول مستودعات يتعايش مع GitHub أو يُعيد استخدام إجراءات عامة من السوق. أما Woodpecker CI فيستجيب لاحتياجات مختلفة: صياغة YAML أكثر مباشرة، وبنيته المعتمدة على الخادم-الوكيل تُتيح فصل بيئة git عن محرك CI — مفيد حين تحتاج أسطول من المشغّلات إلى خدمة عدة بيئات git. وهو أيضاً الأنسب لبناء متعدد المعماريات حيث يُوجَّه كل مهمة إلى وكيل محدد. خلاصة: اختر Forgejo Actions إذا كانت توافقية GitHub Actions أولوية، وWoodpecker CI إذا أردت صياغة مبسّطة أو نشراً مفصولاً أو أسطولاً متغاير المعماريات.
نشر Woodpecker CI على خادم VPS
إنشاء تطبيق OAuth في Forgejo
في Forgejo، انتقل إلى الإعدادات ← التطبيقات ← إدارة تطبيقات OAuth2. أعطِ التطبيق اسماً (مثلاً
woodpecker) وأدخل عنوان إعادة التوجيه: https://ci.votre-domaine.com/authorize. دوّن معرف العميل وسر العميل المُنشأَين؛ ستحتاجهما في متغيرات بيئة خادم Woodpecker.توليد سر مشترك بين الخادم والوكيل
أنشئ سلسلة عشوائية قوية:
openssl rand -hex 32. ستُعيَّن هذه القيمة كـWOODPECKER_AGENT_SECRETفي خدمتي الخادم والوكيل؛ وهي تُصادق على الاتصال عبر gRPC بينهما. احفظها في مدير أسرار أو ملف .envغير خاضع للإصدار.إنشاء المجلد وملف docker-compose.yml
أنشئ المجلد
/opt/woodpecker/وضع فيه ملفdocker-compose.yml. تستخدم خدمة woodpecker-serverالصورة woodpeckerci/woodpecker-server:v3وتكشف المنفذين 8000 (واجهة المستخدم) و9000 (gRPC). عيّن المتغيرات:WOODPECKER_FORGEJO=true،WOODPECKER_FORGEJO_URL،WOODPECKER_FORGEJO_CLIENT،WOODPECKER_FORGEJO_SECRET،WOODPECKER_AGENT_SECRET، وWOODPECKER_HOST=https://ci.votre-domaine.com. تستخدم خدمة woodpecker-agentالصورة woodpeckerci/woodpecker-agent:v3وتُركّب /var/run/docker.sockوتستقبلWOODPECKER_SERVER=woodpecker-server:9000والـWOODPECKER_AGENT_SECRETذاته.تكوين الـ reverse proxy بـ HTTPS
كوّن Traefik أو Caddy لإنهاء TLS على
ci.votre-domaine.comوتوجيه الطلبات إلى woodpecker-server:8000. مع Caddy كتلة بسيطة كافية:ci.votre-domaine.com { reverse_proxy woodpecker-server:8000 }. لا تكشف المنفذ 8000 مطلقاً على الـIP العامة؛ يجب أن يبقى المنفذ 9000 (gRPC) متاحاً فقط على شبكة Docker الداخلية.تشغيل المكدس
في
/opt/woodpecker، نفّذdocker compose up -d. راقب السجلات بـdocker compose logs -f woodpecker-serverحتى ترى server started. يظهر الوكيل في سجلات الخادم برسالة agent connected؛ إن لم يظهر خلال ثلاثين ثانية، تحقق من تطابقWOODPECKER_AGENT_SECRETفي الخدمتين.تسجيل الدخول وتفعيل أول مستودع
افتح
https://ci.votre-domaine.comوسجّل الدخول بحسابك في Forgejo عبر OAuth2. في لوحة التحكم، انقر «إضافة مستودع» واختر المشروع المراد تفعيله. يسجّل Woodpecker تلقائياً webhook في Forgejo لتشغيل عمليات البناء عند كل دفع أو طلب سحب.إضافة ملف .woodpecker.yaml إلى المستودع
في جذر المستودع، أنشئ
.woodpecker.yaml. مثال بسيط بثلاث خطوات:lint(صورة node:20، أمر npm run lint)،test(صورة node:20، أمر npm test) ومرحلة deployمشروطة بالفرع mainتُشغّل سكربت SSH بعيداً. ادفع الملف: تنطلق عملية بناء فوراً في Woodpecker ويظهر نتيجتها في الواجهة وفي حالة الـcommit في Forgejo.التحقق من استمرارية البيانات
بشكل افتراضي، يحفظ Woodpecker قاعدة بيانات SQLite داخل الحاوية. لتثبيت دائم، اربط مجلداً volume باسم على
/var/lib/woodpeckerفي خدمة الخادم واحتفظ بنسخ احتياطية منتظمة. إعادة التشغيل أو تحديث الصورة دون volume يمسح تاريخ عمليات البناء وتكوين المستودعات المُفعَّلة.
كتابة أول pipeline في .woodpecker.yaml
يصف ملف .woodpecker.yaml سلسلة خطوات تُنفَّذ بالتتابع في حاويات Docker منفصلة. لكل خطوة اسم وصورة وقائمة أوامر. يمكن للخطوات مشاركة مساحة العمل (المجلد المستنسخ) عبر مجلد volume يُركّبه Woodpecker تلقائياً. لمشروع Node.js، يشمل pipeline أساسي خطوة lint (node:20، npm ci && npm run lint)، وخطوة test (node:20، npm test)، وخطوة build (node:20، npm run build). لمشروع Docker، أضف خطوة تستخدم الإضافة الرسمية woodpeckerci/plugin-docker-buildx لبناء الصورة ودفعها إلى سجل. يُعبَّر عن التشغيل الشرطي بكتلة when: when: { branch: main, event: push } يُقيّد خطوة النشر بالفرع الرئيسي عند الدفع المباشر فقط.
الأسرار ومتغيرات البيئة في خطوط الأنابيب
يُميّز Woodpecker بين مستويين من الأسرار: أسرار المستودع (مرئية فقط في pipelines المستودع المعني) والأسرار العالمية (متاحة لجميع المستودعات، تُنشأ بحذر). يُعلَن السر في لوحة التحكم — في قسم Secrets للمستودع — ثم يُشار إليه في pipeline بالصياغة from_secret. مثلاً، مفتاح SSH للنشر باسم deploy_key يُحقَن في خطوة عبر environment: { SSH_KEY: { from_secret: deploy_key } }. الأسرار لا تُمرَّر افتراضياً إلى طلبات السحب من forks خارجية. للمتغيرات غير الحساسة المشتركة عبر مستودعات متعددة، استخدم WOODPECKER_ENVIRONMENT على مستوى الخادم.
ضع خادم Woodpecker خلف Traefik أو Caddy بـHTTPS ولا تكشفه مطلقاً مباشرة على المنفذ 8000. فعّل مصادقة القائمة البيضاء (WOODPECKER_ADMIN) لتقييد الوصول إلى لوحة التحكم على الحسابات المُصرَّح بها في Forgejo فقط. خزّن كل أسرار pipeline (رموز SSH، مفاتيح API، كلمات مرور سجل Docker) في أسرار المستودع بلوحة تحكم Woodpecker — تُحقَن كمتغيرات بيئة أثناء البناء دون ظهورها في .woodpecker.yaml الخاضع للإصدار. أخيراً، اربط volume باسم لحفظ قاعدة بيانات SQLite.
أجهزة التشغيل متعددة المعماريات: x86_64 وARM64
يدعم Woodpecker CI v3 أصلاً وكلاء متعددي المعماريات: كل وكيل يُعلن منصته للخادم (linux/amd64، linux/arm64، linux/arm/v7) والخادم يُوجّه المهام إلى الوكيل المطابق. لتعريف مهمة ARM64، أضف platform: linux/arm64 على مستوى pipeline في .woodpecker.yaml. إذا كان لديك VPS بمعمارية ARM وآخر بـx86_64، ثبّت وكيلاً على كل منهما بنفس WOODPECKER_AGENT_SECRET ودع الخادم يوزع عمليات البناء. يُفيد هذا في التصليب المتبادل للثنائيات، واختبار توافق صور Docker عبر المعماريات. تذهب الإضافة woodpeckerci/plugin-docker-buildx أبعد بإنتاج صور متعددة المعماريات من وكيل واحد عبر QEMU، لكن البناء الأصيل على المعمارية المستهدفة يظل دائماً أسرع.
استكشاف الأخطاء: خمسة أخطاء شائعة
تظهر خمسة مشكلات بانتظام أثناء التثبيت أو الاستخدام. الأولى: الوكيل لا يتصل بالخادم (agent could not auth). السبب الأكثر شيوعاً: WOODPECKER_AGENT_SECRET غير متطابق بين الخدمتين. تحقق بـdocker compose exec woodpecker-server env | grep AGENT_SECRET. الثانية: تسجيل الدخول عبر OAuth2 يفشل بـError while authenticating against OAuth provider. تحقق من أن عنوان إعادة التوجيه في تطبيق Forgejo OAuth2 يطابق تماماً WOODPECKER_HOST. الثالثة: pipelines تبقى عالقة في pending. ربما مفتاح المنصة platform لا يطابق أي وكيل متاح؛ احذفه إن لم يكن ضرورياً. الرابعة: الأسرار لا تُحقَن. تُمرَّر الأسرار فقط للـpipelines المُشغَّلة على الفروع الداخلية، لا على PRs من forks خارجية افتراضياً. تحقق من أن الحدث المُشغِّل هو push أو tag. الخامسة: بعد الترقية لـv3.18، سجلات البناء القديمة مفقودة — يتضمن هذا الإصدار ترحيل تخزين سجلات؛ أعد تشغيل الحاوية بصلاحيات كتابة على مجلد البيانات لاستئناف الترحيل.
التكامل مع سوق تطبيقات ServOrbit: نشر تلقائي على VPS
يوفر ServOrbit تطبيق Woodpecker CI في سوق تطبيقاته: يُثبَّت على VPS سحابي بـDocker مُهيَّأ مسبقاً وعنوان IP ثابت، في بضع نقرات من بوابة العميل. بعد توفير الـVPS، ما عليك سوى توجيه WOODPECKER_FORGEJO_URL إلى بيئة Forgejo الموجودة لديك وإدخال مفاتيح OAuth2 لبدء تشغيل خطوط الأنابيب. هذا التكامل مفيد تحديداً للوكالات والفرق التقنية التي تريد عزل محرك CI عن خادم بيئة git. موارد الـVPS قابلة للتعديل في أي وقت من بوابة العميل — إضافة RAM أو vCPU دون إعادة تثبيت — مما يُتيح تحجيم أسطول المشغّلات وفق حمل البناء الفعلي.
من بيئة git إلى النشر المستمر: مكدس سيادي متكامل
يدير Forgejo الكود والمشكلات ومراجعات طلبات السحب؛ ينسّق Woodpecker CI خطوط أنابيب الاختبار والنشر. يتواصل الاثنان عبر OAuth2 والـwebhooks على شبكتك الخاصة، دون اعتماد على GitHub أو GitLab أو خدمة تكامل سحابية. يستجيب هذا المكدس المستضاف ذاتياً لمتطلبات السيادة للوكالات والفرق التقنية التي لا تريد أن تعبر ملكيتها الفكرية أو أسرار تكاملها عبر منصات خارجية. مع Woodpecker CI v3 وForgejo v1.20 أو أحدث، تحصل على بيئة تطوير متكاملة — بيئة git، CI/CD، سجل Docker إذا لزم — تحت سيطرتك الكاملة، على خادم أو خادمَين، بتكلفة شهرية قابلة للتنبؤ.
