ابدأ مجانا
EN
شروحات تقنية 18 دقيقة قراءة

تثبيت ERPNext v15 على Debian 12 / Ubuntu 22.04 LTS: الدليل الحقيقي من مهندس DevOps

يثبّت هذا الدليل ERPNext v15 (أحدث إصدار مستقر) على Debian 12 (Bookworm) أو Ubuntu 22.04 LTS. وكل أمر فيه مجرّب على خادم نظيف فعلاً. قبل أن تبدأ، افهم أن ERPNext ليس 'برنامجاً واحداً'، بل نظام يعتمد على 7 خدمات يجب أن تعمل معاً بشكل صحيح. وهذا هو السبب الحقيقي لفشل التثبيت عند معظم الناس. يشرح هذا الدليل سبب وجود كل خدمة لتفهم ما تبنيه، لا أن تنسخ أوامر بشكل أعمى.

ما الذي تثبّته فعلاً (اقرأ هذا الجزء أولاً)

يعمل ERPNext على إطار عمل اسمه Frappe. ويعتمد الاثنان معاً على 7 خدمات: (1) MariaDB 10.11 — يخزن كل بياناتك في جداول، (2) Redis 7 — يخزن بيانات مؤقتة مثل جلسات المستخدمين وقوائم انتظار المهام الخلفية، (3) Python 3.11 — يشغّل كود تطبيق Frappe/ERPNext، (4) Node.js 18 LTS — يبني الـ JavaScript/CSS للمتصفح، (5) Supervisor — يبقي كل الخدمات عاملة ويعيد تشغيلها عند سقوطها، (6) Nginx — خادم الويب الذي يتصل به المستخدمون، (7) wkhtmltopdf — يحوّل HTML إلى PDF لطباعة الفواتير. وإذا لم تُضبط أي خدمة منها بشكل صحيح، فلن يعمل ERPNext.

الإصدارات المستخدمة في هذا الدليل

نظام التشغيل: Debian 12 (Bookworm) أو Ubuntu 22.04 LTS | ERPNext: v15.x (أحدث إصدار مستقر) | Python: 3.11.x | MariaDB: 10.11.x | Node.js: 18.x LTS | Redis: 7.x | wkhtmltopdf: 0.12.6

متطلبات الخادم — لا تنزل عن هذا الحد

الحد الأدنى للاختبار: 2 CPU، و4 جيجا رام، و40 جيجا SSD. الحد الأدنى للإنتاج حتى 25 مستخدماً: 4 CPU، و8 جيجا رام، و80 جيجا SSD. ومن 25 إلى 100 مستخدم: 8 CPU، و16 جيجا رام، و160 جيجا SSD. والعمل على خادم بأقل من 4 جيجا رام يجعل خطوة بناء الـ JavaScript تنتهي بفشل صامت بسبب نقص الذاكرة.

الخطوة الأولى — تجهيز الخادم (السبب: الخادم القديم يكسر التثبيت)

ابدأ دائماً بنظام محدّث. فالحزم القديمة قد تتعارض مع ما يحتاجه ERPNext. تستغرق هذه الخطوة من 2 إلى 5 دقائق.

bash 
# تحديث قائمة الحزم وترقية كل الحزم الموجودة
sudo apt update && sudo apt upgrade -y

# تثبيت أدوات البناء الأساسية التي تحتاجها حزم Python للتجميع
sudo apt install -y \
  git curl wget \
  python3-dev python3-pip python3-venv \
  build-essential \
  libffi-dev libssl-dev \
  libjpeg-dev zlib1g-dev \
  libmysqlclient-dev pkg-config \
  xvfb libfontconfig fontconfig \
  redis-server supervisor nginx \
  cron
ماذا تفعل هذه الحزم؟

تتيح python3-dev و libmysqlclient-dev للغة Python تجميع موصلات قواعد البيانات من المصدر. وتحتاجها مكتبة التشفير في Python — libffi-dev و libssl-dev — للربط مع ZATCA/ETA. ويطلب wkhtmltopdf كلاً من xvfb و libfontconfig لعرض PDF دون شاشة.

الخطوة الثانية — تثبيت MariaDB 10.11 (السبب: يحتاج ERPNext إعدادات خاصة غير موجودة في الإصدار الافتراضي)

إصدار MariaDB في مستودع Debian/Ubuntu الافتراضي قديم أو تنقصه الميزات المطلوبة. لذلك نثبّت MariaDB 10.11 LTS مباشرة من المستودع الرسمي لـ MariaDB.

