SSD Nodes Learn Hosting plans →
الأدلة Matt Connorبقلم Matt Connor

استضافة Planka ذاتيًا باستخدام Docker Compose

انشر Planka على VPS باستخدام Docker Compose وPostgres وTraefik، واضبط متغيرات إنشاء المشرف وBASE_URL لتجنب خطأ تسجيل الدخول الناتج عن الإعداد الخاطئ.

ما تحصل عليه من الاستضافة الذاتية لـ Planka

تمنحك الاستضافة الذاتية لـ Planka لوحة Kanban لفريقك، مع نموذج البطاقات والقوائم والتسميات الذي يعرفه المستخدمون من Trello، وتعمل على VPS تتحكم فيه. لا توجد حدود لعدد المقاعد ولا فوترة لكل مستخدم، لأن التكلفة الوحيدة هي تكلفة الخادم. ينشر هذا الدليل Planka باستخدام Docker Compose خلف Traefik، مع استخدام Postgres للبيانات ووحدة تخزين مسماة لكل ملف يرفعه المستخدمون.

يصدر Planka 2 بموجب Fair Use License الخاصة بالمشروع. ويصف المشروع هذه الرخصة بأنها تتيح الوصول إلى الشفرة المصدرية وليست رخصة مفتوحة المصدر. يُسمح بتشغيله لمشاريع مؤسستك الداخلية. أما تقديمه إلى جهات خارجية باعتباره خدمة استضافة تجارية، فيتطلب ترخيص Pro أو Enterprise.

أفترض أن القارئ عضو في فريق مكوّن من شخصين إلى خمسة أشخاص، وينتقل من الخطة المجانية في Trello. إذا كنت لا تزال تقرر أي لوحة ستستخدم، فاقرأ أولاً مقارنة بدائل Trello ذاتية الاستضافة. يفترض هذا الدليل أن الاختيار قد حُسم، ولا يغطي إلا عملية النشر.

تحتاج إلى VPS يعمل عليه Docker Engine مع Compose plugin، وإلى سجل DNS من النوع A يشير إليه. تحتاج أيضاً إلى مثيل Traefik مُعد مسبقاً لإنهاء TLS (أمن طبقة النقل) على ذلك الخادم. إذا لم يكن Traefik مثبتاً بعد، فأعد أولاً إعداد Reverse Proxy باستخدام Traefik أمام عدة تطبيقات Compose، واقرأ أساسيات Docker Compose على VPS إذا كان الملف أدناه غير مألوف لك.

ما هي موارد الـ VPS التي يحتاجها Planka؟

توصي الأسئلة الشائعة التقنية للمشروع بذاكرة RAM لا تقل عن 2 GB ومساحة تخزين 10 GB للفرق الصغيرة، لذا تعامل مع هذه الأرقام كنقطة بداية وليس كقياس نهائي.

ما يعمل فعلياً هو حجم صغير: عملية Node.js واحدة تخدم واجهة برمجة التطبيقات (API) والواجهة الأمامية المبنية، وخادم Postgres يحمل البيانات، والذي يشغّل عملية إشراف بالإضافة إلى عملية خلفية واحدة لكل اتصال مفتوح. تعمل أيضاً عملية Proxy صغيرة داخل حاوية Planka لتصفية طلباتها الصادرة. تتوافق خطة 2 GB مع توصية المشروع لذاكرة RAM للفرق الصغيرة. اللوحة (Board) هي جار خفيف، لذا إذا كان من المفترض أن يستضيف نفس الـ VPS مستندات فريقك أيضاً، فقم بتقدير حجم ذلك التطبيق أولاً: تشغيل AFFiNE كمساحة عمل بنمط Notion تتطلب بضعة جيجابايتات بمفردها قبل أن يطلب Planka أي شيء.

قدّر حجم القرص قبل أن تقدّر حجم الذاكرة، لأن المرفقات هي الجزء الذي ينمو. قم بقياس مثيلك الخاص بدلاً من الوثوق بهذه الفقرة:

docker stats --no-stream
docker system df -v

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

كتابة ملف Compose

