توصيل خادم
Add Server Wizard هو الطريق الرسمي لتوصيل RoqueOS frontend (في https://roqueos.com.br/app) بـ RoqueOS Server الخاص بك. يوجد في Settings ← Server ← إضافة خادم.
يستبدل التدفق القديم الذي طلب من المستخدم فتح <server>:27021/admin في المتصفح. الآن يحدث كل شيء داخل التطبيق.
متى الاستخدام
- ✅ خادم مثبت حديثًا (
install.shتم تشغيله، لا توجد API Keys بعد) — wizard ينشئ أول admin key - ✅ خادم قيد الاستخدام بالفعل (لديك apiKey + apiSecret محفوظة) — wizard يتحقق ويضيف إلى القائمة
- ✅ تبديل الخادم — أضف خادمًا ثانيًا، بدّل بينهما عبر Switcher في menubar
تدفق Bootstrap (خادم فارغ)
7 خطوات. الوقت الإجمالي: ~1 دقيقة.
Step 1 — URL
الصق URL للخادم. يقبل:
http://localhost:27021(Docker يعمل على جهازك — يعمل عبر loopback)https://server.example.com(خلف Cloudflare Tunnel أو شهادة TLS)
Wizard يطبع البروتوكول (server.example.com ← https://server.example.com تلقائيًا) ويكتشف الخوادم المسجلة قبل المتابعة.
⚠️ HTTP vs HTTPS — قيود المتصفح
الواجهة الأمامية roqueos.com.br/app تعمل في HTTPS. حسب تصميم المتصفحات الحديثة (سياسة Mixed Content)، صفحة HTTPS لا يمكنها استدعاء APIs HTTP — يحجب المتصفح request بصمت حتى قبل مغادرة الجهاز.
هذا يعني أن محاولة الاتصال بـ http://192.168.1.50:27021 (LAN) أو http://server.com:27021 (عام) سيفشل بـ "couldn't connect" الذي يبدو وكأنه خطأ في الخادم لكنه حجب المتصفح.
يكتشف Wizard هذا لك ويعرض banner أصفر يشرح المشكلة قبل تشغيل request. ثلاثة حلول، بترتيب الأفضلية:
1. HTTPS عبر Cloudflare Tunnel (موصى به)
مجاني، plug-and-play. install.sh لديه دعم built-in بالفعل:
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update
# بعد ذلك: Settings ← Server ← Cloudflare Tunnel ← اتصالالنتيجة: خادمك يصبح على https://<id>.cloud.roqueos.com.br أو نطاقك الخاص. TLS تلقائي، دون العبث بـ firewall، دون الحاجة لـ IP عام.
دليل كامل install.sh + Cloudflare Tunnel ←
2. استخدم تطبيق سطح المكتب أو الجوال
الـ wrappers الأصلية (Microsoft Store، Play Store، App Store) ليس لها قيود mixed content — تشغل كود أصلي، وليس صفحات ويب في HTTPS صارم.
جيد لـ: بيئة homelab حيث لا تريد/لا تستطيع تكوين tunnel.
3. الخادم في localhost (loopback)
http://localhost:27021، http://127.0.0.1:27021 و http://[::1]:27021 تُعامل كسياق آمن من قبل المتصفحات الحديثة عبر Secure Contexts spec — لذا تعمل حتى مع frontend HTTPS.
جيد لـ: dev محلي، الاختبار قبل الرفع على خادم حقيقي.
Step 2 — Detect
يصل Wizard إلى 2 endpoints مجهولة بالتوازي:
GET /health/version-info— الإصدار + minClientVersionGET /admin/setup— إذا أعاد{ needsSetup: true }، الخادم فارغ
يفحص هنا أيضًا compat الإصدار. إذا كان الخادم في v1.0.10 لكن العميل (frontend) يتطلب v1.0.13+، يعرض تحذير ودود "حدّث الخادم أولاً" + رابط لـ install.sh --update.
Step 3 — Bootstrap (خادم فارغ)
زر "إنشاء admin key" ← POST /admin/setup (محدود المعدل بـ IP على الخادم لتجنب setup race).
يُعيد { apiKey, apiSecret } الذي يعرضه wizard في الخطوة التالية.
معالجة race: إذا حاول متصفحان setup في نفس الوقت، يستلم الثاني error: 'Setup already completed' وينتقل wizard إلى step 5 (manual credentials).
Step 4 — keyCreated
يعرض apiKey + apiSecret المعادة في حقول للقراءة فقط مع زر copy.
⚠️ UX guard حرج:
- Modal به
closeOnBackdrop=false(لا يغلق بالنقر خارجه) - زر X يفتح sub-modal تأكيد ("هل حفظت credentials؟")
- مربع اختيار إلزامي "حفظت credentials الخاصة بي" يمكّن زر Next
- إذا أغلقت دون الحفظ، تبقى key على الخادم لكن مفقودة بالنسبة لك — الاسترداد فقط عبر
/adminHTML legacy
Step 5 — credentials (الخادم مكوَّن بالفعل)
إذا أشار الاكتشاف في step 2 إلى أن setup تم بالفعل، يقفز مباشرة إلى هنا:
- حقل
apiKey - حقل
apiSecret - رابط "افتح لوحة admin للخادم ↗" (يفتح
<server>/adminHTML legacy في علامة تبويب جديدة)
تستمر صفحة legacy في كونها الباب الخلفي للاسترداد والأتمتة.
Step 6 — الاسم
الحقل الوحيد: اسم ودود للخادم (يظهر في Server Switcher في menubar).
الافتراضي المقترح: URL.hostname (مثل: demo.level-hard.com أو localhost).
Step 7 — Finalize
يستدعي Wizard:
addBackendService({ name, url })— يحفظ في قائمةbackendSettings.servicessetApiCredentials(apiKey, apiSecret, serviceId)— يحفظ creds في FirestoresetActiveBackendService(serviceId)— يجعله نشطًا
ينغلق Modal. الخادم متصل. أنت في Server Mode.
Server Switcher (menubar)
عندما يكون لديك 2+ خوادم مسجلة، يظهر dropdown في menubar (الزاوية العلوية اليسرى) يعرض الخادم النشط. انقر للتبديل بينها.
الحالة الحالية (مايو 2026): مكون
ROSServerSwitcherلم يُعَد بناؤه بعد بعد جلسة سابقة — الميزة مخططة ولكن لم يتم shipped. حاليًا، التبديل بين الخوادم يتم عبر Settings ← Server ← انقر على الخادم المطلوب.
خادم العرض التوضيحي العام
لاختبار Server Mode دون الحاجة لتثبيت أي شيء على جهازك، يأتي RoqueOS بالفعل مع خادم عرض توضيحي عام مكوَّن مسبقًا:
- سجل الدخول إلى
https://roqueos.com.br/app - اذهب إلى Settings ← Server
- الخادم DEMO يظهر بالفعل في القائمة — انقر للتنشيط
لا حاجة للصق URL أو apiKey أو apiSecret — credentials مدمجة في العميل وتعمل مباشرة.
ما هو العرض التوضيحي: نسخة حقيقية من RoqueOS Server، يحدّثها المؤسس، مع تنظيف يومي (حاويات يتيمة، agents/sessions > 24 ساعة، volumes معلقة). القيود:
- غير admin لا يرى Server Admin Panel (security gate)
- Cloud Gaming قد يطهر جلسة zombie
- تبقى الحاويات ~24 ساعة قبل prune
- مشترك بين جميع الزوار
جيد لـ: استكشاف Containers، Terminal، VS Code المدمج، Files. سيء لـ: persistence طويل، بيانات حساسة أو مهمة — أي شخص مسجل في RoqueOS قد يستخدم نفس العرض التوضيحي بالتوازي.
للاستخدام الحقيقي، ثبت خادمك الخاص بـ one-liner.
استكشاف الأخطاء وإصلاحها
| العرض | الحل |
|---|---|
| "الخادم غير قابل للوصول" | تأكد أن curl <url>/health يعيد 200. ربما المنفذ 27021 ليس مفتوحًا أو Docker متوقف |
| "الخادم مسجل بالفعل" | اكتشف Wizard تكرارًا. اذهب إلى Settings ← Server واختر الموجود |
| "الخادم قديم" | شغل --update على الخادم: curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update |
| "Setup already completed" لكنك لم تكوّن أبدًا | إعادة تعيين: docker exec roqueos-server sqlite3 /app/data/roqueos.db "DELETE FROM api_keys;" (تحذير — يحذف جميع keys الموجودة) |
| تمت إضافة الخادم لكن Settings تعود فارغة | ربما فقد Firestore login. تحقق في DevTools console إذا ظهر Firestore: PERMISSION_DENIED |
المراجع
- install.sh one-liner — لتشغيل الخادم مسبقًا
- Server Admin Panel — الإدارة بعد التوصيل
- Volumes & النسخ الاحتياطي — فهم persistence
- Composable داخلي: src/composables/useAddServerWizard.js (state + flow)