مقدمه

این راهنما مراحل نصب، پیکربندی و دیباگ برنامه‌های Node.js هاست‌ cPanel را توضیح می‌دهد؛ با استفاده از Setup Node.js App و Phusion Passenger می‌توانید وابستگی‌ها را مدیریت، محیط اجرا را تنظیم و عملکرد را در سرور مجازی یا سرور ابری بهینه کنید.

در این سند به‌صورت گام‌به‌گام روش راه‌اندازی یک برنامه Node.js روی cPanel hosting با ابزار Setup Node.js App پوشش داده می‌شود. ابتدا مفهوم Node.js و نقش Phusion Passenger در یکپارچه‌سازی با Apache توضیح داده می‌شود، سپس مراحل ایجاد اپلیکیشن، تنظیم Application root و startup file و نصب وابستگی‌ها با Run NPM Install آمده است. دسترسی از طریق ترمینال، تعریف متغیرهای محیطی و روش‌های اشکال‌زدایی با بررسی لاگ‌های Apache و Passenger نیز شرح داده شده است. نکات عیب‌یابی متداول مثل خطای CXXABI و متوقف‌شدن npm install و توصیه‌هایی برای انتخاب هاست نود جی اس، سرور مجازی یا سرور ابری برای بهبود پایداری و SEO ارائه می‌شود.

Node.js چیست؟

Node.js یک محیط اجرای متن‌باز و چندسکویی است که به شما امکان می‌دهد وب‌سایت یا برنامه‌ای ایجاد کنید و با استفاده از زبان JavaScript آن را روی یک سرور میزبانی کنید. در بسته‌های cPanel و CloudCP ما، مدیر برنامهٔ Node.js را ارائه می‌دهیم تا بتوانید برنامهٔ Node.js خود را روی بستهٔ میزبانی وب cPanel راه‌اندازی کنید. نسخه‌های Node.js از 6.x تا 20.x در دسترس هستند.

Phusion Passenger چیست؟

Phusion Passenger یک ابزار میانی (application server / process manager) است که برنامه‌های وب را با وب‌سرور Apache یا Nginx یکپارچه می‌کند تا فرآیندهای برنامه (مثل برنامه‌های Node.js، Ruby یا Python) به‌صورت پایدار، مدیریت‌شده و امن اجرا شوند؛ Passenger مدیریت راه‌اندازی و نگهداری پروسس‌ها، لاگ‌ها و توزیع بار را برعهده دارد و اجازه نمی‌دهد برنامه‌های Node.js به‌صورت مستقل و با دستورات محلی (مثل npm run start یا pm2) روی وب‌سرور اجرا شوند مگر اینکه با Passenger سازگار باشند.

ما پروکسی معکوس (reverse proxy) راه‌اندازی نمی‌کنیم و برنامه‌های Node.js نمی‌توانند به‌صورت مستقل روی وب‌سرور اختصاصی خود اجرا شوند. اگر به اجرای سرور Node.js با دستوری مانند npm run start یا pm2 start myapp عادت دارید، در بسته‌های میزبانی cPanel ما قادر به انجام این کار نخواهید بود. اگر از یک فریم‌ورک استفاده می‌کنید، بررسی کنید آیا با Phusion Passenger سازگار است یا خیر.

چگونه یک برنامهٔ Node.js را نصب کنم؟

به رابط مدیریت cPanel خود وارد شوید و روی آیکون “Setup Node.js App” کلیک کنید.

در صفحهٔ بعدی، روی دکمهٔ “Create Application” کلیک کنید تا یک برنامهٔ جدید اضافه کنید.

سپس فیلدها را مطابق نیاز برنامه پر کنید:

– Node.js version: نسخهٔ Node.js مورد نیاز برنامه.

– Application mode: حالت اجرای برنامه را تعیین می‌کند؛ یا حالت توسعه (developer) یا حالت تولید (production). این گزینه متغیر محیطی NODE_ENV را تنظیم می‌کند و در حالت توسعه خطاها نمایش داده می‌شوند (مفید برای دیباگ اما ممکن است برای محیط production مشکل‌ساز باشد).