أنشئ المجلد وامنح نفسك ملكيته، حتى لا تضطر أبداً إلى تعديل هذه الملفات باستخدام sudo.

sudo mkdir -p /opt/planka
sudo chown "$USER":"$USER" /opt/planka
cd /opt/planka

أنشئ الأسرار في ملف .env بجانب ملف Compose. يقرأ Compose هذا الملف تلقائياً ويستبدل القيم.

umask 077
{
  printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 64)"
  printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 24)"
  printf 'ADMIN_PASSWORD=%s\n' "$(openssl rand -hex 12)"
} > .env
chmod 600 .env

استخدام openssl rand -hex مقصود. سلسلة الـ hex تحتوي فقط على أرقام وحروف من a إلى f، لذا لا يمكنها كسر سلسلة اتصال DATABASE_URL التي تُدرج فيها. يمكن أن تحتوي صيغة Base64 القياسية على شرطة مائلة، وعلامة زائد، وعلامة يساوي للحشو، ولكن لا تحتوي أبداً على علامة "at"؛ فالرموز ذات المعاني الخاصة في رابط الاتصال تحتاج إلى ترميز النسبة المئوية. النمط الأوسع مغطى في إبقاء الأسرار خارج ملف Compose.

الآن docker-compose.yml. استبدل kanban.example.com باسم المضيف الخاص بك في كلا الموضعين اللذين يظهر فيهما.

services:
  planka:
    image: ghcr.io/plankanban/planka:2.2.1
    restart: unless-stopped
    volumes:
      - planka-data:/app/data
    environment:
      - BASE_URL=https://kanban.example.com
      - DATABASE_URL=postgresql://planka:${POSTGRES_PASSWORD}@postgres/planka
      - SECRET_KEY=${SECRET_KEY}
      - TRUST_PROXY=true
      - DEFAULT_ADMIN_EMAIL=you@example.com
      - DEFAULT_ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - DEFAULT_ADMIN_NAME=Your Name
      - DEFAULT_ADMIN_USERNAME=admin
    networks:
      - proxy
      - internal
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.planka.rule=Host(`kanban.example.com`)"
      - "traefik.http.routers.planka.entrypoints=websecure"
      - "traefik.http.routers.planka.tls.certresolver=default"
      - "traefik.http.services.planka.loadbalancer.server.port=1337"
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=planka
      - POSTGRES_USER=planka
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    networks:
      - internal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U planka -d planka"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  planka-data:
  db-data:

networks:
  proxy:
    external: true
  internal:

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

  • لا يوجد كتلة ports: في خدمة Planka. يصل Traefik إلى الحاوية عبر شبكة proxy، لذا لا يتم نشر المنفذ 1337 على المضيف أبداً. نشره سيعطي أي شخص طريقة لتجاوز الوكيل (proxy) وشهادتك.
  • يحدد loadbalancer.server.port=1337 المنفذ داخل الحاوية. تستمع Planka على المنفذ 1337، بينما يصل المثال المرجعي إليها عبر 3000 لأنه يربط المنفذ بالمضيف. لا يوجد ربط بالمضيف هنا، لذا يجب إخبار Traefik بمنفذ الحاوية.
  • يقترن condition: service_healthy بفحص الحالة (healthcheck) الخاص بـ Postgres. بدونه، تبدأ Planka قبل أن تقبل قاعدة البيانات الاتصالات، فتفشل في استعلامها الأول وتخرج، مما يظهر كحلقة تعطل (crash loop). الآليات مشروحة في فحوصات حالة Compose وترتيب بدء التشغيل.
  • تمت تسمية خدمة قاعدة البيانات postgres عن قصد. توجّه Planka 2 طلباتها الصادرة عبر مرشح داخلي قائمة الحظر الافتراضية فيه هي localhost,postgres. إذا أعدت تسمية الخدمة، فستزيل قاعدة بياناتك بصمت من تلك القائمة.

تحقق من أن Compose يمكنه رؤية أسرارك قبل بدء أي شيء:

docker compose config | grep -E 'image:|BASE_URL|POSTGRES_USER'

