نشر Payload CMS على VPS: دليل شامل

يعتمد Payload CMS نهجاً قائماً على الكود بشكل جذري: يُعرَّف مخطط المحتوى في TypeScript ضمن ملفات إعداد مُصنَّفة بـ Git، ومنذ الإصدار 3 يتثبت Payload مباشرة داخل تطبيق Next.js عبر App Router. هذا يعني أن VPS يتيح لك استضافة نظام إدارة المحتوى والواجهة الأمامية في عملية Node واحدة، تشترك في نفس البناء والـ runtime. تحصل على typing شامل من طرف إلى طرف، وترحيل مخطط مُدار في الكود، دون أي اعتماد على واجهة رسومية لنمذجة المحتوى. الاستضافة الذاتية هي الخيار الطبيعي هنا: صُمِّم Payload للنشر مثل أي تطبيق Next.js، ويمنحك VPS السيطرة الكاملة على قاعدة البيانات (MongoDB أو PostgreSQL)، والرفوعات، ومتغيرات البيئة، دون وسيط.

بما أن Payload يعمل على Next.js، فإن البناء مُطالِب بالموارد: خطط لـ VPS بـ 2 vCPU و4 GB RAM لبناء التطبيق وتشغيله بشكل مريح. ثبِّت Node.js 20 LTS وDocker وDocker Compose. لقاعدة البيانات، جهِّز MongoDB 7 أو PostgreSQL 16 وفق المحوِّل المختار (@payloadcms/db-mongodb أو @payloadcms/db-postgres). وجِّه نطاقك نحو IP الـ VPS. خصص 15 GB قرصياً لـ node_modules وبناء .next والرفوعات ونسخ قاعدة البيانات الاحتياطية.

يدير Payload 3 المستخدمين عبر مجموعة users المعرَّفة في payload.config.ts. فعِّل المصادقة على المجموعة بـ auth: true — هذا يضيف تلقائياً نقاط النهاية /api/users/login و/api/users/logout و/api/users/me و/api/users/refresh-token.

للأدوار، لا يفرض Payload نموذجاً: عرِّف حقل role (نوع select) على مجموعة users، ثم تحكم في الوصول عبر دوال access على مستوى كل مجموعة وكل عملية:

access: {
  read: ({ req: { user } }) => user?.role === 'admin',
  create: isAdmin,
  update: isAdminOrSelf,
  delete: isAdmin,
}

للوصول البرمجي (CI والتكاملات الخارجية)، استخدم مفاتيح API: فعِّل useAPIKey: true في إعداد مصادقة المجموعة. يمكن لكل مستخدم حينئذٍ توليد مفتاح من لوحة الإدارة. مرِّره في ترويسة Authorization: users API-Key مفتاحك. مفاتيح API مُجزَّأة في قاعدة البيانات — المفتاح المفقود لا يُسترد، يُعاد توليده فقط.

تتيح خطافات المجموعة في Payload 3 تنفيذ كود قبل أو بعد كل عملية CRUD. تحلّ محلّ الـ webhooks بشكل أنيق حين تعيش المنطق في نفس الـ runtime:

hooks: {
  afterChange: [
    async ({ doc, operation }) => {
      if (operation === 'create') {
        await notifySubscribers(doc)
      }
    },
  ],
  beforeDelete: [
    async ({ id }) => {
      await cleanupMedia(id)
    },
  ],
}

الخطافات المتاحة: beforeOperation وbeforeValidate وbeforeChange وafterChange وbeforeRead وafterRead وbeforeDelete وafterDelete. خطاف afterChange مثالي لإبطال كاش CDN أو إرسال إشعار أو مزامنة مع خدمة خارجية بعد النشر.

يتبع Payload 3 الإصدار الدلالي. تحديثات الـ patch (3.x.y → 3.x.z) آمنة التطبيق دون ترحيلات. قد تضيف تحديثات الـ minor (3.x → 3.y) أعمدة أو فهارس وتستلزم تشغيل payload migrate.

سير العمل الموصى به لكل تحديث:

# 1. تحديث الإصدار في package.json
npm install [email protected] @payloadcms/[email protected]

# 2. توليد ملف ترحيل إذا تغيّر المخطط
npx payload migrate:create

# 3. الاختبار محلياً على نسخة قاعدة البيانات
npx payload migrate

# 4. حفظ ملف الترحيل مع تحديث الإصدار
git add src/migrations/ package.json package-lock.json
git commit -m "chore: payload 3.88.0"

# 5. في الإنتاج: إيقاف التطبيق، تطبيق الترحيلات، إعادة التشغيل
docker compose run --rm app npx payload migrate
docker compose up -d app

لا تعدِّل يدوياً الملفات المولَّدة في src/migrations/: يتحقق Payload منها بالـ hash. ملف معدَّل يُفشِل migrate برسالة Error: Migration file has been modified since it was created.

هذا أكثر عائق شائع عند النشر على VPS، ويأخذ ثلاثة أشكال متميزة. الأكثر إرباكاً هو Unsupported CPU: prebuilt binaries for linux-x64 require v2 microarchitecture: يصدر من معالج الجهاز، لا من كودك أو تبعياتك. الثنائيات المُجمَّعة مسبقاً تستهدف مجموعة تعليمات لا تتوفر في المعالجات الأقدم — هذا معيار اختيار VPS، لا خطأ يُصلَح. الثاني Could not load the "sharp" module using the linux-x64 runtime، يشير عادةً إلى node_modules مبني على منصة مختلفة — أعِد التثبيت على الجهاز الهدف. الثالث خاص بـ Docker متعدد المراحل: sharp مُثبَّت في مرحلة البناء فقط غائب عن مرحلة التشغيل — ثبِّته صراحةً في المرحلة النهائية.

نفاد ذاكرة البناء — Killed أو JavaScript heap out of memory.
يحدث أثناء npm run build حين تقل الذاكرة المتاحة عن 3 GB. Node.js محدود بـ ~1.8 GB افتراضياً. مرِّر NODE_OPTIONS=--max-old-space-size=3072 قبل البناء، أو ابنِ الصورة على جهاز أقوى وادفعها إلى registry.

PostgreSQL — Error: connect ECONNREFUSED 127.0.0.1:5432.
التطبيق يحاول الاتصال قبل جاهزية PostgreSQL، أو URL الاتصال يشير إلى localhost بدلاً من اسم خدمة Docker (postgres). تحقق من استخدام DATABASE_URI لاسم الخدمة ووجود healthcheck (انظر الخطوة 3).

لوحة الإدارة غير متاحة في الإنتاج — /admin يُعيد 404 أو حلقة إعادة توجيه.
سببان رئيسيان: serverURL غير مُعرَّف أو غير مطابق للـ URL الفعلي، أو ترويسة X-Forwarded-Proto: https غائبة من Nginx. أضف proxy_set_header X-Forwarded-Proto $scheme; للـ vhost وتحقق من تطابق serverURL مع الأصل العام دون شرطة مائلة نهائية.

CORS — Access-Control-Allow-Origin غائبة عن الـ API.
Payload يقرأ cors من payload.config.ts. في الإنتاج، اذكر الأصول المسموحة صراحةً: cors: { origins: ['https://example.com'] }. cors: { origins: [serverURL] } هو الإعداد الآمن الأدنى.

Error: Migration file has been modified since it was created.
ملف في src/migrations/ عُدِّل يدوياً. استعِد الأصلي من Git، ولِّد ملف ترحيل جديداً إذا تغيّر المخطط، وأعِد التطبيق بالترتيب.