التوثيق

ثبّت VendKit، وشغّله، وانشره.

ثبّت VendKit على خادمك، وشغّله محليًا، وافهم تهيئته، ثم انشره بثقة. كل أمر جاهز للنسخ.

راجعناه مقابل README ودليل النسخ الاحتياطي في مستودع VendKit في 21 نوفمبر 2026.

نظرة سريعة

بيئة التشغيل
Docker Compose
قاعدة البيانات
PostgreSQL 16+
الرابط المحلي
localhost:3000
الترخيص
AGPL-3.0
افتح المستودع
في هذه الصفحة

ابدأ من هنا

اختر طريقة تشغيل VendKit.

للتثبيت الفعلي، استخدم Docker Compose على خادم Linux. وللتطوير، شغّل المستودع محليًا باستخدام Node.js وPostgreSQL.

المتطلبات الأساسية

اعرف ما يحتاجه الخادم قبل أن تبدأ.

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

خادم الإنتاج

نقطة بداية مقترحة لمتجر واحد. لا يعلن VendKit حدًا صارمًا للسعة؛ اختر حجم القرص بحسب الصور والنسخ الاحتياطية، لا قاعدة البيانات وحدها.

نظام التشغيل
توزيعة Linux حديثة 64-بت تدعم Docker
بيئة الحاويات
Docker Engine مع إضافة Docker Compose
المعالج
2 vCPU كحد أدنى؛ 4 vCPU لمتجر مزدحم
الذاكرة
2 GB كحد أدنى؛ 4 GB موصى بها
القرص
20 GB إضافة إلى مساحة لصور المنتجات وأرشيفات النسخ الاحتياطي
الشبكة
عنوان IPv4 أو IPv6 عام، ونطاق، والمنفذان 80 و443

التطوير المحلي

استخدم المستودع الأحادي فقط عند العمل على الشيفرة. مسار Docker لا يحتاج Node.js أو PostgreSQL على الخادم.

Node.js
24 أو أحدث
pnpm
11 أو أحدث
PostgreSQL
16 أو أحدث، يعمل محليًا
Git
أي إصدار حديث

المنافذ والتعريض

لا ينشر Compose سوى تطبيق الويب. تبقى واجهة API وقاعدة البيانات على شبكة Docker الداخلية.

تطبيق الويب
3000، منشور؛ غيّره عبر WEB_PORT
واجهة API
4000، داخلي فقط
PostgreSQL
5432، داخلي فقط
HTTPS
443 على الوكيل العكسي

تخطيط القرص

تنمو صور المنتجات وأرشيفات النسخ الاحتياطي أسرع من قاعدة البيانات. أبقِ وحدة vendkit-data على قرص دائم، وراقب المساحة الحرة، وانسخ الأرشيفات خارج الخادم. النسخة الاحتياطية على القرص نفسه ليست خطة تعافٍ من الكوارث.

قبل التثبيت

جهّز هذه العناصر حتى لا يتعطل التشغيل الأول.

  • خادم Linux تستطيع إدارته، مع مستخدم sudo غير جذري
  • Docker Engine وإضافة Compose مثبتان
  • اسم نطاق تشير سجلات DNS فيه إلى الخادم
  • شهادة TLS، يصدرها الوكيل العكسي عادةً
  • خطة للنسخ الاحتياطي خارج الخادم وتحديثات النظام
  • اسم المدير وبريده الإلكتروني للحساب الأول

تحقق من الخادم

تأكد من توفر Docker وCompose وGit قبل الاستنساخ. ثبّت أي أمر ناقص أولًا.

الطرفية
docker --version
docker compose version
git --version

للتطوير المحلي، تحقق من أدوات اللغة وقاعدة البيانات:

الطرفية
node --version
pnpm --version
psql --version

التثبيت باستخدام Docker

من الاستنساخ إلى أول تسجيل دخول.

