🪶 تثبيت Woodpecker CI — خط CI/CD ذاتي الاستضافة

انشر Woodpecker CI على Ubuntu مع Docker — محرك CI/CD بسيط وقوي مع تعريفات pipeline بـ YAML وتنفيذ خطوات داخل حاويات Docker. يتكامل مع Gitea وGitHub وGitLab.

⚠️ راجع أي سكريبت دائمًا قبل تشغيله على سيرفرك، واختبره في بيئة تجريبية أولاً.

📦 الملفات والأكواد المطلوبة

قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.

سكريبت تثبيت آلي — Woodpecker server + agent بأمر واحد.
عرض على GitHub

التثبيت السريع:

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/woodpecker/woodpecker-ubuntu.sh
chmod +x woodpecker-ubuntu.sh
sudo bash woodpecker-ubuntu.sh

خطوات التنفيذ

1 تحميل وتشغيل السكريبت

يثبّت السكريبت Docker، يطلب عنوان سيرفر Gitea وبيانات OAuth، ويشغّل كلاً من Woodpecker server وagent.

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/woodpecker/woodpecker-ubuntu.sh
chmod +x woodpecker-ubuntu.sh
sudo bash woodpecker-ubuntu.sh

2 تسجيل الدخول عبر OAuth

افتح المتصفح وانتقل إلى لوحة Woodpecker. انقر تسجيل الدخول — ستُعاد التوجيه لموفر Git لتفويض تطبيق OAuth:

http://<your-server-ip>:8093

3 تفعيل مستودع

بعد تسجيل الدخول، تظهر مستودعاتك. انقر الزر الجانبي لمستودع لتفعيل CI/CD. سيُضيف Woodpecker تلقائياً webhook لموفر Git.

4 إنشاء أول Pipeline

Add a .woodpecker.yml file to the root of your repository. Each step runs inside a Docker container:

steps:
  - name: build
    image: node:20
    commands:
      - npm install
      - npm run build

  - name: test
    image: node:20
    commands:
      - npm test

المنافذ المستخدمة

المنفذالغرض
8093Woodpecker Web UI & API
9003Agent gRPC (internal)

نظرة عامة

Woodpecker CI هي نسخة مجتمعية من Drone CI — نظام CI/CD حديث وخفيف الوزن يستخدم حاويات Docker لخطوات خط الأنابيب. يُعرَّف خط الأنابيب في ملف .woodpecker.yml في جذر المستودع، مع تشغيل كل خطوة في حاوية Docker خاصة بها. يتكامل نصياً مع Gitea لبناءات تُشغَّل بـ webhooks.

لماذا تستخدمه

Woodpecker CI يكمل مجموعة DevOps ذاتية الاستضافة: Gitea للكود، وWoodpecker للـ CI/CD، وHarbor لتخزين الصور. على عكس Jenkins (ثقيل JVM وضبط XML وجحيم الإضافات) أو GitLab CI (يتطلب GitLab)، Woodpecker ملف ثنائي Go خفيف بخطوط أنابيب YAML أصلية لـ Docker تتكامل بشكل طبيعي مع Gitea عبر OAuth. لا عوامل مرخصة، ولا اعتماد سحابي، وتعريفات خطوط الأنابيب تعيش في المستودع بجانب الكود الذي تبنيه.

متى تحتاجه

  • تستخدم Gitea وتريد CI/CD يتكامل معها بشكل أصلي بدون منصة Git منفصلة
  • تحتاج خطوط أنابيب أصلية لـ Docker حيث تعمل كل خطوة في حاوية خاصة بها
  • تريد نظام CI يعمل على VPS بـ 1 GB RAM بدون JVM أو بيئة تشغيل ثقيلة
  • تحتاج بناء صور Docker ودفعها إلى Harbor عند كل دمج في الفرع الرئيسي
  • تريد تعريفات خطوط الأنابيب في ملفات YAML في المستودع وليس واجهة ويب
  • تحتاج نظام CI يعمل بالكامل بدون اتصال بالإنترنت أو في بيئة معزولة

من يحتاجه

  • مهندسو DevOps الذين يبنون CI/CD كامل ذاتي الاستضافة مع Gitea وHarbor
  • مطورو الخلفية الذين يريدون اختباراً ونشراً آلياً بدون GitHub Actions
  • الفرق في بيئات معزولة أو بدون إنترنت تحتاج CI/CD بدون اتصال
  • مشغّلو Homelab الذين يريدون بناءات آلية بدون خدمات سحابية
  • الفرق المنتقلة من Drone CI التي تريد fork المجتمع المُصان
  • الشركات الناشئة التي تستبدل CI سحابي مكلف (CircleCI، دقائق GitHub Actions) بخطوط أنابيب ذاتية الاستضافة

