تخطي إلى المحتوى
دليل

نشر مشروع Node.js على VPS بـ Docker و Nginx و SSL

بقلم فايز الشامينُشر: حُدّث: قراءة لمدة 9 دقائق
الخلاصة

التطبيق يستمع على 127.0.0.1:3000 داخل Docker، وNginx على المضيف يستقبل 80 و443 ويمرّر الطلبات خلف HTTPS. لا تفتح المنفذ 3000 للعالم. أضف مسار /health، واستخدم Certbot مع تجربة التجديد، واحتفظ بالأسرار في ملف .env خارج Git.

أكثر مرة يتوقف فيها مشروع جاهز عند أصحاب المتاجر والمطورين الذين أتعامل معهم هي وضعه على سيرفر حقيقي بعنوان واضح وشهادة SSL. التطبيق يعمل على جهازك، ثم يُرفع على VPS، ويُفتح المنفذ 3000 على الإنترنت، أو يُنسى تجديد الشهادة، أو تُوقف الحاوية بعد إعادة إقلاع السيرفر. هذا دليل DevOps عملي لنشر مشروع Node.js على VPS بـ Docker وNginx وSSL، بالمسار الذي أستخدمه: التطبيق لا يُسمع إلا على localhost، وNginx يستقبل 80 و443، وLet's Encrypt تصدر الشهادة.

الدليل يفترض VPS على أوبونتو حديثًا، ونطاقًا يشير بسجل A إلى عنوان السيرفر، وتطبيق Node.js يستمع على المنفذ 3000. إن كان متجرك من خطة المتجر المملوك، هذا هو نوع النشر الذي تصبح مسؤولًا عنه بعد استلام الكود.

قبل نشر مشروع Node.js على VPS

أنشئ مستخدمًا عاديًا بصلاحية sudo، وعطّل الدخول بـ root عبر SSH بعد أن تتأكد أن مفتاحك يعمل. حدّث النظام، وثبّت Docker وDocker Compose من مستندات Docker الرسمية لنسختك، لا من حزم قديمة عشوائية.

افتح الجدار الناري قبل أن تنشر التطبيق:

``bash sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable sudo ufw status ``

لا تفتح المنفذ 3000 على العالم. التطبيق سيُنشر على 127.0.0.1:3000 فقط. إن فتحت 3000 ثم أضفت Nginx لاحقًا، يبقى المنفذ المباشر بابًا يتجاوز الشهادة والتوجيه.

تأكد من جهازك أن النطاق يصل إلى السيرفر:

``bash dig +short example.com A curl -I --max-time 10 http://example.com || true ``

استبدل example.com بنطاقك. إذا كان السجل ما زال يشير إلى عنوان قديم، لا تبدأ بإصدار الشهادة؛ Let's Encrypt يتحقق من التحكم بالنطاق عبر HTTP.

ضع أسرار التطبيق في ملف .env على السيرفر، بصلاحية يقرأها مستخدم التشغيل فقط، ولا تُرفع إلى Git. مفتاح بوابة الدفع، وسر توقيع الـwebhook، ومفتاح OpenAI إن وجد، كلها من هذا النوع.

حاوية التطبيق

في جذر المشروع ملف Dockerfile يثبّت الاعتماديات قبل نسخ بقية الكود، حتى لا تُعاد التثبيت مع كل تعديل على ملف واحد:

```dockerfile FROM node:22-alpine AS deps WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci --omit=dev

FROM node:22-alpine WORKDIR /app ENV NODE_ENV=production COPY --from=deps /app/node_modules ./node_modules COPY package.json ./ COPY . . USER node EXPOSE 3000 CMD ["node", "server.js"] ```

إذا كان مدخلك npm start لا node server.js، غيّر السطر الأخير فقط. لا تشغّل العملية كـ root داخل الحاوية. تأكد أن الملفات مقروءة لمستخدم node، وأن التطبيق يستمع على 0.0.0.0:3000 داخل الحاوية (على 127.0.0.1 داخل الحاوية لن يصل إليه توجيه المنفذ).