اتبع هذه الخطوات على خادم Linux لديه Docker وإضافة Compose. أمر الإعداد ينشئ الأسرار المطلوبة تلقائيًا.

قبل أن تبدأ

  • تثبيت Git
  • Docker مع إضافة Compose
  • تخزين دائم لوحدتَي التخزين vendkit-db وvendkit-data
  • وكيل عكسي مع HTTPS للنشر العام
  1. 01

    استنسخ المستودع

    نزّل الشيفرة إلى مجلد على خادمك. هذا هو مستودع VendKit العام على GitHub.

    الطرفية
    git clone https://github.com/MuawiyahDev/vendkit.git
    cd vendkit
  2. 02

    أنشئ ملف البيئة

    أنشئ الأسرار الثلاثة المطلوبة واكتبها في ملف .env جديد انطلاقًا من القالب. ويقصر الأمر صلاحية الملف على مستخدمك.

    الطرفية
    POSTGRES_PASSWORD="$(openssl rand -hex 24)"
    JWT_SECRET="$(openssl rand -hex 32)"
    API_KEY="$(openssl rand -hex 32)"
    
    awk -v pw="$POSTGRES_PASSWORD" -v jwt="$JWT_SECRET" -v key="$API_KEY" '
      /^POSTGRES_PASSWORD=/ { print "POSTGRES_PASSWORD=" pw; next }
      /^JWT_SECRET=/        { print "JWT_SECRET=" jwt; next }
      /^API_KEY=/           { print "API_KEY=" key; next }
      { print }
    ' .env.example > .env
    
    chmod 600 .env
  3. 03

    شغّل الحزمة

    تطبّق حاوية الـAPI الترحيلات تلقائيًا. قد يستغرق البناء الأول بضع دقائق.

    الطرفية
    docker compose up -d --build
  4. 04

    أنشئ الحساب الأول

    افتح التطبيق وأنشئ حساب المدير. ويُغلق التسجيل العام بعد ذلك.

هل تنشر على خادم عام؟ اضبط APP_URL على عنوان HTTPS في ملف .env قبل تشغيل الحزمة. القيمة الافتراضية هي http://localhost:3000.

تحقق من التثبيت

ينبغي أن تظهر الحاويتان بحالة سليمة وأن يعيد فحص السلامة استجابة ناجحة.

الطرفية
docker compose ps
docker compose exec api wget -qO- http://localhost:4000/api/health

إذا فشل فحص السلامة، اقرأ سجل API قبل تغيير الإعدادات.

قائمة فحص التشغيل الأول

بعد إنشاء حساب المدير، أكمل هذه الخطوات ليطابق مساحة العمل طريقة بيعك.

  • افتح Settings → Business profile وأضف التفاصيل التي تُطبع على الفواتير.
  • راجع Settings → Invoice للترقيم وعرض العملة ومدة الاستحقاق والشروط.
  • أضف الفئات والعلامات التجارية والمنتجات قبل إنشاء الطلبات.
  • أنشئ عميلًا وطلبًا تجريبيًا ثم نزّل ملف الفاتورة PDF.
  • نزّل نسخة احتياطية وتأكد من ظهور الأرشيف في سجل النسخ الاحتياطي.

الترقية لاحقًا

اسحب أحدث شيفرة ثم أعد البناء. تُتجاوز الترحيلات المطبقة مسبقًا، لذا يمكن تكرار الأمر بأمان.

الطرفية
git pull
docker compose up -d --build

التطوير

شغّل VendKit محليًا.

استخدم هذا المسار عند العمل على الشيفرة. تحتاج إلى Node.js 24+ وpnpm 11+ وPostgreSQL 16+.

