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

‏Paperless-ngx هو التفرع المجتمعي الأكثر نشاطاً لمشروع Paperless — نظام لإدارة المستندات الإلكترونية يفهرس ملفات PDF والصور الممسوحة ضوئياً، ويستخرج النصوص منها عبر OCR، ويتيح العثور عليها بالكلمة المفتاحية أو التاريخ أو المراسل أو الوسم.

مقارنةً بالبدائل (‏Mayan EDMS وOpenDocMan)، يتميز Paperless-ngx بسهولة التثبيت (‏Docker Compose في أقل من 10 دقائق)، وواجهة ويب تفاعلية مكتوبة بـ Angular، ودعم OCR متعدد اللغات عبر Tesseract.

يتولى المجتمع صيانة المشروع ويصدر نسخاً بانتظام — تحقق من الإصدار الحالي في صفحة الإصدارات على GitHub قبل التثبيت.

حالات الاستخدام الشائعة:
- أرشيف فواتير الموردين لمقاولة ذاتية أو مؤسسة صغيرة ومتوسطة
- الملف الطبي الشخصي أو العائلي (وصفات، تحاليل، مراسلات)
- إدارة وثائق جمعية أو اتحاد ملاك
- أرشيف العقود وعقود الكراء لوكالة عقارية

‏Paperless-ngx أكثر استهلاكاً للموارد مما يبدو، خاصة عند الاستيراد. معالجة OCR لملف PDF متعدد الصفحات تُجهد المعالج بشدة — وهي المصدر الأول لانتهاء المهلة الزمنية على التهيئات الصغيرة.

الحد الأدنى الموصى به:
- المعالج: 2 vCPU (‏OCR أحادي الخيط لكل مهمة، لكن عدة مهام يمكن أن تعمل بالتوازي)
- الذاكرة: 2 جيجابايت كحد أدنى؛ 4 جيجابايت للاستخدام المريح
- التخزين: SSD، 20 جيجابايت كحد أدنى للتطبيق + احسب مساحة مستنداتك
- نظام التشغيل: Debian 12 أو Ubuntu 22.04/24.04

ما الذي يُنتج انتهاء المهلة على VPS الصغير: ملفات PDF الممسوحة بدقة عالية (300+ DPI) أو ذات صفحات كثيرة (50+) قد تتجاوز قيمة PAPERLESS_WORKER_TIMEOUT الافتراضية (1800 ثانية). القسم المخصص أدناه يغطي الحل.

يستخدم التثبيت الرسمي الموصى به Docker Compose مع ثلاث خدمات: webserver (التطبيق) وbroker (طابور المهام) وdb (قاعدة بيانات PostgreSQL).

⚠️ نزّل الملفات الثلاثة، لا ملف docker-compose.yml وحده. ملف compose الرسمي يعلن env_file: docker-compose.env: إعدادات الحاوية تُقرأ من ذلك الملف. أما ملف .env في المجلد فلا يضبط سوى COMPOSE_PROJECT_NAME=paperless — وهو ما يمنح الأحجام بادئتها paperless_ —، ويستعمله Docker Compose لاستبدال المتغيرات، ولا يحقنه في الحاويات. كتابة متغيرات PAPERLESS_* هناك هي الخطأ الصامت الأغلى في هذه الصفحة: الحاوية تقلع، والواجهة تستجيب، ولا يُطبَّق أي إعداد من إعداداتك.

# مجلد العمل
mkdir -p /opt/paperless && cd /opt/paperless

# الملفات الرسمية الثلاثة
BASE=https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose
curl -fsSL $BASE/docker-compose.postgres.yml -o docker-compose.yml
curl -fsSL $BASE/docker-compose.env          -o docker-compose.env
curl -fsSL $BASE/.env                        -o .env

# ولّد المفتاح قبل كتابة أي شيء: heredoc بعلامات اقتباس (<<'EOF') لا يُنفّذ أي
# استبدال، فيُكتب السطر حرفياً ويصير «السر» علنياً.
SECRET_KEY=$(openssl rand -hex 32)

