ما هو Logto — وما ليس هو
Logto هو منصة مصادقة تُسلَّم كحزمة تطوير: تدمجها في شيفرة تطبيقك في نحو خمسة عشر سطراً، فتتكفّل بدورة حياة الحسابات كاملة على خادمك أنت. وهذا يختلف عن أداتَي المصادقة الأخريين في كتالوج ServOrbit:
- Authelia يضيف المصادقة الثنائية والدخول الموحّد *أمام* تطبيقات قائمة، عبر التفويض، من دون المساس بشيفرتها — فهو يحمي تطبيقات لا تملك شاشة دخول أصلاً.
- Authentik مزوّد هوية كامل، لتوحيد الدخول إلى أدواتك المستضافة ذاتياً (Grafana وGitea وNextcloud).
- Logto يحلّ محلّ خدمة مصادقة مستضافة: تستدعي حزمته من تطبيقك بلغة React أو Python أو Go، فيدير الحسابات والجلسات والموصلات الاجتماعية والرموز.
إن كنت تبني منتجاً ينشئ فيه المستخدمون حسابات، فـ Logto هو الأداة المناسبة.
المتطلبات
قبل نشر Logto 1.19+، تحقّق من النقاط التالية على خادمك الافتراضي في ServOrbit:
- الذاكرة: 2 غيغابايت على الأقل (يُنصح بـ 4 غيغابايت إن كنت تتوقع أكثر من 5 000 مستخدم نشط). يعمل Logto على Node.js 20 LTS ويتشارك النسخة نفسها مع PostgreSQL 17.
- المعالج: يكفي 1 vCPU للبدء، لكن 2 vCPU يتجنّبان تأخيرات الدخول تحت الحمل.
- التخزين: احجز 10 غيغابايت على الأقل — يخصّص PostgreSQL سجلات WAL وتتراكم الجلسات النشطة بسرعة مع تسجيل التدقيق الافتراضي.
- Docker ≥ 24.0 وDocker Compose ≥ 2.20 — مثبّتان مسبقاً في جميع باقات ServOrbit.
- PostgreSQL 17 كحدّ أدنى (مضمّن في صورة Logto الرسمية) — الإصدارات الأقدم تفتقر إلى الامتدادات المطلوبة.
- اسم نطاق أو نطاق فرعي موجّه إلى خادمك ومُحلَّل علناً: يضمّن Logto هذا النطاق في كل رمز OIDC يصدره. يجب تحديده قبل أول تشغيل ولا يمكن تغييره دون إعادة تهيئة جميع بيانات المستخدمين.
كيف يعمل Logto في الإنتاج
يشغّل Logto حاويتين: db (وهي PostgreSQL 17 للمستخدمين والتطبيقات والجلسات وسجلّ التدقيق) وlogto (وهي Node.js التي تخدم نقطة OIDC على المنفذ 3001 ووحدة الإدارة على المنفذ 3002). ويحوّل الوكيل العكسي nginx على خادمك حركة HTTPS القادمة إلى نطاقك نحو المنفذ 3001 — وهي النقطة التي تصادق عليها تطبيقاتك. أما المنفذ 3002 فمرتبط بالعنوان المحلي فقط، ولا يُبلغ إلا عبر نفق SSH، وهو ما يبقي إدارة قاعدة المستخدمين بعيداً عن الإنترنت العام.
ما يقدّمه Logto فور التثبيت
- رموز مطابقة لـ OIDC/OAuth 2.0 — رموز JWT موقّعة تتحقّق منها أي مكتبة قياسية (passport.js أو python-jose أو go-oidc) من دون شيفرة خاصة.
- موصلات تسجيل دخول اجتماعي — فعّل Google وGitHub وApple وMicrosoft وDiscord ونحو ثلاثين مزوّداً آخر من وحدة الإدارة بنقرة واحدة.
- مصادقة بلا كلمة مرور — روابط سحرية بالبريد أو رموز لمرة واحدة بالرسائل القصيرة (Twilio أو SendGrid أو Mailgun)، من دون صيانة خدمة إشعارات منفصلة.
- المصادقة الثنائية — رموز TOTP (Google Authenticator وAuthy)، ومفاتيح عتادية بمعيار WebAuthn/FIDO2، ورموز احتياطية، تُفرض بسياسة من وحدة الإدارة.
- التحكّم بالوصول حسب الأدوار — عرّف الأدوار والصلاحيات في وحدة الإدارة، واستقبلها ضمن مطالبة
scopeفي رمز JWT، وطبّقها في واجهتك البرمجية بسطر وسيط واحد. - حزم تطوير لأكثر من عشرين إطاراً — React وNext.js وVue وAngular وReact Native وFlutter وPython وFastAPI وGo وPHP وLaravel و.NET وJava وSpring Boot وغيرها.
النشر عبر Docker Compose خطوة بخطوة
إنشاء المجلد وملف Compose
اتصل بخادمك عبر SSH ثم أنشئ مجلد العمل:
mkdir -p /opt/logto && cd /opt/logtoأنشئ ملف
docker-compose.ymlبالمحتوى التالي. استبدل auth.your-domain.comبنطاقك الخاص.توليد الأسرار وإنشاء ملف .env
ولّد كلمة مرور قاعدة بيانات قوية ومفتاح AES-256:
DB_PASSWORD=$(openssl rand -hex 32) SECRET_VAULT_KEK=$(openssl rand -hex 32) printf "DB_PASSWORD=%s\nSECRET_VAULT_KEK=%s\n" "$DB_PASSWORD" "$SECRET_VAULT_KEK" > .env chmod 600 .envتأكد من أن
.envيحتوي على سطرين غير فارغَين قبل المتابعة.ضبط nginx كوكيل عكسي
أنشئ المضيف الافتراضي
/etc/nginx/sites-available/logtoوأعِد تشغيل nginx بعد اختبار الإعداد:nginx -t && systemctl reload nginxتشغيل المكدّس والتحقّق منه
شغّل الحاويتين:
docker compose up -dتابع السجلات لمدة 60 ثانية للتأكد من أن PostgreSQL جاهز وأن Logto أتمّ ترحيلاته. يجب أن ترى السطر
App is running at https://auth.your-domain.com.التحقّق من وثيقة اكتشاف OIDC
من جهازك المحلي، تحقّق من استجابة نقطة OIDC:
curl -s https://auth.your-domain.com/.well-known/openid-configuration | python3 -m json.tool | head -10يجب أن تحتوي الاستجابة على
issuerوauthorization_endpointوjwks_uri. إن أعادت الأمر خطأ 502، فانتظر 30 ثانية وأعد المحاولة.إعداد النسخ الاحتياطية التلقائية
أضف مهمة cron لتصدير قاعدة البيانات يومياً. للحصول على نسخ آلية مشفّرة نحو S3 أو Backblaze B2، اربط وحدة تخزين
logto_dbبنسخة Backrest المتاحة في كتالوج ServOrbit.
أول تسجيل دخول
فتح نفق SSH إلى وحدة الإدارة
تستمع وحدة الإدارة على المنفذ 3002، المرتبط بالعنوان المحلي لأسباب أمنية. من جهازك، افتح النفق:
ssh -L 3002:127.0.0.1:3002 root@ip-of-your-vpsابقِ هذه النافذة مفتوحة طوال جلسة الإدارة.
إنشاء حساب المدير
افتح
http://localhost:3002في متصفحك. يظهر معالج أول تشغيل — لا توجد أي بيانات اعتماد افتراضية. أدخل عنوان بريد إلكتروني وكلمة مرور قوية، ثم انقر على Create account. احفظ هذه البيانات في مدير كلمات المرور.استكشاف لوحة المعلومات
بعد إنشاء الحساب، تصل إلى لوحة معلومات Logto. من هنا يمكنك الاطلاع على سجل التدقيق وإدارة المستخدمين وضبط الموصلات الاجتماعية وإنشاء تطبيقات — وهي الكيان في Logto الذي يمثّل أحد مشاريعك.
إنشاء تطبيقك الأول
في وحدة الإدارة: Applications → Create application. اختر النوع المناسب لمشروعك (Traditional Web أو Single Page App أو Native أو Machine-to-machine). أعطِه اسماً، ثم أدخل Redirect URI — العنوان الذي يعيد Logto التوجيه إليه بعد نجاح تسجيل الدخول. يولّد Logto عندئذ
App IDوApp Secretاللذان ستستخدمهما في حزمة التطوير.
دمج Logto في تطبيق Next.js
ثبّت حزمة التطوير بالأمر npm install @logto/next، ثم أنشئ ملف logto.ts يصدّر new LogtoClient({ … }) مضبوطاً بـ endpoint (عنوان نسخة Logto لديك) وappId وappSecret (من وحدة إدارة Logto) وbaseUrl (عنوان تطبيقك) وcookieSecret وcookieSecure.
ولحماية مسار، استدعِ getLogtoContext({ getAccessToken: true }) المستورد من @logto/next/server-component: فهو يعيد isAuthenticated ومطالبات المستخدم. وإن كانت isAuthenticated غير محقّقة فأعد التوجيه إلى /api/logto/sign-in، وإلا فاعرض الصفحة اعتماداً على المطالبات الواردة.
تفعيل الدخول عبر Google
في وحدة تحكّم Google Cloud، أنشئ معرّف عميل OAuth 2.0 من نوع تطبيق ويب. اضبط عنوان إعادة التوجيه على https://auth.your-domain.com/callback/google، ثم انسخ معرّف العميل وسرّه.
وفي وحدة إدارة Logto ← الموصلات ← الموصلات الاجتماعية ← Google ← تفعيل. ألصق المعرّف والسرّ ثم احفظ. يظهر Google عندئذ خياراً للدخول في صفحة Logto لديك، من دون أي تعديل في شيفرة تطبيقك.
Logto وAuthentik وAuthelia وKeycloak — أيهم تختار؟
مرّر الجدول أفقيًا
| الحل | حالة الاستخدام الأساسية | الذاكرة الدنيا | تعقيد دمج حزمة SDK |
|---|---|---|---|
| **Logto** | المصادقة لمنتج تبنيه (تسجيل، JWT، موصلات اجتماعية) | 2 غيغابايت | منخفض — حزمة SDK رسمية في 15 سطراً لـ React وNext.js وPython وGo وFlutter وأكثر من 15 إطاراً آخر |
| **Authentik** | SSO مركزي لأدواتك المستضافة ذاتياً (Grafana وGitea وNextcloud وProxmox) | 2 غيغابايت | متوسط — الضبط عبر Providers في وحدة الإدارة، بلا SDK تطبيقية |
| **Authelia** | MFA وبوابة دخول أمام تطبيقات قائمة دون تعديل شيفرتها | 256 ميغابايت | معدوم — تفويض مصادقة عبر ترويسة nginx، بلا دمج SDK |
| **Keycloak** | SSO مؤسسي، تفحيد LDAP/AD، سيناريوهات متعددة المستأجرين المتقدمة | 4 غيغابايت كحدّ أدنى | مرتفع — ضبط OIDC يدوي، مكتبات عميل تُعدّ لكل إطار |
لمنتج SaaS قيد التطوير، Logto هو نقطة البداية الطبيعية. يناسب Keycloak المؤسسات التي تملك دليلاً مؤسسياً تريد دمجه. يلبّي Authelia وAuthentik احتياجات البنية التحتية لا التطبيقات.
استكشاف الأخطاء الشائعة
إليك المشكلات الأربع الأكثر شيوعاً عند أول تثبيت لـ Logto على خادم افتراضي وكيفية حلّها.
وحدة الإدارة غير متاحة (المنفذ 3002)
المنفذ 3002 مرتبط عمداً بـ 127.0.0.1 — فلا يمكن الوصول إليه مباشرة من الإنترنت. إن لم يستجب http://localhost:3002، تحقّق أولاً من أن نفق SSH مفتوح. ثم افحص أن حاوية Logto تعمل: docker compose ps. إن كانت الحاوية في حالة Exit، راجع السجلات: docker compose logs logto --tail=50.
خطأ 502 في اكتشاف OIDC
يُنفّذ Logto ترحيلات قاعدة البيانات عند أول تشغيل، وتستغرق بين 30 و90 ثانية. إن أعاد /.well-known/openid-configuration خطأ 502، فـ nginx يُمرّر الطلبات قبل أن يكون Logto جاهزاً. انتظر 90 ثانية وأعد المحاولة. إن استمرّ الخطأ، تحقّق من سلامة PostgreSQL.
عدم تطابق Redirect URI
يتحقّق Logto من عنوان إعادة التوجيه بدقة: إن لم يطابق العنوان المُرسَل من تطبيقك ما هو مُعلَن في وحدة الإدارة، يفشل تسجيل الدخول بخطأ redirect_uri_mismatch. تأكد من تسجيل العنوان الكامل بما فيه المخطط (https://) والمسار الدقيق. عناوين التطوير (http://localhost:3000/…) يجب إضافتها منفصلة.
Fatal: cannot connect to db
إن ظهر في سجلات Logto Fatal: cannot connect to db، فـ PostgreSQL لم يكن جاهزاً لقبول الاتصالات حين حاول Logto الوصول إليه. أعد تشغيل حاوية Logto: docker compose restart logto. ستُعاد المحاولة فور استعداد PostgreSQL.
استراتيجية النسخ الاحتياطي
يحفظ Logto حالته كلها في وحدة تخزين PostgreSQL باسم logto_db. انسخها احتياطياً بمهمة pg_dump مجدولة، أو اربط الوحدة بنسخة Backrest (وهي أيضاً في كتالوج ServOrbit) للحصول على نسخ آلية مشفّرة ومزالة التكرار نحو S3 أو Backblaze B2 أو SFTP. فقدان وحدة logto_db يعني فقدان كل حسابات المستخدمين وإعدادات التطبيقات وسجلّ التدقيق — انسخها قبل أي ترحيل للخادم.