قبل أن تبدأ

  • Node.js 24 أو أحدث
  • pnpm 11 أو أحدث
  • PostgreSQL 16 أو أحدث
  • Git
  1. 01

    استنسخ المستودع

    نزّل الشيفرة وانتقل إلى جذر المشروع.

    الطرفية
    git clone https://github.com/MuawiyahDev/vendkit.git
    cd vendkit
  2. 02

    ثبّت الاعتماديات

    ثبّت حزم مساحة العمل باستخدام pnpm.

    الطرفية
    pnpm install
  3. 03

    أنشئ قاعدة البيانات

    أنشئ قاعدة PostgreSQL محلية باسم vendkit. يمكنك استخدام createdb أو عميل PostgreSQL.

    الطرفية
    createdb vendkit
  4. 04

    أنشئ ملفات البيئة

    انسخ قوالب بيئة الـAPI وقاعدة البيانات وتطبيق الويب. استخدم DATABASE_URL نفسها في ملفي الـAPI وقاعدة البيانات، وAPI_KEY نفسها في ملفي الـAPI وتطبيق الويب.

    .env
    cp apps/api/.env.example apps/api/.env
    cp packages/database/.env.example packages/database/.env
    cp apps/web/.env.example apps/web/.env
  5. 05

    طبّق الترحيلات

    شغّل ترحيلات قاعدة البيانات قبل بدء التطبيقات.

    الطرفية
    pnpm db:migrate
  6. 06

    ابدأ خوادم التطوير

    شغّل تطبيق الويب والـAPI في وضع المراقبة.

    الطرفية
    pnpm dev

ملفات البيئة

يستخدم الإعداد المحلي ثلاثة ملفات: apps/api/.env وpackages/database/.env وapps/web/.env. حافظ على تطابق DATABASE_URL وAPI_KEY بين الملفات.

لا ترفع أي ملف .env إلى المستودع.

الروابط المحلية

تطبيق الويب
http://localhost:3000
واجهة API
http://localhost:4000/api
فحص الصحة
http://localhost:4000/api/health

أوامر مفيدة

  • pnpm devخادم تطوير الويب والـAPI
  • pnpm buildبناء الإنتاج لمساحة العمل
  • pnpm lintفحص ESLint لمساحة العمل
  • pnpm check-typesفحص أنواع TypeScript
  • pnpm testتشغيل الاختبارات
  • pnpm db:migrateإنشاء ترحيلات التطوير أو تطبيقها
  • pnpm db:studioفتح Prisma Studio

قبل فتح طلب سحب

شغّل ESLint وفحص الأنواع والاختبارات وبناء الإنتاج:

الطرفية
pnpm lint && pnpm check-types && pnpm test && pnpm build

التهيئة

المتغيرات المهمة

يتحقق الـAPI من متغيرات البيئة المطلوبة عند بدء التشغيل، ويرفض الإقلاع مع عرض قائمة بكل مشكلة. أما بيانات النشاط وإعدادات الفواتير فتُحفظ في قاعدة البيانات.

التطوير المحلي

القيم المحلية في apps/api/.env وpackages/database/.env وapps/web/.env. ويقرأ Docker ملف .env في الجذر.
DATABASE_URL
سلسلة اتصال PostgreSQL التي يستخدمها الـAPI وPrisma.
JWT_SECRET
سر توقيع رموز الوصول، بطول 32 حرفًا على الأقل.
API_KEY
المفتاح المشترك الذي يستخدمه تطبيق الويب لاستدعاء الـAPI. أبقِه خاصًا.
APP_URL
الرابط العام لتطبيق الويب. تمرره Compose إلى الـAPI بوصفه أصل CORS مسموحًا به.
ALLOW_PUBLIC_REGISTRATION
معطّل افتراضيًا. فعّله فقط إذا أردت السماح بالتسجيل بعد الحساب الأول.
BACKUP_SAFETY_SNAPSHOT
ينشئ نسخة أمان قبل الاستعادة. مفعّل افتراضيًا.

مرجع البيئة الكامل

يقرأ Compose ملف .env الجذري. تتلقى خدمتا API والويب قيمهما من Compose في Docker، أو من ملفاتهما الخاصة في التطوير المحلي.

Compose (.env)

يقرأه docker compose