أضف ملف .dockerignore في جذر المشروع حتى لا تُنسخ node_modules ولا ملف .env إلى صورة البناء:

`` node_modules .env .git ``

نسخ node_modules من جهازك إلى الصورة يعطّل فائدة npm ci داخل Linux، وقد يكسّر حزمًا أصلية بُنيت على نظام مختلف. ونسخ .env إلى الصورة يثبّت أسرارًا داخل طبقة يمكن تصديرها بالخطأ.

docker-compose.yml بجانب الـDockerfile:

``yaml services: app: build: . restart: unless-stopped env_file: [.env] ports: ["127.0.0.1:3000:3000"] healthcheck: test: [ "CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))" ] interval: 30s timeout: 5s retries: 3 start_period: 20s ``

صورة node:22-alpine لا تتضمن wget أو curl بشكل افتراضي. الفحص أعلاه يستخدم fetch المدمج في Node 22، ولا يحتاج حزمة إضافية. اجعل الفحص خفيفًا: يطلب /health فقط. إذا ربطت الفحص بقاعدة البيانات، ضغط عابر على القاعدة يعيد تشغيل الحاوية في أسوأ لحظة، خصوصًا إن كان التطبيق يؤكد دفعات.

في server.js (أو ملف الإقلاع عندك):

```javascript import express from "express";

const app = express();

app.get("/health", (req, res) => { res.status(200).json({ ok: true }); });

// بقية المسارات...

const port = Number(process.env.PORT || 3000); app.listen(port, "0.0.0.0", () => { console.log(listening on ${port}); }); ```

إذا كان عندك مسار ويب هوك للدفع، لا تستخدم express.json() على هذا المسار قبل التحقق من التوقيع؛ الجسم يجب أن يبقى كما وصل. فصّلت هذا في Building reliable payment webhooks.

البناء والتشغيل من مجلد المشروع على السيرفر:

``bash docker compose build docker compose up -d docker compose ps curl -sS http://127.0.0.1:3000/health ``

يجب أن ترى {"ok":true}. إذا فشلت الحاوية، docker compose logs --tail=100 app يوضح السبب قبل أن تلمس Nginx.

Nginx كوكيل عكسي ثم شهادة SSL

ثبّت Nginx وCertbot على المضيف (خارج الحاوية). هذا أبسط عند التجديد، ويترك Docker للتطبيق فقط:

``bash sudo apt-get update sudo apt-get install -y nginx certbot python3-certbot-nginx ``

ملف الموقع، مثل /etc/nginx/sites-available/app:

```nginx server { listen 80; listen [::]:80; server_name example.com www.example.com;

location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 60s; client_max_body_size 10m; } } ```

فعّل الموقع وألغِ الافتراضي إن كان يتعارض، ثم افحص الإعداد:

``bash sudo ln -s /etc/nginx/sites-available/app /etc/nginx/sites-enabled/app sudo nginx -t sudo systemctl reload nginx curl -I --max-time 10 http://example.com/health ``

إذا عاد 200 من النطاق على المنفذ 80، أصدر الشهادة:

``bash sudo certbot --nginx -d example.com -d www.example.com ``

Certbot يعدل ملف الموقع ليستمع على 443 ويعيد التوجيه من 80 إلى HTTPS. أكمل التحدي من بريدك وموافقتك على الشروط كما يطلب المعالج. بعدها:

``bash curl -I --max-time 10 https://example.com/health sudo certbot renew --dry-run ``

التجديد يعمل عبر مؤقت systemd يثبّته Certbot عادةً. --dry-run يؤكد أن التحدي ما زال ينجح. إذا كنت خلف جدار إضافي أو CDN يقطع المسار /.well-known/acme-challenge/، أصلحه قبل أن تنتهي الشهادة بعد تسعين يومًا.

إذا كان النطاق يمر عبر وكيل (مثل سحابة البرتقالي في Cloudflare)، تحدي HTTP-01 قد يفشل لأن Let's Encrypt لا يصل إلى Nginx مباشرة كما تتوقع. في هذه الحالة إمّا توقّف الوكيل مؤقتًا حتى صدور الشهادة، أو استخدم تحدي DNS، أو أصدر الشهادة على الخادم وأبقِ SSL عنده أو عند الوكيل بوعي، لا بالاثنين مع إعداد متعارض من غير أن تختبر curl -I https://example.com/health.

