الاستضافة الذاتية والتطبيقات الأدلة التقنية

HedgeDoc: محاضر Markdown يكتبها الفريق معاً على سيرفرك

نشغل HedgeDoc، ثم نكتب محضر اجتماع واحداً من متصفحين في اللحظة نفسها، ثم نقطع الشبكة عن أحدهما، ونختبر الإصدار الذي يحذر منه المشروع نفسه والرجوع منه.

HedgeDoc: محاضر Markdown يكتبها الفريق معاً على سيرفرك

اجتمع فريق نقاط البيع بعد حادثة تكرار الطلبات في تطبيق الكاشير، وهي الحادثة التي كتبنا مراجعتها في صفحات الـ Wiki في مقالات هذه المرحلة. وفي الاجتماع ثلاثة أشخاص يريدون أن يكتبوا في الوقت نفسه: موظف الدعم يكتب ما قاله المطعم، ومهندس العمليات يكتب ما رآه في السجلات، وقائد التطوير يكتب القرار. والطريقة المعتادة أن يكتب شخص واحد المحضر ويشارك شاشته، والبقية يملون عليه، فيتأخر المحضر عن النقاش، ويضيع نصف ما قيل. والطريقة الثانية أن يفتح الجميع مستند Google Docs، وهذا يعمل جيداً، ولكنه يعيد المحضر إلى خدمة خارجية بعد أن نقل الفريق كل معرفته إلى سيرفره.

والأداة التي صممت لهذه اللحظة بالذات هي HedgeDoc: محرر Markdown في المتصفح، يفتح فيه عدة أشخاص الملاحظة نفسها، ويرى كل واحد مؤشر الآخر وما يكتبه حرفاً بحرف، مع معاينة مباشرة بجانب المحرر. وهو ليس Wiki، فلا توجد فيه مساحات ولا شجرة صفحات ولا بحث قوي، وإنما ملاحظات Notes لكل واحدة رابط. ولكن قبل أن نثبته يجب أن نتحدث عن توقيت كتابة هذا المقال، ففي 4 نوفمبر 2026، أي قبل يوم واحد، أصدر المشروع إصدارين خلال ساعتين، سحب الأول منهما، وكتب في أول سطر من الثاني «لا تحدث إلى هذا الإصدار». لذلك فهذا المقال عن الكتابة المشتركة، وعن كيف تقرر أي إصدار تثبت عندما تكون صفحة الإصدارات نفسها في حالة طوارئ.

وسوف نناقش في هذا المقال ما يلي:

  • لماذا تحتاج إلى محرر مشترك بجانب الـ Wiki، ومن أين جاء HedgeDoc.
  • أي إصدار تثبت اليوم، وما رأيناه عندما جربنا الإصدارات الثلاثة الأخيرة.
  • التثبيت بال Docker Compose، ومثال التوثيق الذي لا يعمل مع PostgreSQL 18، وإعدادات الأمان التي يجب أن تغيرها.
  • ماذا يحدث إذا لم تضبط النطاق CMD_DOMAIN، وصلاحيات الملاحظات.
  • متصفحان يكتبان في الملاحظة نفسها في اللحظة نفسها، وماذا يحدث خلف الشاشة، وماذا يحدث إذا انقطعت الشبكة عن أحدهما.
  • العربية، والتحديث والرجوع منه، والنسخ الاحتياطي، ومتى تكتب في HedgeDoc ومتى في الـ Wiki.

لماذا لا تكفي الـ Wiki للكتابة السريعة؟ Collaborative Editor

في Docmost وWiki.js وOutline كتابة مشتركة أيضاً، فلماذا أداة أخرى؟ والإجابة أن الـ Wiki مصممة للنتيجة، وليس للمسودة. فالصفحة فيها لها مكان في شجرة، ومالك، ووسوم، وتظهر في البحث، وكل هذا مفيد للصفحة التي سوف يقرؤها الناس بعد شهر، ولكنه عبء على محضر اجتماع يكتب في ساعة ونصفه خواطر لن تبقى. فإذا كتب الفريق المحاضر في الـ Wiki نفسها امتلأت المساحات بصفحات «اجتماع 3 نوفمبر» التي لا يراجعها أحد، وأصبحت نتائج البحث عن «تكرار الطلبات» عشرين محضراً قبل صفحة المراجعة نفسها، وهذا عكس ما شرحناه في مقال قاعدة معرفة الفريق عن الصفحة القديمة.

لذلك تفصل كثير من الفرق بين مكانين: محرر مشترك سريع للمسودات، يفتح برابط في المحادثة ولا يحتاج قراراً عن مكانه، والـ Wiki للنتيجة. وHedgeDoc مناسب للمكان الأول لثلاثة أسباب: كل ما فيه Markdown عادي، فالنقل إلى أي Wiki نسخ ولصق؛ والملاحظة تفتح في ثوان من زر New؛ والملاحظة نفسها يمكن أن تعرض كشرائح Slide Mode لورشة أو عرض قصير. وسوف نعود إلى هذا الفصل في آخر المقال بقاعدة عملية للفريق.

من HackMD إلى HedgeDoc: لماذا يهمك تاريخ المشروع؟ History

تاريخ المشروع هنا ليس معلومة جانبية، لأنه يفسر لماذا تجد على الإنترنت ثلاثة أسماء لأداة واحدة. فبحسب صفحة التاريخ في موقع المشروع، بدأ HackMD سنة 2015 وأطلق موقعه العام hackmd.io، ثم انقسم في أكتوبر 2017 إلى نسخة تجارية مغلقة يطورها فريق HackMD، ونسخة مجتمعية مفتوحة غير المجتمع ترخيصها إلى AGPLv3. وفي يونيو 2018 سميت النسخة المجتمعية CodiMD، ثم اختلف المجتمع مع فريق HackMD عندما اقترح استبدال كود المجتمع بإعادة كتابة تجارية بنموذج النواة المفتوحة Open Core وترخيص Apache 2.0، فأنشأ المجتمع نسخة منفصلة Fork في منظمته على GitHub. ولكي ينتهي الالتباس بين مستودعين باسم CodiMD اختار المجتمع في يوليو 2020 اسم HedgeDoc، وصدر الإصدار 1.7 بالاسم الجديد في ديسمبر 2020.

والدرس العملي من هذه القصة لمن يختار أداة مفتوحة المصدر: ترخيص HedgeDoc اليوم AGPL-3.0 لأن المجتمع تمسك به عندما عرض عليه غيره، ولا توجد نسخة مدفوعة تحجز ميزات، والفريق الذي يطوره متطوعون. وهذا يعني أن كل ما في المشروع لك، ويعني أيضاً أن الإصدارات تأتي بإيقاع المتطوعين، وأن HedgeDoc 2، وهو إعادة كتابة بلغة TypeScript بدأت سنة 2020، ما زال قيد التطوير، فالصفحة نفسها كانت تذكر سنة 2025 موعداً مبدئياً له، وآخر إصدار منشور اليوم ما زال من السلسلة 1.x. وإذا رأيت في دليل قديم اسم CodiMD أو صورة hackmdio/hackmd فهو الجد الأقدم لما نثبته هنا.