POSTGRES_PASSWORD
مطلوب
كلمة مرور خدمة PostgreSQL المرفقة. استخدم أحرفًا آمنة في URL فقط؛ لأنها تُدرج في DATABASE_URL.
JWT_SECRET
مطلوب (32+ حرفًا)
يوقّع رموز الوصول.
API_KEY
مطلوب
مفتاح مشترك بين تطبيق الويب وAPI.
APP_URL
http://localhost:3000
عنوان الويب العام. يمرره Compose إلى API كـ CORS_ORIGINS.
ALLOW_PUBLIC_REGISTRATION
false
يسمح بالتسجيل بعد إنشاء المدير الأول.
WEB_PORT
3000
منفذ المضيف المنشور لحاوية الويب.
APP_VERSION
0.1.0
الإصدار المسجل في بيانات النسخ الاحتياطي.

API

يُتحقق منه عند البدء

DATABASE_URL
مطلوب
سلسلة اتصال PostgreSQL التي يستخدمها API وPrisma.
JWT_SECRET
مطلوب (32+ حرفًا)
يوقّع رموز الوصول.
API_KEY
مطلوب
مفتاح مشترك بين تطبيق الويب وAPI.
PORT
4000
منفذ API داخل الحاوية.
CORS_ORIGINS
من APP_URL
أصول الويب المسموح بها مفصولة بفواصل. يستنتجها Compose من APP_URL.
ALLOW_PUBLIC_REGISTRATION
false
يسمح بالتسجيل بعد إنشاء المدير الأول.
IMAGE_STORAGE_DIR
uploads/images
دليل رفع الصور. يضبط Compose القيمة /data/images.
IMAGE_MAX_FILE_SIZE
5 MB (بالبايت)
أكبر صورة مقبولة للرفع.
BACKUP_STORAGE_DIR
uploads/backups
دليل أرشيفات النسخ الاحتياطي. يجب ألا يكون داخل دليل الصور. يضبط Compose القيمة /data/backups.
BACKUP_MAX_FILE_SIZE
1 GB
أكبر ملف نسخ احتياطي مقبول للرفع أو الأرشيف.
BACKUP_MAX_EXTRACTED_SIZE
2 GB
أكبر حجم استعادة غير مضغوط مقبول.
BACKUP_RESTORE_TRANSACTION_TIMEOUT_MS
10 دقائق
مهلة معاملات اللقطة والاستعادة.
BACKUP_SAFETY_SNAPSHOT
true
ينشئ نسخة أمان قبل الاستعادة.
APP_VERSION
0.1.0
الإصدار المسجل في بيانات النسخ الاحتياطي.

الويب

يجب أن يطابق مفتاح API

NEST_API_URL
مطلوب
عنوان API الأساسي مع /api. يضبط Compose القيمة http://api:4000/api.
API_KEY
مطلوب
مفتاح مشترك بين تطبيق الويب وAPI.
لا تضع بيانات النشاط أو ترقيم الفواتير أو الشروط في متغيرات البيئة. مكانها الإعدادات، وهي مشمولة في النسخ الاحتياطي.

البيانات والنسخ الاحتياطي

اعرف أين تعيش بياناتك.

يحفظ VendKit سجلات الأعمال في PostgreSQL والملفات المرفوعة على القرص. كلاهما داخل وحدات Docker مسماة ويجب أن يبقيا بعد استبدال الحاويات.

vendkit-db

دليل بيانات PostgreSQL: المنتجات والعملاء والطلبات والمدفوعات والفواتير والمخزون والإعدادات.

vendkit-data

الصور المرفوعة وأرشيفات النسخ الاحتياطي التي تكتبها حاوية API.

المسارات داخل حاوية API

تُكتب النسخ الاحتياطية على نظام ملفات خادم API، لا في خدمة سحابية. يجب ألا يكون دليل النسخ الاحتياطي داخل دليل الصور.