يطبع هذا الأمر الملف مع استبدال قيم .env بالفعل. القيمة الفارغة تعني أن Compose لا يقرأ ملف .env، وعادة ما يحدث ذلك لأنك تشغل الأمر من دليل مختلف.

ما الذي تفعله متغيرات تهيئة المسؤول فعلياً

بدءاً من الإصدار 1.13 من Planka، لا يتم إنشاء حساب مسؤول تلقائياً، لذا لا يوجد مستخدم يمكنه تسجيل الدخول في قاعدة بيانات جديدة. تُعد مجموعة DEFAULT_ADMIN_* إحدى الطريقتين لحل هذه المشكلة.

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

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

يجب توخي الحذر فيما يخص سطر كلمة المرور. أي شيء تحت environment: يمكن لأي شخص لديه صلاحية تشغيل docker inspect على الحاوية قراءته، لذا لا ينبغي أن يظل DEFAULT_ADMIN_PASSWORD هناك بشكل دائم. قم بتسجيل الدخول، واحذف ذلك السطر، وشغّل docker compose up -d مرة أخرى، ثم غيّر كلمة مرورك من داخل الواجهة.

الطريقة الأنظف هي تجاوز المتغيرات تماماً. قم بإلغاء تفعيل مجموعة DEFAULT_ADMIN_* بالكامل، ثم أنشئ الحساب بشكل تفاعلي:

docker compose run --rm planka npm run db:create-admin-user

سيطلب منك النظام إدخال البريد الإلكتروني، وكلمة المرور، واسم العرض، واسم مستخدم اختياري، ثم يكتب بيانات المستخدم مباشرة في قاعدة البيانات. لا تلمس كلمة المرور ملف Compose أو بيئة الحاوية المهيأة. استخدم هذه الطريقة إذا كان هناك أكثر من شخص لديه صلاحية الوصول إلى الـshell على الـVPS. يبدأ الأمر بـPostgres أولاً بسبب depends_on، لذا فهو يعمل حتى على حزمة لم يتم تشغيلها من قبل.

تتركك كلتا الطريقتين في وضع إدارة كلمات مرور Planka يدوياً. حتى الإصدار 2.1.1، كان بإمكان إصدار Community تسليم عمليات تسجيل الدخول إلى مزود OIDC مثل Authentik الذي يعمل كخادم تسجيل دخول موحد خاص بك، ولكن الإصدار 2.2.0، الذي صدر في أغسطس 2026، نقل ميزات OIDC وSSO إلى PLANKA Pro. ما اكتسبه إصدار Community في نفس الإصدار هو المصادقة الثنائية (TOTP) للحسابات المحلية، لذا قم بتفعيلها لحساب المسؤول على الأقل.

لماذا يؤدي عدم تطابق BASE_URL مع اسم المضيف إلى فشل تسجيل الدخول

BASE_URL هو العنوان الدقيق الذي يكتبه المستخدمون في المتصفح، متضمناً البروتوكول وبدون شرطة مائلة في النهاية. بالنسبة لهذه الحزمة، هذا العنوان هو https://kanban.example.com. يبني Planka روابطه وقائمة مصادر WebSocket المسموح بها بناءً على هذه القيمة، مما يعني أن قيمة BASE_URL الخاطئة لا تظهر لك خطأً واضحاً. بدلاً من ذلك، ستحصل على صفحة يتم تحميلها ثم تتوقف عن العمل دون اكتمال.

السيناريو الشائع: أنت تنسخ مثال المصدر، وتترك BASE_URL=http://localhost:3000 كما هو، ثم تصل إلى الموقع عبر HTTPS باستخدام نطاقك الحقيقي. يتم إرسال نموذج تسجيل الدخول وتُقبل بيانات اعتمادك، لكن لوحة التحكم لا تظهر أبداً. افتح وحدة تحكم المطور في المتصفح وستجد طلبات إلى /socket.io/ تفشل، لأن المقبس (socket) يتصل بمصدر صفحة المتصفح، بينما يسمح تقييد المصدر في الخادم فقط بالمصدر المشتق من BASE_URL.