# القالب يأتي بـ PAPERLESS_SECRET_KEY=change-me: يُستبدل، لا يُضاعف.
sed -i "s|^PAPERLESS_SECRET_KEY=.*|PAPERLESS_SECRET_KEY=$SECRET_KEY|" docker-compose.env

# بقية الإعدادات في نفس الملف (heredoc بلا اقتباس: $VAR يُستبدل فعلاً)
cat >> docker-compose.env <<EOF
PAPERLESS_URL=https://paperless.your-domain.com
PAPERLESS_TIME_ZONE=Africa/Casablanca
PAPERLESS_OCR_LANGUAGE=fra+eng+ara
PAPERLESS_OCR_LANGUAGES=fra ara
EOF

docker compose pull
docker compose up -d

# حساب المدير
docker compose exec webserver createsuperuser

المتغيرات PAPERLESS_DBENGINE وPAPERLESS_DBHOST وPAPERLESS_REDIS موجودة أصلاً في كتلة environment: داخل ملف compose الرسمي: لا تكررها في docker-compose.env. أما إذا كتبت ملف compose خاصاً بك، فإن PAPERLESS_DBENGINE=postgresql إلزامي ابتداءً من الإصدار 3 (انظر قسم الترقية).

تصبح الواجهة متاحة على المنفذ 8000 بعد نحو 60 ثانية من الإقلاع. ثم اضبط reverse proxy (‏nginx أو Traefik) لعرض الخدمة عبر TLS.

‏OCR هو جوهر Paperless-ngx. ضبطه يحدد جودة الفهرسة والقدرة على العثور على مستنداتك لاحقاً.

لغات Tesseract المتاحة: يقبل المتغير PAPERLESS_OCR_LANGUAGE رموز لغات Tesseract مفصولة بعلامة +. لرصيد وثائقي بالفرنسية والعربية والإنجليزية:

PAPERLESS_OCR_LANGUAGE=fra+ara+eng   # اللغات المستعملة في OCR
PAPERLESS_OCR_LANGUAGES=fra ara      # حزم Tesseract التي يجب تثبيتها (مفصولة بمسافات)

⚠️ المتغيران ضروريان معاً، وهذا أغلى فخ في هذه الصفحة. قيمة PAPERLESS_OCR_LANGUAGE الافتراضية هي eng، وهو لا يفعل سوى *اختيار* اللغة؛ ولأي لغة غير موجودة في الصورة، توجب الوثائق ضبط PAPERLESS_OCR_LANGUAGES أيضاً (قائمة مفصولة بـمسافات، لا بعلامات +) في عمليات النشر عبر Docker. بدونها يعود OCR بصمت إلى الإنجليزية: تُفهرس مستنداتك، لكن النص الفرنسي والعربي يبقى غير مقروء — ولا شيء في الواجهة يشير إلى ذلك.

تأتي الصورة أصلاً بالإنجليزية والألمانية والإيطالية والإسبانية والفرنسية؛ ما عداها هو ما يحتاج تثبيتاً. واحتفظ في ذهنك بأن Tesseract يستهلك معالجاً أكثر بكثير مع تفعيل عدة لغات: لا تعلن إلا ما تمسحه فعلاً.

وضع OCR: يتحكم PAPERLESS_OCR_MODE في متى يُطبَّق OCR. توجد أربع قيم — والقيمة skip، التي تُقرأ كثيراً، ليست واحدة منها:
- auto (الافتراضي): يتحقق Paperless عبر pdftotext مما إذا كان PDF يحمل نصاً بالفعل؛ فإن وُجد ما يكفي، يُتخطى OCR لذلك المستند، وإلا فيعمل بشكل طبيعي. وهو الخيار الأأمن لرصيد مختلط
- redo: يعيد تمرير OCR على كل الصفحات ويحاول استبدال طبقات النص الموجودة — مفيد حين ينتج الماسح الضوئي OCR رديئاً. قد يفشل على بعض المستندات (الاستمارات)، ويُحتفظ عندها بالنص الأصلي
- force: يحوّل المستند إلى صور، فيصير النص صورة، ثم يضع OCR فوقه. يعمل في كل الحالات، لكن حجم الملف يكبر والنص يبدو أقل وضوحاً عند التكبير
- off: لا يستدعي OCR أبداً؛ في ملفات PDF يُستخرج النص بـpdftotext وحده، وتخرج الصور بلا نص