bash 
# تثبيت سكربت إعداد مستودع MariaDB
curl -LsS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash -s -- --mariadb-server-version=10.11

# تثبيت MariaDB
sudo apt update
sudo apt install -y mariadb-server mariadb-client

# التحقق من الإصدار المثبت
mysql --version
# المتوقع: mysql  Ver 15.1 Distrib 10.11.x-MariaDB

شغّل معالج الأمان. سيحذف قواعد البيانات التجريبية ويضبط كلمة مرور root:

bash 
sudo mysql_secure_installation
# الإجابات: N (لا لمصادقة المقبس), Y (نعم لكلمة مرور root), Y, Y, Y, Y

والآن طبّق إعدادات MariaDB الخاصة بـ ERPNext. فدونها لن يستطيع ERPNext إنشاء قواعد بيانات بدعم عربي:

bash 
sudo nano /etc/mysql/mariadb.conf.d/50-erpnext.cnf

الصق هذه الإعدادات:

ini 
[mysqld]
# مجموعة الأحرف — مطلوبة للبيانات العربية والفارسية وكل Unicode
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

# إعدادات InnoDB — مطلوبة لصيغة صفوف ERPNext
innodb-file-format = barracuda
innodb-file-per-table = 1
innodb-large-prefix = 1

# الأداء: اضبط على 50-70% من إجمالي RAM
# سيرفر 4 جيجا = 2G, سيرفر 8 جيجا = 5G, سيرفر 16 جيجا = 10G
innodb_buffer_pool_size = 2G

# منع انتهاء المهلة في التقارير الطويلة
wait_timeout = 28800
interactive_timeout = 28800

[mysql]
default-character-set = utf8mb4

[client]
default-character-set = utf8mb4
bash 
# إعادة تشغيل MariaDB لتطبيق الإعدادات
sudo systemctl restart mariadb
sudo systemctl enable mariadb

# التحقق من صحة مجموعة الأحرف
mysql -u root -p -e "SHOW VARIABLES LIKE 'character_set_server';"
# المفروض يظهر: utf8mb4
أكثر خطأ شائع هنا

إذا تجاوزت إعداد مجموعة الأحرف ثم ظهر لك خطأ 'Incorrect string value' عند حفظ نص عربي، فهذا هو السبب. ولا يمكن إصلاحه بعد دخول البيانات إلا عبر عملية ترحيل موجعة. افعله الآن.

الخطوة الثالثة — تثبيت Node.js 18 LTS (السبب: يتطلب بناء JavaScript في ERPNext الإصدار 18 تحديداً)

يتطلب ERPNext v15 الإصدار Node.js 18 LTS. أما Node.js 20 أو 21 فسيسبب فشل البناء. وإصدار Node.js الافتراضي في النظام خاطئ. ثبّت من المستودع الرسمي:

bash 
# تثبيت Node.js 18 LTS من NodeSource
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# التحقق — المفروض يظهر v18.x.x
node --version

# تثبيت yarn (مدير الحزم الذي يستخدمه ERPNext)
sudo npm install -g yarn
yarn --version

الخطوة الرابعة — تثبيت wkhtmltopdf 0.12.6 (السبب: الإصدار في المستودعات يطبع PDF فارغة)

نسخة wkhtmltopdf الموجودة في مستودعات Ubuntu/Debian لا تدعم مزايا 'headless' التي يستخدمها ERPNext. عليك تثبيت النسخة 0.12.6 مع Qt المرقّع. والفواتير الفارغة أو المكسورة سببها دائماً النسخة الخاطئة.

bash 
# تنزيل الإصدار الصحيح حسب نظامك
# لـ Ubuntu 22.04 (Jammy):
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb

# لـ Debian 12 (Bookworm):
# wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.bookworm_amd64.deb

# التثبيت
sudo apt install -y ./wkhtmltox_0.12.6.1-3.jammy_amd64.deb

# التحقق
wkhtmltopdf --version
# المفروض يظهر: wkhtmltopdf 0.12.6.1 (with patched qt)
جزء '(with patched qt)' مهم

إذا لم يحتوِ الناتج على 'with patched qt'، فستكون فواتيرك بصيغة PDF فارغة أو ناقصة الـ CSS. احذفه وأعد تثبيت الملف الثنائي الصحيح من رابط GitHub أعلاه.

الخطوة الخامسة — إنشاء مستخدم نظام مخصص (السبب: لا تشغّل ERPNext كـ root أبداً)

يجب أن يعمل ERPNext بمستخدم غير root حفاظاً على الأمان. وهذا المستخدم يملك كل ملفات ERPNext وعملياته. سننشئ مستخدماً اسمه 'frappe'.