بعد نجاح Certbot، أعد فحص الرؤوس من خارج السيرفر لا من localhost فقط. من جهازك:

``bash curl -I --max-time 15 https://example.com/health ``

ابحث عن 200 وعن أن الاتصال TLS يعمل بالاسم الصحيح. إن ظهر تحذير اسم لا يطابق الشهادة، فغالبًا server_name ناقص أو طلبت الشهادة للنطاق بلا www ثم يزور الناس www.

تحديث التطبيق من دون أن تنسى خطوة

بعد سحب نسخة جديدة على السيرفر:

``bash git pull docker compose build docker compose up -d docker compose ps curl -sS http://127.0.0.1:3000/health ``

restart: unless-stopped يعيد تشغيل الحاوية بعد إعادة إقلاع VPS. هذا لا يغني عن نسخة احتياطية لقاعدة البيانات إن كانت على السيرفر نفسه. إذا أضفت Postgres في Compose، اجعل لها volume مسمّى، ولا تعتمد على قرص الحاوية. خذ نسخة pg_dump مجدولة إلى مكان خارج السيرفر. لا أفصّل هنا محركًا معيّنًا لأن اختيار القاعدة قرار مشروعك؛ المهم ألا يعيش البيانات الوحيدة على حاوية تُحذف في docker compose down -v.

سجلات التطبيق: docker compose logs -f --tail=200 app. لا تطبع أسرارًا ولا أجسام ويب هوك كاملة في الإنتاج إذا كانت تتضمن أرقام عمليات أو بيانات زبون.

تعديل .env لا يصل إلى حاوية تعمل إلا بعد إعادة إنشائها، لا بعد restart فقط:

``bash docker compose up -d --force-recreate app ``

راجع بعدها /health ومسارًا واحدًا حقيقيًا (إنشاء طلب تجريبي أو ويب هوك تجريبي) لأن الحاوية قد تقلع والمفتاح الجديد ناقص أو مسمّى خطأ.

ضبط المنطقة الزمنية إن كانت الفواتير أو نوافذ الدفع تعتمد على توقيت دمشق. الحاوية تتبع UTC ما لم تضبط TZ. يمكنك إضافة TZ=Asia/Damascus في .env إذا كان تطبيقك يقرأها، أو تعتمد UTC في قاعدة البيانات وتعرض التوقيت في الواجهة فقط. المهم ألا تختلط المهلة «حتى نهاية اليوم» بين منطقتين دون أن تدري.

مساحة القرص تمتلئ بهدوء من صور Docker القديمة ومن السجلات. بعد كل نشر ناجح يمكن حذف الصور غير المستخدمة: docker image prune. راقب df -h بين فترة وأخرى، خصوصًا على VPS صغير. سيرفر يرفض الكتابة في منتصف حفظ طلب أو حدث دفع أصعب في التشخيص من حاوية لم تقلع أصلًا.

إذا أضفت n8n على نفس السيرفر، امنحه اسم مضيف فرعيًا وملف Nginx خاصًا، ولا تضعه على منفذ مكشوف. خطوات ربط الطلبات والإشعارات في أتمتة شغل متجرك بـ n8n. بوت الدعم في بوت خدمة عملاء بالعربي يُنشر بالطريقة نفسها: حاوية، منفذ محلي، وكيل، شهادة.

أعطال أقابلها بعد أول نشر

شفت أكثر من مرة تطبيق متجر يُفتح على http://IP:3000 أيامًا قبل ربط النطاق. الموقع يعمل، لكن بلا HTTPS، والمنفذ مكشوف، وأي شخص يصل إلى العنوان يتجاوز Nginx. اربط النطاق والشهادة قبل أن تعلن الرابط للزبائن، وأغلق 3000 على الجدار كما في الخطوات أعلاه.