TRUST_PROXY=true هو النصف الآخر من المشكلة نفسها. يعمل Planka خلف Traefik، لذا يصل كل طلب إليه من عنوان الوكيل عبر بروتوكول HTTP عادي داخل شبكة Docker. بدون TRUST_PROXY، يتجاهل التطبيق ترويسات X-Forwarded-Proto وX-Forwarded-For التي يضبطها Traefik، فيعتقد أن الاتصال غير آمن ويعامل كل عميل كعنوان IP مشترك واحد. عند ضبطه، يقرأ التطبيق تلك الترويسات ويتوافق مع المتصفح حول البروتوكول المستخدم.

يقوم Traefik بتمرير اتصالات WebSockets دون الحاجة إلى إعدادات إضافية، وهذا أحد أسباب تفضيله هنا. في nginx، يجب على الوكيل تمرير ترويسات الترقية، proxy_set_header Upgrade $http_upgrade وproxy_set_header Connection "upgrade"، وإلا ستحصل على مؤشر التحميل العالق نفسه ولكن لسبب مختلف. يمكن وضع هذه الترويسات في كتلة location / العامة؛ كما تعمل كتلة منفصلة لـ /socket.io أيضاً ولكنها ليست مطلوبة.

نقل لوحة التحكم إلى اسم مضيف جديد لاحقاً يعني تغيير شيئين معاً: قيمة BASE_URL وقاعدة Host() في Traefik. إذا غيرت أحدهما ونسيت الآخر، ستعود إلى مشكلة مؤشر التحميل. تقديم Planka من مسار فرعي مثل https://example.com/planka يعمل بدءاً من الإصدار 2.1.0، الذي تم إصداره في مارس 2026. في الإصدارات الأقدم، خصص له نطاقاً فرعياً خاصاً به.

أين يحفظ Planka المرفقات والصور الرمزية

يخزّن Planka 2 كل ما يرفعه المستخدم تحت مسار واحد داخل الحاوية: /app/data. وتوجد المرفقات، وصور المستخدمين الرمزية، وصور خلفيات اللوحات جميعها تحت هذا المسار. كانت الإصدارات الأولى تستخدم ثلاثة مجلدات منفصلة، لذا فإن ملف Compose المنسوخ من مقال قديم يقوم بربط مسارات لم تعد موجودة، مما يؤدي إلى فقدان ربط البيانات المقصود.

هذا الربط الفردي هو الفارق بين لوحة تنجو من الترقية وبين ضياع بياناتك. تعلن صورة Docker عن /app/data كـ volume، لذا فإن حذف الربط من ملف Compose يضع المرفقات في volume مجهول. يحافظ Compose على هذا الـ volume أثناء إعادة إنشاء الحاوية عبر up، لكن تنفيذ down متبوعاً بـ up لا يعيد ربطه تلقائياً. ستعود اللوحة لتبدو سليمة، وستجد البطاقات في مكانها، لكن كل روابط المرفقات ستكون معطلة، لأن سجلات قاعدة البيانات لا تزال تشير إلى ملفات في الـ volume القديم.

يمنع الـ volume المسمى في ملف Compose أعلاه حدوث ذلك. يعمل الـ bind mount أيضاً ويجعل أخذ نسخة احتياطية من الملفات أسهل باستخدام الأدوات العادية، لكنه يحتاج إلى خطوة إضافية. تعمل عملية Node داخل الحاوية بمعرف المستخدم UID 1000، لذا فإن وجود مجلد على المضيف مملوك لـ root سيؤدي إلى خطأ في الصلاحيات عند أول عملية رفع:

sudo chown -R 1000:1000 /opt/planka/data

تمت مناقشة المفاضلة بين الخيارين في الربط المباشر (bind mounts) مقابل الـ volumes المسماة.

إذا تجاوز حجم المرفقات مساحة القرص في خطتك، يمكن لـ Planka كتابتها في تخزين متوافق مع S3، وذلك عبر S3_ENDPOINT و S3_BUCKET ومتغيرات المفاتيح المطابقة. يمكن أن يشير هذا إلى bucket مستضاف أو إلى مخزن كائنات MinIO ذاتي الاستضافة على خادم آخر. اتخذ هذا القرار قبل أن يملأ الفريق اللوحة، لأن تفعيل S3 يحوّل عمليات القراءة والكتابة إلى تلك الواجهة الخلفية دون نقل المرفقات الموجودة مسبقاً.

