Platypus

مركز إدارة للمضيفين لأسراب من أجهزة لينكس. قم بتثبيت وكيل Platypus على كل مضيف تملكه؛ يتصل الوكيل عائدًا بخادم Platypus عبر TLS + protobuf؛ من الخادم تحصل على شل تفاعلي، وإدارة الملفات، ونفق الشبكة على كل مضيف مُدار — من خلال لوحة تحكم مركزية واحدة.

لقطات الشاشة

واجهة مستخدم ذات تنقل مسطح على غرار Vercel مع لوحة تحكم المشروع، ومتصفح للمضيف/المستمع/الجلسة، ووحدة تحكم إرسال متعددة المضيفين، ومدير مستخدم إداري. اطّلع على المعرض الكامل في docs/screenshots/. أعد تشغيل make screenshots لتوليدها من التطبيق المباشر.

البنية

يتم شحن Platypus كملفين ثنائيين للخلفية بالإضافة إلى عميل سطح مكتب مستقل:

الخادم هو مجرد واجهة برمجة تطبيقات — لا توجد واجهة ويب مضمنة. يمكن لأجهزة سطح المكتب متعددة الاتصال بنفس الخادم في وقت واحد.

الميزات

• قناة TLS + protobuf بين الوكيل والخادم
• منافذ دخول متعددة بحيث تشارك الأسراب في شبكات مختلفة محورًا واحدًا
• شل تفاعلي لكل مضيف، منقول عبر WebSocket
• قراءة / كتابة / رفع / تنزيل الملفات مع نقل مقسم
• أنفاق الشبكة: توجيه المنفذ المحلي، توجيه المنفذ البعيد، SOCKS5 الديناميكي
• واجهة REST API مصادقة بواسطة Bearer-token
• حزمة تطوير بايثون
• بدء تشغيل المستمعين تلقائيًا من config.yml
• إيقاف تشغيل رشيق (يصرف الاتصالات عند SIGINT/SIGTERM خلال 30 ثانية)

المستندات

• Chinese | 中文文档

البدء السريع

النشر بنقرة واحدة (موصى به)

أسرع طريقة لتشغيل نظام Platypus كامل (بما في ذلك الخادم، وواجهة الويب، وموزع الوكيل المدعوم من MinIO) هي استخدام Docker Compose:

git clone https://github.com/WangYihang/Platypus
cd Platypus
docker-compose up -d

• واجهة الويب: افتح https://localhost:9443 في متصفحك (تحتوي الحاوية على شهادة ذاتية التوقيع؛ سيطالبك المتصفح بقبولها عند الزيارة الأولى).
• تسجيل الدخول: يتم كتابة bootstrap_secret إلى /app/data/bootstrap.secret داخل الحاوية عند أول تشغيل (الوضع 0600). اقرأه باستخدام docker compose exec platypus-server cat /app/data/bootstrap.secret، استخدمه مرة واحدة لإنشاء المسؤول الأول، ثم احذف الملف. بعد اكتمال التمهيد، لن يتم قبول السر بعد ذلك.
• إضافة وكلاء: انقر على "إضافة وكيل" في واجهة المستخدم للحصول على أمر سطر واحد curl ... | sh، موقع ومرتبط بسلطة التصديق (CA) الخاصة بالمشروع، لنشر الوكلاء في أسطولك.

البناء من المصدر

يتطلب Go 1.24+ و protoc (فقط إذا أعدت توليد كود protobuf).

git clone https://github.com/WangYihang/Platypus
cd Platypus
make build              # → ./build/{platypus-server,platypus-agent}

أهداف مفيدة أخرى: make test، make lint، make snapshot (عبر المنصات باستخدام goreleaser)، make help.

التطوير (خطافات pre-commit)

يجب على المساهمين تثبيت خطافات git بحيث يتم تشغيل gofmt / goimports / go vet / golangci-lint قبل كل commit:

pip install pre-commit   # or: pipx install pre-commit
make hooks               # one-time: wires .git/hooks/pre-commit
make pre-commit          # optional: run all hooks against every file now