/data/images
رفع الصور، مثبت من وحدة vendkit-data.
/data/backups
أرشيفات النسخ الاحتياطي، وهي أيضًا على وحدة vendkit-data.

ماذا تتضمن النسخة الاحتياطية

كل أرشيف ملف tar مضغوط بـ gzip ومُصدّر بإصدار، ويتضمن بيانًا ومجاميع تحقق وبيانات الأعمال.

  • الفئات والعلامات التجارية والمنتجات وصور المنتجات
  • العملاء والطلبات وبنود الطلب والمدفوعات والمرتجعات
  • الفواتير وتسلسلات المستندات
  • حركات المخزون وإعدادات الأعمال
  • كل صورة مرفوعة تشير إليها قاعدة البيانات

ماذا يستثني

تُستثنى بعض السجلات عمدًا حتى لا تؤدي الاستعادة إلى إغلاق وصولك أو محو تاريخها.

  • حسابات المستخدمين وتجزئات كلمات المرور ورموز التحديث
  • سجل النسخ الاحتياطي والاستعادة
  • متغيرات البيئة وعناوين قاعدة البيانات والأسرار

اعرض النسخ على الخادم

تُنشأ الأرشيفات من Settings → Backup & Restore، ويكتبها API في /data/backups، وهي وحدة vendkit-data.

الطرفية
docker compose exec api ls -lh /data/backups

انسخ الأرشيفات خارج الخادم

نزّل النسخ من التطبيق، أو انسخ دليل الأرشيف إلى جهازك. التخزين على الخادم نفسه لا يكفي.

الطرفية
mkdir -p offsite-backups
docker compose cp api:/data/backups/. ./offsite-backups/

استعد نسخة احتياطية

استعد من Settings → Backup & Restore. يُتحقق من الأرشيف قبل استبدال أي بيانات حالية.

  1. 1أنشئ نسخة احتياطية جديدة من البيانات الحالية، رغم إنشاء لقطة أمان افتراضيًا.
  2. 2ارفع الأرشيف الذي تريد الاستعادة منه من شاشة النسخ الاحتياطي.
  3. 3أكّد الاستعادة. يجب أن يطابق إصدار البيان إصدار التطبيق العامل.
  4. 4انتظر انتهاء المهمة وتحقق من النتيجة في سجل النسخ الاحتياطي.
  5. 5افتح طلبًا وفاتورة وصورة منتج للتأكد من البيانات المستعادة.
تستبدل الاستعادة بيانات الأعمال. تبقى حسابات المستخدمين وسجل النسخ، لكن الكتابات التي تتم أثناء نافذة التبديل لا يُضمن حفظها. نفّذ الاستعادة في وقت قليل الحركة.

لا يوجد مجدول تلقائي

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

النشر

انشر VendKit في الإنتاج.

شغّل حزمة Compose واحدة خلف HTTPS. أبقِ الـAPI خاصًا واحتفظ بنسخ احتياطية لوحدتَي التخزين.

قبل النشر

  • خادم Linux مع Docker وإضافة Compose
  • نطاق يشير إلى الخادم
  • وكيل عكسي بشهادة TLS صالحة
  • تخزين دائم وخطة نسخ احتياطي خارج الخادم
  1. 01

    اضبط الرابط العام

    اضبط APP_URL على أصل HTTPS النهائي في .env. يُستخدم لـCORS وللروابط المُنشأة.

    .env
    APP_URL=https://your-domain.example
  2. 02

    شغّل الحزمة

    ابنِ وشغّل تطبيق الويب والـAPI وPostgreSQL. تُطبَّق الترحيلات تلقائيًا عند بدء حاوية الـAPI.

    الطرفية
    docker compose up -d --build
  3. 03

    ضعه خلف HTTPS

    أنهِ TLS عند وكيل عكسي مثل Caddy أو nginx أو Traefik، ووجّه الحركة إلى تطبيق الويب فقط.

    مثال تهيئة Caddy

    Caddyfile
    vendkit.example.com {
      encode zstd gzip
      reverse_proxy 127.0.0.1:3000
    }

    وكيل عكسي بسيط لتثبيت واحد. عدّله حسب نطاقك وخادمك. استبدل vendkit.example.com بنطاقك. وإذا غيّرت WEB_PORT فحدّث منفذ الوجهة.

  4. 04

    تحقق من النشر

    تأكد من صحة الحاويتين ثم افحص نقطة صحة الـAPI.

    الطرفية
    docker compose ps
    docker compose exec api wget -qO- http://localhost:4000/api/health
  5. 05

    أنشئ الحساب الأول

    افتح الرابط العام وأنشئ حساب المدير. يُغلق التسجيل العام بعد ذلك.