حالات الاستخدام الشائعة

  • بناء الكود واختباره ونشره تلقائياً عند دفع التغييرات إلى Gitea
  • تشغيل خطوات خط أنابيب متوازية في حاويات منفصلة لتسريع بناءات CI
  • بناء صور Docker ودفعها إلى Harbor أو Docker Hub عند الدمج في الفرع الرئيسي
  • نشر التطبيقات على سيرفرات الإنتاج عبر SSH عند إتمام خط الأنابيب بنجاح
  • فحص الكود بحثاً عن ثغرات أو تشغيل linters كبوابات جودة آلية
  • تشغيل مجموعات اختبارات تكاملية مقابل حاوية قاعدة بيانات تُشغَّل لكل خط أنابيب

الميزات الرئيسية

  • خطوط أنابيب أصلية لـ Docker — كل خطوة تعمل في صورة Docker محددة
  • تعريف خط الأنابيب بـ YAML (.woodpecker.yml) في جذر المستودع
  • تكامل أصلي مع Gitea وGitHub وGitLab وBitbucket عبر OAuth2
  • خطوات متوازية — تشغيل خطوات مستقلة في آنٍ واحد لتقليل وقت البناء
  • إدارة الأسرار — تخزين بيانات الاعتماد بشكل آمن وحقنها كمتغيرات بيئة
  • بناءات Matrix — اختبار عبر إصدارات لغة أو ضبط متعدد من YAML واحد
  • خطوط أنابيب Cron — جدولة بناءات منتظمة مستقلة عن أحداث git push
  • معمارية العوامل — تشغيل عوامل على أجهزة مختلفة لعزل البناء أو بناءات ARM

كيفية الاستخدام بعد التثبيت

  • افتح https://woodpecker.yourdomain.com وسجّل دخولك باستخدام حساب Gitea
  • فعّل المستودعات التي تريد CI لها: انقر + وفعّل المستودع
  • أضف ملف .woodpecker.yml لجذر مستودعك لتعريف خط الأنابيب
  • اضبط Secrets على مستوى المستودع لبيانات الاعتماد (سجل Docker ومفاتيح SSH ورموز API)
  • ادفع التزاماً لتشغيل خط الأنابيب الأول — راقبه يعمل في واجهة Woodpecker
  • اضبط سر سجل Harbor لدفع الصور المبنية: REGISTRY_PASSWORD كسر
  • اضبط إشعارات البريد أو ntfy لفشل خطوط الأنابيب في إعدادات المؤسسة/المشروع
  • أضف شارات خطوط الأنابيب لـ README مستودع Gitea باستخدام URL الشارة من Woodpecker

أفضل ممارسات الأمان

  • خزّن جميع الأسرار في قسم Secrets بـ Woodpecker — لا تضمّن بيانات الاعتماد في .woodpecker.yml
  • استخدم مفاتيح نشر للقراءة فقط لاستنساخ git في خطوات خطوط الأنابيب — لا رموز مسؤول
  • قيّد أحداث تشغيل خطوط الأنابيب — ابنِ فقط عند push/PR من الفروع الموثوقة
  • فعّل WOODPECKER_AUTHENTICATE_PUBLIC_REPOS=false لطلب تسجيل الدخول لعرض حالة خطوط الأنابيب
  • ضع سيرفر Woodpecker خلف Nginx Proxy Manager مع HTTPS — لا تكشف المنفذ 8000 مباشرة
  • دوّر الأسرار بانتظام، خاصة مفاتيح النشر وبيانات اعتماد السجل
  • استخدم إصدارات محددة لصور Docker في خطوات خطوط الأنابيب (لا :latest) لبناءات قابلة للاستنساخ

المنافذ وإعدادات جدار الحماية

يعمل سيرفر Woodpecker على المنفذ 8000 (gRPC للعوامل) والمنفذ 8080 (واجهة الويب). ضع واجهة الويب خلف Nginx Proxy Manager على HTTPS المنفذ 443. يجب أن يكون المنفذ 8000 قابلاً للوصول من عوامل Woodpecker — إذا كانت العوامل على نفس الجهاز فهو داخلي. ترسل Gitea webhooks لـ URL HTTPS العام لـ Woodpecker على المنفذ 443 — تأكد من أن Gitea تصل لنطاق Woodpecker. لا منافذ واردة إضافية غير 443 إذا كانت العوامل مشتركة مع السيرفر.