شغّل المكدس وتحقق من نجاحه

docker compose pull
docker compose up -d
docker compose ps

يجب أن يعرض docker compose ps القيمة postgres بوصفها healthy، والقيمة planka بوصفها running. إذا كان Planka يُعاد تشغيله في حلقة، فتحقق من اتصال قاعدة البيانات أولاً، وليس من التطبيق.

docker compose logs -f planka

يشغّل الإقلاع الأول السليم عمليات ترحيل قاعدة البيانات، لكن إعداد الإنتاج يضبط noShip: true ويمنع رسالة بدء التشغيل التي تُبلغ عن المنفذ 1337. تأكد من تطبيق المخطط فعلياً عبر الاستعلام من Postgres مباشرة، بدلاً من الوثوق بالسجل:

docker compose exec postgres psql -U planka -d planka -c '\dt'

تعني قائمة الجداول التي تتضمن board وcard أن عمليات الترحيل نُفِّذت. وتعني الرسالة "Did not find any relations" أن Planka لم يتصل بقاعدة البيانات قط، لذا قارِن DATABASE_URL بقيمتي POSTGRES_USER وPOSTGRES_PASSWORD في .env.

بعد ذلك، تحقّق من المسار من جهازك أنت، وليس من VPS:

curl -I https://kanban.example.com

تعني HTTP/2 200 أن Traefik يمتلك شهادة ويصل إلى الحاوية. ويعني الخطأ 404 الذي يقدّمه Traefik أن أي موجه لم يطابق الطلب: قاعدة Host() لا تطابق اسم المضيف الذي طلبته، أو أن Traefik لم يلتقط التسميات. ويعني الخطأ 502 أن الموجه طابق الطلب، لكن Traefik لم يتمكن من الوصول إلى الحاوية، مثلاً لأنها غير متصلة بشبكة proxy. افتح الموقع الآن وسجّل الدخول باستخدام حساب المسؤول.

خذ نسخة احتياطية عبر pg_dump قبل كل تحديث للإصدار

يتم تخزين بيانات لوحتك في مكانين منفصلين، لذا يجب أن تغطي النسخة الاحتياطية كلاً منهما: قاعدة بيانات Postgres ومجلد planka-data. قم بتصدير قاعدة البيانات أثناء تشغيل الحزمة (stack).

docker compose exec -T postgres pg_dump -U planka -d planka > "planka-db-$(date +%F).sql"

يؤدي الخيار -T إلى تعطيل تخصيص الطرفية الوهمية (pseudo-terminal) الخاص بـ Compose، مما يبقي مخرجات التصدير في تدفق بيانات نصي بسيط.

بعد ذلك، انتقل إلى الملفات المرفوعة. ابحث عن اسم المجلد الحقيقي أولاً، لأن Compose يضيف اسم دليل المشروع كبادئة له.

docker volume ls | grep planka
docker run --rm -v planka_planka-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/planka-files-$(date +%F).tgz -C /data .

يوفر المشروع أيضاً docker-backup.sh وdocker-restore.sh في مستودعه، وتوصي الوثائق الرسمية بجدولتهما عبر مهمة cron يومية. كلا النهجين مقبول. ما ليس مقبولاً هو الاعتماد على نسخة احتياطية لم تقم باستعادتها من قبل؛ لذا قم باستعادة نسخة واحدة على خادم افتراضي (VPS) تجريبي مرة واحدة، وتأكد من قدرتك على تسجيل الدخول وفتح مرفق. يظهر هذان المخزنان في كل تطبيق يعمل بنظام Compose ويقبل المرفقات، لذا إذا قمت لاحقاً بتثبيت Chatwoot على نفس الخادم مع مكتب الدعم الخاص بك، فإن الإجراء الذي تبنيه هنا سيظل صالحاً مع تغيير أسماء المجلدات فقط.

