دیپلوی لاراول روی هاست ابری و سرور

دیپلوی لاراول؛ آموزش قدم‌به‌قدم انتشار پروژه Laravel روی هاست ابری و VPS

روی لپ‌تاپ همه چیز درست کار می‌کند. php artisan serve را می‌زنید، صفحه بالا می‌آید، فرم‌ها ثبت می‌شوند. بعد پروژه را روی سرور می‌برید و اولین چیزی که می‌بینید یک صفحهٔ سفید با خطای 500 است. یا بدتر، صفحهٔ خطای رنگی لاراول که رمز دیتابیس را جلوی چشم همهٔ بازدیدکننده‌ها گذاشته است.

دیپلوی لاراول سخت نیست، ولی چند قدم دارد که اگر یکی جا بیفتد، سایت یا بالا نمی‌آید یا ناامن بالا می‌آید. این راهنما همان قدم‌ها را به ترتیب می‌آورد: چه چیزی باید روی سرور برسد، فایل .env عملیاتی چه شکلی است، روی VPS و روی هاست ابری چه دستورهایی اجرا می‌شود، صف و زمان‌بند را چطور زنده نگه دارید و بعد از دیپلوی چه چیزهایی را چک کنید. آخر مقاله هم جدول خطاهای رایج و راه رفعشان آمده است.

دیپلوی لاراول یعنی چه؟

دیپلوی (Deploy) یعنی کدی که روی سیستم خودتان نوشته‌اید، روی سروری اجرا شود که کاربر واقعی به آن وصل می‌شود. در لاراول این کار فقط کپی فایل نیست. باید وابستگی‌های Composer نصب شوند، فایل‌های فرانت با Vite ساخته شوند، جدول‌های دیتابیس با migration ساخته یا به‌روز شوند، کش تنظیمات و مسیرها ساخته شود و پروسه‌های پس‌زمینه مثل صف دوباره راه بیفتند.

یک قاعدهٔ ساده کمک می‌کند: هر چیزی که در گیت هست، روی سرور هم باید برسد؛ هر چیزی که در .gitignore است، روی سرور ساخته یا جداگانه تنظیم می‌شود. پوشهٔ vendor با composer install ساخته می‌شود، node_modules اصلاً روی سرور لازم نیست، و .env را هیچ‌وقت در مخزن کد نمی‌گذارید.

بخش پروژه در گیت؟ روی سرور چطور می‌رسد
کد برنامه (app، routes، resources، config) بله با git، CLI یا FTP
vendor خیر composer install روی سرور
public/build (خروجی Vite) معمولاً خیر npm run build روی سرور یا در CI و ارسال خروجی
.env هرگز دستی روی سرور یا متغیرهای محیطی پنل
storage/app و فایل‌های آپلودی خیر روی سرور می‌مانند؛ باید از بازنویسی در دیپلوی بعدی محافظت شوند

پیش‌نیازهای سرور برای دیپلوی لاراول

طبق مستند رسمی دیپلوی لاراول، نسخهٔ فعلی فریم‌ورک (Laravel 13) دست‌کم PHP 8.3 می‌خواهد و این اکستنشن‌ها باید روی سرور فعال باشند: Ctype، cURL، DOM، Fileinfo، Filter، Hash، Mbstring، OpenSSL، PCRE، PDO، Session، Tokenizer و XML. اگر پروژه‌تان روی نسخهٔ قدیمی‌تر است، بازهٔ PHP هر نسخه را در جدول پشتیبانی نسخه‌ها ببینید؛ مثلاً Laravel 11 با PHP 8.2 تا 8.4 کار می‌کند.

قبل از هر کاری، بخش require فایل composer.json را باز کنید و نسخهٔ PHP روی سرور را با آن تطبیق بدهید. بخش بزرگی از خطاهای «روی سیستم من کار می‌کرد» از همین اختلاف نسخه می‌آید.