النسخ الاحتياطي والصيانة

  • انسخ قاعدة بيانات Woodpecker (ملف SQLite أو PostgreSQL) — تحتوي على تاريخ خطوط الأنابيب والأسرار
  • انسخ docker-compose.yml ومتغيرات البيئة التي تضبط Woodpecker
  • تعريفات خطوط الأنابيب (.woodpecker.yml) موجودة بالفعل في git — لا نسخة احتياطية إضافية مطلوبة
  • صدّر الأسرار قبل الترقيات إن أمكن — أسرار Woodpecker ليست سهلة التصدير (وثّقها في Vaultwarden)
  • سجلات خطوط الأنابيب مخزنة في قاعدة البيانات — النشر الكبير يجب أن يفكر في PostgreSQL بدلاً من SQLite

الأخطاء الشائعة

  • إنشاء تطبيق Gitea OAuth بـ URL callback خاطئ — يكسر المصادقة
  • تضمين الأسرار في .woodpecker.yml — تظهر في تاريخ git وسجلات خطوط الأنابيب
  • استخدام صور Docker :latest في خطوات خطوط الأنابيب — البناءات تصبح غير قابلة للاستنساخ
  • عدم ضبط إشعارات SMTP أو ntfy — فشل خطوط الأنابيب الصامت يمر دون تنبيه
  • نسيان ضبط WOODPECKER_HOST لـ URL HTTPS للسيرفر — لن تعمل webhooks
  • عدم اختبار خط الأنابيب محلياً قبل الدفع — كرّر بشكل أسرع بـ Woodpecker CLI

استكشاف الأخطاء وإصلاحها

  • خط الأنابيب لا يُشغَّل → تحقق من webhook في Gitea إعدادات المستودع > Webhooks — يجب أن يظهر آخر التسليمات
  • المصادقة تفشل → تحقق من أن client ID/secret لـ OAuth يطابق تطبيق Gitea بالضبط
  • العامل منفصل → تأكد من أن WOODPECKER_AGENT_SECRET متطابق في بيئة السيرفر والعامل
  • سحب صورة Docker يفشل في خط الأنابيب → تأكد من وصول العامل للإنترنت أو ضبط بيانات اعتماد Harbor
  • السر غير متاح في الخطوة → تحقق من التهجئة الدقيقة لاسم السر (حساس للحالة)
  • البناء في الطابور لكن لا يعمل → تحقق من أن العامل متصل في Woodpecker UI > Agents
  • 502 في واجهة الويب → تحقق من: docker compose logs woodpecker-server عن أخطاء بدء التشغيل
  • تسليم webhook يفشل → تأكد من أن URL HTTPS لـ Woodpecker قابل للوصول علناً من سيرفر Gitea

البدائل

Drone CI هو المصدر الأصلي لـ Woodpecker — لا يزال مُصاناً تجارياً من Harness. Jenkins هو أكثر أنظمة CI استخداماً لكنه يتطلب صيانة كبيرة وموارد JVM وإدارة إضافات. GitHub Actions ممتاز على GitHub لكنه يربطك بمنصتهم وحصة الدقائق. GitLab CI متكامل عمقاً مع GitLab لكنه يتطلب المجموعة الكاملة لـ GitLab. Tekton أصلي لـ Kubernetes لكنه يتطلب مجموعة Kubernetes.

متى لا تستخدمه

تجنب Woodpecker إذا كنت بحاجة لميزات CI مؤسسية كتحليلات الاختبارات غير الثابتة أو طبقات تخزين مؤقت متطورة أو تشغيل الاختبارات على 50+ جهازاً متوازياً. لا تستخدمه إذا كان الكود على GitHub وتريد تكاملاً وثيقاً مع GitHub PR — GitHub Actions أبسط. يمتلك Woodpecker أيضاً نظام إضافات أصغر من Jenkins؛ تحقق من مكتبة إضافات Woodpecker أولاً إذا كنت تعتمد على إضافات Jenkins محددة.

هل تحتاج مساعدة احترافية؟

توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.

  • التثبيت وتجهيز السيرفر
  • الإعداد المتقدم وإعداد التوجيه
  • تصليب الأمان وتحسين جدار الحماية
  • إعداد شهادات SSL/TLS مع Let's Encrypt
  • ربط النطاق المخصص والوكيل العكسي
  • جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
  • المراقبة الفورية وتنبيهات الجاهزية
  • الترحيل من المنصات القائمة
  • استكشاف مشكلات الاتصال والأداء وإصلاحها
  • سكريبتات أتمتة مخصصة وعقود دعم مستمر
تواصل مع PrismaTechWork

الأسئلة الشائعة