– Application root: مکان ریشهٔ برنامهٔ Node.js شما نسبت به ریشهٔ FTP. توصیه می‌شود برنامهٔ Node.js را در پوشهٔ public_html قرار ندهید.

– Application URL: آدرس ریشهٔ URL برنامهٔ Node.js شما.

– Application startup file: نام فایل .js که Passenger برای راه‌اندازی برنامه به Node.js ارسال می‌کند.

پس از پیکربندی، روی دکمهٔ “Create” کلیک کنید.

اگر فایل شروع برنامه وجود نداشته باشد، ابزار این فایل را بلافاصله با محتوای نمونه ایجاد می‌کند. این نمونه در تمام درخواست‌های HTTP مرتبط پیام “It works!” را نمایش می‌دهد.

محتوای نمونهٔ اسکریپت:

var http = require('http'); var server = http.createServer(function(req, res) { res.writeHead(200, {'Content-Type': 'text/plain'}); var message = 'It works!\n', version = 'NodeJS ' + process.versions.node + '\n', response = [message, version].join('\n'); res.end(response); }); server.listen();

همچنین می‌توانید فایل package.json را از طریق رابط ویرایش کنید تا وابستگی‌ها را اضافه کنید و آن‌ها را با دکمهٔ “Run NPM Install” نصب نمایید.

توجه داشته باشید که در صورت تغییر وابستگی‌ها باید برنامه را ری‌استارت کنید.

همچنین می‌توانید متغیرهای محیطی را در بخش Environment variables تعریف کنید اگر برنامهٔ شما برای دریافت پارامترهایی به آن‌ها متکی است.

دسترسی به برنامهٔ شما از طریق ترمینال

استفاده از خط فرمان و ترمینال بخش جدایی‌ناپذیر اکوسیستم Node.js است. برای دسترسی به محیط برنامه از طریق ترمینال، به ترمینال وب cPanel یا از طریق یک کلاینت SSH متصل شوید و دستور نشان‌داده‌شده را کپی کنید تا وارد محیط برنامه شوید.

این کار به‌طور خودکار محیط مجازی مناسب برنامه را فعال می‌کند، شامل نسخهٔ صحیح Node.js و NPM و همچنین وابستگی‌های نصب‌شده در محیط (به‌جای نصب در پوشهٔ “node_modules” داخل پوشهٔ برنامه).

برای راه‌اندازی Node.js روی cPanel hosting، از Setup Node.js App استفاده کنید و قبل از استقرار، سازگاری فریم‌ورک با Phusion Passenger را بررسی کنید؛ انتخاب یک هاست مناسب مانند هاست نود جی اس یا nodejs host و بررسی مشخصات سرور مجازی یا سرور ابری بر اساس نیازهای RAM و CPU به پایداری و سرعت برنامه کمک می‌کند.

اشکال‌زدایی یک برنامهٔ Node.js

برای دیباگ یک برنامهٔ Node.js می‌توانید لاگ خطاهای Apache را بررسی کنید. فایل لاگ خطای Apache شامل:

– خروجی STDOUT و STDERR برنامهٔ Node.js

– خطاهای مرتبط با Passenger

– خطاهای مرتبط با Apache

اگر مقدار PassengerLogFile را در .htaccess سایت خود به‌صورت دستی تنظیم کرده‌اید، خروجی STDOUT و STDERR و خطاهای Passenger به آن فایل فرستاده می‌شوند به‌جای لاگ Apache.

همچنین می‌توانید PassengerFriendlyErrorPages را در .htaccess روی on قرار دهید تا خطاهای مربوط به راه‌اندازی برنامه مستقیماً در مرورگر نمایش داده شوند.

Common Node.js errors

Error: /lib64/libstdc++.so.6: version 'CXXABI_X.X.X' not found

