pingap

قبل أن يصبح إصدار pingap مستقرًا، لن يتم قبول أي طلبات سحب (pull requests). إذا كان لديك أي أسئلة، يُرجى إنشاء issue جديد أولاً.

نظرة عامة

Pingap هو وكيل عكسي عالي الأداء مدعوم بـ Cloudflare Pingora. يبسّط الإدارة التشغيلية من خلال تمكين إعادة التحميل السريع للتكوين بشكل ديناميكي وبدون توقف، عبر ملفات TOML موجزة وواجهة إدارة ويب بديهية.

تكمن قوته الأساسية في نظام إضافات قوي، يوفّر أكثر من عشرين ميزة جاهزة للمصادقة (JWT، Key Auth)، والأمان (CSRF، قيود IP/Referer/UA)، والتحكم في حركة المرور (تحديد المعدل، التخزين المؤقت)، وتعديل المحتوى (إعادة التوجيه، استبدال المحتوى)، والمراقبة (Request ID). هذا يجعل Pingap ليس مجرد وكيل، بل بوابة تطبيقات مرنة وقابلة للتوسيع، مصمّمة للتعامل بسهولة مع السيناريوهات المعقدة من حماية API إلى نشر تطبيقات الويب الحديثة.

中文说明 | Documentation · 中文文档 | Examples | Plugins | Crates