HedgeDoc أم Etherpad أم Google Docs؟ Alternatives

قبل أن تثبت أي محرر مشترك يجب أن ترى الخيارات الثلاثة التي تقابلها الفرق عادة، لأن كل واحد منها يناسب نوعاً من الكتابة. فالخيار الأول هو المستندات السحابية مثل Google Docs أو Microsoft 365، وهي أسهل ما يكون للموظف غير التقني، ونصها منسق Rich Text يطبع بشكل جميل، ولكنها خارج سيرفرك، والنقل منها إلى الـ Wiki يمر بالتصدير إلى Word أو HTML وما يجره ذلك من تنسيق يفسد في الطريق. والخيار الثاني هو Etherpad، وهو أقدم محرر مشترك مفتوح المصدر معروف، وأغلب من جربه يتذكر الألوان التي تميز نص كل كاتب، وفكرة الرابط الحر الذي ينشئ مستنداً بمجرد كتابته في المتصفح، وهي الفكرة التي يحملها في HedgeDoc الخيار CMD_ALLOW_FREEURL. ولكن نص Etherpad منسق بطريقته الخاصة وليس Markdown، ويقول دليل النقل من Etherpad في توثيق HedgeDoc إن النقل يأخذ النص فقط، وتضيع معه المراجعات وأسماء الكتاب والتنسيق وروابط المستندات القديمة.

والخيار الثالث هو HedgeDoc، والذي يميزه لفريق تقني أمران: أن الملاحظة Markdown من أول حرف، وهو الشكل نفسه الذي تقبله كل أدوات الـ Wiki في هذه المرحلة ومستودعات Git، فلا يوجد تحويل عند النقل؛ وأن المعاينة بجانب المحرر تعرض الجداول والكود والمخططات بال Mermaid كما سوف تظهر في الـ Wiki تقريباً. وعيبه في المقابل أن موظف المبيعات الذي لا يعرف Markdown سوف يحتاج إلى نصف ساعة ليتعلم # و- و**، وهذا ثمن معقول إذا كانت المحاضر تنتقل في النهاية إلى Wiki تكتب بالصيغة نفسها. وإذا كانت خصوصية المحتوى نفسه هي الأهم، بحيث لا يقرؤه حتى مدير السيرفر، فهذا مطلب آخر تماماً، تحققه أدوات بتشفير من طرف إلى طرف End-to-End Encryption، وليس HedgeDoc ولا أي أداة في هذه المرحلة.

أي إصدار تثبت اليوم؟ Release Notes

عندما بدأنا المختبر في 5 نوفمبر 2026 كانت صفحة الإصدارات على GitHub كما يلي: 1.12.0 الصادر في 21 أغسطس، ثم 1.12.1 في 4 نوفمبر ومعه إصلاحات لثغرات أمنية، منها انتحال هوية مستخدم عندما يعطي مزودا دخول المعرف نفسه، وتعطيل سيرفر الكتابة اللحظية بتحديد غير صالح، وحقن HTML في أسماء المستخدمين. ولكن في أول ملاحظاته الآن تنبيه بأن المشروع سحبه بسبب أخطاء مع PostgreSQL. ثم 1.12.2 بعده بساعتين، وأول سطر فيه بالأحرف الكبيرة: لا تحدث إلى هذا الإصدار لأنه قد يعطل نسختك. وفي صباح 5 نوفمبر كانت هناك بلاغات مفتوحة، منها فشل التحديث من 1.12.0 إلى 1.12.2 في تغيير الجداول الخاص بتفرد البريد، والتسجيل بالبريد في 1.12.2 يحفظ المستخدم دون بريد، و1.12.2 يعيد 403 للمستخدمين المسجلين على الملاحظات المحدودة.

فماذا تفعل؟ لا تقرر من العناوين، وإنما جرب. فجربنا الإصدارات بأنفسنا، والصورة التالية تلخص ما رأيناه، وسوف نشرح كل تجربة في قسمها:

ثلاثة إصدارات من HedgeDoc 1.12: الإصدار 1.12.0 في 21 أغسطس 2026 يتطلب Node 20.17 وأصلح أخطاء في الاتصال اللحظي وعمل كل شيء في المختبر، ثم 1.12.1 في 4 نوفمبر أصلح سبع ثغرات أمنية على الأقل وسحبه المشروع بسبب أخطاء مع PostgreSQL، ثم 1.12.2 في 4 نوفمبر وأول سطر فيه لا تحدث إلى هذا الإصدار، وفي المختبر أنشأ التسجيل بالبريد مستخدماً دون بريد، وبعد التحديث من 1.12.0 حصل مالك الملاحظة على 403، وتحتها ما فعلناه: نسخة pg_dump ثم الرجوع إلى 1.12.0 مع pg_restore والبقاء عليه خلف VPN حتى يصدر إصلاح مستقر
الإصدار الذي فيه الإصلاحات الأمنية مسحوب، والذي بعده يحذر منه المشروع نفسه

والقرار الذي وصلنا إليه لفريقنا: نثبت 1.12.0، لأنه الإصدار الأخير الذي لا يحذر منه المشروع وعمل كاملاً في المختبر، ولكننا نعرف أن فيه الثغرات التي أصلحها 1.12.1، لذلك لا نعرضه على الإنترنت، وإنما يصل إليه الموظفون عبر شبكة WireGuard الخاصة كما في صفحة «الدخول إلى السيرفرات عبر VPN» في الـ Wiki، ونعطل التسجيل المفتوح والدخول دون حساب، ونراقب صفحة الإصدارات حتى يصدر إصدار يصلح الثغرات دون أن يعطل البيانات. وهذا ما نسميه إدارة المخاطر وليس تجاهلها: الثغرة التي تحتاج حساباً أو وصولاً للشبكة أقل خطراً على سيرفر لا يصل إليه إلا الموظفون.

التثبيت مع Docker Compose Installation

مثال التوثيق لا يعمل مع PostgreSQL 18 Data Directory

أول ما فعلناه هو أن نسخنا ملف Compose من صفحة Docker في التوثيق كما هو، وفيه postgres:18.6-alpine وquay.io/hedgedoc/hedgedoc:1.12.2، وال Volume الخاص بقاعدة البيانات على المسار /var/lib/postgresql/data. وبعد docker compose up -d بقي HedgeDoc ينتظر، وظهر في سجله:

warn: Database cannot be reached. Try 1 of 30. (SequelizeHostNotReachableError: connect EHOSTUNREACH 172.18.0.2:5432)
warn: Database cannot be reached. Try 2 of 30. (SequelizeHostNotFoundError: getaddrinfo ENOTFOUND database)

وحالة قاعدة البيانات Restarting (1)، وفي سجلها السبب:

Error: in 18+, these Docker images are configured to store database data in a
       format which is compatible with "pg_ctlcluster" (specifically, using
       major-version-specific directory names).
       ...
       Counter to that, there appears to be PostgreSQL data in:
         /var/lib/postgresql/data (unused mount/volume)

