📈 تثبيت marimo — دفاتر بايثون تفاعلية بدون حالة مخفية

انشر marimo على Ubuntu بـ Docker — دفاتر بايثون تفاعلية مخزّنة كملفات .py عادية، بدون حالة مخفية ومع تحكم نظيف بالإصدارات، محمية برمز وصول، على المنفذ 2718.

⚠️ راجع أي سكريبت دائمًا قبل تشغيله على سيرفرك، واختبره في بيئة تجريبية أولاً.

📦 الملفات والأكواد المطلوبة

قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.

سكريبت تثبيت آلي — أمر واحد ينشر marimo على المنفذ 2718 مع كلمة مرور رمزية مولّدة. دفاترك تُخزَّن كملفات .py عادية تتحكم بإصداراتها بنظافة.
عرض على GitHub

التثبيت السريع:

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/data-science/marimo/marimo-ubuntu.sh
chmod +x marimo-ubuntu.sh
./marimo-ubuntu.sh

خطوات التنفيذ

1 تحميل السكريبت

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/data-science/marimo/marimo-ubuntu.sh

2 منحه صلاحية التنفيذ

chmod +x marimo-ubuntu.sh

3 تشغيل المثبت

./marimo-ubuntu.sh

4 فتح marimo باستخدام الرمز

http://your-server-ip:2718

المنافذ المستخدمة

المنفذالغرض
2718marimo web interface, token-protected

نظرة عامة

marimo هو دفتر بايثون مفتوح المصدر يعالج مشكلتين قديمتين في Jupyter. إنه تفاعلي: عند تغيير خلية، تُعاد تلقائياً تشغيل كل خلية تعتمد عليها، لذا تتطابق حالة الدفتر المعروضة على الشاشة دائماً مع الكود، بدون متغيرات متبقية من خلية حذفتها أو شغّلتها خارج الترتيب. وبدلاً من صيغة JSON الخاصة بـ Jupyter (.ipynb)، دفتر marimo هو ملف .py عادي، فيتم مقارنته (diff) بنظافة في Git، ويُراجَع مثل أي كود عادي، ويمكن تشغيله مباشرة كسكريبت أو استيراده كوحدة. مبني على FastAPI وبايثون، ويُثبَّت كحزمة واحدة عبر pip، ومُرخَّص برخصة Apache-2.0.

لماذا تستخدمه

إذا سبق أن فتحت دفتر Jupyter وحصلت على نتائج مختلفة عمّا هو معروض، فتلك حالة مخفية — خلايا شُغِّلت خارج الترتيب وذاكرة النواة لم تعد تطابق الكود الظاهر. نموذج التنفيذ التفاعلي في marimo يجعل هذا النوع من الأخطاء مستحيلاً بنيوياً: يتتبع رسماً بيانياً للاعتماديات بين الخلايا ويعيد تشغيل كل ما يعتمد على التغيير تلقائياً. ولأن الدفاتر ملفات .py عادية، تندمج بشكل طبيعي في سير عمل Git — مقارنات ذات معنى، مراجعة كود حقيقية، ولا مزيد من تعارضات الدمج في كتلة JSON ضخمة. ودفتر marimo ليس مجرد ملف تجريبي — نفس الدفتر يمكن أن يعمل كسكريبت، أو يُنشر كتطبيق ويب تفاعلي بعناصر واجهة مدمجة، أو يُشارك كرابط يعمل بالكامل في المتصفح عبر WebAssembly.

متى تحتاجه

  • عانيت من أخطاء الحالة المخفية في Jupyter — دفتر يبدو صحيحاً على الشاشة لكنه لم يعد يعكس ما هو موجود فعلياً في الذاكرة
  • تريد إبقاء الدفاتر في Git والحصول على مقارنات ذات معنى ومراجعات طلبات سحب بدلاً من كتل JSON غير قابلة للقراءة
  • تحتاج تحويل دفتر استكشافي إلى تطبيق أو لوحة تحكم تفاعلية قابلة للمشاركة دون إعادة كتابته في إطار عمل منفصل
  • تُدرّس أو تنشر تحليلاً وتريد أن يكون الدفتر نفسه قابلاً لإعادة الإنتاج من البداية للنهاية في كل مرة يُشغَّل فيها
  • تريد عناصر واجهة تفاعلية مدمجة — أشرطة تمرير، قوائم منسدلة، جداول — تُحدّث الخلايا المعتمدة عليها تلقائياً دون أدوات إضافية