قم بتشغيل التصدير مباشرة قبل كل تغيير في الإصدار. النسخة الاحتياطية التي أخذتها الليلة الماضية ليست هي نفسها النسخة الاحتياطية التي تؤخذ قبل عملية الترحيل التي توشك على تنفيذها.

ثبّت الوسوم واقرأ ملاحظات الإصدار

وسما الصورتين في ذلك الملف مثبتان عمداً.

ghcr.io/plankanban/planka:2.2.1 إصدار محدد، وهو الإصدار الحالي حتى أكتوبر 2026. أُصدر Community 2.3.0 في 4 نوفمبر 2026، مع إصلاحات أمنية، ويوصي المشروع الأساسي بالتحديث إليه. وتلاه Community 2.3.1 في 5 نوفمبر 2026، لإصلاح تعطل يحدث عند تعديل أوصاف البطاقات في اللوحات التي تضم عضواً بلا اسم مستخدم. ويتغير latest كلما نشر المشروع الأساسي إصداراً جديداً، ولذلك قد يؤدي تشغيل docker compose pull المعتاد إلى تطبيق ترحيل للمخطط في وقت لم تختره. اقرأ ملاحظات الإصدار قبل تغيير ذلك الرقم، لأن التغييرات غير المتوافقة والإصلاحات الأمنية موضحة هناك. نُشر الإصدار 2.0.3 كإصدار أمني، وهذا تحديداً ما يجب أن تقرأه بدلاً من تطبيقه عرضاً. وينطبق الأمر نفسه على 2.2.1، الذي أُصدر في أغسطس 2026؛ فهو يصلح ثغرة اجتياز المسارات كانت تتيح لمستخدم سجّل الدخول قراءة ملفات عشوائية على المثيلات التي تستخدم التخزين المحلي للملفات، وهو الإعداد المستخدم في هذا الدليل، ويذكر التنبيه أن الإصدار 2.1.1 والإصدارات الأقدم متأثرة. إذا كنت تنتقل من 2.1.x، فاقرأ ملاحظات 2.2.0 أولاً، لأن ذلك الإصدار يعطّل المستخدمين الذين سجّلوا الدخول عبر SSO فقط حتى يمنحهم مسؤول كلمة مرور ويعيد تفعيلهم. تثبيت الإصدارات سهل هنا لأن المشروع الأساسي ينشر صوراً أصلاً، أما عندما لا ينشر المشروع صوراً، فعليك اتباع الانضباط نفسه مع خطوة إضافية، كما في openGym الذي بُني على الخادم من وسم git مسحوب.

postgres:16-alpine مثبت على إصدار رئيسي لسبب أكثر أهمية. يكتب Postgres دليل البيانات بتنسيق مرتبط بالإصدار الرئيسي، ويرفض الخادم فتح دليـل كتبته نسخة أخرى. اكتب postgres:latest، ودَع الوسم يتجاوز 16، ولن تبدأ الحاوية. تتوقف صورة 17، مثلاً، مع الرسالة التالية:

FATAL:  database files are incompatible with server
DETAIL:  The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17.

لا تُفقد أي بيانات، ولا يعالج إعادة التشغيل المشكلة. يعني الانتقال إلى إصدار رئيسي جديد من Postgres أخذ نسخة dump من الإصدار القديم واستعادتها في دليل بيانات جديد على الإصدار الجديد، أو تنفيذ pg_upgrade الذي يحوّل البيانات من دون dump لكنه يحتاج إلى توفّر ملفات الخادم التنفيذية للإصدارين القديم والجديد معاً، أو استخدام النسخ المتماثل المنطقي إلى خادم يعمل بالإصدار الجديد ثم إجراء تحويل الخدمة إليه. كل مسار من هذه المسارات عملية ترحيل مخططة، وليس أثراً جانبياً لسحب صورة؛ إذ يتيح النسخ المتماثل المنطقي للخادم القديم مواصلة العمل بينما يلحق به الخادم الجديد.