والسبب أن Docker Image الخاصة ب PostgreSQL من الإصدار 18 غيرت مكان البيانات إلى مجلد باسم الإصدار تحت /var/lib/postgresql، كما في التغيير في مستودع الصورة، وإذا وجدت Volume على المسار القديم ترفض أن تبدأ، لكي لا تكتب البيانات في مكان وتترك ال Volume فارغاً. والرسالة نفسها تقترح الحل: Volume واحد على /var/lib/postgresql. فالمثال في التوثيق حدث رقم الإصدار إلى 18 ولم يحدث المسار. وهذه مشكلة سوف تراها في أي دليل قديم لأي تطبيق يستخدم PostgreSQL، فإذا رأيت قاعدة بيانات تعيد التشغيل في حلقة بعد تحديث الإصدار الرئيسي في ملف Compose، فاقرأ سجلها قبل أي شيء.

وبعد تصحيح المسار عمل المثال، فجربنا التسجيل بالبريد على 1.12.2، ثم الدخول بالحساب نفسه:

register 302 -> http://localhost:3000/
login 302 -> http://localhost:3000/
03c57504-76c3-48eb-992f-9293fe55b13f|NULL|
{"status":"forbidden"}

السطران الأولان ردود التسجيل والدخول، وكلاهما تحويل إلى الصفحة الرئيسية، ولكن السطر الثالث من جدول المستخدمين يبين أن الحساب حفظ وبريده NULL، والسطر الأخير هو رد /me بعد الدخول، أي أن الدخول لم ينجح. وهذا البلاغ نفسه الذي ذكرناه، فمن ينسخ المثال من التوثيق اليوم يحصل على نسخة لا يستطيع أحد أن يسجل فيها. ولاحظ أيضاً أن التحويل ذهب إلى localhost:3000 وليس إلى المنفذ الذي فتحناه، وسوف نشرح السبب في قسم النطاق.

ملف compose.yaml للفريق

وهذا الملف الذي اعتمدناه بعد التجارب، بالإصدار 1.12.0:

name: wr-kb-hd
services:
  database:
    image: postgres:18.6-alpine
    environment:
      POSTGRES_USER: hedgedoc
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: hedgedoc
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hedgedoc -d hedgedoc"]
      interval: 5s
      retries: 20
    volumes:
      - database:/var/lib/postgresql
    restart: unless-stopped

  app:
    image: quay.io/hedgedoc/hedgedoc:${HEDGEDOC_TAG}
    environment:
      CMD_DB_URL: postgres://hedgedoc:${DB_PASSWORD}@database:5432/hedgedoc
      CMD_DOMAIN: localhost
      CMD_PORT: "23300"
      CMD_URL_ADDPORT: "true"
      CMD_PROTOCOL_USESSL: "false"
      CMD_SESSION_SECRET: ${SESSION_SECRET}
      CMD_ALLOW_ANONYMOUS: "false"
      CMD_ALLOW_FREEURL: "false"
      CMD_ALLOW_EMAIL_REGISTER: "false"
      CMD_DEFAULT_PERMISSION: limited
    volumes:
      - uploads:/hedgedoc/public/uploads
    ports:
      - "127.0.0.1:23300:23300"
    depends_on:
      database:
        condition: service_healthy
    restart: unless-stopped

volumes:
  database:
  uploads:

وبجانبه ملف .env فيه HEDGEDOC_TAG=1.12.0 وكلمة مرور قاعدة البيانات وSESSION_SECRET مولدين بالأمر openssl rand -hex. وكل متغير هنا له سبب من صفحة الإعدادات:

  • CMD_SESSION_SECRET: المفتاح الذي توقع به ملفات تعريف الجلسة Session Cookies، وإذا لم تضعه يولد HedgeDoc مفتاحاً عشوائياً عند كل تشغيل، فيخرج كل المستخدمين عند كل إعادة تشغيل أو تحديث.
  • CMD_ALLOW_ANONYMOUS: قيمته الافتراضية true، أي أن أي شخص يصل إلى الموقع يستطيع أن ينشئ ملاحظة دون حساب، وهذا مناسب لموقع عام مثل hackmd.io وليس لفريق، فجعلناه false.
  • CMD_ALLOW_EMAIL_REGISTER: قيمته الافتراضية true، فأي زائر يسجل حساباً لنفسه، وجعلناه false لأن حسابات الفريق ننشئها نحن، كما في القسم التالي.
  • CMD_ALLOW_FREEURL: إذا فعلته ينشئ HedgeDoc ملاحظة جديدة لأي رابط غير موجود، مثل /meeting-notes، كما في Etherpad، وتركناه معطلاً لكي لا تنشأ ملاحظات من روابط مكتوبة بخطأ.
  • CMD_DEFAULT_PERMISSION: صلاحية الملاحظة الجديدة، وlimited تعني أن كل مسجل يقرأ ويكتب ولا يقرأ الزائر شيئاً، وسوف نشرح المستويات الستة بعد قليل.
  • uploads: الصور التي يلصقها المستخدمون في الملاحظات تحفظ هنا وليس في قاعدة البيانات، فهذا ال Volume جزء من النسخة الاحتياطية.

ومع هذا الملف بدأ HedgeDoc في ثوان، وظهر في سجله السطران All migrations performed successfully وHTTP Server listening at 0.0.0.0:23300. وحجم Docker Image الخاصة به 884 ميجابايت على القرص، واستهلاكه بعد التجارب 219 ميجابايت للتطبيق و44 لقاعدة البيانات.

إنشاء الحسابات من سطر الأوامر manage_users

بعد تعطيل التسجيل تنشئ الحسابات بالسكربت bin/manage_users الذي تذكره صفحة الإعدادات، مع NODE_ENV=production لكي يقرأ الإعدادات الصحيحة:

for u in support ops; do
  docker compose exec -T app sh -c "NODE_ENV=production bin/manage_users --add [email protected] --pass '…'"
done
Created user with email [email protected]
Created user with email [email protected]

وهذا يناسب فريقاً صغيراً، أما إذا كان عندك authentik فصفحة الإعدادات فيها أقسام لدخول OAuth2 وSAML وLDAP، وكلها في النسخة نفسها، وعندها تعطل الدخول بالبريد كله ب CMD_EMAIL=false، وفي 1.12.0 إذا لم تبق إلا طريقة دخول خارجية واحدة يتخطى HedgeDoc نافذة الدخول ويحول المستخدم إليها مباشرة.

ماذا لو لم تضبط CMD_DOMAIN؟ What If