ما الفرق بين Woodpecker CI وDrone CI؟

Woodpecker CI هي fork مجتمعية من Drone CI 0.8 (قبل تجاريته). Woodpecker مرخصة بـ MIT ومُصانة بنشاط من المجتمع ومجانية لأي استخدام. Drone CI مملوكة الآن من Harness والنسخة المؤسسية مدفوعة. طوّرت Woodpecker تحسيناتها الخاصة وهي الخيار الموصى به للنشر الذاتي. معظم ملفات YAML لـ Drone CI تعمل في Woodpecker مع تعديلات طفيفة.

كيف أبني صورة Docker وأدفعها في خط أنابيب Woodpecker؟

استخدم إضافة woodpeckerci/plugin-docker-buildx: image: woodpeckerci/plugin-docker-buildx مع إعدادات repo وregistry وusername (من سر) وpassword (من سر). أشر السجل لـ URL نسخة Harbor. تبني الإضافة Dockerfile في مستودعك وتدفع الصورة. اضبط tags: latest,${CI_COMMIT_SHA} لتوسيم البناءات بكليهما.

هل يمكن تشغيل Woodpecker على ARM (Raspberry Pi، Apple Silicon)؟

نعم. تنشر Woodpecker صور Docker متعددة المعماريات لـ amd64 وarm64. يمكن تشغيل سيرفر Woodpecker على x86 وتوصيل عوامل ARM (Raspberry Pi، Oracle Ampere) لبناء صور ARM أصلية. مفيد للتصريف المتقاطع أو تشغيل اختبارات ARM أصلية في خط الأنابيب. اضبط WOODPECKER_AGENT_TAGS للعامل بتصنيفات المعمارية لتوجيه خطوات خطوط الأنابيب المحددة للعامل الصحيح.

كيف أمرّر الأسرار لخطوة خط أنابيب؟

في واجهة Woodpecker، اذهب للمستودع > Secrets > Add Secret. أنشئ سراً باسم وقيمة. في .woodpecker.yml، أشر إليه تحت environment: بصيغة from_secret: DB_PASSWORD: from_secret: db_password. يُحقن السر كمتغير بيئة في حاوية الخطوة — لن يظهر أبداً في ملف YAML أو المستودع.

هل يمكنني تشغيل عوامل Woodpecker على سيرفر مختلف عن سيرفر Woodpecker؟

نعم. يتواصل سيرفر Woodpecker والعوامل عبر gRPC (المنفذ 8000). شغّل العوامل على أي سيرفر يستطيع الوصول للمنفذ 8000 على سيرفر Woodpecker. اضبط WOODPECKER_SERVER وWOODPECKER_AGENT_SECRET على كل عامل للاتصال. هذا يتيح تشغيل البناءات على أجهزة مخصصة — أجهزة أقوى أو لوحات ARM أو سيرفرات في شبكة مختلفة.

كيف أضغر التبعيات بين تشغيلات خطوط الأنابيب؟

استخدم إضافة woodpeckerci/plugin-caching أو ثبّت Docker volume مسمى في خطوة خط الأنابيب. لتبعيات npm/pip/maven، ثبّت volume cache في مجلد cache لمدير الحزم. بالاختيار، ابنِ صورة Docker مخصصة تُثبّت مسبقاً تبعياتك واستخدمها كصورة خطوة خط الأنابيب — هذا أبسط نهج لمجموعات التبعيات الثابتة.

كيف أنشر لسيرفر إنتاج من خط أنابيب Woodpecker؟

استخدم خطوة SSH: image: appleboy/drone-ssh (متوافقة مع Woodpecker) مع host وusername وkey (من سر — مفتاح SSH الخاص للسيرفر). في السكريبت، شغّل docker compose pull && docker compose up -d على السيرفر الهدف. أضف شرطاً when: branch: main للنشر فقط عند الدمج في الفرع الرئيسي. خزّن مفتاح SSH الخاص كسر Woodpecker.

هل هناك محرر ويب لـ .woodpecker.yml أم يجب التحرير محلياً دائماً؟

لا يمتلك Woodpecker محرر YAML مدمج لخطوط الأنابيب — تحرر .woodpecker.yml في مستودعك وتدفع لتشغيل التغييرات. لكن Gitea تمتلك محرر ويب للملفات، فيمكنك تحرير .woodpecker.yml مباشرة في واجهة Gitea. يوفر Woodpecker أداة CI Lint للتحقق من صحة YAML قبل التشغيل. Woodpecker CLI (woodpecker-cli exec) يتيح اختبار خطوط الأنابيب محلياً بدون دفع.