شغّله بأمان

  • شغّل مثيل API واحدًا. تحديد معدل المصادقة يُحفظ في الذاكرة.
  • لا تكشف منفذ الـAPI للعامة.
  • احفظ وحدتَي التخزين vendkit-db وvendkit-data.
  • انسخ أرشيفات النسخ خارج الخادم ضمن سياسة النسخ لديك.
  • استخدم HTTPS. ملفات جلسة الإنتاج مضبوطة على Secure.

ترقية تثبيت إنتاجي

اسحب أحدث شيفرة ثم أعد البناء. تُتجاوز الترحيلات المطبقة مسبقًا، لذا يمكن تكرار الأمر بأمان.

الطرفية
git pull
docker compose up -d --build

الترقيات

رقّي وتراجع بأمان.

يطبق VendKit ترحيلات قاعدة البيانات عند بدء حاوية API. خطط للتحديث، واحتفظ بنسخة سليمة، وتحقق من الحزمة قبل إغلاق نافذة الصيانة.

قبل الترقية

سجّل ما يعمل واحمِ البيانات الحالية.

  • اقرأ ملاحظات الإصدار أو التزامات المستودع التي ستُنشر.
  • أنشئ نسخة احتياطية من Settings → Backup & Restore ونزّلها.
  • سجّل الالتزام الحالي لتتمكن من العودة إليه.
  • اختر وقتًا قليل الحركة؛ إذ تُعاد واجهة API أثناء إعادة البناء.
الطرفية
git rev-parse --short HEAD
docker compose exec api ls -lh /data/backups

طبّق التحديث

اسحب أحدث شيفرة وأعد بناء صورتي التطبيق. تبقى حاوية قاعدة البيانات قيد التشغيل.

الطرفية
git pull
docker compose up -d --build

تُتخطى الترحيلات المطبقة سابقًا، لذا يمكن تكرار الأمر بأمان. قد تستغرق أول عملية بناء بعد تغيير كبير عدة دقائق.

تحقق بعد الترقية

تأكد من سلامة الحاويتين، ثم سجّل الدخول وافتح طلبًا وفاتورة وصورة منتج.

الطرفية
docker compose ps
docker compose exec api wget -qO- http://localhost:4000/api/health

التراجع

إذا فشل الإصدار الجديد، عد إلى الالتزام السابق وأعد البناء. ثم استعد النسخة الاحتياطية التي أخذتها قبل الترقية.

الطرفية
git log --oneline -5
git checkout <previous-commit>
docker compose up -d --build
ترحيلات قاعدة البيانات تتقدم فقط. إذا غيّرت الترقية المخطط، فقد لا يعمل الالتزام الأقدم مع قاعدة البيانات الأحدث. استعد نسخة ما قبل الترقية قبل تشغيل الشيفرة القديمة.

استبدل previous-commit بالالتزام الذي سجلته. أبقِ النسخة الاحتياطية حتى يستقر الإصدار الجديد لبضعة أيام.

العمليات

شغّله بلا مفاجآت

افحص الحزمة واقرأ السجلات وحافظ على وحدات التخزين. معظم الحوادث تظهر في docker compose ps وسجل API.

النسخ الاحتياطي