إذا كنت تنقل تثبيت Planka 1.x موجوداً بدلاً من البدء من الصفر، فلهذا التحديث إجراء موثق خاص به في وثائق المشروع، ولا توجد طريقة للعودة إلى الإصدار 1 من دون نسخة احتياطية أُخذت مسبقاً.

أنماط الفشل والرسائل التي ستراها

يعيد Planka التشغيل في حلقة مفرغة ويشير السجل إلى قاعدة البيانات. بيانات الاعتماد في DATABASE_URL لا تطابق بيئة Postgres. لاحظ أن POSTGRES_PASSWORD لا تُطبّق إلا عند تهيئة مجلد البيانات لأول مرة، لذا فإن تعديل المتغير بعد إقلاع أول خاطئ لن يغير شيئاً. غيّر كلمة مرور دور قاعدة البيانات باستخدام ALTER ROLE لتطابق كلمة المرور المحددة؛ حذف المجلد db-data هو خيار متاح فقط للتثبيتات المؤقتة التي لا تحتوي على بيانات تحتاج للحفاظ عليها.

تنجح عملية تسجيل الدخول ولكن لوحة التحكم لا تُحمّل. BASE_URL لا تطابق العنوان الموجود في شريط المتصفح، لذا يرفض الخادم أصل المقبس (socket). تعرض وحدة تحكم المتصفح طلبات فاشلة إلى /socket.io/.

تفشل عمليات الرفع بينما يعمل كل شيء آخر. المجلد المربوط (bind mount) مملوك للمستخدم root. نفّذ sudo chown -R 1000:1000 على مجلد المضيف وأعد تشغيل الحاوية.

اختفت المرفقات بعد الترقية. لم يتم ربط /app/data بمجلد الرفع الأصلي. أعد ربط ذلك المجلد أو استعد الملفات من نسخة احتياطية، ثم استخدم مجلداً مسمى (named volume) قبل أن تلمس وسم الصورة (image tag) مجدداً.

يعيد Traefik الخطأ 404. لا يوجد مسار (router) يطابق الطلب: قاعدة Host() لا تطابق سجل DNS الخاص بك، أو أن التسميات (labels) لم تصل إلى Traefik. يعرض docker compose config التسميات بعد الاستبدال، وهي النقطة التي تظهر فيها الأخطاء المطبعية. أما الخطأ 502 فيعني أن المسار طابق الطلب ولكن تعذر الوصول إلى الحاوية، لذا تحقق من وجودها على الشبكة proxy.

الإشعارات أو الـwebhooks لا تصل أبداً. يرسل Planka 2 طلبات HTTP الصادرة عبر مرشح داخلي، وتغطي قائمة الحظر الافتراضية localhost وpostgres. الـwebhook الموجه إلى localhost محظور افتراضياً، وبمجرد ضبط OUTGOING_ALLOWED_HOSTS، سيتم حظر كل مضيف ليس ضمن تلك القائمة. وجّه الـwebhook إلى اسم خدمة الحاوية الأخرى، وأضف ذلك الاسم إلى OUTGOING_ALLOWED_HOSTS إذا كنت تستخدم قائمة سماح، بدلاً من إزالة المرشح.

بمجرد تشغيله، يكون الحمل التشغيلي ضئيلاً. راقب ملاحظات الإصدار، وقم بتصدير قاعدة البيانات قبل كل عملية ترقية. تؤدي إعادة التشغيل إلى استعادة حزمة الخدمات تلقائياً بفضل restart: unless-stopped، طالما أن خدمة Docker نفسها مفعّلة عند الإقلاع، ويغطي الرابط حزم Compose التي تعود للعمل بعد إعادة التشغيل الحالات التي لا يحدث فيها ذلك.

FAQ

لماذا يستمر Planka في التحميل إلى ما لا نهاية بعد تسجيل الدخول؟