جز PHP به این‌ها هم نیاز دارید:

  • وب‌سرور: Nginx یا Apache که همهٔ درخواست‌ها را به public/index.php بفرستد. ریشهٔ سایت باید پوشهٔ public باشد، نه ریشهٔ پروژه؛ وگرنه فایل‌هایی مثل .env از اینترنت قابل دسترسی می‌شوند.
  • دیتابیس: MySQL، MariaDB یا PostgreSQL. اگر هنوز بین این‌ها مردد هستید، مقایسهٔ MySQL و PostgreSQL را بخوانید.
  • Composer روی سرور، و اگر فرانت را روی سرور می‌سازید، Node.js.
  • دسترسی نوشتن برای پروسهٔ وب‌سرور روی پوشه‌های storage و bootstrap/cache.

سه مسیر رایج برای دیپلوی لاراول

برای دیپلوی لاراول سه گزینهٔ معمول دارید و هر کدام مقدار متفاوتی کار روی دوش شما می‌گذارد:

معیار هاست اشتراکی (cPanel/DirectAdmin) سرور مجازی (VPS) هاست ابری (PaaS)
نصب PHP و وب‌سرور از قبل نصب است ولی محدود با شما آماده؛ نسخهٔ PHP از پنل انتخاب می‌شود
دسترسی ترمینال و Artisan گاهی هست، گاهی نه کامل از طریق کنسول سرویس
صف و Supervisor معمولاً ممکن نیست خودتان نصب و تنظیم می‌کنید با یک فایل تنظیم در ریشهٔ پروژه
Cron برای زمان‌بند از پنل هاست با crontab با فایل تنظیم در ریشهٔ پروژه
SSL، فایروال و به‌روزرسانی سیستم‌عامل با میزبان با شما با میزبان
مناسب برای پروژهٔ خیلی ساده بدون صف تیمی که کنترل کامل سرور را می‌خواهد تیمی که می‌خواهد روی کد تمرکز کند

روی هاست اشتراکی معمولاً مجبورید محتوای public را جابه‌جا کنید یا با rewrite دور بزنید، که هم خطاساز است و هم خلاف توصیهٔ خود لاراول. اگر بین دو گزینهٔ بعدی تردید دارید، مقایسهٔ PaaS و VPS و PaaS چیست تفاوت هزینهٔ نگهداری را باز کرده‌اند.

آماده‌سازی پروژه قبل از دیپلوی لاراول

این کارها را روی سیستم خودتان انجام بدهید، قبل از اینکه حتی سراغ سرور بروید:

  1. فایل .env عملیاتی را جدا بنویسید. APP_ENV روی production و APP_DEBUG روی false. مستند لاراول صریح می‌گوید روشن ماندن debug در محیط عملیاتی مقادیر حساس تنظیمات را به کاربر نشان می‌دهد.
  2. APP_KEY را بسازید و نگه دارید. این کلید برای رمزنگاری سشن و کوکی‌ها استفاده می‌شود. اگر بعداً عوضش کنید، کاربران از حساب خارج می‌شوند و داده‌های رمزشده با کلید قبلی دیگر خوانده نمی‌شوند.
  3. در کد مستقیماً env() صدا نزنید. بعد از config:cache، فایل .env دیگر خوانده نمی‌شود و هر env() بیرون از پوشهٔ config مقدار null برمی‌گرداند. مقدار را در یک فایل config بگذارید و با config() بخوانید.
  4. migrationها را تست کنید. یک بار روی دیتابیس خالی php artisan migrate:fresh بزنید تا مطمئن شوید از صفر کامل اجرا می‌شوند.
  5. composer.lock را commit کنید. بدون آن، سرور ممکن است نسخهٔ دیگری از پکیج‌ها نصب کند.

یک نمونهٔ حداقلی از .env عملیاتی:

APP_NAME=MyShop
APP_ENV=production
APP_KEY=base64:GENERATED_BY_KEY_GENERATE
APP_DEBUG=false
APP_URL=https://example.com

LOG_CHANNEL=stack
LOG_LEVEL=warning

DB_CONNECTION=mysql
DB_HOST=db-host
DB_PORT=3306
DB_DATABASE=myshop
DB_USERNAME=myshop_user
DB_PASSWORD=change-me

CACHE_STORE=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis
REDIS_HOST=redis-host

اگر Redis ندارید، CACHE_STORE و QUEUE_CONNECTION را روی database بگذارید؛ برای شروع کافی است.

دیپلوی لاراول روی VPS قدم‌به‌قدم