HedgeDoc يبني من CMD_DOMAIN وCMD_PORT وCMD_URL_ADDPORT وCMD_PROTOCOL_USESSL العنوان الكامل الذي يكتبه في الصفحات وفي التحويلات وفي اتصال الكتابة اللحظية. لذلك رأينا في مثال التوثيق تحويلاً إلى localhost:3000، لأن HedgeDoc يعمل داخل ال Container على المنفذ 3000، ومع CMD_URL_ADDPORT=true يضيف هذا المنفذ للعنوان، بينما فتحناه نحن على منفذ آخر. والحل في ملفنا أن يعمل HedgeDoc داخل ال Container على المنفذ نفسه الذي يصل إليه المتصفح، أي 23300 في الطرفين. وعلى سيرفر حقيقي خلف Reverse Proxy بشهادة TLS تكون القيم CMD_DOMAIN=notes.example.com وCMD_PROTOCOL_USESSL=true وCMD_URL_ADDPORT=false.

ثم سألنا: ماذا لو حذفنا CMD_DOMAIN كله، على أمل أن يستخدم HedgeDoc عنواناً نسبياً يعمل من أي مكان؟ فحذفناه مع CMD_URL_ADDPORT وأعدنا إنشاء ال Container، فظهر في السجل:

warn: Neither 'domain' nor 'CMD_DOMAIN' is configured. This can cause issues with various components.

والصفحة الرئيسية فتحت، والدخول نجح، ولكن عندما فتحنا الملاحظة بقيت الصفحة على شعار التحميل، ولم يظهر المحرر أبداً، وفي الشريط العلوي الحالة OFFLINE:

صفحة ملاحظة في HedgeDoc دون إعداد CMD_DOMAIN، وفيها شعار القنفذ وكلمة HedgeDoc كبيرة على شاشة التحميل ولا يظهر المحرر
دون CMD_DOMAIN تبقى الملاحظة على شاشة التحميل

فالتحذير في السجل ليس تحذيراً، وإنما هو خطأ سوف تراه في أول ملاحظة. وأعدنا CMD_DOMAIN فعاد كل شيء. والقاعدة: إذا فتحت ملاحظة في HedgeDoc ورأيت OFFLINE أو بقيت على شاشة التحميل، فقارن العنوان في المتصفح حرفاً بحرف مع ما تعطيه المتغيرات الأربعة، ثم تأكد أن ال Reverse Proxy يمرر WebSocket كما في تطبيقك خلف Reverse Proxy.

خلف الـ Reverse Proxy بشهادة TLS

على سيرفر حقيقي لا يصل المتصفح إلى HedgeDoc مباشرة، وإنما عبر Reverse Proxy يحمل الشهادة، ويشرح دليل ال Reverse Proxy في التوثيق الإعدادات التي تتغير عندها. فالقيمة CMD_DOMAIN تصبح النطاق الكامل مثل notes.example.com، وCMD_PROTOCOL_USESSL=true لأن الزائر يصل عبر HTTPS حتى لو كان الاتصال بين ال Reverse Proxy وHedgeDoc عادياً، وCMD_URL_ADDPORT=false لأن الزائر لا يكتب أي منفذ، وCMD_HOST عنوان لا يصل إليه إلا ال Reverse Proxy، مثل 127.0.0.1 إذا كان على السيرفر نفسه. والسبب أن HedgeDoc يبني من هذه القيم روابط الملفات الثابتة مثل الخطوط والأنماط، وعنوان اتصال الكتابة اللحظية، فأي اختلاف بينها وبين ما في شريط العنوان يعيدك إلى شاشة التحميل التي رأيناها عندما حذفنا النطاق. والدليل نفسه يحذر من أمر خاص بمن يستخدم Cloudflare أمام سيرفره: يجب أن تعطل خاصية Rocket Loader، وإلا تعطلت النسخة، لأنها تغير طريقة تحميل ملفات JavaScript في الصفحة. وأما WebSocket فيحتاج إلى ترويستي Upgrade وConnection كما في أي تطبيق كتابة مشتركة في هذه المرحلة.

صلاحيات الملاحظة Note Permissions

لا توجد في HedgeDoc 1.x مساحات ولا مجموعات، وإنما مالك لكل ملاحظة، ومستخدمون مسجلون، وزوار، وستة مستويات صلاحية يختارها المالك وحده بحسب صفحة الصلاحيات:

جدول صلاحيات الملاحظة في HedgeDoc: Freely يقرأ ويكتب فيه الجميع، وEditable يكتب فيه المسجلون ويقرأ الزوار، وLimited وهو ما اخترناه يقرأ ويكتب فيه المسجلون ولا يرى الزوار شيئاً، وLocked يكتب فيه المالك فقط ويقرأ الجميع، وProtected يكتب فيه المالك ويقرأ المسجلون فقط، وPrivate للمالك وحده، وتحته أن CMD_ALLOW_ANONYMOUS=false يخفي Freely ويحول الزائر إلى الدخول وأن قيمته الافتراضية true
Limited للفريق: كل مسجل يكتب، والزائر لا يرى شيئاً

والصورة التالية من القائمة نفسها في الملاحظة، ولاحظ أن Freely غير موجودة لأننا عطلنا الدخول دون حساب:

قائمة الصلاحيات في ملاحظة HedgeDoc مفتوحة من زر Limited، وفيها Editable وLimited وLocked وProtected وPrivate مع شرح كل واحدة، ثم Delete this note، وخلفها ملاحظة الاجتماع بالعربية من اليمين إلى اليسار
المالك وحده يغير الصلاحية من الزر في أعلى المعاينة

وفي المختبر طلبنا ملاحظة الاجتماع دون جلسة فرجع الرمز 302، أي تحويل إلى الدخول. والنقطة التي يجب أن يعرفها الفريق أن الرابط نفسه هو طريقة المشاركة، فرابط الملاحظة فيه معرف عشوائي طويل مثل /522BYIRfQP-HJN2tLLNhOg، ومن يملك الرابط ويملك حساباً يستطيع أن يكتب في ملاحظة Limited. فإذا كان المحضر فيه ما لا يجب أن يراه كل الموظفين، فاجعله Private أو Protected، ولا تعتمد على أن الرابط صعب التخمين.

متصفحان على الملاحظة نفسها Realtime Collaboration

الآن التجربة الأساسية. فتحنا متصفحي Chrome منفصلين، لكل واحد ملف تعريف مستقل وجلسة مستقلة: الأول بحساب الدعم، والثاني بحساب العمليات. وأنشأ الأول ملاحظة جديدة من /new وكتب فيها قالب المحضر:

---
title: اجتماع مراجعة حادثة تكرار الطلبات
dir: rtl
tags: اجتماع, حادثة
---

# اجتماع مراجعة حادثة تكرار الطلبات

**الحضور:** الدعم، العمليات، التطوير

## ما حدث
- ظهر كل طلب مرتين في تقرير المطبخ عند ثلاثة مطاعم.

## القرارات
-

## المهام
- [ ] 

ثم فتح الثاني الرابط نفسه بالوضع ?both، أي المحرر والمعاينة جنباً إلى جنب، لأن الملاحظة التي يفتحها شخص آخر تفتح افتراضياً في وضع القراءة، وهذا ما حدث في محاولتنا الأولى قبل أن نضيف ?both. ووضعنا مؤشر المتصفح الأول في سطر القرارات، ومؤشر الثاني في سطر المهام، ثم كتب كل منهما جملة، كلمة من الأول ثم كلمة من الثاني بالتناوب، لكي تتقاطع التعديلات على السيرفر بدلاً من أن تصل واحدة بعد الأخرى. وبعد ثلاث ثوان قارن السكربت نص المحرر في المتصفحين:

same text in both browsers: true
- ظهر كل طلب مرتين في تقرير المطبخ عند ثلاثة مطاعم.
- نضيف مفتاحاً فريداً لكل طلب Idempotency Key في خدمة الطلبات
- [ ] العمليات: تنبيه إذا تكرر رقم الطلب أكثر من مرة خلال دقيقة

النص في المتصفحين متطابق حرفاً بحرف، والأسطر الثلاثة الأخيرة من الملف الذي أعاده /download، أي من السيرفر نفسه وليس من المتصفح: الجملتان كاملتان، كل واحدة في سطرها، دون أن تتداخل كلماتهما. والصورتان التاليتان من المتصفحين في اللحظة نفسها:

المتصفح الأول بحساب الدعم في HedgeDoc، المحرر على اليسار بخلفية داكنة وفيه الملاحظة بصيغة Markdown، والمعاينة على اليمين من اليمين إلى اليسار وفيها العنوان والحضور وما حدث والقرار والمهمة، وفي الأعلى 2 ONLINE
المتصفح الأول: 2 ONLINE، والسطران في مكانيهما
المتصفح الثاني بحساب العمليات في HedgeDoc، والمحرر فيه سطر المهمة في السطر 18 والقرار في السطر 15، والمعاينة فيها مربع المهمة على الجهة اليسرى بعيداً عن نصها العربي
المتصفح الثاني: النص نفسه، والمؤشر في سطر المهمة

ماذا يحدث خلف الشاشة؟ Operational Transformation

رأينا في مقال Docmost أنه يستخدم Yjs، وهو من نوع CRDT، أما HedgeDoc فيستخدم طريقة أقدم اسمها التحويل التشغيلي Operational Transformation، واختصاراً OT، ويقول توثيق المطورين إنه يستخدم نسخة من مكتبة ot.js منذ الإصدار 0.3.2، وهي الطريقة نفسها التي شرحتها Google في 2010 عندما أعادت بناء Google Docs، وتشرحها صفحة مشروع OT. والصورة التالية تبين الفكرة بالتعديلين من المختبر:

رسم التحويل التشغيلي في HedgeDoc: المتصفح A للدعم يكتب في السطر 15 بعد الحرف 2 بعملية retain ثم insert، والمتصفح B للعمليات يكتب في السطر 18 بعد الحرف 6 في اللحظة نفسها، وسيرفر HedgeDoc يعطي كل ملاحظة رقم نسخة Revision ويطبق العملية التي وصلت أولاً ويحول الثانية بزيادة موضعها بطول النص الذي أضيف قبلها، ثم يحفظ في PostgreSQL ويرسل إلى المتصفحات عبر WebSocket، والنتيجة النص نفسه في المتصفحين، وإذا انقطع الاتصال يتحول المحرر إلى القراءة فقط
كل متصفح يرسل العملية، والسيرفر يحول الثانية لكي تنطبق على النسخة الجديدة

فكل تعديل لا يرسل كملف، وإنما كعملية Operation صغيرة: تجاوز هذا العدد من الحروف Retain، ثم أدخل هذا النص Insert، أو احذف هذا العدد Delete. والمتصفح الثاني بنى عمليته على نسخة الملاحظة قبل أن تصله جملة الأول، فلو طبقها السيرفر كما هي لدخلت الجملة في موضع خاطئ، لأن جملة الأول التي دخلت قبلها زادت طول النص. لذلك يحول السيرفر العملية الثانية Transform قبل تطبيقها، فيزيد موضعها بطول ما أضيف قبلها، ثم يرسلها إلى المتصفح الأول، ويرسل إلى الثاني تأكيداً. والفرق العملي بين OT وCRDT أن OT يحتاج سيرفراً مركزياً يرتب العمليات، بينما CRDT يسمح لكل نسخة أن تدمج التعديلات وحدها، ولذلك يسهل في CRDT أن يكتب شخص دون اتصال ثم يدمج لاحقاً، وهذا ما سوف نختبره الآن في HedgeDoc.

ماذا لو انقطعت الشبكة عن أحدهما؟ Offline

في المحاولة الأولى استخدمنا خيار قطع الشبكة في أدوات المطور في Chrome، وهو الخيار نفسه الذي يجربه أغلب الناس، ثم كتبنا سطراً في المتصفح الأول. ولكن السطر وصل إلى المتصفح الثاني فوراً، وبقيت الحالة 2 ONLINE، والسبب أن محاكاة الانقطاع في Chrome تمنع الطلبات الجديدة ولا تغلق اتصال WebSocket المفتوح. وهذا درس في الاختبار قبل أن يكون درساً في HedgeDoc: إذا اختبرت تطبيقاً يعمل باتصال دائم بهذه الطريقة فأنت لم تختبر الانقطاع، ولذلك بقي هذا السطر في الملاحظة كما ترى في الصور.

وفي المحاولة الثانية قطعنا الاتصال فعلاً: أغلقنا كل WebSocket في المتصفح الأول، وأوقفنا كل طلب جديد إلى /socket.io دون أن يرد، وتركنا الثاني متصلاً. ثم حاول الأول أن يكتب سطراً في آخر الملاحظة، وكتب الثاني «ثم المبيعات» في سطر الحضور، وبعد ذلك أعدنا الاتصال للأول وانتظرنا تسع ثوان:

A readOnly: true
A local has offline line: false
after reconnect same: true | A has offline line: false | B has offline line: false | A has B edit: true
المتصفح الأول في HedgeDoc بعد قطع الاتصال، وفي الأعلى زر أحمر OFFLINE بدلاً من عدد المتصلين، والمحرر ما زال ظاهراً ولكنه لا يقبل الكتابة
عند الانقطاع يظهر OFFLINE ويتحول المحرر إلى القراءة فقط

ولنقرأ النتيجة سطراً سطراً: عند الانقطاع ظهر الزر الأحمر OFFLINE، وأصبح المحرر للقراءة فقط readOnly: true، فلم يدخل السطر الذي حاول الأول كتابته أصلاً. وعند عودة الاتصال أخذ الأول تعديل الثاني، وأصبح النص في المتصفحين واحداً. أي أن HedgeDoc 1.12.0 لا يسمح بالكتابة دون اتصال، وهذا قرار تصميم يتسق مع OT: فالعمليات التي لا يعرف عنها السيرفر لا يمكن تحويلها بأمان بعد وقت طويل، فالأسلم ألا تقبلها أصلاً. وملاحظات الإصدار 1.12.0 تذكر إصلاح أخطاء في الاتصال اللحظي كانت تفقد بيانات من اتصاله متقطع، و1.12.1 يضيف تنبيه المستخدم فوراً بعد عودة الاتصال إذا كان سيفقد شيئاً، فهذه المنطقة بالذات هي التي يعمل عليها المشروع. وما يعنيه هذا للفريق: في اجتماع على شبكة ضعيفة، الشخص الذي ينقطع اتصاله يرى OFFLINE ولا يخسر شيئاً كتبه، ولكنه لا يستطيع أن يكتب حتى يعود، فلا تجعله الكاتب الوحيد للمحضر.