في معظم الاستعمالات اترك القيمة auto: فهي تتجنب إعادة معالجة ملفات PDF الأصلية رقمياً (العقود، الفواتير الصادرة عن برنامج) دون أن تضبط أي شيء.

الاكتشاف التلقائي للتواريخ من أقوى ميزات Paperless-ngx — ومن أكثرها إثارة للإحباط حين لا تعمل. افتراضياً يحاول Paperless-ngx اكتشاف تاريخ المستند داخل محتواه النصي وفي اسم ملفه. وعدة أسباب قد تؤدي إلى تاريخ خاطئ أو غائب.

المشكلة الأولى: التاريخ بتنسيق غير معروف. يكتشف Paperless-ngx التنسيقات الشائعة (DD/MM/YYYY وYYYY-MM-DD وغيرها) لكنه قد يخطئ في التنسيقات الملتبسة (08/09/2025: الثامن من شتنبر أم التاسع من غشت؟).

الحل: التحقق — لا «الضبط» — من ترتيب القراءة. قيمة PAPERLESS_DATE_ORDER هي أصلاً DMY افتراضياً، أي اليوم ثم الشهر ثم السنة: وضعها صراحةً لا يغيّر شيئاً ولا يحل أي التباس. هذا الإعداد لا يفيد إلا في الخروج عن ذلك الترتيب، مثلاً لرصيد من وثائق أمريكية:

PAPERLESS_DATE_ORDER=MDY  # MM/DD/YYYY — لا تضعه إلا إذا كانت مستنداتك مؤرخة هكذا

وفي رصيد مختلط لا يمكن لأي ترتيب عام أن يكون صحيحاً: تسمية الملفات (المشكلة الثالثة أدناه) هي التي تحسم.

المشكلة الثانية: المستند يحمل تواريخ متعددة فيُختار الخاطئ منها. مثلاً فاتورة تذكر تاريخ الخدمة وتاريخ الإصدار معاً — يأخذ Paperless-ngx أول ما يجد.

الحل: استخدام حقل التاريخ اليدوي في الواجهة لتصحيح المستندات سيئة التأريخ، أو ضبط قواعد المطابقة (Matching rules) التي تسند تاريخاً انطلاقاً من اسم الملف.

المشكلة الثالثة: يُستعمل تاريخ إنشاء الملف بدلاً منه. حين لا يُعثر على أي تاريخ في المحتوى، يلجأ Paperless-ngx إلى تاريخ تعديل الملف — وهو أمر شديد التضليل مع وثائق قديمة مُسحت حديثاً.

الحل: تسمية ملفات الاستيراد بتاريخ المستند (YYYY-MM-DD_اسم-المستند.pdf) — يكتشف Paperless-ngx هذا التنسيق في اسم الملف قبل تحليل المحتوى.

على VPS بمعالج أو معالجَي vCPU، قد تتجاوز معالجة OCR للمستندات الكبيرة المهلة الافتراضية وتترك المستند في حالة «في انتظار المعالجة» إلى ما لا نهاية.

التشخيص: راجع سجلات العامل:

docker compose logs celery --tail=50

السطور التي تحمل SoftTimeLimitExceeded تؤكد انتهاء المهلة.

الحل — أربع روافع:

1. زيادة مهلة المهام:

PAPERLESS_WORKER_TIMEOUT=3600  # ساعة واحدة (الافتراضي: 1800 ثانية)

⚠️ الاسم الدقيق مهم: PAPERLESS_WORKER_TIMEOUT. إعداد مكتوب بخطأ إملائي لا يرفضه Paperless — بل يُتجاهل بصمت، وتستمر المهل في الانتهاء كما كانت تماماً، وهو ما يُقرأ خطأً على أنه «الإصلاح لم ينفع».