bash 
# إنشاء مستخدم frappe بدليل رئيسي
sudo adduser --disabled-password --gecos '' frappe

# منح مستخدم frappe صلاحيات sudo (مطلوبة أثناء التثبيت فقط)
sudo usermod -aG sudo frappe

# التحول لمستخدم frappe لبقية الخطوات
sudo su - frappe
كل الأوامر من هنا: شغّلها كمستخدم 'frappe'

أنت الآن داخل بحساب 'frappe'. ويجب أن يظهر في سطر الأوامر 'frappe@اسم-خادمك'. لا تعد إلى root في الخطوات التالية إلا حين يُطلب منك صراحة.

الخطوة السادسة — تثبيت Frappe Bench (السبب: bench هو الأداة التي تدير كل شيء)

Frappe Bench أداة سطر أوامر (مثل git أو npm) تثبّت ERPNext وتنشئ المواقع وتدير النظام كله. اعتبره لوحة التحكم لكل شيء.

bash 
# تثبيت bench باستخدام pip (كمستخدم frappe)
pip3 install frappe-bench

# التحقق من تثبيت bench
bench --version
# المفروض يظهر: 5.x.x أو أعلى

# لو ما لقاش 'bench'، ضيف pip bin لـ PATH:
export PATH=$PATH:~/.local/bin
echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc

انتهت 6 خطوات والمنظومة لم تعرض صفحة بعد. مانجلي يمنحك نسخة عاملة في 3 دقائق دون طرفية إطلاقاً.

تجاوز التثبيت

الخطوة السابعة — تهيئة Frappe Bench وتنزيل ERPNext v15

تنزّل هذه الخطوة إطار عمل Frappe (فرع v15)، وتنشئ بيئة Python افتراضية، وتجهّز هيكل المجلدات. وتستغرق من 5 إلى 15 دقيقة حسب سرعة الاتصال.

bash 
# تهيئة bench مع Frappe v15 — ينزل ~200 ميجابايت
bench init --frappe-branch version-15 frappe-bench

# الانتقال لمجلد bench (ابق هنا لبقية الدليل)
cd ~/frappe-bench

والآن نزّل تطبيق ERPNext نفسه:

bash 
# تنزيل ERPNext v15
bench get-app erpnext --branch version-15

# اختياري لكن موصى به: تنزيل وحدة HR بشكل منفصل
bench get-app hrms --branch version-15

# التحقق من تنزيل التطبيقات
bench version
# المفروض يعرض: frappe, erpnext, (hrms)

الخطوة الثامنة — إنشاء أول موقع ERPNext

'الموقع' في ERPNext هو قاعدة بيانات وإعداد معزولان تماماً لشركة واحدة. ويمكن أن يكون لديك أكثر من موقع على الخادم نفسه. غيّر 'mycompany.local' إلى اسم نطاقك.

bash 
# إنشاء موقع جديد
# استبدل 'mycompany.local' بنطاقك
# استبدل 'كلمة_مرور_DB' بكلمة مرور root لـ MariaDB التي ضبطتها في الخطوة الثانية
# استبدل 'كلمة_مرور_الأدمين' بكلمة المرور التي تريدها لمستخدم أدمين ERPNext

bench new-site mycompany.local \
  --mariadb-root-password كلمة_مرور_DB \
  --admin-password كلمة_مرور_الأدمين \
  --no-mariadb-socket

ثبّت ERPNext (وHRMS) على هذا الموقع:

bash 
# تثبيت تطبيق ERPNext على الموقع
bench --site mycompany.local install-app erpnext

# تثبيت HRMS لو نزلته
bench --site mycompany.local install-app hrms

# اضبط هذا كموقع افتراضي
bench use mycompany.local
اختبار سريع قبل إعداد الإنتاج

شغّل 'bench start' لبدء خادم التطوير. افتح http://IP_السيرفر:8000 في متصفحك. سجّل الدخول بـ 'Administrator' وكلمة المرور التي ضبطتها. فإذا نجح الدخول، فكل شيء يعمل. اضغط Ctrl+C لإيقاف خادم التطوير.

الخطوة التاسعة — الإعداد الإنتاجي: Nginx وSupervisor وSSL

خادم التطوير (bench start) للاختبار فقط. أما للإنتاج فتحتاج Nginx كخادم ويب وSupervisor لتشغيل ERPNext كخدمة خلفية. شغّل هذه الأوامر كـ root (اخرج من مستخدم frappe أولاً).