النشر والعرض بالشرائح Publish Mode

للملاحظة الواحدة في HedgeDoc ثلاثة روابط بحسب صفحة الروابط في التوثيق، ومعرفتها تمنع خطأ شائعاً في مشاركة المحاضر. فالرابط الطويل العشوائي مثل /522BYIRfQP-HJN2tLLNhOg هو رابط المحرر، والتعديلات تظهر فيه لحظة كتابتها، وتختار معه وضع العرض: ?edit للمحرر وحده، و?view للمعاينة وحدها، و?both للاثنين. أما زر Publish فيعطي رابطاً قصيراً بالبادئة /s/، وهو نسخة للقراءة فقط لا تتحدث إلا عند إعادة تحميل الصفحة، والبادئة /p/ بالمعرف القصير نفسه تعرض الملاحظة كشرائح Slide Mode، حيث تفصل بين الشرائح بسطر فيه ثلاث شرطات.

والخطأ الشائع أن يرسل شخص رابط المحرر إلى من يحتاج أن يقرأ فقط، مثل مدير يريد أن يرى ما اتفق عليه، فيفتحه ويضيف تعديلاً دون قصد في محضر لم يحضر اجتماعه، أو يرسل الرابط إلى قناة كبيرة فيكتب فيه كل من يمر. لذلك اتفق مع الفريق على أن رابط المحرر للحاضرين فقط، وأن رابط /s/ هو ما يرسل لغيرهم، وتذكر أن صلاحية الملاحظة تبقى سارية على الرابطين، فملاحظة Limited لا يقرؤها الزائر حتى من رابط النشر. وفي ورشة داخلية يمكن أن يكتب المقدم الشرائح في ملاحظة يراجعها زملاؤه معه في اللحظة نفسها، ثم يعرضها من رابط /p/ دون أن ينقلها إلى برنامج عروض، وهذا من الاستخدامات التي لا تقدمها أدوات الـ Wiki.

العربية في HedgeDoc: الخيار dir مع المحرر LTR

في ترويسة الملاحظة أعلاه السطر dir: rtl، وهو من خيارات بيانات YAML في الملاحظة، ويجعل المعاينة والملاحظة المنشورة من اليمين إلى اليسار، والقيمة الافتراضية دونه من اليسار إلى اليمين. والنتيجة في المعاينة جيدة كما رأيت في الصور: العناوين والفقرات والقوائم في مكانها. ولكن هناك أمرين يجب أن يعرفهما الفريق قبل أول اجتماع:

  • المحرر نفسه من اليسار إلى اليمين: فالسطر # اجتماع مراجعة… يظهر في المحرر وعلامة # في آخره من الجهة اليمنى، والشرطة في بداية عنصر القائمة على اليسار بعيداً عن النص، لأن المحرر CodeMirror يعامل كل سطر كنص من اليسار إلى اليمين. والكتابة تعمل، ولكن العين تحتاج أياماً لتتعود، والحل العملي أن يعمل الفريق بالوضع both وينظر إلى المعاينة.
  • مربعات المهام على اليسار: في قائمة المهام - [ ] ظهر المربع في الجهة اليسرى من المعاينة بعيداً عن نص المهمة العربي، كما في صورة المتصفح الثاني، فإذا كانت المهام كثيرة فاكتب اسم المسؤول في أول السطر لكي يقرأ السطر دون الرجوع إلى المربع.

والواجهة نفسها، أي القوائم والأزرار، بالإنجليزية، والاتجاه يتغير للمحتوى وحده. وإذا نسي أحد السطر dir: rtl في ملاحظة جديدة فالمعاينة تأتي من اليسار، لذلك ضع القالب في ملاحظة ثابتة ينسخ منها الفريق، أو اجعله ملفاً في الـ Wiki.

قالب غرفة الحادثة Incident Notes

أكثر لحظة يحتاج فيها الفريق إلى كتابة مشتركة هي الحادثة نفسها، عندما يعمل ثلاثة أشخاص على العطل في وقت واحد، ويسأل المدير في المحادثة كل عشر دقائق «ما الوضع؟». والفكرة أن تكون هناك ملاحظة واحدة يكتب فيها الجميع ما يعرفونه الآن، فيقرأ المدير الملاحظة بدلاً من أن يقطع العاملين، وفي آخر الحادثة تكون مادة المراجعة جاهزة بأوقاتها. وهذا القالب الذي وضعه فريقنا في ملاحظة ثابتة ينسخ منها المناوب:

---
title: حادثة [التاريخ] [وصف قصير]
dir: rtl
tags: حادثة
---

# حادثة: [وصف قصير بكلمات العميل]

**الحالة:** جارية · **قائد الحادثة:** [الاسم] · **التواصل مع العملاء:** [الاسم]

## ما نعرفه الآن
- 

## الخط الزمني بتوقيت السعودية
- 10:32 التنبيه الأول: ...

## من يفعل ماذا
- [ ] [الاسم]: ...

## ما جربناه ولم ينجح
- 

في القالب أعلاه لاحظ التالي: قسم «ما نعرفه الآن» يكتب في أعلى الملاحظة لأنه ما يقرؤه من يدخل متأخراً، ويعدل باستمرار ولا يتراكم، أما الخط الزمني فيتراكم ولا يعدل، لأنه سوف يصبح خط المراجعة الزمني كما هو. وقسم «ما جربناه ولم ينجح» هو الذي يوفر أكثر وقت، لأنه يمنع الشخص الثالث من أن يعيد تجربة فشلت قبل نصف ساعة. والصلاحية لهذه الملاحظة Limited أو Protected، ولا ترسل رابطها إلى القنوات العامة. وبعد الحادثة يكتب قائدها صفحة المراجعة في الـ Wiki كما في دليل التشغيل Runbook ومقال إدارة الحوادث، ويضع رابط الملاحظة في آخرها.

تجربة التحديث إلى 1.12.2 ثم الرجوع منه Rollback

بعد أن عمل كل شيء على 1.12.0 جربنا ما سوف يفعله كل من يقرأ إعلان الثغرات الأمنية ويريد أن يحدث: أخذنا نسخة من قاعدة البيانات، ثم غيرنا الوسم إلى 1.12.2:

docker compose exec -T database pg_dump -U hedgedoc -d hedgedoc -Fc > backup/hedgedoc-1.12.0.dump
sed -i 's/HEDGEDOC_TAG=1.12.0/HEDGEDOC_TAG=1.12.2/' .env
docker compose up -d

والسجل قال All migrations performed successfully، أي أن تغيير الجداول الذي فشل عند صاحب البلاغ 6940 نجح عندنا، والسبب المرجح أن بريد كل مستخدم عندنا مختلف، بينما كان عنده مستخدمان والتغيير يضيف شرط تفرد على البريد. ثم دخلنا بالحسابين وطلبنا تنزيل ملاحظة الاجتماع:

support me: {"status":"ok","id":"ecb70752-…","name":"support",…}
support note download: 403
ops me: {"status":"ok","id":"c67cb3b2-…","name":"ops",…}
ops note download: 403

الدخول نجح للاثنين، ولكن الملاحظة رفضت ب 403 حتى لموظف الدعم وهو مالكها، وهذا البلاغ 6946 نفسه. فرجعنا: أعدنا الوسم إلى 1.12.0، واستعدنا النسخة فوق قاعدة البيانات التي غيرها 1.12.2، ثم شغلنا HedgeDoc:

docker compose stop app
docker compose exec -T database pg_restore -U hedgedoc -d hedgedoc --clean --if-exists --no-owner --single-transaction < backup/hedgedoc-1.12.0.dump
docker compose up -d app
support note download: 200
ops note download: 200
guest: 302
20260622225700-remove-temp.js

عادت الملاحظة ب 200 للاثنين، والزائر يحول إلى الدخول، والسطر الأخير آخر تغيير مسجل في جدول SequelizeMeta، وهو آخر تغيير في 1.12.0، أي أن تغييرات 1.12.2 على الجداول لم تعد موجودة. ولاحظ أن الرجوع لم يكن ممكناً بتغيير الوسم وحده، لأن 1.12.2 غير الجداول، والإصدار الأقدم لا يعرف كيف يتراجع عنها، فالنسخة التي أخذناها قبل التحديث هي التي جعلت الرجوع ممكناً في دقيقة. وهذه القاعدة تنطبق على كل أداة في هذه المرحلة: نسخة قبل كل تحديث، ووسم ثابت، واختبار للتحديث على نسخة من البيانات قبل السيرفر الحقيقي.

كيف تقرر التحديث في المرة القادمة؟ Release Triage

ما حدث مع HedgeDoc في هذا الأسبوع ليس حالة نادرة، وإنما يحدث لأي مشروع يصدر إصلاحاً أمنياً عاجلاً، ولذلك يستحق أن يكون للفريق إجراء مكتوب في الـ Wiki يتبعه مع كل إصدار جديد لأي أداة، بدلاً من أن يقرر في كل مرة من جديد. وهذا الإجراء الذي كتبناه بعد هذه التجربة:

  1. اقرأ ملاحظات الإصدار كاملة: وأول ما تبحث عنه كلمات مثل Security وBreaking وMigration، ثم التنبيهات في أعلى الصفحة، فقد أضيف تنبيه السحب إلى 1.12.1 بعد نشره بساعات.
  2. صنف الثغرات بحسب وضعك: الثغرة التي تحتاج حساباً على النسخة أو مزودي دخول متعددين أقل خطراً على نسخة لا يصل إليها إلا الموظفون عبر VPN، أما الثغرة التي يستغلها زائر من الإنترنت فتعني أن تحدث اليوم أو أن تغلق الوصول اليوم.
  3. انتظر يومين إذا استطعت: فالبلاغات 6940 و6943 و6946 ظهرت كلها خلال أقل من يوم من الإصدار، ومن يحدث في الساعة الأولى يكتشفها بنفسه على بيانات فريقه.
  4. جرب على نسخة من البيانات: شغل الإصدار الجديد على نسخة من قاعدة البيانات في Container منفصل، وجرب الدخول وفتح ملاحظة لكل مستوى صلاحية، فهذا ما كشف لنا 403 في دقائق.
  5. خذ نسخة قبل التحديث الحقيقي ودون أمر الرجوع: اكتب أوامر الرجوع قبل أن تحتاجها، كما فعلنا بالأمر pg_restore --clean، لأن الرجوع بالوسم وحده لا يعمل بعد تغيير الجداول.

وهذا الإجراء نفسه مثال على ما شرحناه في مقال قاعدة المعرفة: معرفة جاءت من تجربة مؤلمة، مكانها صفحة لها مالك، وليس ذاكرة الشخص الذي عاشها.

النسخ الاحتياطي Backup

صفحة Docker في التوثيق تذكر pg_dump للنسخ والاستعادة قبل أول تشغيل للتطبيق، ونضيف إليها ثلاثة أشياء من التجربة: النسخة بالصيغة المخصصة -Fc لكي تستعاد ب pg_restore --clean فوق قاعدة موجودة كما فعلنا في الرجوع، وكان حجمها 16,010 بايت لملاحظتين وثلاثة مستخدمين؛ وال Volume الخاص بالصور uploads لأن الصور لا تحفظ في قاعدة البيانات؛ والقيمة CMD_SESSION_SECRET في ملف .env، وإلا خرج كل المستخدمين بعد الاستعادة. ثم انقل الملفات خارج السيرفر كما في قاعدة 3-2-1. ولكن تذكر أن HedgeDoc مكان للمسودات، فالمعرفة المهمة يجب أن تكون انتقلت إلى الـ Wiki قبل أن تحتاج إلى استعادة.

متى نكتب في HedgeDoc، ومتى في الـ Wiki؟ Workflow

القاعدة التي اتفق عليها فريقنا بسيطة، والصورة التالية تلخصها:

رسم من ثلاث مراحل: HedgeDoc لمحضر الاجتماع وغرفة الحادثة ومسودة الإجراء والورشة بالشرائح برابط في المحادثة يعيش أياماً أو أسابيع، ثم نهاية الاجتماع حيث ينقل صاحب القرار الخلاصة بالقرار والمهام والروابط بالنسخ أو التنزيل، ثم صفحة الـ Wiki لسجل القرار ومراجعة الحادثة ودليل المهمة بعد اعتماده ولها مالك وتاريخ مراجعة ويجدها البحث
المسودة في HedgeDoc، والنتيجة في الـ Wiki
  • كل اجتماع له ملاحظة في HedgeDoc، ورابطها في دعوة الاجتماع وفي قناة الفريق، وكل الحاضرين يكتبون فيها.
  • في آخر الاجتماع خمس دقائق للقرارات والمهام، ومن يملك القرار ينقله إلى صفحة في الـ Wiki، مثل سجل القرار أو مراجعة الحادثة، ويضع رابط المحضر في آخرها كمرجع.
  • أثناء الحوادث تفتح ملاحظة واحدة باسم الحادثة، يكتب فيها من يعمل عليها ما يعرفه الآن ومن يفعل ماذا، كما شرحنا في إدارة الحوادث، ثم تصبح مادة مراجعة الحادثة.
  • لا تصبح ملاحظة HedgeDoc مرجعاً دائماً، فإذا وجدت نفسك ترسل الرابط نفسه للمرة الثانية، فمكانه الـ Wiki بحسب قاعدة المرة الثانية.

متى تختار HedgeDoc؟ نقاط القوة Strengths ثم نقاط الضعف