2. تقليل دقة الاستيراد. إن كنت تمسح المستندات بنفسك، فإن 200 DPI تكفي لجودة OCR جيدة — و300 DPI تضاعف زمن المعالجة دون تحسن ملموس في النص العادي.

3. تحديد المعالجة المتوازية:

PAPERLESS_TASK_WORKERS=1        # المهام المتوازية (الافتراضي: 1)
PAPERLESS_THREADS_PER_WORKER=1  # الصفحات المعالَجة بالتوازي داخل مستند واحد

إن لم يُضبط، فقيمة PAPERLESS_THREADS_PER_WORKER هي max(floor(عدد_النوى / PAPERLESS_TASK_WORKERS), 1). والقاعدة التي لا يجوز تجاوزها حسب المشروع: حاصل ضرب TASK_WORKERS × THREADS_PER_WORKER يجب ألا يتجاوز عدد النوى، وإلا صارت النسخة بطيئة للغاية. عمّال كثيرون = مستندات كثيرة بالتوازي؛ خيوط كثيرة = مستند ضخم يُعالَج أسرع.
على VPS بمعالجَين، معالجة مستندين في آن واحد قد تُنتج انتهاء مهلة كانت المعالجة التتابعية لنفس الحجم لتتجنبه.

4. تحسين المعالجة القبلية لـ PDF:

PAPERLESS_OCR_USER_ARGS={"optimize": 1, "pdfa-image-compression": "jpeg"}

هذا يضغط الصور داخل ملفات PDF قبل المعالجة، فيخفف الحمل على الذاكرة والمعالج.

تجلب سلسلة ‎3.x تغييرات هيكلية تجعل الترقية في المكان إلزامية، وتضيف شروطاً مسبقة لم تكن موجودة في الفرع ‎2.x.

الشرط المسبق الذي يُنسى: الترقية إلى الإصدار 3 مدعومة انطلاقاً من 2.20.15 فقط. إن كنت تشغّل إصداراً أقدم، فرقِّ أولاً إلى 2.20.15 ثم انتقل بعدها إلى ‎3.x. تغيير وسم الصورة مباشرةً من 2.14 إلى ‎3.x ليس مساراً مدعوماً.

التصدير/الاستيراد بين الإصدارات (document_exporter ثم document_importer على نسخة جديدة) غير مدعوم: فالتصدير يحمل نسخة طبق الأصل من قاعدة البيانات ولا يُستورَد في إصدار آخر. عملياً ينبّه document_importer (Version mismatch: Currently 3.1.x, importing 2.20.15. Continuing, but import may fail.) ثم يفشل بخطأ KeyError: 'show_on_dashboard'، وهو حقل أُعيدت تسميته في السلسلة ‎3.x. الطريق الآمن الوحيد هو ترك الهجرات تُطبَّق على قاعدة البيانات القائمة.

الإجراء الموصى به:

1. خذ نسخة احتياطية كاملة قبل أي شيء (انظر القسم المخصص أدناه).
2. أوقف الخدمات: docker compose down.
3. راجع في docker-compose.env وفي ملف docker-compose.yml الإعدادات الثلاثة التي يجعلها الإصدار 3 إلزامية أو يغيّرها (أدناه).
4. وجّه صورة docker-compose.yml إلى إصدار ‎3.x المستهدف وأعد التشغيل: docker compose up -d — تُطبَّق هجرات Django تلقائياً عند إقلاع webserver.
5. راقب السجلات: docker compose logs webserver --tail=100 — الهجرة الفاشلة تعرض الخطأ وتمنع الإقلاع.

‏PAPERLESS_SECRET_KEY يصير إلزامياً. كان هناك سابقاً مفتاح داخلي افتراضي؛ في الإصدار 3 يجب التصريح به. إعادة استعمال القيمة السابقة تحفظ الجلسات والرموز الموقَّعة، ووضع قيمة جديدة يُبطلها كلها.