أنشئ أرشيفًا كاملًا من Settings → Backup & Restore. وانسخ الأرشيفات خارج الخادم ضمن روتين النسخ الاحتياطي لديك.

فحص الصحة

تبلغ GET /api/health عن حالة الـAPI وقاعدة البيانات للحاويات والمراقبة.

النشر

لا تكشف منفذ الـAPI. شغّل مثيل API واحدًا، واحتفظ بوحدتي التخزين، وأنهِ HTTPS عند وكيل عكسي.

الاستعادة

تتحقق الاستعادة من الأرشيف وتستبدل بيانات النشاط داخل معاملة واحدة. وتُنشأ نسخة أمان أولًا افتراضيًا.

أوامر يومية

نفّذها من جذر المستودع على الخادم.

  • docker compose psحالة الحاويات وسلامتها
  • docker compose logs -f --tail=100 apiتابع سجل API؛ استخدم web لتطبيق Next.js
  • docker compose restart apiأعد تشغيل خدمة واحدة دون إعادة بناء
  • docker compose exec api wget -qO- http://localhost:4000/api/healthاسأل API وقاعدة البيانات عن حالتهما
  • docker system dfاعرف المساحة التي تستهلكها الصور والحاويات
  • docker compose downأوقف الحاويات والشبكة وأزلها؛ تبقى وحدات التخزين
  • docker compose up -dشغّل الحاويات الموجودة مجددًا
لا تضف --volumes إلى docker compose down إلا إذا كنت تنوي حذف قاعدة البيانات وكل ملف مرفوع. استخدمه فقط عند إتلاف التثبيت عمدًا.

لا يوجد مجدول نسخ احتياطي تلقائي أو عامل خلفي في هذا الإصدار. cron على الخادم والنسخ خارج الخادم مسؤوليتك.

الأمان

حصّن تثبيتًا مستضافًا ذاتيًا.

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

استخدم HTTPS

تُعلَّم ملفات جلسة الإنتاج بـ Secure. لن يسجّل HTTP العادي دخول المستخدمين. أنهِ TLS على وكيل عكسي وأعد توجيه HTTP إلى HTTPS.

أبقِ API خاصًا

لا يُنشر سوى تطبيق الويب. يستدعي المتصفح Next.js التي تمرر الطلبات إلى API بالمفتاح المشترك. لا تنشر المنفذ 4000.

احمِ الأسرار

استخدم قيمًا عشوائية طويلة لـ POSTGRES_PASSWORD وJWT_SECRET وAPI_KEY. أبقِ .env بصلاحيات 600، ولا ترفعه إلى المستودع، ولا تعِد استخدام قيمة بين تثبيتين.

أبقِ التسجيل مغلقًا

يصبح الحساب الأول مديرًا ثم يُغلق التسجيل العام. لا تفعّل ALLOW_PUBLIC_REGISTRATION إلا إذا أردت عمدًا حسابات ذاتية.

أدر الأشخاص

يمكن للمديرين إنشاء أعضاء وإعادة تعيين كلمات المرور من Team. أزل الوصول غير اللازم وتجنب مشاركة حساب مدير واحد.

احمِ النسخ الاحتياطية

تحتوي الأرشيفات على بيانات اتصال العملاء وسجلات الأعمال. خزّن النسخ على تخزين مشفر ومقيّد الوصول واحذفها عند عدم الحاجة.

حصّن الخادم

حدّث نظام التشغيل وDocker، وقيّد SSH، وافتح فقط المنافذ اللازمة: SSH و80 و443. لا تعرّض PostgreSQL.

تابع التحديثات

راقب المستودع للإصدارات وإصلاحات الأمان. اقرأ دليل الترقية، وخذ نسخة احتياطية أولًا، وتحقق بعد كل تحديث.

إذا تسرّب سر

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

أبلغ عن ثغرة بشكل خاص

لا تفتح مشكلة عامة لمسألة أمنية. اتبع سياسة الأمان في المستودع وتواصل مع المشرف بشكل خاص.