نقاط القوة:

  • كتابة مشتركة لحظية مثبتة بالتجربة: تعديلان متقاطعان من متصفحين وصلا كاملين، والنص متطابق في الطرفين.
  • Markdown عادي من أول حرف، فالنقل إلى أي Wiki أو مستودع نسخ ولصق، ومعاينة مباشرة، وعرض بالشرائح من الملاحظة نفسها.
  • خفيف: 219 ميجابايت للتطبيق و44 لقاعدة البيانات، ولا يحتاج إلى Redis.
  • كل شيء مجاني بترخيص AGPL-3.0، ومنه الدخول بال OAuth2 وSAML وLDAP.
  • عند الانقطاع يمنع الكتابة بدلاً من أن يخاطر بالدمج، فلا يفقد المستخدم نصاً ظن أنه حفظه.

نقاط الضعف:

  • الإصداران الأخيران في حالة طوارئ يوم كتابة المقال: الإصلاحات الأمنية في إصدار مسحوب، والإصدار بعده يحذر منه المشروع، ومثال Compose في التوثيق يستخدمه.
  • الإعدادات الافتراضية مفتوحة: الدخول دون حساب والتسجيل الحر مفعلان، ودون CMD_DOMAIN لا يعمل المحرر.
  • المحرر من اليسار إلى اليمين مع النص العربي، ومربعات المهام على اليسار، والواجهة بالإنجليزية.
  • لا توجد مساحات ولا مجموعات ولا بحث جيد، فهو ليس Wiki ولا يجب أن يستخدم كواحدة.
  • HedgeDoc 2 قيد التطوير منذ سنوات، والسلسلة 1.x تحصل على الإصلاحات ولكن على ميزات قليلة، والفريق الذي يطوره متطوعون، فالإصلاح يأتي بإيقاعهم وليس بإيقاع حاجتك.

قائمة تحقق Checklist قبل أول اجتماع

البندكيف تتحقق منه
الإصدار مختار بعد قراءة ملاحظاتهصفحة الإصدارات والبلاغات المفتوحة في يوم التثبيت
ال Volume الخاص ب PostgreSQL 18 على /var/lib/postgresqlقاعدة البيانات ليست في حالة Restarting
CMD_DOMAIN والمنفذ والبروتوكول تطابق العنوان في المتصفحالملاحظة تفتح دون OFFLINE ودون شاشة تحميل دائمة
CMD_SESSION_SECRET ثابتإعادة تشغيل ال Container لا تخرج المستخدمين
الدخول دون حساب والتسجيل الحر معطلانطلب ملاحظة دون جلسة يعيد 302
الصلاحية الافتراضية limitedملاحظة جديدة تظهر عليها Limited
قالب المحضر فيه dir: rtlالمعاينة من اليمين إلى اليسار
WebSocket يعمل خلف ال Reverse Proxyمتصفحان يريان 2 ONLINE وتعديلات بعضهما
نسخة قبل كل تحديثpg_dump -Fc وال Volume الخاص بالصور، واستعادة مجربة

تدريب عملي Practice

  • افتح ملاحظة من متصفحين، واكتبا في السطر نفسه في اللحظة نفسها، ولاحظ أين انتهى كل نص، ثم افتح تاريخ الملاحظة من القائمة Revision.
  • غير CMD_DEFAULT_PERMISSION إلى private، وأنشئ ملاحظة بحساب، ثم افتح رابطها بحساب آخر وسجل الرد.

حذف المختبر Cleanup

docker compose down -v
docker rmi quay.io/hedgedoc/hedgedoc:1.12.0 quay.io/hedgedoc/hedgedoc:1.12.2

هذا المقال جزء من مرحلة التوثيق والمعرفة، وقبله مقالات قاعدة معرفة الفريق وDocmost وWiki.js، وبعده المقارنة بين أدوات الـ Wiki. وهذه المقالات المنشورة المرتبطة به:

دليلOutline: قاعدة معرفة فريقك على سيرفرككيف تشغل Outline على سيرفرك ليكتب فيه فريقك إجراءاته وقراراته، ويدخل إليه الموظفون بحساباتهم في authentik.دليلBookStack: توثيق فريقك في كتب وفصول على سيرفرككيف تشغل BookStack على سيرفرك وتنظم توثيق فريقك في أرفف وكتب وفصول، مع صلاحيات ودخول موحد وبحث بالعربية.دليلإدارة الحوادث Incident Response: من التنبيه إلى عودة الخدمةنعيش حادثة حقيقية على PostgreSQL من التنبيه إلى الإغلاق بخط زمني مسجل بالثواني، ونرى لماذا لم تنفع إعادة التشغيل وما الذي أنهى الحادثة.دليلكيف يرى تطبيقك عنوان الزائر الحقيقي خلف ال Reverse Proxyإذا كان تطبيقك يرى عنوان ال Proxy بدلاً من الزائر أو يولد روابط http، فهذا هو السبب والإعداد الصحيح لإطار عملك.دليلالنسخ الاحتياطي بقاعدة 3-2-1 واختبار الاستعادةكيف تحدد كم بيانات تقبل أن تخسر، وتبني نسخاً لا يستطيع المخترق حذفها، وتتأكد أنك تستطيع استعادتها فعلاً.

الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • HedgeDoc محرر Markdown مشترك للمسودات والمحاضر، وليس Wiki، وترخيصه AGPL-3.0 بعد قصة طويلة من HackMD إلى CodiMD.
  • يوم كتابة المقال كان 1.12.1 مسحوباً و1.12.2 محذراً منه، وفي المختبر سجل 1.12.2 مستخدماً دون بريد ورفض ملاحظة مالكها ب 403، فاخترنا 1.12.0 خلف VPN مع مراقبة الإصدارات.
  • مثال التوثيق يحتاج تصحيح مسار ال Volume إلى /var/lib/postgresql مع PostgreSQL 18، ودون CMD_DOMAIN لا يظهر المحرر.
  • عطل الدخول دون حساب والتسجيل الحر، وثبت CMD_SESSION_SECRET، واجعل الصلاحية الافتراضية limited.
  • تعديلان متقاطعان من متصفحين وصلا كاملين بالتحويل التشغيلي OT، وعند الانقطاع الحقيقي يصبح المحرر للقراءة فقط ثم يأخذ تعديلات الآخرين عند العودة، ومحاكاة الانقطاع في أدوات Chrome لا تختبر WebSocket.
  • dir: rtl يصلح المعاينة، والمحرر يبقى من اليسار إلى اليمين، والمسودة تنتقل إلى الـ Wiki في آخر الاجتماع.

وفي المقال القادم بإذن الله نجمع أدوات الـ Wiki الأربع، Outline وBookStack وWiki.js وDocmost، على الصفحات نفسها، ونقيس البحث بالعربية والذاكرة ووقت الإعداد والصلاحيات والتصدير.

سجل التحديثات Changelog

  • نوفمبر 2026: كتابة الدليل واختباره على HedgeDoc 1.12.0 من quay.io/hedgedoc/hedgedoc:1.12.0 وتجربة 1.12.2 والرجوع منه، مع postgres:18.6-alpine على Docker Engine 29.8.0، وحالة الإصدارات والبلاغات كما كانت في 5 نوفمبر 2026.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.