‏PAPERLESS_DBENGINE يصير إلزامياً مع PostgreSQL أو MariaDB. في الإصدار 2 كان المحرك يُستنتج من وجود PAPERLESS_DBHOST؛ وفي الإصدار 3 يجب التصريح به، والقيمة الافتراضية هي sqlite. والقيم المقبولة هي sqlite وpostgresql وmariadb — لا غير:

# v2 (PostgreSQL مستنتَج من PAPERLESS_DBHOST)
PAPERLESS_DBHOST: db
# v3 (المحرك يجب أن يكون صريحاً)
PAPERLESS_DBENGINE: postgresql
PAPERLESS_DBHOST: db

القيمة PAPERLESS_OCR_MODE=skip تختفي. حُذفت القيمتان skip وskip_noarchive، والمتغير المحذوف لا يُطبَّق بصمت: يُسجَّل تنبيه عند الإقلاع. والحفاظ على سلوك الإصدار 2 يقتضي توزيع النية على إعدادين صارا مستقلين:

# v2: تخطَّ OCR إن وُجد نص، لكن أنشئ الأرشيف دائماً
PAPERLESS_OCR_MODE=skip
# v3: المكافئ
PAPERLESS_OCR_MODE=auto
PAPERLESS_ARCHIVE_FILE_GENERATION=always

عدم توافق ‎Redis → Valkey. منذ الإصدار 3 يأتي ملف compose الرسمي بـValkey وسيطاً (valkey/valkey:9-alpine) لا بـ Redis: ليس خياراً منك، بل هو ما تحصل عليه إن استبدلت ملف compose الخاص بك بقالب المشروع. وإذا كان حجم الوسيط قد أنشأته نسخة حديثة من Redis، يرفض Valkey تحميله وتدخل الحاوية في حلقة إعادة تشغيل مع الخطأ Can't handle RDB format version 15 (أو 13 حسب المصدر)، بينما يظل webserver في انتظار الوسيط. والحل هو حذف حجم الوسيط قبل التبديل: فهو لا يحوي سوى مهام في الطابور، ولا بيانات دائمة حرجة.

docker compose down
docker volume rm paperless_redisdata   # البادئة تأتي من COMPOSE_PROJECT_NAME
docker compose up -d

فهرس البحث يُعاد بناؤه وحده. يستبدل الإصدار 3 محرك Whoosh بـ Tantivy، والصيغتان غير متوافقتين: يُعاد توليد الفهرس من الصفر عند أول إقلاع (تشغّل الحاوية document_index reindex --if-needed في كل بداية)، وهذا ما يفسر إقلاعاً أول أبطأ من المعتاد. وإن فشل استهلاك المستندات بعد الترقية بالخطأ Schema error: 'An index exists but the schema does not match.'، فافرض إعادة بناء نظيفة بـ docker compose exec webserver document_index reindex --recreate. وانتبه أيضاً لصيغة البحث: note: تصير notes.note: وcustom_field: تصير custom_fields.value: — العروض المحفوظة ببادئة صريحة تُهاجَر وحدها، أما بحث بلا بادئة كان يعثر على ملاحظة فلن يعثر عليها بعد اليوم.

تغييران في السلوك يفاجئان. يُمحى سجل المهام أثناء الترقية، ولم يعد الإصدار 3 يرفض المستندات المكرَّرة افتراضياً: إن كنت تعتمد على ذلك الرفض، فأعد تفعيله بـ PAPERLESS_CONSUMER_DELETE_DUPLICATES=true. وخلف reverse proxy، تغيّرت طريقة تحديد عنوان IP للعميل في تحديد معدل تسجيل الدخول: إن أعاد تسجيل الدخول الخطأ 403 Forbidden بعد الترقية، فصرّح بسلسلة الوسطاء عبر PAPERLESS_TRUSTED_PROXIES وعند الحاجة PAPERLESS_ALLAUTH_TRUSTED_PROXY_COUNT.