من يحتاجه

  • علماء البيانات ومهندسو تعلم الآلة الذين يريدون دفاتر قابلة لإعادة الإنتاج بدون مزالق ترتيب التنفيذ في Jupyter
  • مطورو بايثون الذين يحتفظون بكود التحليل في Git ويريدون دفاتر تُقارَن وتُراجَع فعلياً بشكل جيد
  • المعلمون والباحثون الذين يحتاجون أن يُنتج كل تشغيل لدفتر منشور نفس النتيجة
  • الفرق التي تبني أدوات ولوحات تحكم داخلية وتريد الانتقال من دفتر إلى تطبيق قابل للمشاركة في نفس الملف
  • المهندسون المهاجرون من Jupyter الذين يريدون محرراً حديثاً بإكمال تلقائي ومدير حزم ومساعدة خلايا بالذكاء الاصطناعي

حالات الاستخدام الشائعة

  • استكشاف وتنظيف مجموعة بيانات تفاعلياً، مع الثقة بأن النتائج المعروضة تطابق دائماً الكود الحالي
  • بناء نموذج أولي لتعلم آلي وتكراره، بتعديل المعاملات عبر أشرطة تمرير تفاعلية بدلاً من إعادة تشغيل الخلايا يدوياً
  • تحويل دفتر منتهٍ إلى لوحة تحكم داخلية أو تطبيق بيانات بأمر `marimo run`، دون إعادة كتابته في Streamlit أو Flask
  • إبقاء دفاتر البحث والتحليل تحت التحكم بالإصدارات في Git، مع مراجعة كود حقيقية على طلبات السحب
  • تدريس مقرر بايثون أو علوم بيانات حيث يُشغّل كل طالب نفس الدفتر القابل لإعادة الإنتاج تماماً
  • استعلام قاعدة بيانات محلية أو بعيدة مباشرة من خلية SQL وتمرير النتائج إلى خلايا بايثون لاحقة

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

  • تنفيذ تفاعلي — تغيير خلية يُعيد تشغيل كل خلية تعتمد عليها تلقائياً، ويمنع marimo تعريف نفس المتغير في خليتين للحفاظ على وضوح رسم الاعتماديات
  • الدفاتر تُخزَّن كملفات .py عادية صديقة لـ Git بدلاً من صيغة JSON الخاصة بـ Jupyter (.ipynb)
  • عناصر واجهة تفاعلية مدمجة (أشرطة تمرير، قوائم منسدلة، جداول، رفع ملفات) تُشغّل الخلايا اللاحقة تلقائياً
  • شغّل نفس الملف بثلاث طرق: كدفتر قابل للتحرير، أو كسكريبت بايثون عادي، أو كتطبيق ويب تفاعلي منشور بأمر `marimo run`
  • خلايا SQL أصلية تستعلم قواعد البيانات أو أطر البيانات وتُعيد النتائج لبايثون
  • يعمل بالكامل في المتصفح عبر WebAssembly للمشاركة بدون تثبيت، بالإضافة إلى وضع السيرفر ذاتي الاستضافة
  • إدارة حزم مدمجة، بما فيها وضع صندوق رملي معزول لتبعيات قابلة لإعادة الإنتاج لكل دفتر
  • تجربة محرر حديثة مع إكمال تلقائي ومساعدة خلايا بـ GitHub Copilot/الذكاء الاصطناعي ومحرك إعادة تشغيل سريع يدرك الاعتماديات