فرض می‌کنیم روی سرور مجازی اوبونتو، PHP و Nginx و Composer نصب شده‌اند و دیتابیس آماده است. اولین دیپلوی این شکلی است:

cd /var/www
git clone git@github.com:you/myshop.git
cd myshop

composer install --no-dev --optimize-autoloader
cp .env.example .env    # then edit production values
php artisan key:generate

npm ci && npm run build

php artisan migrate --force
php artisan storage:link
php artisan optimize

sudo chown -R www-data:www-data storage bootstrap/cache

چند نکته دربارهٔ همین دستورها:

  • --no-dev پکیج‌های توسعه مثل ابزار تست را نصب نمی‌کند و --optimize-autoloader نقشهٔ کلاس‌ها را از قبل می‌سازد.
  • migrate --force لازم است چون لاراول در محیط production بدون این سوئیچ قبل از اجرای migration تأیید می‌خواهد.
  • php artisan optimize کش تنظیمات، رویدادها، مسیرها و viewها را یکجا می‌سازد. اگر تنظیمی را عوض کردید و اثری نداشت، اول php artisan optimize:clear را بزنید.
  • key:generate فقط بار اول. در دیپلوی‌های بعدی به آن دست نزنید.

در Nginx، root باید به /var/www/myshop/public اشاره کند. نمونهٔ کامل تنظیمات Nginx در همان مستند رسمی آمده است. بعد از آن SSL را با Certbot یا هر روش دیگری فعال کنید و APP_URL را با https بنویسید.

دیپلوی‌های بعدی کوتاه‌ترند:

cd /var/www/myshop
php artisan down
git pull origin main
composer install --no-dev --optimize-autoloader
npm ci && npm run build
php artisan migrate --force
php artisan optimize
php artisan queue:restart
php artisan up

همین چند خط را در یک اسکریپت deploy.sh بگذارید تا هر بار ترتیب یکسان بماند. قدم بعدی این است که با هر push به شاخهٔ اصلی خودکار اجرا شود؛ ایدهٔ کلی‌اش را در استقرار خودکار چیست نوشته‌ایم.

 

مراحل دیپلوی لاراول از کد محلی تا نصب پکیج، migration، بهینه‌سازی و بررسی سایت زنده

 

دیپلوی لاراول روی هاست ابری چابکان

روی هاست ابری، نصب PHP، وب‌سرور، SSL و به‌روزرسانی سیستم‌عامل با میزبان است و شما فقط کد و تنظیمات را می‌دهید. در هاست ابری لاراول چابکان مسیر این‌طور است:

  1. ساخت سرویس: از داشبورد، ساخت سرویس جدید ← هاست ابری ← Laravel. نسخهٔ PHP را بعداً از تنظیمات سرویس هم می‌توانید عوض کنید؛ فهرست نسخه‌های قابل انتخاب در مستند استقرار Laravel آمده است.
  2. ارسال کد: روش پیشنهادی CLI است. بعد از نصب CLI، با chabok login وارد می‌شوید و در پوشهٔ پروژه chabok deploy را می‌زنید. git از داخل کنسول سرویس، FTP و فایل‌منیجر هم پشتیبانی می‌شوند. اگر حجم پروژه از 100 مگابایت بیشتر است، مستندات FTP را پیشنهاد می‌کند. جزئیات در راهنمای استقرار با CLI.
  3. متغیرهای محیطی: مقادیر .env را در تنظیمات سرویس، بخش متغیرهای محیطی وارد کنید. ذخیرهٔ این بخش سرویس را دوباره مستقر می‌کند.
  4. دیتابیس: یک دیتابیس ابری MySQL یا دیگر موتورهای دیتابیس ابری بسازید و DB_HOST، DB_PORT، DB_DATABASE، DB_USERNAME و DB_PASSWORD را از داشبورد همان دیتابیس در متغیرهای محیطی بگذارید.
  5. Migration: از منوی سرویس، کنسول را باز کنید و php artisan migrate --force را بزنید.