VendKit مرخّص بموجب AGPL-3.0. إذا شغّلت نسخة معدّلة كخدمة شبكية، يلزمك الترخيص بتقديم شيفرتها إلى مستخدميها.

استكشاف الأخطاء وإصلاحها

أصلح الأعطال الشائعة.

ابدأ بحالة الحاويات وسجل API. يتحقق VendKit من بيئته عند البدء ويذكر القيم الناقصة أو غير الصالحة في السجل.

اقرأ سجل API

ترفض API البدء عند غياب متغير مطلوب وتسرد كل مشكلة وجدتها.

الطرفية
docker compose logs --tail=200 api

تحقق من ملف Compose

تأكد من وجود .env ومن حل ملف Compose قبل إعادة البناء.

الطرفية
docker compose config --quiet

يتوقف Compose عند رسالة Set … in .env

ملف .env الجذري مفقود أو قيمة مطلوبة فارغة. انسخ .env.example إلى .env وأنشئ الأسرار مجددًا.

حاوية API تعيد التشغيل مرارًا

اقرأ سجل API. غياب DATABASE_URL أو JWT_SECRET أو API_KEY، أو كون JWT_SECRET أقصر من 32 حرفًا، يمنع بدء API.

تسجيل الدخول يدور أو لا يفعل شيئًا

ملفات تعريف ارتباط الإنتاج Secure. استخدم عنوان HTTPS لا عنوان HTTP عاديًا، وتأكد من مطابقة APP_URL للأصل العام.

تطبيق الويب لا يصل إلى API

تأكد من سلامة API. في Compose يجب أن يكون NEST_API_URL هو http://api:4000/api وأن يتطابق API_KEY في خدمتي الويب وAPI.

المنفذ 3000 مستخدم بالفعل

عيّن WEB_PORT إلى منفذ آخر في .env، وأعد تشغيل الحزمة، وحدّث عنوان الوكيل العكسي. تظل الحاوية تستمع إلى 3000 داخليًا.

اختفت البيانات بعد إعادة التشغيل

ربما أُزيلت الحزمة مع وحدات التخزين. لا تستخدم docker compose down --volumes في تثبيت حقيقي. استعد آخر نسخة واحتفظ بوحدتي التخزين المسماتين.

رفضت الاستعادة

يجب أن يطابق إصدار البيان التطبيق العامل، وأن تنجح كل مجاميع التحقق وأحجام الوسائط. استخدم أرشيفًا يطابق تنسيقه التطبيق العامل وافحص سجل النسخ لمعرفة السبب.

تفشل عمليات البناء أو يتباطأ التطبيق

افحص المساحة الحرة عبر df -h واستهلاك Docker عبر docker system df. نظّف الصور والذاكرة المؤقتة غير المستخدمة فقط عند وجود نسخة احتياطية حديثة.

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

البنية

تطبيق ويب واحد، واجهة API واحدة، وقاعدة بيانات واحدة

يتواصل المتصفح مع تطبيق Next.js فقط، وهو يمرر الطلبات إلى NestJS من جهة الخادم بمفتاح API مشترك، لذا لا تحتاج واجهة API إلى أن تكون عامة.

المستودع

  • apps/web

    واجهة Next.js والوكيل الخادمي لواجهة API.

  • apps/api

    واجهة NestJS ومنطق العمل وفواتير PDF والنسخ الاحتياطي.

  • packages/database

    مخطط Prisma والترحيلات والعميل المولّد.

  • packages/ui

    مكوّنات واجهة مشتركة للتطبيق.

  • docker-compose.yml

    الويب والـAPI وPostgreSQL، مع وحدات تخزين دائمة للبيانات والملفات.

المراجع

المستودع هو المصدر الموثوق

تشير هذه الروابط إلى مستودع VendKit، وهي تُحدَّث مع التطبيق لا مع هذا الموقع.