كيفية الاستخدام بعد التثبيت

  • افتح واجهة الويب على عنوان IP الخاص بسيرفرك على المنفذ 2718 وأدخل رمز الوصول المطبوع في سجلات الحاوية
  • أنشئ دفتراً جديداً من المحرر وابدأ إضافة الخلايا — يُشغّل marimo الخلايا المعتمدة تلقائياً أثناء تحريرك
  • ثبّت أي حزم بايثون يحتاجها دفترك من داخل المحرر، أو فعّل وضع الصندوق الرملي لتبعيات معزولة وقابلة لإعادة الإنتاج
  • أضف عناصر واجهة تفاعلية مثل أشرطة التمرير أو القوائم المنسدلة لبناء استكشاف تفاعلي دون كتابة كود استدعاء
  • احفظ الدفتر — يُكتب على القرص كملف .py عادي، فأودعه في Git مثل أي ملف مصدري آخر
  • عندما يصبح جاهزاً للمشاركة، شغّله كتطبيق بأمر `marimo run notebook.py` لإخفاء الكود وعرض المخرجات التفاعلية فقط
  • أعدّ وكيلاً عكسياً مع HTTPS إذا احتجت الوصول للمحرر من خارج شبكتك المنزلية، فالرمز وحده ليس بديلاً عن TLS

أفضل ممارسات الأمان

  • عامل رمز الوصول مثل كلمة مرور الجذر — دفتر marimo يمكنه تنفيذ أي كود بايثون، بما في ذلك أوامر الصدفة
  • لا تكشف المنفذ 2718 مباشرة للإنترنت بدون وكيل عكسي يوفر TLS — وإلا سينتقل الرمز بنص عادي HTTP
  • فضّل ربط السيرفر بشبكتك المحلية أو VPN مثل WireGuard على كشفه علناً تماماً للاستخدام الشخصي
  • أعد توليد الرمز وأعد تشغيل الحاوية إذا اشتبهت في تسربه، لأنه الحاجز الوحيد أمام تنفيذ كود عن بُعد
  • راجع الدفاتر التي كتبها آخرون قبل فتحها وتشغيلها — ملف .py خبيث يمكنه تنفيذ أي شيء يستطيع بايثون فعله
  • حافظ على تحديث صورة marimo Docker لتحصل على إصلاحات الأمان لسيرفر المحرر وتبعياته

المنافذ وإعدادات جدار الحماية

يستمع marimo على منفذ واحد — 2718 افتراضياً، مطابقاً للمنفذ الداخلي للحاوية دون إعادة تعيين مربكة. يخدم هذا المنفذ محرر الدفاتر وأي تطبيقات منشورة بأمر `marimo run`، والوصول محمي بالرمز المولّد عند بدء التشغيل. ولأن الرمز يحمي واجهة قادرة على تنفيذ كود عشوائي، يجب ألا يُحوَّل المنفذ 2718 مباشرة للإنترنت أبداً؛ ضعه خلف وكيل عكسي مثل Nginx Proxy Manager مع شهادة TLS صالحة، أو الأفضل، أبقه متاحاً فقط عبر VPN أو شبكتك المحلية إذا لم تكن تحتاج وصولاً عن بُعد إطلاقاً.

النسخ الاحتياطي والصيانة

  • انسخ ملفات دفاترك .py احتياطياً — لأنها نص عادي، أبسط وأمتن نسخ احتياطي هو مستودع Git بإيداعات منتظمة
  • انسخ أي ملفات بيانات محلية تشير إليها دفاترك احتياطياً، بشكل منفصل عن الدفاتر نفسها
  • احفظ docker-compose.yml وأي متغيرات بيئة محفوظة (بما فيها رمز الوصول إذا ثبّته) لإعادة إنشاء نفس الإعداد بالضبط
  • لا توجد قاعدة بيانات لنسخها احتياطياً — حالة marimo تعيش بالكامل في ملفات الدفاتر ومصادر البيانات التي توجهها إليها
  • اختبر أن حاوية جديدة يمكنها فتح دفتر وإعادة إنتاج مخرجاته بشكل صحيح بعد الاستعادة من تاريخ Git لديك