بناء تطبيق سطح المكتب

يتطلب Node 22+، وتبعيات Wails CLI (wails doctor)، ومكتبات WebView الخاصة بالمنصة (webkit2gtk-4.1 على لينكس، WebView2 على ويندوز، WKWebView على ماك).

make desktop-deps       # one-time: install Wails CLI + pnpm packages
make desktop-build      # → desktop/build/bin/platypus-desktop
make desktop-dev        # hot-reload dev mode

أو: استخدم واجهة الويب المستقلة (بدون تثبيت)

نفس الصفحات، نفس الميزات (بدون دفع الأحداث في الوقت الفعلي)، تعمل في أي متصفح:

make web-ui             # → desktop/frontend/dist-web/ (static bundle)
make web-ui-serve       # preview at http://localhost:8080

dist-web/ ثابتة بالكامل؛ ضعها على GitHub Pages / S3 / nginx. وجّهها إلى أي platypus-server عبر نموذج تسجيل الدخول.

ملاحظات كاملة في desktop/README.md.

التثبيت من الثنائيات الجاهزة

قم بتنزيل الأرشيف المناسب لنظام التشغيل/الهندسة الخاص بك من صفحة الإصدارات، واستخرجه، وقم بتشغيله.

التشغيل باستخدام Docker

docker build -t platypus-server .
docker run --rm -p 9443:9443 \
  -e PLATYPUS_DEV=1 \
  -v $(pwd)/config.yml:/config.yml \
  platypus-server

PLATYPUS_DEV=1 يفعل الاحتياطي الموجود على القرص KEK بحيث تعمل البداية الجديدة "فقط"؛ للإنتاج، قم بإزالة متغير البيئة هذا وقم بتعيين PLATYPUS_CA_KEK (32 بايت ست عشري؛ openssl rand -hex 32) بدلاً من ذلك بحيث لا يتم كتابة مفتاح تشفير المفتاح الخاص للـ CA بجانب قاعدة البيانات المشفرة.

التشغيل

./build/platypus-server                # foreground; Ctrl-C for graceful shutdown

للإنتاج، قم بتشغيل الخادم تحت systemd بدلاً من تشغيله في الخلفية يدويًا.

ملاحظات الإنتاج

• مثيل واحد فقط. يقوم مُحقق الرمز المميز المعتم (opaque-token verifier) بتخزين الرموز المميزة المُتحقق منها مؤقتًا في LRU لكل عملية. يؤدي الإلغاء (تسجيل الخروج، تغيير كلمة المرور، إلغاء AAT، حذف المستخدم) إلى إزالة الإدخال على نفس العملية بشكل متزامن — ولكن في نشر متعدد النسخ المتماثلة لا توجد قناة إلغاء عبر العمليات اليوم، لذا يمكن للرمز المميز الملغي الاستمرار في العمل على نسخ متماثلة أخرى لمدة تصل إلى TTL ذاكرة التخزين المؤقت (30 ثانية). لا تقم بتشغيل أكثر من platypus-server واحد ضد نفس قاعدة البيانات حتى يتم تنفيذ الإلغاء عبر العمليات. القياس الرأسي + وضع استعداد عالي التوفر هو الشكل المدعوم؛ النسخ المتماثلة المتوازنة الحمل غير مدعومة.
• PLATYPUS_CA_KEK في البيئة. يتم إغلاق المفتاح الخاص للـ CA باستخدام AES-256-GCM مقابل هذه القيمة السداسية العشرية المكونة من 32 بايت. بدون تعيينها، يرفض الخادم البدء ما لم يكن PLATYPUS_DEV=1 موجودًا أيضًا (وهو ما يفعل احتياطيًا على القرص خاصًا بالتطوير فقط في <data-dir>/ca.kek — غير آمن للإنتاج لأن النص المشفر والمفتاح ينتهيان على نفس وحدة التخزين).
• منفذ عرض بحجم سطح المكتب، لا تخطيط جوال (حتى الآن). تستهدف واجهة الويب منافذ عرض بحجم ≥ 1280px؛ يأخذ شريط السكة / الشريط الجانبي / شريط الحالة حوالي 300px، تاركًا الجسم المحتوى في نطاق القراءة المثالي من 80 إلى 100 حرف. لا يوجد طي متجاوب للنوافذ الضيقة اليوم — منافذ العرض أقل من 1024px ستظهر أشرطة تمرير أفقية على الجداول. دعم الأجهزة اللوحية / الهواتف موجود في قائمة المهام المتراكمة (P4 في تدقيق تجربة المستخدم) لكنه ليس عائقًا؛ العمل الإداري هو عمل مكتبي.
• بيانات اعتماد تخزين الكائنات. عندما يتم تمكين الموزع (distributor.store.endpoint set)، قم بتعيين PLATYPUS_DISTRIBUTOR_STORE_ACCESS_KEY_ID و PLATYPUS_DISTRIBUTOR_STORE_SECRET_ACCESS_KEY بدلاً من تضمينها في config.yml. يتم شحن المرفق مع حقول YAML فارغة لهذا السبب.

