استضافة Excalidraw على VPS: لوح تعاوني مفتوح المصدر

لماذا تستضيف Excalidraw بنفسك بدلاً من النسخة العامة

الفوائد الملموسة

• لا رسوم برمجية — المكوّنان (الواجهة وخادم التعاون) برخصة MIT. تدفع مقابل VPS فقط.
• سرية النماذج — يبقى الرسم المباشر على بنيتك التحتية. أما المشهد المحفوظ وصور الغرفة فيحتاجان إلى معالجة (Firebase افتراضياً): راجع «ما ينجح فعلاً في الاستضافة الذاتية».
• التحكم في الوصول — قائمة IP أو SSO‏ OIDC أو HTTP Basic Auth أمام nginx حسب مستوى العزل المطلوب.
• جلسات وأعضاء غير محدودين — لا سقف يفرضه الخطة؛ الحد الوحيد هو ذاكرة RAM للخادم، وخادم excalidraw-room خفيف الوزن.
• استمرارية اختيارية — ربط وحدة تخزين Docker أو حاوية S3 متوافقة لأرشفة اللوحات المصدَّرة بصيغة JSON.
• التكامل مع مجموعة الأدوات المستضافة ذاتياً — Excalidraw إلى جانب Penpot وMattermost وDocmost يُغلق محيط SaaS لوكالة بأكملها.

البنية: حاويتان بأدوار مختلفة

المتطلبات الأساسية

قائمة التحقق من المتطلبات

• خادم VPS بما لا يقل عن 1 نواة و512 ميغابايت RAM (يُوصى بـ 1 غيغابايت للفريق).
• Docker Engine وإضافة Docker Compose مثبَّتان (للتحقق: docker compose version).
• اسم نطاق مُوجَّه نحو IP الخادم — بدون TLS تُحجب WebSockets في المتصفحات الحديثة.
• وصول SSH بصلاحيات root أو مستخدم بصلاحيات sudo.
• شهادة TLS صالحة — يهيئ ServOrbit Let's Encrypt تلقائياً.

نشر Excalidraw في 5 خطوات

1. 01

   إنشاء VPS وتثبيت Docker

   شغّل VPS Ubuntu 24.04 من لوحة تحكم ServOrbit. بعد الاتصال عبر SSH، إن لم يكن Docker مثبتاً بعد، شغّل:

   curl -fsSL https://get.docker.com | sh

   تحقق من استجابة Docker Compose Plugin قبل المتابعة:

   docker compose version

2. 02

   بناء الصورة مع رابط التعاون الخاص بك

   انسخ المستودع الرسمي ثم اضبط عنوان الغرفة في ملف ‎‎.env.production من المستودع قبل البناء. استبدل ‎collab.yourdomain.com بالنطاق الفرعي الذي تخصصه لـ excalidraw-room:

   ‎git clone https://github.com/excalidraw/excalidraw.git
cd excalidraw
   ‎sed -i 's|^VITE_APP_WS_SERVER_URL=.*|VITE_APP_WS_SERVER_URL=https://collab.yourdomain.com|' .env.production
   ‎docker build -t my-excalidraw:latest .

   لماذا لا نستعمل --build-arg؟ لأن Dockerfile الأصلي لا يعلن أي ARG لمتغيرات VITE_APP_*: فالأمر --build-arg VITE_APP_WS_SERVER_URL=… لا يصل أبداً إلى أمر البناء، وتُبنى الصورة بشكل طبيعي وتظل موجّهة إلى خادم Excalidraw. كما أن ‎‎.dockerignore الأصلي لا يقبل إلا ‎‎.env.development و‎‎.env.production، فيُتجاهل ‎‎.env.production.local. العنوان مدمج في الحزمة، لذا يستلزم تغيير النطاق إعادة البناء.

   تحقق من النتيجة: يجب أن يطبع الأمر ‎‎docker run --rm --entrypoint sh my-excalidraw:latest -c "grep -rl oss-collab.excalidraw.com /usr/share/nginx/html || echo clean" الكلمة clean. صورة excalidraw/excalidraw الرسمية مناسبة للتجارب المحلية، لكنها تستهدف خدمات Excalidraw العامة.