الأخطاء الشائعة

  • كشف المنفذ 2718 مباشرة للإنترنت، بالاعتماد على الرمز وحده بدلاً من وضع TLS أمامه
  • عدم إيداع الدفاتر في Git إطلاقاً، مما يُهدر أكبر ميزة لـ marimo على صيغة JSON غير القابلة للتحكم بإصداراتها في Jupyter
  • مقاومة النموذج التفاعلي بمحاولة إعادة تعريف نفس المتغير في عدة خلايا، وهو ما يمنعه marimo عن قصد للحفاظ على تنفيذ حتمي
  • تشغيل الحاوية كجذر أو بصلاحيات مفرطة بينما لا يحتاج الدفتر نفسه أي وصول على مستوى المضيف
  • نسيان أن أمر `marimo run` يُخفي الكود عن المشاهدين بتصميم مقصود — استخدامه بينما كنت تريد فعلياً مشاركة الكود المصدري
  • عدم استخدام تبعيات معزولة/صندوق رملي، مما يسبب تسرب تعارضات الحزم بين دفاتر غير مرتبطة تعمل على نفس التثبيت

استكشاف الأخطاء وإصلاحها

  • أخطاء "المتغير معرّف مسبقاً" — أعد تسمية المتغير أو ادمج الخلايا المتعارضة؛ يتطلب marimo تعريف كل متغير عام في خلية واحدة بالضبط
  • فقدان أو نسيان رمز الوصول — تحقق من سجلات الحاوية (`docker logs`) حيث يطبعه marimo عند بدء التشغيل، أو أعد تشغيل الحاوية لتوليد رمز جديد
  • أخطاء استيراد الحزم داخل دفتر — ثبّت الحزمة المفقودة من لوحة الحزم في المحرر، أو فعّل وضع الصندوق الرملي لبيئة نظيفة ومعزولة
  • المنفذ 2718 غير متاح — تأكد أن الحاوية تعمل، وأن تعيين المنفذ في docker-compose.yml صحيح، وأن جدار حماية المضيف يسمح بالمنفذ
  • تغييرات الدفتر لا تُحفظ — تحقق أن حجم التخزين المربوط للدفاتر لديه صلاحيات كتابة صحيحة لمستخدم الحاوية
  • الخلايا تُعاد تشغيلها بشكل غير متوقع — تذكّر أن هذا تفاعلي بتصميم مقصود؛ تحقق من عرض رسم الاعتماديات لترى بالضبط سبب تشغيل الخلية

البدائل

Jupyter وJupyterLab هما الخيار الافتراضي لمعظم الناس ولديهما نظام بيئي أكبر بكثير من الإضافات والنواتات والألفة المؤسسية — إذا لم تزعجك الحالة المخفية والدفاتر غير القابلة للتحكم بإصداراتها في سير عملك، يظلان خياراً معقولاً جداً. تقدم Google Colab وDeepnote دفاتر مستضافة سحابياً مجانية أو منخفضة التكلفة بدون أي صيانة سيرفر، على حساب تشغيل كودك على بنية تحتية لشخص آخر. Pluto.jl هو دفتر لغة Julia الذي ألهم تصميم marimo التفاعلي، للفرق العاملة بـ Julia بدلاً من بايثون. كدفتر بايثون ذاتي الاستضافة تفاعلي، يُخزَّن كملفات .py عادية، ويمكنه العمل كتطبيق قابل للنشر، يُعد marimo حالياً الخيار الأكمل.

متى لا تستخدمه

إذا كان فريقك مستثمراً بعمق في النظام البيئي لـ Jupyter — نواتات محددة، إضافات، أو خطوط عمل قائمة على nbconvert — فقد تكلف هجرة كل شيء إلى marimo أكثر مما يوفره النموذج التفاعلي. كما أن قاعدة marimo الصارمة التي تمنع إعادة تعريف متغير عبر عدة خلايا، رغم أنها ما يمنع أخطاء الحالة المخفية، قد تبدو مقيّدة إذا اعتدت على أسلوب Jupyter الحر ولا تريد تعديل عاداتك. وإذا كنت تحتاج فقط دفتراً عرضياً لمرة واحدة ولا يهمك التحكم بالإصدارات أو إعادة الإنتاج، فدفتر سحابي سريع مثل Google Colab يتجنب تشغيل سيرفر تماماً.