تم قبول بيانات الاعتماد ولكن الاتصال المباشر لم يُقبل. يفتح المتصفح مقبس (socket) إلى أصل الصفحة، بينما يستمد Planka أصول المقابس المسموح بها من BASE_URL، لذا فإن ترك هذا المتغير عند http://localhost:3000 بينما تصل إلى الموقع عبر https://kanban.example.com يجعل الخادم يرفض الاتصال. تُظهر وحدة تحكم المطور طلبات فاشلة إلى /socket.io/. اضبط BASE_URL على العنوان العام الدقيق بدون شرطة مائلة في النهاية، وأضف TRUST_PROXY=true لكي يحترم التطبيق ترويسة X-Forwarded-Proto القادمة من الـ reverse proxy الخاص بك، ثم نفّذ docker compose up -d.

كيف أنشئ أول مستخدم إداري في Planka؟

منذ الإصدار 1.13، لا يتم إنشاء أي مدير تلقائياً. إما أن تضبط DEFAULT_ADMIN_EMAIL مع متغيرات كلمة المرور والاسم واسم المستخدم المطابقة له وتبدأ الحزمة (stack)، أو نفّذ docker compose run --rm planka npm run db:create-admin-user وأجب على المطالبات. الأمر التفاعلي هو الأكثر أماناً على خادم مشترك، لأن كلمة المرور لا تدخل أبداً إلى بيئة الحاوية المهيأة حيث يمكن لـ docker inspect قراءتها. إبقاء DEFAULT_ADMIN_EMAIL مضبوطاً بعد ذلك يمنع إجراء تغييرات على اسم ذلك الحساب أو دوره أو عنوان بريده الإلكتروني، ويمنع حذفه من الواجهة. أزل DEFAULT_ADMIN_PASSWORD بعد الإعداد، لأن تركه مضبوطاً يؤدي إلى إعادة تعيين كلمة مرور الحساب المطابق عند كل بدء تشغيل.

أين يخزن Planka المرفقات والصور الرمزية؟

توجد جميع الملفات المرفوعة تحت /app/data داخل الحاوية في Planka 2، بما في ذلك المرفقات، وصور المستخدمين الرمزية، وخلفيات اللوحات. اربط (mount) هذا المسار على وحدة تخزين مسماة (named volume). بدون ربط صريح، تستخدم صورة Docker وحدة تخزين مجهولة، والتي لا يعيد docker compose up توصيلها تلقائياً بعد docker compose down. يعمل الربط المباشر (bind mount) أيضاً، ولكن عملية Node تعمل بمعرّف مستخدم UID 1000، لذا نفّذ sudo chown -R 1000:1000 على دليل المضيف وإلا ستفشل عمليات الرفع بسبب خطأ في الصلاحيات.

ما مقدار ذاكرة الوصول العشوائي (RAM) التي يحتاجها Planka المستضاف ذاتياً؟

توصي الأسئلة الشائعة التقنية للمشروع بذاكرة RAM لا تقل عن 2 GB ومساحة تخزين 10 GB للفرق الصغيرة. يشغّل نشر Docker الافتراضي عملية Node، وخادم Postgres مع عملية خلفية لكل اتصال مفتوح، ووكيل Squid داخلي لتصفية الطلبات الصادرة. نفّذ docker stats --no-stream بعد أسبوع عمل عادي وحدد الحجم بناءً على أرقامك الخاصة. راقب القرص بشكل أدق من الذاكرة، لأن المرفقات هي التي تنمو.

كيف أقوم بترقية Planka دون فقدان البيانات؟

قم بتصدير قاعدة البيانات وأرشفة وحدة تخزين المرفقات فوراً قبل الترقية، وليس بناءً على جدول الليلة الماضية. استخدم docker compose exec -T postgres pg_dump -U planka -d planka > planka-db.sql، مع الاحتفاظ بـ -T لتعطيل تخصيص الطرفية الزائفة (pseudo-terminal) للمخرجات المُعاد توجيهها. اقرأ ملاحظات الإصدار لكل نسخة تتخطاها، وغيّر وسم الصورة (image tag) إلى إصدار محدد بدلاً من latest، ثم نفّذ docker compose pull وdocker compose up -d وراقب السجلات (log) لمتابعة عملية الترحيل. اترك وسم Postgres مثبتاً على إصداره الرئيسي، لأن الخادم يرفض فتح دليل بيانات مكتوب بواسطة إصدار رئيسي مختلف.

هل كان هذا المقال مفيدًا؟