دلایل ممکن: برنامهٔ Node.js شما یا یکی از وابستگی‌های آن به قابلیت‌های خاصی از کتابخانهٔ C++ نیاز دارد که در سرور فعلی موجود نیست. این مورد ممکن است در محیط‌هایی با CloudLinux 7 (برپایهٔ CentOS/RHEL 7) رخ دهد، در حالی که یکی از وابستگی‌ها نیاز به RHEL 8/CentOS 8 یا بالاتر دارد.

راه‌حل: می‌توانید درخواست پشتیبانی باز کنید تا به سروری با سیستم‌عامل CloudLinux 8 مهاجرت شوید.

فرآیند هنگام اجرای npm install متوقف شد

دلایل ممکن: ممکن است فرآیند توسط سرور متوقف شود اگر از زمان اجرا یا منابع مجاز (CPU، RAM و غیره) فراتر رفته باشد. سابقهٔ توقف فرآیند را از ابزار “Logs” در رابط cPanel می‌توانید مشاهده کنید.

راه‌حل: می‌توانید مصرف رم npm را با متغیر محیطی NODE_OPTIONS محدود کنید، مثلاً:

NODE_OPTIONS='--max-old-space-size=2048' npm install

این نمونه محدودیتی معادل 2048 MiB (2 GB) نشان می‌دهد.

پوشهٔ مشخص‌شده هنگام ایجاد از «Setup Node.js App» قبلاً توسط /home/$USER/public_html/monapp استفاده شده است.

دلایل ممکن:

– برنامهٔ Node.js، Python یا Ruby قبلاً در دایرکتوری مشخص منتشر شده است.

– برنامهٔ root و برنامهٔ مشخص‌شده توسط URL به یک پوشه اشاره می‌کنند.

راه‌حل:

1. بررسی کنید که هیچ برنامهٔjs، Python یا Ruby در پوشهٔ مشخص منتشر نشده باشد. فایل .htaccess آن پوشه را از طریق فایل منیجر یا FTP بررسی کنید.

2. مطمئن شوید فایل‌های برنامه (.js، json …) که در application root مشخص شده‌اند در پوشهٔ منتشرشده توسط application URL قرار ندارند. برخلاف برنامه‌های PHP، فایل‌های برنامهٔ Node.js نباید و نیازی نیست در public_html قرار گیرند.

نکات پایانی

هنگام برنامه‌نویسی و راه‌اندازی Node.js، مدیریت وابستگی‌ها با package.json و اجرای Run NPM Install در محیط مدیریت cPanel، بهترین شیوه است؛ برای محیط production حالت NODE_ENV را درست تنظیم کنید و برای توسعه از حالت developer استفاده کنید تا دیباگ راحت‌تر باشد؛ این موارد به SEO و تجربهٔ کاربری روی هاست نود جی اس و nodejs host کمک می‌کنند.

برای اطمینان از عملکرد پایدار در سرور مجازی یا سرور ابری انتخابی، لاگ‌های Apache و تنظیمات PassengerLogFile و PassengerFriendlyErrorPages را بررسی کنید؛ این کار خطاهای runtime را سریع‌تر نشان می‌دهد و زمان خرابی را کاهش می‌دهد که برای تجربهٔ کاربر و رتبهٔ سایت در موتورهای جست‌وجو مهم است.

اگر با خطای CXXABI مواجه شدید یا npm install متوقف شد، بررسی نسخهٔ سیستم‌عامل سرور (CloudLinux 7 vs 8) و محدود کردن حافظهٔ npm با NODE_OPTIONS بهترین راه‌حل‌های اولیه هستند؛ انتخاب یک nodejs host مناسب یا مهاجرت به سرور مجازی/سرور ابری با نسخهٔ جدیدتر سیستم‌عامل می‌تواند مشکل را حل کند.

در مستندات استقرار، تاکید کنید فایل‌های برنامه را خارج از public_html نگه دارید، Application URL و Application root را جدا تعریف کنید و از Workflowهای استاندارد برای راه‌اندازی Node.js و مدیریت وابستگی‌ها استفاده کنید؛ این روش‌ها در هاست نود جی اس و nodejs host به کاهش خطا و بهبود SEO کمک خواهند کرد.