الاستخدام

الهيكلية

• الخادم: 192.168.88.129
  • مدخل TLS الموحد (REST API + رابط الوكيل + المثبت): 0.0.0.0:9443
• المضيف المُدار: 192.168.88.130 (يعمل عليه platypus-agent)

جولة سريعة

أولاً، قم بتشغيل ./platypus-server. يتم توليد config.yml من assets/config.example.yml إذا لم يكن موجودًا. الإعدادات الافتراضية معقولة.

لتسجيل مضيف مُدار جديد:

1. افتح واجهة الويب / تطبيق سطح المكتب، انتقل إلى المشروع، انقر على إضافة وكيل.
2. اختر نظام التشغيل/الهندسة المستهدف و TTL، انقر على توليد.
3. انسخ الأمر ذو السطر الواحد الذي تعرضه واجهة المستخدم وقم بتشغيله على المضيف المُدار.

الأمر ذو السطر الواحد الذي يعرضه الخادم يبدو كالتالي:

curl -fsSL https://<server>:9443/api/v1/install/<one-shot-token> | sh

يضمن رمز التثبيت أحادي الاستخدام انتهاء صلاحيته بعد وقت قصير من الإصدار ويتم حرقه عند أول طلب ناجح. البرنامج النصي الذي يعيده الخادم:

• يضمّن سلطة التصديق (CA) الخاصة بالمشروع بحيث يتم التحقق من تنزيل ثنائي الوكيل باستخدام curl --cacert (بدون -k، بدون TOFU);
• يحقن PAT أحادي الاستخدام بحيث يمكن للوكيل إكمال التسجيل والحصول على شهادة عميل mTLS;
• يرفض التشغيل إذا لم يكن لدى الخادم CA مشروع مهيأ، ما لم يحدد المشغل بشكل صريح PLATYPUS_INSECURE_DOWNLOAD=1.

لا تقم بكتابة URLs curl http://... يدويًا مقابل المسار القديم /agent/<host>:<port> — تم إزالة هذا التدفق. قم دائمًا بعرض أمر التثبيت عبر واجهة المستخدم بحيث يحمل مرساة الثقة.

سطح المكتب / الويب

افتح تطبيق سطح المكتب (platypus-desktop) أو واجهة الويب (make web-ui-serve)، املأ URL الخادم والسر، وستكون داخل التطبيق. التبويبات: الجلسات (كل وكيل اتصل بالخادم)، الطرفية، الملفات، الأنفاق، المستمعين.

الاستخدامات المتقدمة

• واجهة REST API
• حزمة تطوير بايثون

مواد أخرى

• عرض تقديمي في KCon 2019
• عرض تقديمي في GCSIS 2021

المساهمون

هذا المشروع موجود بفضل كل الأشخاص الذين يساهمون.

الداعمون

شكرًا لجميع داعمينا! 🙏 [كن داعمًا]

الرعاة

ادعم هذا المشروع من خلال أن تصبح راعيًا. سيظهر شعارك هنا مع رابط لموقعك على الويب. [كن راعيًا]