bash 
# الخروج لمستخدم root/sudo
exit

# إعداد وضع الإنتاج — يهيئ Nginx وSupervisor تلقائياً
sudo bench setup production frappe --yes

# إعادة توليد إعداد Nginx
sudo bench setup nginx
sudo nginx -t  # اختبار إعداد nginx — المفروض يقول 'syntax is ok'
sudo systemctl reload nginx

اضبط SSL (HTTPS) بـ Let's Encrypt. ويجب أن يكون نطاقك مؤشَّراً إلى IP هذا الخادم قبل تشغيل الأمر:

bash 
# تثبيت certbot
sudo apt install -y certbot python3-certbot-nginx

# الحصول على شهادة SSL (استبدل بنطاقك الفعلي)
sudo certbot --nginx -d mycompany.com --non-interactive --agree-tos -m [email protected]

# التحقق من عمل التجديد التلقائي
sudo certbot renew --dry-run
bash 
# التحقق من تشغيل كل الخدمات
sudo supervisorctl status
# المفروض تظهر كل الخدمات: RUNNING

sudo systemctl status nginx
# المفروض يظهر: active (running)

Nginx وSupervisor وSSL هي بالضبط الجزء الذي يسقط الساعة 2 ليلاً. نتحملها عنك.

شاهد ما نشغّله بالضبط

الخطوة العاشرة — إعداد النسخ الاحتياطي التلقائي

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

bash 
# إضافة نسخ احتياطي تلقائي — يعمل يومياً عند 2:30 صباحاً
crontab -e -u frappe

# أضف هذا السطر:
30 2 * * * cd /home/frappe/frappe-bench && bench --site mycompany.local backup --with-files >> /home/frappe/backup.log 2>&1

# تمكين النسخ الاحتياطي التلقائي المدمج في ERPNext (كل 6 ساعات)
bench --site mycompany.local set-config --global backup_limit 3
bench --site mycompany.local enable-scheduler
اختبار مكالمة الساعة 3 صباحاً

اسأل نفسك: لو تعطل قرص الخادم تماماً الساعة 3 فجر اليوم، أتستطيع استعادة كل شيء قبل الصباح؟ إذا كانت الإجابة لا، فخطة النسخ الاحتياطي لديك غير جاهزة للإنتاج. انسخ يومياً إلى S3 أو Google Cloud Storage أو خادم آخر. وملفات النسخ في: /home/frappe/frappe-bench/sites/mycompany.local/private/backups/

النسخة الاحتياطية على الخادم نفسه ليست نسخة احتياطية. لدينا نسخ احتياطي يومي خارج الخادم في كل الباقات.

انقل نسختي إلى مانجلي

الملخص الصريح: ماذا بنيت

إذا اتبعت كل خطوة، فلديك الآن خادم ERPNext v15 يعمل في الإنتاج. وما بنيته هو 7 خدمات تعمل معاً: MariaDB يخزن بياناتك، وRedis يمسك الذاكرة المؤقتة والطوابير، وPython يشغّل منطق ERPNext، وأصول Node.js يقدمها nginx، وsupervisor يبقي ذلك كله حياً. وما بقي عليك صيانته: تحديثات الأمان الشهرية، وترقيات إصدارات ERPNext السنوية (وهي مشاريع موجعة لا عمليات تلقائية)، وتجديد شهادات SSL، ومتابعة مساحة القرص.

تجاوز هذا كله

ينشر مانجلي كلاود ERPNext إنتاجياً في 3 دقائق وكل ما سبق مضبوط. امتثال ضريبي أصلي لـ ETA/ZATCA، وحسابات بلا حدود دون رسوم على المقعد، ونسخ احتياطي تلقائي، وتحديثات — كل ذلك داخل الاشتراك. استخدم هذا الدليل إذا أردت فهم ERPNext من الداخل. واستخدم مانجلي إذا أردت إدارة شركتك. تدفع كودك عبر Git فينشره النظام على قاعدة بياناتك المعزولة ونطاقك الخاص، وتصدّر بياناتك متى شئت.

لديك ERPNext مثبت؟ أرسل لنا النسخة الاحتياطية ونرفعها لك على مانجلي مجاناً. وإذا لم تجد فرقاً، خذ نسختك الاحتياطية وامضِ.

انقل نسختك مجاناً

10 خطوات الآن، و7 خدمات تسهر عليها.

تطبيقات المتجر على نفس بياناتك، حسب باقتك.

انقل نسختك مجانًا ارفع تطبيقك من Git

سيب تعليقك

التعليقات