3. 03

   كتابة ملف docker-compose.yml

   أنشئ مجلد عمل وضع الملف التالي. تستمع الخدمتان داخلياً؛ nginx (الخطوة التالية) هو نقطة الدخول العامة الوحيدة:

   mkdir ~/excalidraw-stack && cd ~/excalidraw-stack

   محتوى docker-compose.yml:

   services:
     excalidraw:
       image: my-excalidraw:latest
       restart: unless-stopped
       networks:
         - excalidraw
   
     excalidraw-room:
       image: excalidraw/excalidraw-room:latest
       environment:
         - CORS_ORIGIN=https://draw.yourdomain.com
       restart: unless-stopped
       networks:
         - excalidraw
   
   networks:
     excalidraw:

   شغّل المجموعة:

   docker compose up -d

4. 04

   إعداد nginx مع ترويسات WebSocket

   هذه الخطوة هي المكان الذي تفشل فيه معظم عمليات النشر بصمت: بدون ترويستَي Upgrade وConnection، يفتح المتصفح اتصالاً HTTP عادياً بدلاً من WebSocket، وتبدو ميزة التعاون كأنها لا تعمل دون أي رسالة خطأ.

   كتلة nginx للواجهة الأمامية لـ ‎Excalidraw (draw.yourdomain.com):

   server {
       listen 443 ssl;
       server_name draw.yourdomain.com;
   
       location / {
           proxy_pass http://excalidraw:80;
           proxy_set_header Host $host;
       }
   }

   كتلة nginx لخادم الغرفة (collab.yourdomain.com):

   server {
       listen 443 ssl;
       server_name collab.yourdomain.com;
   
       location / {
           proxy_pass http://excalidraw-room:80;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_set_header Host $host;
           proxy_read_timeout 86400s;
       }
   }

   أعِد تحميل nginx (nginx -s reload) بعد وضع الكتل.

5. 05

   اختبار التعاون في الوقت الفعلي

   افتح https://draw.yourdomain.com في علامتَي تبويب أو متصفحَين مختلفَين. انقر على Live collaboration في شريط الأدوات وأنشئ جلسة. انسخ رابط الجلسة في علامة التبويب الثانية.

   ارسم شيئاً في علامة التبويب الأولى: يجب أن تظهر اللمسة في الثانية فوراً. إن لم تظهر، تحقق أولاً من ترويسات WebSocket في nginx (تُظهر أدوات الشبكة في المتصفح إن كان الاتصال قد ارتقى إلى 101 Switching Protocols).

   افتح بعد ذلك تبويب الشبكة في المتصفح: يجب أن يستهدف اتصال الوقت الفعلي ‎collab.yourdomain.com لا ‎oss-collab.excalidraw.com أبداً. أما ما يستقبله Firebase فتعالجه الفقرة التالية.

ما ينجح فعلاً في الاستضافة الذاتية

ثلاثة تركيبات ممكنة، وما يتركه كل منها لدى طرف ثالث

• التركيب أ — الغرفة وحدها (تركيب هذا الدليل). تغيّر VITE_APP_WS_SERVER_URL ولا شيء غيره. يمر الرسم المباشر عبر خادمك؛ أما المشهد المحفوظ وصور الغرف فتبقى مكتوبة في Firebase التابع لـ Excalidraw. مقبول للوحات قليلة الحساسية، ولا يجوز تقديمه على أنه «لا شيء لدى طرف ثالث».
• التركيب ب — الغرفة مع مشروع Firebase خاص بك. تنشئ مشروع Firebase خاصاً بك وتضع إعداداته بصيغة JSON في VITE_APP_FIREBASE_CONFIG. تقرأ الشيفرة هذا المتغير وحده؛ لم ننشره من البداية إلى النهاية، ويبقى Firebase خدمة من Google لا استضافة ذاتية بالمعنى الصارم.
• التركيب ج — نسخة فردية. تقدّم الواجهة وحدها دون غرفة ودون رابط: يرسم كل شخص ويصدّر إلى ‎‎.excalidraw أو إلى صورة ويؤرشف الملفات عندك. لا شيء يذهب إلى طرف ثالث بسبب التعاون، لأنه غير موجود.
• ما لا يوجد في الجانب الرسمي. لا خادم تخزين مفتوح لروابط #json=، ولا خيار ينقل المحيط كله إلى نطاقك بمتغير واحد وقت التشغيل. إن كان شرطك «لا بيانات لدى طرف ثالث» مع التعاون والمشاركة، فالجواب الصادق هو عمل تكييف أو تفريع (fork) لا مجرد تثبيت.