سه نکتهٔ مخصوص این محیط که اگر ندانید، وقت می‌گیرند:

  • مسیرهای دائمی: با هر دیپلوی از طریق CLI، فایل‌های قبلی سرویس پاک و نسخهٔ جدید جایگزین می‌شود. پوشهٔ storage (فایل‌های آپلودی، لاگ‌ها) را بعد از اولین دیپلوی در بخش مسیرهای دائمی ثبت کنید تا در دیپلوی بعدی حذف نشود.
  • پروکسی معکوس: درخواست‌ها از پروکسی معکوس چابکان به سرویس می‌رسند. اگر لاراول پروکسی را trust نکند، لینک‌ها با http ساخته می‌شوند و فرم‌ها خطای Mixed Content می‌دهند. در Laravel 11 به بعد در bootstrap/app.php از $middleware->trustProxies(at: '*') استفاده کنید؛ در نسخه‌های قدیمی‌تر فایل TrustProxies.php را طبق نکات تکمیلی Laravel تغییر دهید.
  • تنظیمات php.ini: برای عوض‌کردن مقادیری مثل upload_max_filesize یا memory_limit، فایلی به نام chabok-php.ini در ریشهٔ پروژه بسازید و سرویس را یک بار ری‌استارت کنید.

اگر Composer موقع نصب پکیج‌ها کند بود یا به packagist نرسید، همان صفحهٔ نکات تکمیلی آدرس میرور Composer چابکان را دارد که در بخش repositories فایل composer.json می‌نشیند.

صف و زمان‌بند: بخش‌هایی که بعد از دیپلوی فراموش می‌شوند

سایت بالا آمده، ولی ایمیل‌های تأیید ارسال نمی‌شوند و گزارش شبانه هم ساخته نمی‌شود. دلیلش معمولاً این است که پروسه‌های پس‌زمینه را کسی روشن نکرده است. لاراول در محیط عملیاتی سه بخش اجرایی دارد:

بخش دستور چه کسی اجرایش می‌کند بعد از هر دیپلوی
وب public/index.php PHP-FPM یا Apache کش‌ها را با optimize بازسازی کنید
صف (Queue) php artisan queue:work Supervisor php artisan queue:restart
زمان‌بند (Scheduler) php artisan schedule:run Cron، هر دقیقه کاری لازم نیست

صف: ورکر صف یک پروسهٔ طولانی است و کد را یک بار در حافظه بار می‌کند. اگر بعد از دیپلوی آن را ری‌استارت نکنید، با کد قدیمی به کارش ادامه می‌دهد. queue:restart به ورکرها می‌گوید بعد از تمام‌کردن کار فعلی خارج شوند و Supervisor دوباره بالا می‌آوردشان. روی VPS یک فایل تنظیم Supervisor می‌سازید؛ نمونهٔ کاملش در مستند صف لاراول هست. در هاست ابری چابکان کافی است فایلی به نام supervisor.conf در ریشهٔ پروژه بگذارید و سرویس را ری‌استارت کنید:

[program:app-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/html/artisan queue:work --tries=3
directory=/var/www/html
autostart=true
autorestart=true
numprocs=1
redirect_stderr=true
stdout_logfile=/app-worker.log

زمان‌بند: طبق مستند Task Scheduling، کل زمان‌بندی لاراول با یک خط cron اجرا می‌شود که هر دقیقه schedule:run را صدا می‌زند و خود لاراول تصمیم می‌گیرد کدام کار وقتش رسیده است. روی VPS این خط را در crontab -e می‌گذارید. در چابکان فایلی به نام cron-jobs در ریشهٔ پروژه می‌سازید؛ مسیر پروژه در سرویس Laravel برابر /var/www/html است:

* * * * * cd /var/www/html && php artisan schedule:run >> /dev/null 2>&1

این فایل موقع راه‌اندازی سرویس خوانده می‌شود، پس بعد از هر تغییر سرویس را ری‌استارت کنید. آخر فایل هم یک خط خالی بگذارید. راهنماهای کامل: Supervisor در چابکان و Cron Job در چابکان.

 

اجزای اجرایی لاراول بعد از دیپلوی شامل وب، ورکر صف، زمان‌بند، دیتابیس، Redis و فضای ذخیره‌سازی

 

فایل‌های آپلودی کجا بمانند؟

لاراول فایل‌های عمومی را در storage/app/public نگه می‌دارد و با php artisan storage:link یک لینک نمادین از public/storage به آن می‌سازد. دو اشتباه رایج اینجا پیش می‌آید: لینک را بعد از دیپلوی نمی‌سازند و تصاویر 404 می‌دهند، یا پوشهٔ storage در هر دیپلوی بازنویسی می‌شود و آپلودهای کاربران پاک می‌شوند.

اگر فقط یک سرور دارید، محافظت از storage (روی VPS با نگه‌داشتنش بیرون از مسیری که git بازنویسی می‌کند، در چابکان با مسیر دائمی) کافی است. اگر می‌خواهید بعداً چند نمونه از برنامه را کنار هم اجرا کنید یا حجم فایل‌ها زیاد است، دیسک لاراول را روی فضای سازگار با S3 ببرید. لاراول درایور S3 دارد و با پکیج league/flysystem-aws-s3-v3 به هر فضای سازگار وصل می‌شود. فضای ذخیره‌سازی ابری چابکان با پروتکل S3 سازگار است و مراحل اتصالش در مستند اتصال Laravel به S3 آمده است. مفهوم کلی را هم در فضای ذخیره‌سازی S3 چیست توضیح داده‌ایم.

چک‌لیست بعد از دیپلوی لاراول

قبل از اینکه لینک را برای مشتری یا تیم بفرستید، این موارد را یکی‌یکی بررسی کنید:

  • آدرس /up را باز کنید. لاراول از نسخهٔ 11 این مسیر سلامت را دارد و اگر برنامه بدون خطا بوت شود، کد 200 برمی‌گرداند. همین آدرس را به سرویس مانیتورینگ آپتایم بدهید.
  • یک صفحهٔ ناموجود را باز کنید. باید صفحهٔ 404 ساده ببینید، نه صفحهٔ دیباگ با مسیر فایل‌ها.
  • آدرس https://example.com/.env را امتحان کنید. باید 404 یا 403 بگیرید.
  • ثبت‌نام یا یک فرم را تست کنید تا سشن، CSRF و ارسال ایمیل از طریق صف معلوم شوند.
  • یک فایل آپلود کنید و مطمئن شوید آدرسش باز می‌شود.
  • storage/logs/laravel.log یا بخش لاگ‌های سرویس را نگاه کنید. خطای تکرارشونده‌ای نباید باشد.
  • بکاپ دیتابیس را بررسی کنید. اولین migration روی دادهٔ واقعی بهترین زمان برای داشتن یک بکاپ سالم است.

خطاهای رایج بعد از دیپلوی لاراول

خطا یا نشانه علت محتمل راه رفع
صفحهٔ سفید یا خطای 500 بدون توضیح دسترسی نوشتن روی storage یا bootstrap/cache نیست، یا نسخهٔ PHP با پروژه نمی‌خواند لاگ لاراول و لاگ وب‌سرور را ببینید؛ مالکیت پوشه‌ها و نسخهٔ PHP را درست کنید
No application encryption key has been specified APP_KEY خالی است بار اول php artisan key:generate و بعد کش تنظیمات را دوباره بسازید
تنظیم جدید در .env اثر ندارد کش تنظیمات قدیمی است php artisan optimize:clear و دوباره optimize
مقدار env() در کد null است env() بیرون از پوشهٔ config صدا زده شده و config کش شده است مقدار را به یک فایل config ببرید و با config() بخوانید
خطای 419 Page Expired در فرم‌ها سشن ذخیره نمی‌شود یا دامنهٔ کوکی با APP_URL نمی‌خواند SESSION_DRIVER، SESSION_DOMAIN و https بودن APP_URL را بررسی کنید
لینک‌ها و assetها با http ساخته می‌شوند پروکسی معکوس trust نشده است trustProxies را تنظیم کنید
Vite manifest not found فرانت روی سرور build نشده است npm run build را اجرا کنید یا پوشهٔ public/build را بفرستید
تصاویر آپلودی 404 می‌دهند لینک public/storage ساخته نشده یا پوشه پاک شده php artisan storage:link و محافظت از مسیر storage
ایمیل‌ها و jobها اجرا نمی‌شوند ورکر صف روشن نیست یا با کد قدیمی کار می‌کند Supervisor را بررسی و queue:restart را به اسکریپت دیپلوی اضافه کنید
Call to undefined function ... shell_exec() تابع‌های exec و shell_exec به دلایل امنیتی بسته‌اند در چابکان طبق مستند مشکلات احتمالی عمل کنید

کدام مسیر برای دیپلوی لاراول مناسب‌تر است؟

اگر می‌خواهید Nginx را خودتان تنظیم کنید، روی سرور Redis و Meilisearch و ابزارهای دیگر هم نصب کنید و از کار با لینوکس لذت می‌برید، سرور ابری انعطاف کامل می‌دهد. فقط یادتان باشد امنیت، به‌روزرسانی، بکاپ و مانیتورینگ هم از همان روز اول کار شماست.

اگر ترجیح می‌دهید وقت تیم صرف کد شود، هاست ابری لاراول چابکان PHP و وب‌سرور آماده، کنسول برای Artisan، Supervisor و Cron با یک فایل، SSL و بکاپ خودکار را یکجا می‌دهد. منابع سرویس را هم هر وقت لازم شد از پنل بالا می‌برید. پلن‌ها و امکانات هر کدام را در جدول تعرفهٔ صفحهٔ هاست لاراول مقایسه کنید. اگر سایت فعلی‌تان جای دیگری است، راهنمای انتقال سایت به هاست جدید مراحل جابه‌جایی را توضیح داده است.

سؤالات متداول

دیپلوی لاراول روی هاست اشتراکی cPanel ممکن است؟

ممکن است، ولی با محدودیت. باید ریشهٔ دامنه را به پوشهٔ public ببرید و اگر پنل اجازه نمی‌دهد، به ترفندهایی مثل جابه‌جایی index.php رو می‌آورید که مستند لاراول صریحاً از آن منع می‌کند. صف دائمی هم معمولاً روی هاست اشتراکی اجرا نمی‌شود. برای پروژهٔ جدی، VPS یا هاست ابری انتخاب امن‌تری است.

آیا پوشهٔ vendor را روی سرور آپلود کنم؟

بهتر است نه. composer.lock را بفرستید و روی سرور composer install --no-dev بزنید تا همان نسخه‌های دقیق نصب شوند. آپلود vendor از ویندوز روی سرور لینوکس گاهی به مشکل مسیر و دسترسی می‌خورد. در هاست ابری چابکان نصب پکیج‌ها بعد از دیپلوی خودکار انجام می‌شود.

بعد از هر دیپلوی لاراول کدام دستورها را باید اجرا کنم؟

حداقل composer install --no-dev --optimize-autoloader، php artisan migrate --force، php artisan optimize و اگر صف دارید php artisan queue:restart. اگر فرانت با Vite دارید، npm run build هم لازم است.

APP_DEBUG را کی روشن کنم؟

در محیط عملیاتی هیچ‌وقت. برای پیدا کردن خطا، لاگ storage/logs یا لاگ‌های سرویس را بخوانید. اگر لازم است خطا را موقتاً ببینید، روی یک نسخهٔ staging جدا این کار را بکنید.

دیتابیس را کنار برنامه روی همان سرور نصب کنم یا جدا؟

برای شروع روی یک VPS، نصب کنار برنامه ساده‌تر است. وقتی ترافیک بالا رفت یا خواستید برنامه را روی چند سرور اجرا کنید، دیتابیس جدا و مدیریت‌شده بکاپ و به‌روزرسانی را از دوش شما برمی‌دارد و منابع برنامه با کوئری‌های سنگین درگیر نمی‌شود.

Laravel Octane را هم می‌توانم روی هاست ابری اجرا کنم؟

در سرویس Laravel چابکان بله. با مقداردهی متغیر محیطی START_COMMAND به دستور php artisan octane:start --server=swoole --host=0.0.0.0 --port=80 سرویس با Octane بالا می‌آید. قبلش مطمئن شوید کدتان با اجرای ماندگار در حافظه سازگار است؛ مثلاً state سراسری بین درخواست‌ها نشت نکند.

دیدگاه خود را بنویسید:

آدرس ایمیل شما نمایش داده نخواهد شد.

فوتر سایت