استضافة ‎HedgeDoc‎ على ‎VPS‎ : محرر ‎Markdown‎ التعاوني

لماذا ‎HedgeDoc‎ بدلاً من ‎Notion‎ أو ‎Google Docs‎؟

‎HedgeDoc‎ يمنح فريقك التقني: ‎Markdown‎ أصيل مع عرض فوري، تحرير تعاوني بمؤشرات متعددة في آنٍ واحد، مقاطع كود مع تلوين بناء الجملة لأكثر من 200 لغة، مخططات مدمجة (‎Mermaid‎، ‎PlantUML‎)، صيغ رياضية (‎LaTeX‎ عبر ‎MathJax‎)، تصدير بنقرة واحدة إلى ‎PDF‎ أو ‎Markdown‎ أو ‎HTML‎، واستضافة على ‎VPS‎ الخاص بك.

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

خادم ‎VPS‎ يعمل بـ‎Ubuntu 22.04‎ أو ‎Debian 12‎ بـ 1 جيجابايت ذاكرة كحد أدنى.
‎Docker Engine ≥ 24‎ و‎Docker Compose V2‎ مثبّتان.
اسم نطاق يشير إلى ‎VPS‎ الخاص بك (مطلوب لـ‎TLS‎ — تحتاج ‎WebSockets‎ اتصالاً آمناً).
المنفذ 3000 متاح (المنفذ الافتراضي لـ‎HedgeDoc‎).
‎Nginx‎ مثبَّت مع دعم ‎WebSocket‎ — ضروري.

تثبيت ‎HedgeDoc‎ باستخدام ‎Docker Compose‎

الخطوة 1 — إنشاء هيكل المشروع

mkdir -p /opt/hedgedoc && cd /opt/hedgedoc

أنشئ ملف docker-compose.yml مع حاويتَي ‎PostgreSQL‎ و‎HedgeDoc‎، مستخدماً الصورة quay.io/hedgedoc/hedgedoc:1.11.1. اربط التطبيق بـ127.0.0.1:3000:3000.

الخطوة 2 — إنشاء ملف البيئة

cat > /opt/hedgedoc/.env << 'EOF'
POSTGRES_PASSWORD=كلمة_مرور_قوية_هنا
CMD_DOMAIN=hedgedoc.نطاقك.com
CMD_SESSION_SECRET=سلسلة_عشوائية_طويلة_وثابتة
EOF

⚠️ يجب أن تكون CMD_SESSION_SECRET ثابتة ولا تتغير أبداً بعد أول تشغيل. أنشئها بـ openssl rand -base64 32.

الخطوة 3 — تشغيل الحاويات

docker compose up -d
docker compose ps
docker compose logs app

سيُطبّق ‎HedgeDoc‎ ترحيلات قاعدة بيانات ‎PostgreSQL‎ تلقائياً عند أول إقلاع. بمجرد ظهور listening on port 3000 في السجلات، يكون التطبيق جاهزاً.

الخطوة 4 — ضبط ‎Nginx‎ مع دعم ‎WebSocket‎

⚠️ يجب أن يتضمن إعداد ‎Nginx‎ لـ‎HedgeDoc‎ كتلة /socket.io/ مع رؤوس ‎WebSocket‎. غيابها يُعطّل التعاون الفوري صامتاً.

server {
    server_name hedgedoc.نطاقك.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
    }
    location /socket.io/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

الخطوة 5 — إنشاء الحساب الأول

اذهب إلى https://notes.نطاقك.com وسجّل حسابك الأول (بريد إلكتروني + كلمة مرور). يصبح هذا الحساب هو المسؤول.

لتعطيل التسجيل العام بعد الإعداد:

CMD_ALLOW_REGISTRATION=false
CMD_ALLOW_ANONYMOUS=false

ثم أعد تشغيل الحاوية: docker compose up -d hedgedoc.

ميزات جديرة بالاكتشاف

مشاركة ملاحظة: لكل ملاحظة في ‎HedgeDoc‎ رابط فريد. انقر زر المشاركة للحصول على الرابط واختر وضع الوصول (للقراءة فقط، تعليقات، تحرير).

إدراج مخطط ‎Mermaid‎:

graph LR
    A[العميل] --> B[واجهة برمجية]
    B --> C[قاعدة بيانات]

تصدير الملاحظة: في القائمة (أيقونة ≡)، اختر تصدير للتنزيل بصيغة ‎Markdown‎ أو ‎HTML‎ أو ‎PDF‎.

وضع العرض التقديمي: أضف --- بين الأقسام لتحويلها إلى شرائح.