المتغير ← الوظيفة ← ما ينكسر بدونه

مرّر الجدول أفقيًا

التحقق ممّن يستقبل ماذا

استكشاف الأخطاء: التعاون لا يبدأ، أو لا يتذكر شيئاً

الأعراض والأسباب والحلول

• تذهب الجلسة إلى ‎oss-collab.excalidraw.com (تبويب الشبكة) رغم أنك بنيت صورتك. السبب: لم يُؤخذ العنوان في الحسبان وقت البناء (--build-arg بلا أثر، و‎‎.env.production.local يتجاهله ‎‎.dockerignore). الحل: عدّل ‎‎.env.production وأعد البناء وأعد فحص grep من الخطوة 2. وتغيير النطاق يخضع للقاعدة نفسها.
• يُرفض اتصال المتصفح بالغرفة. سبب متكرر بعد ضبط CORS_ORIGIN: المصدر لا يطابق تماماً مصدر الصفحة (مخطط http بدل https، أو المنفذ، أو شرطة مائلة أخيرة). الحل: يجب أن تكون القيمة هي المصدر الدقيق للواجهة، مثل ‎https://draw.yourdomain.com.
• تظهر الخطوط مباشرةً، لكن مشاركاً ينضم لاحقاً أو بعد إعادة تشغيل الغرفة لا يجد المحتوى أو الصور. السبب: يُحفظ المشهد والصور عبر Firebase لا عبر excalidraw-room الذي لا يحتفظ بشيء. إن كان VITE_APP_FIREBASE_CONFIG فارغاً أو لا يمكن الوصول إليه فلا يُقرأ شيء. الحل: اختر التركيب أ أو ب أعلاه.
• تحذير ‎Error JSON parsing firebase config. Supplied value: في وحدة تحكم المتصفح. السبب: VITE_APP_FIREBASE_CONFIG ليس JSON صالحاً، وغالباً بسبب علامات اقتباس غير محمية جيداً أو سطر جديد في الملف. الحل: JSON في سطر واحد بين علامتي اقتباس مفردتين في ‎‎.env.production كما في الملف الأصلي.
• تفشل المشاركة بالرابط، أو يشير الرابط الناتج إلى ‎json.excalidraw.com. السبب: لم يُغيَّر VITE_APP_BACKEND_V2_POST_URL وVITE_APP_BACKEND_V2_GET_URL، أو يشيران إلى خادم لا ينفّذ الواجهة المتوقعة. الحل: الإبقاء على الافتراضي عن علم، أو تبادل ملفات ‎‎.excalidraw.
• خطأ تشفير أو توليد مفتاح على شبكة محلية عبر http://. السبب: واجهة التشفير في المتصفح (‎window.crypto) لا تُتاح إلا في سياق آمن؛ وينبّه الخيط الأصلي إلى هذا الفخ في الاستضافة الذاتية على شبكة محلية. الحل: تقديم الواجهة عبر HTTPS (أو على localhost) كما يشترط متطلب TLS أعلاه.

Excalidraw المستضاف ذاتياً مقابل بدائل SaaS

مرّر الجدول أفقيًا

للمزيد: SSO وقوائم IP المسموح بها

allow 203.0.113.0/24;
allow 198.51.100.42;
deny all;

التكامل مع مجموعة الأدوات المستضافة ذاتياً