بخصوص MariaDB. لا تزال مدعومة (PAPERLESS_DBENGINE=mariadb)، وإن كان المشروع يوصي بـ PostgreSQL. أما إخفاقات الهجرة على Debian 12 المتداولة في المنتديات فمصدرها تثبيتات مباشرة على النظام فُكَّت فيها النسخة الجديدة فوق القديمة: ملفات الهجرة المتقادمة الباقية على القرص تُنتج خطأ NodeNotFoundError عند manage.py migrate. والعلاج هو حذف شجرة المصادر السابقة (src/ وstatic/) قبل النشر، لا العبث بمحرك قاعدة البيانات — وفي نشر عبر Docker كالذي يصفه هذا الدليل، لا يقع هذا السيناريو أصلاً.

البريد بعد الترقية. الأمر الذي يفرض جلب البريد هو mail_fetcher، بلا وسائط؛ وهو يعالج كل الحسابات والقواعد المضبوطة:

docker compose exec webserver mail_fetcher

وإن توقف سير عمل بريدي عن إنتاج المستندات بعد الترقية، فانظر أولاً إلى خطأ المهمة في الواجهة: الحالات المبلَّغ عنها كانت تشير إلى فهرس البحث (Schema error أعلاه) لا إلى بيانات الاعتماد. ثم تحقق من أن الحساب ما زال يملك صلاحيات IMAP؛ وإن كنت تستعمل رمز OAuth، فأشِّر على الخانة التي تفيد بأن كلمة السر هي في الواقع رمز.

يدير Paperless-ngx نوعين من البيانات الحيوية: قاعدة بيانات PostgreSQL (البيانات الوصفية والوسوم والمراسلون والقواعد) وملفات المستندات. ويجب أخذ نسخة احتياطية من الاثنين — أحدهما دون الآخر لا يستعيد شيئاً مفيداً.

سكريبت النسخ الاحتياطي اليومي:

#!/bin/bash
BACKUP_DIR="/backups/paperless/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# تفريغ PostgreSQL
docker compose exec -T db pg_dump -U paperless paperless \
  | gzip > "$BACKUP_DIR/db.sql.gz"

# التصدير الأصلي لـ Paperless (يشمل الإعدادات والمستندات)
docker compose exec -T webserver document_exporter ../export
tar -czf "$BACKUP_DIR/export.tar.gz" /opt/paperless/export/

# التدوير — الاحتفاظ بـ 14 يوماً
find /backups/paperless -maxdepth 1 -type d -mtime +14 -exec rm -rf {} +

echo "انتهى النسخ الاحتياطي: $BACKUP_DIR"

جدوِل هذا السكريبت في cron (0 3 * * * عند الثالثة صباحاً)، وتحقق من وصول النسخ إلى تخزين خارج الخادم (‏rsync نحو دلو S3 أو نحو خادم آخر). والخيار -T بعد exec يتفادى خطأ «the input device is not a TTY» حين يعمل السكريبت بلا طرفية.

يُصدر Paperless-ngx نسخاً بانتظام. والتحديث بسيط مع Docker Compose:

# سحب الصورة الجديدة
docker compose pull

# إعادة تشغيل الخدمات (هجرات قاعدة البيانات تُطبَّق تلقائياً)
docker compose up -d

# التحقق من أن كل شيء على ما يرام
docker compose logs webserver --tail=20

قبل كل تحديث رئيسي: اقرأ CHANGELOG على GitHub — الإصدارات الرئيسية (‎v2.x → ‎v3.x) قد تتطلب خطوات هجرة إضافية، وأحياناً إصداراً وسيطاً إلزامياً. ويفصّل القسم السابق التعارضات المعروفة لسلسلة ‎3.x.

المراقبة: لا يكشف Paperless-ngx نقطة نهاية /metrics خاصة به. الموجود هو Flower، مُراقب مهام Celery، ويُفعَّل بضبط PAPERLESS_ENABLE_FLOWER؛ وهو الذي يُصدر مقاييس قابلة للاستهلاك من Prometheus، فضلاً عن عرض المهام الجارية والمنتظرة والمكتملة. وهو المكان الصحيح لرصد معالجة تتوقف بصمت — وهو بالضبط عَرَض انتهاء مهلة OCR.