تثبيت Paperless-ngx على VPS عبر Docker Compose
شغّل Paperless-ngx على VPS باستخدام Docker Compose وPostgres الرسمي، واضبط PAPERLESS_URL ومجلد consume ولغات OCR وHTTPS والنسخ الاحتياطية.
ما الذي ستبنيه
يحوّل Paperless-ngx على VPS مجلداً من المستندات الورقية الممسوحة ضوئياً إلى أرشيف قابل للبحث. تضع ملف PDF في مجلد تتم مراقبته، فيجري الخادم OCR (التعرّف الضوئي على الحروف)، ويستخرج النص، ويخمّن التاريخ والمراسِل، ثم يفهرس الملف. يتكوّن التثبيت من ملف Docker Compose واحد يضم أربع خدمات. بعد ذلك، كل ما تحتاج إليه هو الإعداد، ولذلك يخصص هذا الدليل معظم طوله له، لأن الإعداد هو الموضع الذي تتعطل فيه عمليات التثبيت. هذا البرنامج ليس مكتبة صور: لا يفيد OCR وتخمين المراسِل في مجلد يضم ملفات JPEG لرحلات العطلات، لذا ضعها في خادم صور مخصص لها، واترك Paperless للمستندات الورقية. وينطبق الأمر نفسه على الفيديو: مكان مجموعة الأفلام المنسوخة هو خادم وسائط، حيث يجعل شيء مثل واجهة Jellyfin الأمامية المصممة على هيئة متجر تأجير من التسعينيات التصفح هو الغرض بدلاً من البحث.
Paperless-ngx هو fork مجتمعي مُصان من مشروع Paperless الأصلي. وهو مجاني ومستضاف ذاتياً، ويخزّن مستنداتك كملفات عادية على القرص، لذلك لا تُحرم أبداً من الوصول إلى أرشيفك الخاص. تشغيله على VPS بدلاً من جهاز منزلي يعني أن عمليات المسح الضوئي لديك متاحة من أي مكان دون فتح منفذ على موجّه منزلك، كما يتكامل جيداً مع مثيل Nextcloud خاص لملفاتك غير الورقية. وينطبق المنطق نفسه على الجهاز المكتبي الموصول به الماسح الضوئي، إذ يتيح لك مرحل RustDesk تملكه على VPS نفسه التحكم في ذلك الجهاز من مكان آخر دون فتح منفذ في الموجّه أيضاً.
ما الذي يشغّله المكدس فعلياً
يبدأ ملف Compose الرسمي أربع حاويات. يساعدك فهم وظيفة كل حاوية على قراءة السجلات.
webserver: صورة paperless-ngx نفسها. تشغّل واجهة الويب وواجهة API والعامل الذي يراقب مجلد الإدخال وعمال مهام Celery الذين ينفّذون OCR.db: PostgreSQL. يحتفظ بالبيانات الوصفية والوسوم والمراسِلين وجداول فهرس البحث في النص الكامل. ولا يحتفظ بملفات PDF.broker: Valkey، وهو مخزن قيم مفتاحية متوافق مع Redis. يوفّر قائمة المهام بين عملية الويب والعمال.gotenbergوtika: اختياريان، ويظهران فقط في متغيرات Compose الخاصة بـ-tika. يحوّلان مستندات Office (.docxو.xlsxو.odt) إلى PDF لكي يتمكن paperless من فهرستها.
اعتباراً من أكتوبر 2026، يثبّت ملف Compose الخاص بـpostgres الإصدارين docker.io/library/postgres:18 وdocker.io/valkey/valkey:9-alpine، ويسحب التطبيق من ghcr.io/paperless-ngx/paperless-ngx:latest.
المتطلبات الأساسية
- خادم KVM VPS يعمل بنظام Ubuntu 24.04، مع صلاحية
sudo، وDocker مع تثبيت Compose plugin مسبقاً. إذا كان هذا الجزء جديداً عليك، فابدأ بـ أساسيات Docker Compose لخادم VPS ثم عد إلى هنا. - اسم نطاق يتضمن سجل A يشير إلى VPS. لن يقبل Paperless تسجيل الدخول عبر HTTPS باستخدام اسم مضيف لم تُعرِّفه فيه، لذلك يجب إعداد ذلك في مرحلة أبكر مما تتوقع.
- الذاكرة هي القيد الفعلي. يمكن أن تعمل PostgreSQL وValkey وخادم الويب Granian وعامل Tesseract OCR معاً ضمن 2 GB للاستخدام الخفيف. خصص 4 GB إذا كنت تخطط لاستيراد تراكم يضم مئات عمليات المسح، لأن OCR لملف PDF كبير متعدد الصفحات يسبب زيادة الذاكرة التي تؤدي إلى إنهاء العامل بواسطة قاتل نفاد الذاكرة في kernel.
- القرص: يُخزَّن أرشيفك مرتين، مرة في الملف الأصلي ومرة في ملف PDF مؤرشف نُفِّذت عليه OCR، لذلك خصص مساحة تعادل تقريباً ضعف حجم عمليات المسح.
الحصول على ملفات compose الرسمية
يوجد مُثبّت تفاعلي:
bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"يطرح المُثبّت أسئلة ويكتب الملفات نيابةً عنك. تنفيذ ذلك يدوياً يتطلب أربعة أوامر، ويجعلك تعرف مكان كل شيء. هذا هو المطلوب على خادم ستتولى صيانته.
mkdir -p ~/paperless && cd ~/paperless
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml
curl -fsSL -o docker-compose.env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
curl -fsSL -o .env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.envتوجد المتغيرات في الدليل نفسه: docker-compose.sqlite.yml وdocker-compose.mariadb.yml، وإصدار -tika من كل منهما. اختر postgres عند إجراء تثبيت جديد. يكفي SQLite لبضع مئات من المستندات، لكن فهرس البحث في النص الكامل يصبح بطيئاً قبل PostgreSQL بوقت طويل.
يحتوي الملف .env على سطر واحد هو COMPOSE_PROJECT_NAME=paperless. يصبح هذا الاسم البادئة لكل حاوية ووحدة تخزين، لذلك لا تحذفه ثم تتساءل عن سبب عدم تمكّن docker compose down -v من العثور على بياناتك.
إعداد docker-compose.env قبل التشغيل الأول
هناك إعدادان إلزاميان. أنشئ المفتاح السري باستخدام الأمر الموثق في المشروع:
python3 -c "import secrets; print(secrets.token_urlsafe(64))"ثم عدّل docker-compose.env:
PAPERLESS_SECRET_KEY=<the long string you just generated>
PAPERLESS_URL=https://paperless.example.com
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu+eng
USERMAP_UID=1000
USERMAP_GID=1000تأتي PAPERLESS_SECRET_KEY بالقيمة الحرفية change-me. وتستخدمها لتوقيع رموز الجلسات. وتتعامل الإصدارات الحالية مع هذه القيمة النائبة على أنها غير مضبوطة: يرفض paperless البدء عندما يكون المفتاح مفقوداً أو فارغاً أو لا يزال change-me. لذلك لن تبدأ الحزمة حتى تستبدلها. اضبطها قبل التشغيل الأول، لأن تغييرها لاحقاً يؤدي إلى تسجيل خروج جميع المستخدمين.
PAPERLESS_URL هو الإعداد الذي يوفر عليك ساعة من التشخيص. Paperless تطبيق Django، ويفحص Django كلاً من ترويسة Host والمصدر الذي يرسله المتصفح في نموذج تسجيل الدخول. اضبط PAPERLESS_URL، وسيضيف عنوانك إلى ALLOWED_HOSTS وCORS_ALLOWED_HOSTS وCSRF_TRUSTED_ORIGINS تلقائياً. إذا تركته فارغاً ووجّهت نطاقاً إلى الخادم، فستظل صفحة تسجيل الدخول تُحمّل، لأن PAPERLESS_ALLOWED_HOSTS تكون * افتراضياً. لكن إرسال النموذج عبر HTTPS يفشل مع CSRF verification failed. Request aborted. لأن نطاقك ليس مصدراً موثوقاً. اكتب القيمة من دون شرطة مائلة في النهاية ومن دون مسار.
تحدد USERMAP_UID وUSERMAP_GID المستخدم الذي تعمل الحاوية به. اجعلهما مطابقين لحسابك، وتحقق من ذلك باستخدام id -u وid -g. إذا لم تتطابق القيم، فلن يتمكن المستهلك من قراءة الملفات التي تنسخها إلى مجلد الاستهلاك، وسيعرض السجل خطأ في الصلاحيات بدلاً من إجراء الاستيراد.
شغّل المكدس وأنشئ المستخدم الأول
docker compose pull
docker compose up -d
docker compose run --rm webserver createsuperuser
docker compose logs -f webserverيطلب createsuperuser اسم مستخدم وبريداً إلكترونياً وكلمة مرور. لا يوجد تسجيل دخول افتراضي. إذا تخطيت هذه الخطوة، فستطلب واجهة الويب من أول من يفتحها إنشاء المستخدم المتميز. وطالما أن المنفذ 8000 ما زال مفتوحاً أمام الإنترنت، فقد لا تكون أنت ذلك الشخص. لذلك أنشئ الحساب من الصدفة الطرفية فوراً. انتظر سطر السجل الذي يفيد بأن الخادم يستمع على المنفذ 8000 قبل تجربة المتصفح. يشغّل التشغيل الأول أيضاً عمليات ترحيل قاعدة البيانات، وقد يستغرق ذلك دقيقة أو دقيقتين.
تحقق منه محلياً قبل استخدام نطاق:
curl -I http://127.0.0.1:8000تعني إعادة توجيه 302 إلى /accounts/login/ أن المكدس يعمل بصورة سليمة.
ضع HTTPS أمام التطبيق
ينشر ملف compose الافتراضي المنفذ 8000:8000، ويربطه بكل الواجهات. على VPS عام، يعرّض ذلك أرشيف مستنداتك بالكامل عبر HTTP غير المشفّر لأي شخص يعثر على العنوان. غيّر سطر المنفذ لربطه بواجهة loopback فقط:
ports:
- "127.0.0.1:8000:8000"بعد ذلك، أنهِ TLS (أمان طبقة النقل) في reverse proxy ووجّه الطلبات إلى 127.0.0.1:8000. إذا كان هذا هو التطبيق الوحيد على الخادم، فسيعمل أي proxy يتضمن عميل ACME (بيئة إدارة الشهادات تلقائياً). إذا كنت تشغّل عدة حاويات خلف إعداد واحد للشهادة، فاتبع نمط Traefik لـ reverse proxy مع عدة تطبيقات Docker Compose، وأضف خدمة webserver إلى شبكة proxy من دون نشر أي منفذ على الإطلاق.
أياً كان proxy الذي تستخدمه، فإن التحقق من origin في نموذج تسجيل الدخول هو موضع تعطل إعدادات HTTPS. يتجاهل Paperless القيمة X-Forwarded-Proto ما لم تضبط PAPERLESS_PROXY_SSL_HEADER، وهي معطّلة افتراضياً. لذلك يتعامل Django مع كل طلب يمر عبر proxy على أنه HTTP عادي، ولا ينجح origin https:// الذي يرسله متصفحك إلا إذا كان مدرجاً ضمن origins الموثوقة. إن ضبط PAPERLESS_URL على عنوان https:// المطابق تماماً لما تكتبه في المتصفح هو ما يضيفه إلى تلك القائمة. من دونه، تحصل على CSRF verification failed. Request aborted. في صفحة تبدو صحيحة.
ارفع أيضاً حد حجم الرفع في proxy. فإذا مرّ ملف مسح ضوئي حجمه 40 MB عبر proxy يحدّ حجم الطلبات إلى 1 MB، فسيُرفض قبل أن يراه paperless، وسيعرض المتصفح فشل رفع عاماً.
طريقة عمل مجلد consume
يربط ملف Compose عبر bind mount المسار ./consume من مجلد Compose داخل الحاوية. يُستورَد كل ما تضعه هناك، ثم يُحذف من المجلد، لأن الملف يصبح موجوداً الآن في وحدة التخزين media التي يديرها paperless.
cp ~/scan-2026-07-14.pdf ~/paperless/consume/
docker compose logs -f webserverيجب أن ترى consumer يلتقط اسم الملف، وينفّذ OCR، وينتهي بسطر يفيد بإضافة المستند. تستغرق الدورة كاملةً بضع ثوانٍ لمسح من صفحة واحدة، وقد تستغرق دقيقة أو أكثر لمستند طويل.
يغيّر إعدادان طريقة العثور على الملفات. يجعل PAPERLESS_CONSUMER_RECURSIVE=true paperless يبحث في المجلدات الفرعية، ويحوّل PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true اسم كل مجلد فرعي إلى وسم، ولذلك يؤدي إسقاط ملف في consume/invoices/2026/ إلى وسمه بالوسمين invoices و2026. هذا أبسط نظام أرشفة يمكنك إنشاؤه.
الكشف عن الملفات هو الجانب الآخر. تكون قيمة PAPERLESS_CONSUMER_POLLING_INTERVAL افتراضياً هي 0، ما يعني أن paperless يستخدم إشعارات نظام الملفات الأصلية التي تعمل فوراً. لا تكون هذه الإشعارات موثوقة عند استخدام نظام ملفات عبر الشبكة. إذا كان مجلد consume لديك مشاركة NFS أو SMB تكتب فيها ماسحة ضوئية عبر الشبكة، فقد تبقى الملفات هناك من دون اكتشافها. ويكون الحل بتعيين الفاصل الزمني إلى عدد موجب من الثواني، لكي يفحص paperless المجلد بدلاً من ذلك.
لغات OCR وتكلفتها
PAPERLESS_OCR_LANGUAGE يقبل رمز Tesseract المكوّن من ثلاثة أحرف، والقيمة الافتراضية هي eng. ادمج اللغات باستخدام علامة الجمع، كما في deu+eng. بعد ذلك، يعالج Tesseract كل لغة مدرجة في كل صفحة، لذلك تضيف كل لغة إضافية وقتاً من المعالج إلى كل عملية مسح. في VPS ذي vCPU مشترك، قد يكون الفرق بين اكتمال المسح خلال عشر ثوانٍ واكتماله خلال دقيقة. أدرج اللغات التي كُتبت مستنداتك بها فعلياً فقط.
تتضمن image اللغات الإنجليزية والألمانية والإيطالية والإسبانية والفرنسية. لإضافة أي لغة أخرى، أضفها إلى PAPERLESS_OCR_LANGUAGES كقائمة مفصولة بمسافات، مثل PAPERLESS_OCR_LANGUAGES=tur ces، ثم أعد التشغيل. تنزّل الحاوية حزم بيانات Tesseract عند بدء التشغيل، لذلك يكون الإقلاع الأول بعد هذا التغيير أبطأ.
انسخ قاعدة البيانات والوسائط
يؤدي نسخ وحدات Docker أثناء تشغيل PostgreSQL إلى إنشاء نسخة احتياطية قد يتعذر استعادتها. يوفّر Paperless أداة تصدير خاصة به، تكتب المستندات وبيان JSON يتضمن كل البيانات الوصفية في نقطة الربط ./export:
docker compose exec -T webserver document_exporter ../export --delete --no-progress-barتزيل --delete الملفات المصدَّرة التي لم تعد تطابق مستنداً حالياً، ولذلك يبقى المجلد مطابقاً للمصدر بدلاً من أن يزداد حجمه باستمرار. وتحافظ --no-progress-bar على نظافة المخرجات عند تشغيل ذلك من cron، بينما تمنع -T Compose من طلب طرفية لا يملكها cron.
تتم الاستعادة document_importer مقابل المجلد نفسه على مكدس جديد، ما يعني أن مجلد التصدير هو الشيء الوحيد الذي يجب عليك الحفاظ عليه بأمان. أرسله إلى موقع خارج الخادم وفق جدول زمني باستخدام نسخ restic الاحتياطية المشفّرة والمزالة للتكرار من VPS، وشغّل التصدير أولاً حتى لا يلتقط restic أرشيفاً كُتب جزء منه فقط.
تحقق من النسخة الاحتياطية بالتأكد من وجود export/manifest.json، ومن أن عدد الملفات يطابق عدد المستندات الظاهر في الواجهة. النسخة الاحتياطية التي لم تعرض محتوياتها قط ليست نسخة احتياطية. والأسوأ من ذلك أن يبدأ تصدير ليلي بالفشل بصمت، لذلك اجعل مهمة cron ترسل حالة خروجها إلى خادم ntfy الخاص بك، وستعرف بالأسبوع الذي حدث فيه العطل بدلاً من اليوم الذي تحتاج فيه إلى الاستعادة.
FAQ
لماذا تعرض كل صفحة الرسالة "Bad Request (400)" بعد توجيه النطاق إليها؟
لا ينبغي أن يحدث ذلك مع الملفات الافتراضية، لأن PAPERLESS_ALLOWED_HOSTS تكون قيمته الافتراضية *. ظهور 400 مع DisallowedHost في سجل الحاوية يعني أن PAPERLESS_ALLOWED_HOSTS ضُبطت على قائمة لا تتضمن نطاقك. اضبط PAPERLESS_URL=https://paperless.example.com في docker-compose.env من دون شرطة مائلة في النهاية، وستضيف paperless اسم المضيف هذا إلى القائمة، أو احذف سطر PAPERLESS_ALLOWED_HOSTS. ثم شغّل docker compose up -d لإعادة إنشاء الحاوية. تعديل ملف البيئة وحده لا يغيّر شيئاً، لأن الحاوية قيد التشغيل تحتفظ ببيئة التشغيل التي بدأت بها.
أسقطت ملف PDF في مجلد consume ولم يحدث شيء. ما المشكلة؟
تحقق من docker compose logs webserver أولاً. يعني خطأ الصلاحيات أن USERMAP_UID وUSERMAP_GID لا يتطابقان مع الحساب الذي يملك الملف، لذا أصلح القيمتين ثم أعد إنشاء الحاوية. عدم ظهور أي سطر في السجل يعني أن حدث الملف لم يصل قط. يحدث ذلك مع مشاركات الشبكة لأن إشعارات نظام الملفات الأصلية لا تكون موثوقة فيها. اضبط PAPERLESS_CONSUMER_POLLING_INTERVAL على قيمة مثل 30، وسيفحص paperless المجلد كل 30 ثانية بدلاً من ذلك.
هل يمكنني تشغيل paperless-ngx باستخدام SQLite بدلاً من PostgreSQL؟
نعم، docker-compose.sqlite.yml مدعوم ويستخدم ذاكرة أقل، ولذلك يناسب VPS صغيراً. يظهر المقابل مع نمو الأرشيف: يتباطأ البحث في النص الكامل والتعديلات المجمعة للوسوم بشكل ملحوظ عند الوصول إلى آلاف المستندات. تتطلب عملية الترحيل لاحقاً تصديراً واستيراداً، لذلك اختر PostgreSQL الآن إذا كنت تتوقع استمرار نمو الأرشيف.
ما مقدار مساحة القرص التي يحتاج إليها أرشيف عمليات المسح فعلياً؟
تحتاج تقريباً إلى ضعف حجم ملفات المصدر. يحتفظ paperless بالنسخة الأصلية دون تعديل، ويخزن نسخة PDF ثانية خضعت لـOCR وتحتوي على طبقة نص قابلة للبحث، بالإضافة إلى صور مصغرة صغيرة. يظل مستند ممسوح ضوئياً نصياً بحجم 200 KB صغيراً. أما مستند ملوّن ممسوح ضوئياً بحجم 30 MB لعقد طويل، فيشغل نحو 60 MB. أضف دليل التصدير إذا كنت تحتفظ به على القرص نفسه، وعندها سيشغل الأرشيف نفسه ثلاثة أضعاف المساحة على القرص.
هل أحتاج إلى حاويتي Tika وGotenberg؟
تحتاج إليهما فقط إذا أردت فهرسة ملفات Word أو Excel أو OpenDocument إلى جانب ملفات PDF. تحول الحاويتان هذه التنسيقات إلى PDF، حتى يتمكن paperless من تنفيذ OCR والبحث فيها. كما تضيفان حاويتين قيد التشغيل وبضع مئات من الميغابايتات إلى استهلاك الذاكرة، لذلك تخطهما على خادم صغير إذا كانت كل الملفات التي تحفظها عبارة عن PDF أو صور.