flowchart LR
  internet("Internet") -- request --> pingap["Pingap"]
  pingap -- proxy:pingap.io/api/* --> apiUpstream["10.1.1.1,10.1.1.2"]
  pingap -- proxy:cdn.pingap.io --> cdnUpstream["10.1.2.1,10.1.2.2"]
  pingap -- proxy:/* --> upstream["10.1.3.1,10.1.3.2"]

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

• 🚀 أداء عالٍ وموثوقية

  • مبني بلغة Rust لأمان الذاكرة وأداء من الطراز الأول.
  • مدعوم بـ Cloudflare Pingora، مكتبة شبكات غير متزامنة مجرّبة ومختبرة.
  • يدعم HTTP/1.1 وHTTP/2 وتمرير gRPC-web.

• 🔧 ديناميكي وسهل الاستخدام

  • تغييرات تكوين بدون توقف مع إعادة التحميل السريع.
  • ملفات تكوين TOML بسيطة وقابلة للقراءة البشرية.
  • واجهة ويب كاملة الميزات لإدارة بديهية وفورية.
  • يدعم كلًا من الملفات وetcd كخلفيات للتكوين.
  • يدعم سجل تاريخ التكوين، ويمكن الاستعادة إلى الإصدار السابق بنقرة واحدة.

• 🧩 قابلية توسيع قوية

  • نظام إضافات غني للتعامل مع مهام البوابة الشائعة.
  • توجيه متقدم مع مطابقة المضيف والمسار والتعبيرات النمطية.
  • اكتشاف الخدمات المدمج عبر القوائم الثابتة أو DNS أو تسميات Docker.
  • HTTPS تلقائي مع Let's Encrypt (يدعم تحديات HTTP-01 وDNS-01).

• 📊 مراقبة حديثة

  • مقاييس Prometheus أصلية للمراقبة (وضعا السحب والدفع).
  • دعم OpenTelemetry مدمج للتتبع الموزّع.
  • سجلات وصول قابلة للتخصيص بدرجة عالية مع أكثر من 30 متغيرًا.
  • بصمات عميل JA4 TLS ({:ja4} في سجلات الوصول، $ja4 في ترويسات upstream) للتمييز بين العملاء حسب حزمة TLS الخاصة بهم، على حد سواء في بنيات OpenSSL وrustls.
  • مقاييس أداء مفصّلة، بما في ذلك وقت الاتصال بـ upstream ووقت المعالجة والمزيد.

🚀 البدء

أسهل طريقة للبدء مع Pingap هي استخدام Docker Compose.

1. أنشئ ملف docker-compose.yml:

# docker-compose.yml
version: '3.8'

services:
  pingap:
    image: vicanso/pingap:latest # For production, use a specific version like vicanso/pingap:0.12.1-full
    container_name: pingap-instance
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      # Mount a local directory to persist all configurations and data
      - ./pingap_data:/opt/pingap
    environment:
      # Configure using environment variables
      - PINGAP_CONF=/opt/pingap/conf
      - PINGAP_ADMIN_ADDR=0.0.0.0:80/pingap
      - PINGAP_ADMIN_USER=pingap
      - PINGAP_ADMIN_PASSWORD=<YourSecurePassword> # Change this!
    command:
      # Start pingap and enable hot-reloading
      - pingap
      - --autoreload

2. أنشئ دليل بيانات وشغّل:

mkdir pingap_data
docker-compose up -d

3. الوصول إلى واجهة الإدارة:

نسخة Pingap الخاصة بك تعمل الآن! يمكنك الوصول إلى واجهة إدارة الويب على http://localhost/pingap باستخدام بيانات الاعتماد التي قمت بتعيينها.

تثبيت الملف التنفيذي عبر curl

بالنسبة لـ Linux وmacOS، يمكنك تثبيت أحدث ملف تنفيذي مُجمّع مسبقًا إلى /usr/local/bin/pingap بأمر واحد:

curl -sSL https://raw.githubusercontent.com/vicanso/pingap/main/install.sh | sh

متغيرات البيئة الاختيارية:

• PINGAP_FULL=1 — تثبيت بنية -full (جميع الميزات الاختيارية مُفعّلة)
• PINGAP_LIBC=gnu — على Linux، استخدم بنية glibc بدلاً من بنية musl الثابتة الافتراضية
• PINGAP_TLS=rustls — على Linux، ثبّت بنية -rustls-full (خلفية TLS من rustls، جميع الميزات الاختيارية، بدون OpenSSL)؛ راجع خلفية TLS

# Full-featured build
curl -sSL https://raw.githubusercontent.com/vicanso/pingap/main/install.sh | PINGAP_FULL=1 sh

الأهداف المدعومة: Linux x86_64/arm64، Darwin x86_64/arm64. راجع صفحة الإصدارات لجميع الأصول المتاحة.

للحصول على تعليمات أكثر تفصيلاً، بما في ذلك التشغيل من ملف تنفيذي، راجع التوثيق.

تشغيل وكيل بدون ملف تكوين

أمر واحد يكفي لخدمة نطاق عبر https وتمريره إلى خلفية:

# certificate requested from let's encrypt
pingap --domain=pingap.io --upstream=192.168.1.1:3000

# or bring your own certificate
pingap --domain=pingap.io --upstream=192.168.1.1:3000 --cert=/etc/ssl/pingap.io

بدون --cert، يطلب Pingap شهادة من Let's Encrypt عبر تحدي HTTP-01، لذا يجب أن يُترجم pingap.io إلى هذا المضيف ويجب أن يكون المنفذ 80 قابلاً للوصول من الإنترنت. تُحفظ الشهادة الصادرة في ~/.pingap/acme/<domains>.toml وتُعاد استخدامها عند إعادة التشغيل — الإصدار محدود المعدل، لذا لا تحذفها. كل شيء آخر لا يزال يأتي من سطر الأوامر: تغيير --upstream يسري عند التشغيل التالي دون المساس بالشهادة.

يقبل --cert الشهادة نفسها أو الدليل الذي يحتويها — التخطيطات الشائعة fullchain.pem / privkey.pem وcert.pem / key.pem وtls.crt / tls.key تُكتشف تلقائيًا، استخدم --key لأي شيء آخر. المستمع افتراضيًا 0.0.0.0:443 عند وجود شهادة و0.0.0.0:80 عند عدم وجود شهادة ولا نطاق، ويتجاوزها --addr. يأخذ --upstream قائمة خلفيات مفصولة بفواصل، ويأخذ --domain قائمة مضيفين مفصولة بفواصل (احذفه لخدمة كل مضيف عبر http عادي). الطلبات لمضيف غير مُدرج يُجاب عليها بـ 404.

يُولّد التكوين عند كل تشغيل، لذا لا يمكن تعديله عبر واجهة الإدارة: لأي شيء يتجاوز خادمًا واحدًا استخدم --conf، الذي لا يمكن دمجه مع هذه الأعلام.

التكوين الديناميكي

صُمّم Pingap للتكيّف مع تغييرات التكوين دون توقف.

إعادة التحميل السريع (--autoreload): لمعظم التغييرات — مثل تحديث upstreams أو locations أو الإضافات — يطبّق Pingap التكوين الجديد خلال 10 ثوانٍ دون إعادة تشغيل. هذا هو الوضع الموصى به لبيئات الحاويات.

إعادة التشغيل السلسة (-a أو --autorestart): للتغييرات الجوهرية (مثل تعديل منافذ استماع الخادم)، ينفّذ هذا الوضع إعادة تشغيل كاملة بدون توقف، مما يضمن عدم إسقاط أي طلبات.

التسليم مدفوع بالجاهزية بدلاً من التوقيت: يُشغّل البديل بـ -d -u، ويبلّغ عبر مقبس unix بجوار مقبس الترقية في اللحظة التي يصبح فيها جاهزًا لتولي المستمعين، وعندها فقط يرسل العملية الجارية لنفسها SIGQUIT. إذا خرج البديل، أو مات خادمه، أو مرّ basic.restart_ready_timeout (الافتراضي 1m) أولاً، تُلغى إعادة التشغيل ويستمر العملية الجارية في الخدمة.

🔧 التطوير

make dev

إذا كنت بحاجة إلى إدارة ويب، يجب عليك تثبيت nodejs وبناء أصول الويب.

# generate admin web asset
cd web
npm i 
cd ..
make build-web

خلفية TLS

تبني البنية الافتراضية TLS باستخدام OpenSSL، المُجمّع من المصدر بواسطة حزمة openssl. للبناء باستخدام rustls بدلاً من ذلك، مما يُلغي بناء مصدر OpenSSL (لا يزال مطلوبًا مترجم C: مزوّدو التشفير في rustls، ring وaws-lc-rs، يحتويان على C ولغة التجميع):

cargo build --release --no-default-features --features tls-rustls
# with the optional features as well
cargo build --release --no-default-features --features tls-rustls,full