استضافة Paperless-ngx على خادمك الافتراضي الخاص (VPS)

لماذا تستضيف Paperless-ngx ذاتيًا على خادم VPS

الفواتير والعقود وكشوف الرواتب والمراسلات الإدارية: تتعامل إدارة المستندات مع بيانات سرّية قلّما ترغب الشركات في تسليمها إلى سحابة طرف ثالث. يستوعب Paperless-ngx كل ملف PDF أو صورة ممسوحة، ويطبّق عليه OCR (التعرّف على النص) لجعله قابلاً للبحث، ثم يصنّفه تلقائيًا حسب المُراسِل والنوع والوسوم بفضل محرّك مطابقة. على خادم VPS، تحصل على أرشيف يمكن الوصول إليه من أي مكان، يُغذّى بمجرد إسقاط الملفات في مجلد مُراقَب أو عبر البريد الإلكتروني. يعتمد المكدّس على PostgreSQL للفهرس، وRedis لطابور المهام، وخدمة معالجة تشغّل Tesseract لـOCR. وتتحكم أنت بالاحتفاظ القانوني وتشفير النسخ الاحتياطي والوصول، دون الاعتماد على مطوّر.

فوائد Paperless-ngx المُستضاف ذاتيًا

‎OCR تلقائي عبر Tesseract: يصبح كل ملف ممسوح أو PDF قابلاً للبحث في نصه الكامل.
تصنيف تلقائي حسب المُراسِل ونوع المستند والوسوم وفق قواعدك.
مجلد مُراقَب واستيراد عبر البريد الإلكتروني: أسقِط ملفًا، فتتم معالجته وفهرسته تلقائيًا.
بحث فوري في كل المحتوى النصّي، وليس أسماء الملفات فقط.
الحفاظ على النسخ الأصلية سليمة إلى جانب النسخ المعالَجة بـOCR، من أجل القيمة الإثباتية.
نسخ احتياطي مُتحكَّم به لأرشيف حسّاس قانونيًا، دون سحابة طرف ثالث.

المتطلبات العتادية والبرمجية

‎Paperless-ngx معقول عند الخمول، لكن OCR نهِم على دفعات: يوفّر 2 vCPU و3 إلى 4 غيغابايت من RAM راحة جيدة، إذ يُجهد OCR مستندٍ متعدد الصفحات المعالَج مؤقتًا. وللاستيراد الأولي الكبير لعدة آلاف من المستندات، تسرّع الأنوية الإضافية المعالجة بشكل ملحوظ. خصّص تخزينًا للنسخ الأصلية إضافةً إلى ملفات الأرشيف المعالَجة بـOCR، أي نحو ضعف الحجم الخام. على الجانب البرمجي: ‎Docker وdocker compose الإصدار v2، وPostgreSQL، وRedis، ولغات Tesseract التي تحتاجها (fra وeng وara). ونطاق (docs.yourcompany.com)، واختياريًا حساب IMAP مخصّص للاستيراد التلقائي لمرفقات البريد الإلكتروني.

نشر Paperless-ngx خطوة بخطوة

تجهيز الخادم VPS والأحجام

ثبّت Docker، ثم أنشئ المجلدات الدائمة: consume (نقطة إسقاط مُراقَبة) وmedia (الأرشيف المعالَج بـOCR) وdata وexport. سيكون مجلد consume صندوق وارد مستنداتك.

جلب ملف compose الرسمي

يوفّر المشروع سكربت تثبيت تفاعليًا، لكن في الإنتاج انطلق من ملف docker-compose.yml الرسمي الذي يعلن webserver وbroker (Redis) وdb (PostgreSQL) والعامل (worker). عدّل مسارات الأحجام لتشير إلى المجلدات التي أنشأتها.

إعداد لغات OCR والأسرار

في ملف البيئة، عيّن PAPERLESS_OCR_LANGUAGE=fra+eng+ara، وPAPERLESS_SECRET_KEY المولَّد بـopenssl rand -base64 48، والعنوان العام PAPERLESS_URL=https://docs.yourcompany.com.

إنشاء المستخدم الفائق والبدء

شغّل docker compose up -d، ثم أنشئ المسؤول بـdocker compose run --rm webserver createsuperuser. بعدها سجّل الدخول إلى الواجهة للتحقق من أن العمّال (workers) يعالجون طابور المهام بشكل صحيح.

إضافة وكيل عكسي وSSL

ضع Caddy أمام خدمة الويب لـdocs.yourcompany.com، مع شهادة Let's Encrypt تلقائية. زِد الحدّ الأقصى لحجم الرفع في الوكيل لقبول ملفات PDF الممسوحة الكبيرة دون خطأ 413.

توصيل الاستيراد عبر البريد الإلكتروني

من Administration، اضبط حساب IMAP مخصّصًا: سيجلب Paperless-ngx مرفقات الرسائل الواردة، ويعالجها بـOCR، ويصنّفها تلقائيًا وفق قواعد المطابقة لديك.