كتلة ‎Socket.io‎ مفقودة = تعاون معطّل صامتاً

الأعراض: الواجهة تُحمَّل بشكل طبيعي، يمكنك الكتابة في الملاحظات، لكن تغييرات المستخدمين الآخرين لا تظهر في الوقت الفعلي — دون رسالة خطأ.

التحقق السريع:

curl -v -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
  https://hedgedoc.نطاقك.com/socket.io/?transport=websocket

يجب أن ترى 101 Switching Protocols. إذا رأيت 200 أو 400، فالكتلة مفقودة.

‎proxy_pass‎ مع شرطة مائلة في النهاية = صفحة بيضاء أو خطأ 404

في توجيه proxy_pass في ‎Nginx‎، تُغيّر الشرطة المائلة النهائية السلوك:

# صحيح — بدون شرطة مائلة نهائية
proxy_pass http://127.0.0.1:3000;

# خاطئ — الشرطة النهائية تُعيد كتابة المسار
proxy_pass http://127.0.0.1:3000/;

تتسبب الشرطة النهائية في كسر توجيه ‎HedgeDoc‎ الداخلي. احذف دائماً الشرطة المائلة النهائية.

‎HedgeDoc‎ مقابل ‎Notion‎ و‎Confluence‎

المعيار	‎HedgeDoc‎ (استضافة ذاتية)	‎Notion‎	‎Confluence‎ (سحابي)
السعر	مجاني (تكلفة ‎VPS‎)	مجاني حتى 10 أعضاء، ثم ~10$/عضو/شهر	~5.75$/مستخدم/شهر (10 حد أدنى)
التنسيق	‎Markdown‎ أصيل	كتل احتكارية	محرر ثري (‎WYSIWYG‎)
مخططات أصيلة	‎Mermaid, PlantUML, Vega-lite‎	محدودة	عبر وحدات ماكرو
استضافة البيانات	‎VPS‎ الخاص بك	خوادم ‎Notion‎ (أمريكا)	خوادم ‎Atlassian‎
كتل الكود	200+ لغة مع تلوين	نعم (محدود)	نعم (عبر إضافة)
استضافة البيانات	‎VPS‎ الخاص بك	خوادم ‎Notion‎ (أمريكا)	خوادم ‎Atlassian‎
تصدير ‎Markdown‎	نعم (أصيل)	جزئي	غير أصيل
التعاون في الوقت الفعلي	نعم (‎WebSocket‎)	نعم	نعم
صيغ ‎LaTeX‎	نعم (‎MathJax‎)	نعم	عبر إضافة

النسخ الاحتياطي والتحديثات

# نسخ احتياطي لـPostgreSQL
docker compose exec -T database pg_dump -U hedgedoc hedgedoc | gzip > /opt/hedgedoc/backups/hedgedoc-$(date +%Y%m%d).sql.gz

# تحديث HedgeDoc
cd /opt/hedgedoc
docker compose pull app
docker compose up -d app

تُطبَّق ترحيلات قاعدة البيانات تلقائياً عند إقلاع الإصدار الجديد. تحقق من السجلات. الصورة الحالية: quay.io/hedgedoc/hedgedoc:1.11.1.

إدارة المستخدمين والصلاحيات

تُدير ‎HedgeDoc‎ ثلاثة مستويات وصول لكل ملاحظة: مفتوح (الجميع يُعدّل بدون حساب)، قابل للتحرير (المستخدمون المسجّلون فقط)، محدود (المالك يُعدّل، الآخرون يُعلّقون)، مقفل (قراءة فقط للجميع باستثناء المالك)، خاص (المالك فقط).

تعطيل التسجيل العام: عيّن CMD_ALLOW_REGISTRATION: 'false' في .env. أنشئ حسابات عبر ‎CLI‎: docker compose exec app npm run manage_users -- --add [email protected] --password Password.

حل المشكلات الشائعة

الواجهة تُحمَّل لكن التعاون الفوري لا يعمل: تحقق من كتلة /socket.io/ في ‎Nginx‎ (راجع التنبيه المخصص أعلاه).

خطأ 502 بعد الإقلاع: انتظر 60 ثانية. تحقق أن database في حالة healthy بـ docker compose ps.

الصور المرفوعة تختفي بعد إعادة التشغيل: تحقق أن حجم uploads مُثبَّت بشكل صحيح (نوع volume وليس bind).

خطأ في تصدير ‎PDF‎: إذا لم يتضمن صورة ‎Docker‎ الخاصة بك ‎Chromium‎، عطّل تصدير ‎PDF‎ بـ CMD_ALLOW_PDF_EXPORT: 'false'.