تطبيق Flashcards مفتوح المصدر للاستضافة الذاتية والتكرار المتباعد
نعم، يمكن استضافة Flashcards ذاتيًا. فالشيفرة الكاملة للتطبيق والبنية التحتية مفتوحة المصدر بموجب ترخيص MIT. يمكنك تشغيل الخدمات محليًا لأغراض التطوير أو نشر مكدس الإنتاج الموثق في المستودع على AWS. وإذا كنت لا تريد تشغيل البنية التحتية بنفسك، يظل التطبيق المستضاف متاحًا.
ما الذي يمكن استضافته ذاتيًا؟
يحتوي المستودع على الخدمات والبنية التحتية المستخدمة في نظام Flashcards الأساسي:
- تطبيق الويب وتطبيق الإدارة
- واجهة API الخلفية وخدمة المصادقة بلا كلمة مرور
- مخطط PostgreSQL وعمليات الترحيل والمزامنة وجدولة المراجعة المبنية على FSRS
- خادم MCP وواجهة Agent API المخصصة للآلات
- مكدس AWS CDK للشبكات وقاعدة البيانات والمصادقة وواجهات API واستضافة الويب الثابتة والأسرار والنسخ الاحتياطية والمراقبة وCI/CD
كما يتضمن عملاء أصليين لنظامي iOS وAndroid. وهذه التطبيقات إصدارات مستقلة؛ فنشر مكدس AWS لا ينشر نيابةً عنك إصداراتك الخاصة في App Store أو Google Play.
هناك طريقتان مدعومتان لتشغيل مكدس الخادم:
- التطوير المحلي: يشغّل Docker Compose قاعدة PostgreSQL ومهمة الترحيل، بينما تشغّل نصوص المستودع خوادم تطوير المصادقة والخلفية والويب والإدارة على الجهاز المضيف.
- الإنتاج على AWS: ينشر مكدس CDK المرفق بنية AWS الموثقة ويربط نطاقاتها العامة عبر Cloudflare.
ليس Docker Compose نشرًا إنتاجيًا بأمر واحد. فمسار الإنتاج خاص بـ AWS، ولا يدّعي المشروع توفير بنية تحتية محايدة تجاه مزودي الخدمات.
ما الذي يتضمنه المستودع حاليًا؟
هذا أكثر من مجرد محرر مستقل للبطاقات التعليمية. يتضمن المستودع الحالي:
- عميل ويب وتطبيق إدارة مبنيين بـ React
- عميل iOS أصليًا بـ SwiftUI وعميل Android أصليًا بـ Jetpack Compose
- تخزينًا محليًا أولًا ومزامنة لعملاء المستخدمين
- بطاقات بوجهين، ووسومًا، ووسائط مرتبطة، ومراجعة باستخدام FSRS
- رمز OTP عبر البريد الإلكتروني بلا كلمة مرور من خلال Amazon Cognito وخدمة المصادقة
- دردشة ذكاء اصطناعي تعتمد على عامل غير متزامن منشور وبيانات اعتماد النموذج التي يوفرها المشغّل
- نقطة نهاية MCP لعملاء الذكاء الاصطناعي المتوافقين
- واجهة Agent API لأدوات الطرفية ومسارات العمل المؤتمتة الأخرى
تُعد وثائق المعمارية أفضل مصدر للحدود الحالية بين الخدمات. ويشرح دليل API العام نقطة دخول Agent API المستضافة.
التطبيق المستضاف مقابل الاستضافة الذاتية
| الجانب | التطبيق المستضاف | النشر المستضاف ذاتيًا |
|---|---|---|
| الإعداد الأولي | افتح التطبيق وسجّل الدخول | اضبط الحسابات والأسرار والنطاقات وانشر مكدس AWS |
| البنية التحتية | يشغّلها مشروع Flashcards | تشغّلها أنت في حسابيك على AWS وCloudflare |
| قاعدة البيانات والنسخ الاحتياطية | تُدار نيابةً عنك | تقع مسؤولية RDS وسياسة النسخ الاحتياطي وعمليات الترحيل والاستعادة عليك |
| المصادقة والبريد الإلكتروني | يُداران نيابةً عنك | Cognito مع بيانات اعتماد إرسال البريد وDNS الخاصة بك |
| الذكاء الاصطناعي | يستخدم إعداد الخدمة المستضافة | يستخدم العامل المنشور وبيانات اعتماد نموذجك؛ وللوصول بصفة ضيف حصة منفصلة |
| المراقبة | تُدار نيابةً عنك | CloudWatch وSNS وإعداد Sentry الخاص بك |
| التحديثات | تصدرها الخدمة المستضافة | تسحب التحديثات وتتحقق منها وتنشرها وتراقبها بنفسك |
| التكلفة | تسري شروط الخطة المستضافة | تدفع تكاليف AWS ومزودي الخدمات الآخرين مباشرةً |
تمنحك الاستضافة الذاتية التحكم في النشر وقاعدة البيانات، لكنها تجعلك أيضًا مسؤولًا عن تحديثات الأمان والأسرار والتوافر والنسخ الاحتياطية وتسليم البريد والمراقبة وتكاليف السحابة.
المتطلبات والبدء المحلي السريع
يتطلب التطوير المحلي حاليًا Git وBash وGNU Make وDocker مع Docker Compose وNode.js 24 وnpm. يشغّل ملف Compose المرفق PostgreSQL 18.4 ويطبّق عمليات ترحيل قاعدة البيانات.
من جذر المستودع:
git clone https://github.com/kirill-markin/flashcards-open-source-app.git
cd flashcards-open-source-app
cp .env.example .env
make db-up
npm install --prefix api
npm install --prefix apps/auth
npm install --prefix apps/backend
npm install --prefix apps/web
npm install --prefix apps/admin
لأقصر تشغيل محلي فقط، شغّل الخلفية بالدور الذي أنشأته عملية الترحيل، وفعّل المصادقة المحلية غير الآمنة صراحةً:
AUTH_MODE=none \
ALLOW_INSECURE_LOCAL_AUTH=true \
DATABASE_URL=postgresql://backend_app:backend_app@localhost:5432/flashcards \
REPORTING_DATABASE_URL=postgresql://reporting_readonly:reporting_readonly@localhost:5432/flashcards \
make backend-dev
ثم شغّل العميلين في نافذتين منفصلتين للطرفية:
make web-dev
make admin-dev
لا يشغّل هذا المسار خدمة مصادقة Cognito عمدًا. يوضح دليل الاستضافة الذاتية عناوين URL المنفصلة لقاعدة البيانات وخطوات تحميل متغيرات البيئة لمسار Cognito كامل باستخدام make auth-dev. يعمل تطبيق الويب على http://localhost:3000، وتطبيق الإدارة على http://localhost:3001، والخلفية على http://localhost:8080/v1، ومصادقة Cognito، عند إعدادها، على http://localhost:8081.
يغطي هذا البدء السريع تطوير الخلفية الأساسية والويب والإدارة. ولا يجعل Chat V2 متاحًا، لأن هذه المسارات لا تقبل نقل المصادقة AUTH_MODE=none، ولأن الأوامر المحلية لا تشغّل عامل الدردشة غير المتزامن.
للإنتاج، استخدم مسار النشر الأول في المستودع بدلًا من Docker Compose:
npm ci --prefix apps/auth
bash scripts/deploy/first-deploy.sh \
--region eu-central-1 \
--domain example.com \
--alert-email alerts@example.com
يُطلب تثبيت حزمة المصادقة صراحةً حاليًا عند البدء من نسخة مستنسخة نظيفة، لأن مساعد النشر يحزم تلك الحزمة لكنه لا يثبتها. وبعد ذلك ينشئ المساعد موارد سحابية حقيقية ويحدّثها. اقرأ دليل نشر الخلفية والويب ودليل نشر AWS CDK قبل تشغيله.
قابلية نقل البيانات مفيدة لكنها محدودة عمدًا
يشمل استيراد حزم Flashcards وتصديرها البطاقات ووسومها والوسائط المرتبطة بها. ولا ينقل سجل المراجعة أو حالة مجدول FSRS أو إعدادات مساحة العمل أو هياكل مجموعات البطاقات الكاملة أو بيانات الحساب.
هذا الفرق مهم إذا كنت تنتقل بين الخدمة المستضافة ونشرك الخاص. فالحزمة القابلة للنقل وسيلة لنقل المحتوى، وليست ترحيلًا كاملًا لقاعدة البيانات أو الحساب. وللحصول على نسخة احتياطية تشغيلية كاملة، يجب على مشغّل الاستضافة الذاتية إدارة قاعدة بيانات PostgreSQL وتخزين الوسائط اللذين ينشئهما مكدس AWS أيضًا.
الذكاء الاصطناعي وبيانات اعتماد الخدمات الخارجية
لا تتضمن الشيفرة المصدرية حسابات سحابية أو أرصدة نماذج أو بيانات اعتماد إنتاجية. ويوفر مشغّل الاستضافة الذاتية الإعدادات ذات الصلة:
- بيانات اعتماد AWS وحساب AWS لمكدس CDK
- نطاق وبيانات اعتماد Cloudflare لإعداد DNS الموثق
- بيانات اعتماد Resend لتسليم البريد الإلكتروني
- إعداد Sentry اللازم لمراقبة الخلفية
- بيانات اعتماد OpenAI وLangfuse الاختيارية للذكاء الاصطناعي والتتبع
- إعداد GitHub لمسار النشر المرفق
الذكاء الاصطناعي اختياري في نشر AWS. ينشر مكدس CDK عامل الدردشة غير المتزامن، وتتيح بيانات اعتماد النموذج طلبات الذكاء الاصطناعي الموثقة والمدعومة. يتحكم GUEST_AI_WEIGHTED_MONTHLY_TOKEN_CAP بشكل منفصل في استخدام الضيوف للذكاء الاصطناعي؛ وهو ليس مفتاحًا عامًا لطلبات الذكاء الاصطناعي للمستخدمين المسجّلين أو الموثقة برمز الحامل. وإذا ربطت MCP أو عميل ذكاء اصطناعي خارجيًا آخر، فقد يعالج ذلك المزود الخارجي بيانات البطاقات المضمّنة في الطلب وفق شروطه؛ فاستضافة قاعدة البيانات ذاتيًا لا تُبقي تلك الطلبات داخل بنيتك التحتية.
حدود الإصدار التجريبي والتشغيل بصراحة
لا يزال Flashcards منتجًا في مرحلة مبكرة. فالمستودع نشط، وقد تتغير عمليات الترحيل وإعدادات النشر، وتفترض الاستضافة الذاتية أنك مرتاح لتشغيل تطبيق على AWS.
يتضمن مكدس CDK نسخًا احتياطية وتنبيهات وأسرارًا وأتمتة للنشر، لكن هذه المكونات ما زالت تحتاج إلى مشغّل. وينبغي أن تتوقع:
- مراجعة تغييرات البنية التحتية قبل النشر
- مراقبة الإصدارات وفحوص نقاط النهاية العامة
- تأكيد اشتراكات التنبيه وDNS لنطاق البريد الإلكتروني
- حماية بيانات الاعتماد وتدويرها
- اختبار الاستعادة والتخطيط لتكاليف AWS
- بناء تطبيقات الهاتف الأصلية وتوزيعها بشكل منفصل إذا أردت إصداراتك الخاصة
إذا لم يكن هذا العمل التشغيلي مفيدًا لك، فالتطبيق المستضاف هو المسار الأبسط.
مقارنة موجزة مع Anki وQuizlet
يُعد Anki خيارًا ناضجًا مفتوح المصدر، وله منظومة كبيرة ومسارات عمل قوية على سطح المكتب. أما Quizlet فهو خدمة مُدارة للمستهلكين تقدم تجربة دراسة لا تتطلب إعدادًا كبيرًا. وقد يكون أي منهما الاختيار المناسب بحسب ما إذا كنت تفضّل أداة محلية راسخة أو منصة مُدارة بالكامل.
يتخذ Flashcards مسارًا مختلفًا: مستودع مفتوح للويب والهاتف وواجهات API والبنية التحتية، مبني حول FSRS والمزامنة ومسارات عمل الذكاء الاصطناعي وMCP وخيار الاستضافة الذاتية على AWS. وهو أحدث عمرًا من Anki، ويتطلب عند استضافته ذاتيًا عملًا تشغيليًا أكبر بكثير من Quizlet. وسبب اختياره هو أن هذا المزيج يلائم احتياجاتك، لا أن على كل متعلم تشغيل مكدس سحابي.
جرّب التطبيق المستضاف أو شغّل مكدسك الخاص
استخدم النسخة المستضافة عندما تريد الدراسة من دون صيانة البنية التحتية. واستخدم مسار الاستضافة الذاتية عندما يكون التحكم في النشر جديرًا بما يتطلبه من عمل على AWS وDNS والبريد الإلكتروني والمراقبة والتحديثات.