عرّف المُراسِلين وأنواع المستندات بقواعد مطابقة تلقائية (بالكلمة المفتاحية أو التعبير النمطي) منذ البداية. يتعلّم Paperless-ngx أيضًا عبر التصنيف: بعد وسم نحو خمسين مستندًا يدويًا، فعّل المصنِّف التلقائي كي يقترح وحده وسوم الملفات الجديدة. وبدمجه مع مجلد consume المُراقَب، تحصل على سلسلة تلقائية بالكامل من المسح إلى الأرشيف المفهرس.

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

تفتح REST API الخاصة بـ Paperless-ngx (المتاحة على /api/ مع توثيق Swagger) إمكانات كثيرة. في n8n، يمكن لعقدة HTTP Request أن تطلق استيعاب وثيقة فور وصول فاتورة إلى صندوق Gmail. ومع Nextcloud، تتيح إضافة Paperless-ngx إرسال الملفات مباشرة إلى نظام إدارة الوثائق من واجهة Nextcloud. وفي خطوط التكامل المستمر، يكفي أمر curl لرفع ملف PDF لتقرير البناء عند نجاح النشر، مع تطبيق الوسمين #ci و#deploy تلقائيًا.

الانتقال من Paperless-ngx v2 إلى v3 : ثلاث نقاط إعاقة

يستبدل الإصدار v3 من Paperless-ngx محرّك البحث النصي ‎Whoosh بـ‎Tantivy. يحسّن هذا التغيير أداء الفهرسة لكنه يُبطل بصمت استعلامات العروض المحفوظة الموجودة: تظل العروض مرئية في الواجهة لكنها لا تُعيد أي نتائج. يضاف إلى ذلك أن مشكلتين في البنية التحتية تعوقان بدء تشغيل الـworker على خوادم VPS التي لا تملك وصولاً شبكيًا صادرًا غير مقيّد: محاولة تجميع مكتبة C الخاصة بـ‎psycopg-c عند الإطلاق الأول، وحدّ واصفات الملفات المنخفض الذي لا يستوعب ‎Celery وRedis معًا. لا تظهر هذه النقاط الثلاث في دليل الترحيل الرسمي لـv3 — إغفالها يؤدي إلى worker لا يبدأ أبدًا أو أرشيف لا تعمل فيه المرشّحات المحفوظة بعد التحديث.

إجراءات الترحيل من v2 إلى v3

نسخ احتياطي لقاعدة البيانات والوسائط

قبل أي تحديث، صدِّر قاعدة بيانات PostgreSQL بـdocker compose exec db pg_dump -U paperless paperless > backup-$(date +%F).sql وأنشئ أرشيفًا لحجم media الذي يحتوي جميع ملفاتك الأصلية والمعالَجة بـ‎OCR. الترحيل دون نسخة احتياطية مسبقة لا يمكن التراجع عنه.

تحديث الصورة وإعادة التشغيل

في ملف docker-compose.yml الخاص بك، حدّث وسم صورة ghcr.io/paperless-ngx/paperless-ngx إلى إصدار v3 المستهدف. ثم نفّذ docker compose pull تليها docker compose up -d. يطبّق الـworker ترحيلات قاعدة البيانات عند بدء التشغيل.

إعادة إنشاء العروض المحفوظة

بعد التحديث، استعرض كل عرض محفوظ في الواجهة (قائمة العروض). يستبدل ‎Tantivy محرّكَ ‎Whoosh النصي: الاستعلامات المُجمَّعة تحت v2 لم تعد صالحة. احذف كل عرض متأثر وأعد إنشاءه بالمعايير ذاتها — يعمل البحث النصي الكامل بشكل صحيح مجدّدًا بعد إعادة البناء.

ضبط PAPERLESS_OCR_LANGUAGE في ملف ‎.env

على خادم VPS لا يملك وصولاً شبكيًا صادرًا كاملاً، يحاول الحاوي تجميع مكتبة C الخاصة بـ‎psycopg-c عند الإطلاق الأول ويفشل دون رسالة خطأ واضحة، تاركًا الـworker في حالة انتظار. إضافة PAPERLESS_OCR_LANGUAGE=fra+eng صراحةً (أو اللغات التي تحتاجها) إلى ملف ‎‎.env قبل الإطلاق يتجنّب هذا البناء البارد. تحقق من سجل الـworker بـdocker compose logs worker إن لم يستجب الخدمة.

ضبط ulimits nofile في docker-compose.yml

يفتح ‎Celery وRedis معًا أكثر من 1024 واصف ملف تحت الحمل. الحدّ الافتراضي للنظام (ulimit -n 1024) يُوقف تشغيل الـworker دون تحذير مقروء. أضف الكتلة التالية إلى خدمة webserver وخدمة الـworker في ملف docker-compose.yml الخاص بك:

ulimits:
  nofile:
    soft: 65536
    hard: 65536

أعد التشغيل بعدها بـdocker compose up -d لكي يُؤخذ الحدّ بعين الاعتبار.

اختبر دائمًا على نسخة قبل الترحيل إلى الإنتاج. استعد نسختك الاحتياطية على خادم VPS ثانٍ أو في مشروع Docker ثانٍ، وطبّق ترحيل v3، وتحقق من أن عروضك المحفوظة وإدخال البريد الإلكتروني ونتائج البحث تتوافق مع توقعاتك. تعتمد مدة الفهرسة الأولية في ‎Tantivy على الحجم: خصّص عدة دقائق لأرشيف يضم آلاف المستندات.