هل تحتاج مساعدة احترافية؟

توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.

  • التثبيت وتجهيز السيرفر
  • الإعداد المتقدم وإعداد التوجيه
  • تصليب الأمان وتحسين جدار الحماية
  • إعداد شهادات SSL/TLS مع Let's Encrypt
  • ربط النطاق المخصص والوكيل العكسي
  • جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
  • المراقبة الفورية وتنبيهات الجاهزية
  • الترحيل من المنصات القائمة
  • استكشاف مشكلات الاتصال والأداء وإصلاحها
  • سكريبتات أتمتة مخصصة وعقود دعم مستمر
تواصل مع PrismaTechWork

الأسئلة الشائعة

ما هو marimo؟

marimo هو دفتر بايثون حديث يحل مشكلتين متأصلتين في Jupyter. إنه تفاعلي: غيّر خلية وستُعاد تلقائياً كل خلية معتمدة عليها، فلا توجد حالة مخفية ويتطابق الدفتر دائماً مع الكود. ويخزّن الدفاتر كملفات .py عادية، فتُقارَن بنظافة في Git وتُراجَع مثل كود عادي، بدلاً من JSON الفوضوي في Jupyter. يمكنه حتى العمل كسكريبت أو يصبح تطبيقاً تفاعلياً.

ما المنفذ الذي يستخدمه وكيف أسجّل الدخول؟

يعمل marimo على المنفذ 2718 على المضيف، وهو منفذه القياسي — هنا منفذ الحاوية والمضيف متطابقان. الوصول محمي برمز مولَّد يعمل ككلمة مرور، يُطبع بعد الإعداد. افتح http://your-server:2718 وأدخل الرمز. حافظ عليه بأمان، لأن الدفتر يمكنه تنفيذ أي كود، ولا تكشف المنفذ علناً أبداً بدون TLS أمامه.

كيف يختلف عن Jupyter؟

بطريقتين كبيرتين. يتيح لك Jupyter تشغيل الخلايا بأي ترتيب، مما يخلق حالة مخفية — قد لا تعكس الشاشة ما هو موجود فعلياً في الذاكرة، ويمكن أن تُكسر الدفاتر بشكل خفي. marimo تفاعلي، فتُعاد تلقائياً الخلايا المعتمدة ويبقى الدفتر متسقاً دائماً. ويخزّن Jupyter الدفاتر كـ JSON مع مخرجات مضمّنة، مما يُقارَن بشكل سيئ في Git، بينما يستخدم marimo ملفات .py عادية تتحكم بإصداراتها بنظافة.

هل الدفاتر فعلاً مجرد ملفات بايثون؟

نعم — كل دفتر marimo هو ملف .py عادي، وهذا محوري في تصميمه. هذا يعني أنه يُقرأ كبايثون عادي، ويُقارَن بنظافة في Git لمراجعة كود حقيقية، ويمكن تشغيله مباشرة كسكريبت أو استيراده كوحدة، وليس فيه مخرجات مضمّنة غامضة. إنها ميزة عملية كبيرة على صيغة JSON (.ipynb) الخاصة بـ Jupyter لأي شخص يحتفظ بدفاتره في مستودع أو يراجعها.

هل يجب أن أستخدم marimo أم JupyterLab؟

إذا كانت أخطاء الحالة المخفية والدفاتر غير القابلة للتحكم بإصداراتها في Jupyter تُزعجك، فإن marimo يعالج الاثنتين مباشرة ويُعد ترقية حقيقية. إذا كنت مستثمراً بعمق في النظام البيئي الواسع لـ Jupyter وإضافاته، أو يعمل فريقك بالكامل في Jupyter، فقد يكون JupyterLab أكثر واقعية رغم عيوبه. كلاهما بيئتا دفاتر بايثون ممتازتان — الاختيار بين نموذج marimo التفاعلي الأنظف ونظام JupyterLab البيئي الراسخ.