الشهادة تفشل لأن النطاق لا يشير إلى هذا السيرفر، أو لأن المنفذ 80 مغلق في لوحة مزوّد الـVPS حتى بعد فتح UFW. افحص الاثنين. بعض المزوّدين لديهم جدار منفصل عن النظام.

التطبيق يعيد توجيهًا حلقيًا أو يبني روابط http:// بعد تفعيل HTTPS. السبب غالبًا أنه لا يثق بـ X-Forwarded-Proto. في Express، خلف Nginx، استخدم app.set("trust proxy", 1) إذا كنت تعتمد على هذا الرأس في بناء الروابط أو في ملفات تعريف الارتباط الآمنة.

الحاوية «صحية» وNginx يرجع 502. عندها إما التطبيق لا يستمع على 0.0.0.0، أو المنفذ في Compose غير 3000، أو العملية خرجت بعد نجاح فحص الصحة الأول. راجع السجلات فورًا.

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

والنشر من جهازك إلى السيرفر بحساب root وملفات مملوكة لـroot يجعل USER node يفشل في قراءة الكود. اضبط الملكية قبل compose up.

قائمة تحقق قبل فتح النطاق للزبائن

  • سجل A يشير إلى السيرفر، وSSH يعمل بمفتاح على مستخدم غير root.
  • UFW يسمح بـ 22 و80 و443 فقط لما تحتاجه، والمنفذ 3000 غير مفتوح للعالم.
  • الحاوية تعيد التشغيل بعد إعادة الإقلاع، و/health يرجع 200 من localhost ثم من HTTPS.
  • .env خارج Git، وصلاحياته ضيقة، والأسرار الناقصة تمنع الإقلاع.
  • Certbot --dry-run ينجح، وتعرف أين تُحفظ السجلات إذا فشل تجديد بعد شهرين.
  • إن وُجدت قاعدة بيانات، لها volume ونسخة خارج السيرفر.
  • مسار الويب هوك، إن وُجد، يقرأ الجسم الخام ويتحقق من التوقيع.

أسئلة تتكرر

هل أضع Nginx داخل Docker أم على المضيف؟

على المضيف أخف للبداية وأوضح في التجديد مع Certbot. وضعه في Compose خيار صحيح أيضًا إذا أردت أن يكون كل شيء في ملف واحد، لكنه يحتاج ترتيب volumes لتحدي HTTP ولقراءة الشهادات. لا تخلط الطريقتين على نفس النطاق.

هل يكفي هذا لموقع فيه بطاقات دفع دولية؟

هذا أساس نشر آمن بما يكفي لتطبيق Node خلف HTTPS. متطلبات شركة البطاقة (مثل عزل إضافي أو قيود PCI) أوسع من هذا الدليل. لمتاجر تدفع بسيريتل كاش أو شام كاش، التطبيق يتصل بالبوابة المستضافة كما في ربط سيريتل كاش، والسيرفر عندك لا يخزّن المحفظة.

كم يكلف إعداد السيرفر إذا طلبت مني أن أقوم به؟

خدمة إعداد VPS تبدأ من 40 دولارًا مرة واحدة. إصلاح سرعة أو عطل يبدأ من 50 دولارًا. العناية المستمرة بالسيرفر 25 دولارًا في الشهر. الاستضافة نفسها تدفعها لمزوّد الـVPS حسب الخطة التي تختارها.

ماذا عن التطبيق إن كان على استضافة مشتركة بلا Docker؟

هذا الدليل لـVPS تتحكم به. الاستضافة المشتركة لها أسلوب رفع مختلف، ولن تشغّل الحاويات كما هي. إن كنت لا تريد إدارة سيرفر أصلًا، خطة المتجر المستضاف موجودة لهذا السبب.

إذا بدك أجهّز لك السيرفر أو أراجع نشرًا قائمًا، راسلني من صفحة الموقع أو على fayezalshami.dev@gmail.com. اذكر نظام التشغيل على الـVPS، ونطاقك، وما إذا كان مع التطبيق قاعدة بيانات أو ويب هوك دفع.

أدلّة ومقارنات

تحتاج إلى بناء هذا أو ربطه لعملك؟

استعرض الخدمات