پس از توسعه یک پروژه Laravel روی سیستم شخصی، یکی از مهم‌ترین مراحل، انتقال آن به سرور و آماده‌سازی برای استفاده کاربران است. این فرایند که با نام Deploy یا Deployment شناخته می‌شود، تنها به کپی‌کردن فایل‌های پروژه محدود نیست؛ بلکه باید محیط اجرای PHP، وب‌سرور، پایگاه داده، تنظیمات امنیتی و سرویس‌های موردنیاز برنامه نیز به‌درستی پیکربندی شوند.
Ubuntu یکی از سیستم‌عامل‌های رایج برای میزبانی برنامه‌های PHP و Laravel است. در این مقاله، مراحل استقرار یک پروژه Laravel روی سرور Ubuntu را با استفاده از Nginx، PHP-FPM و MySQL بررسی می‌کنیم.
Deploy لاراول چیست؟
Deploy کردن لاراول یعنی آماده‌سازی و انتقال پروژه از محیط توسعه به محیطی که کاربران بتوانند از طریق اینترنت به آن دسترسی داشته باشند.
در یک استقرار معمولی، مراحل زیر انجام می‌شوند:
- آماده‌سازی سرور و نصب نرم‌افزارهای موردنیاز
- انتقال کد پروژه به سرور
- نصب وابستگی‌های PHP
- تنظیم فایل محیطی
.env - آماده‌سازی پایگاه داده
- پیکربندی وب‌سرور
- تنظیم مجوزهای فایل‌ها
- اجرای Migrationها و دستورات بهینه‌سازی
- فعال‌سازی HTTPS و بررسی عملکرد برنامه
جزئیات این مراحل به نسخه Laravel، نوع پروژه و معماری سرور بستگی دارد؛ اما اصول کلی در بسیاری از پروژه‌ها یکسان است.
پیش‌نیازهای Deploy لاراول روی Ubuntu
قبل از شروع، به یک سرور Ubuntu با دسترسی SSH و مجوزهای لازم برای نصب و پیکربندی سرویس‌ها نیاز دارید.
همچنین باید موارد زیر مشخص باشند:
- نسخه Laravel و نسخه PHP سازگار با پروژه
- نوع پایگاه داده، مانند MySQL یا PostgreSQL
- دامنه‌ای که قرار است به پروژه متصل شود
- تنظیمات محیطی پروژه
- روش انتقال کد، مانند Git یا SFTP
در این آموزش از Nginx، PHP-FPM و MySQL استفاده می‌کنیم. فرض می‌کنیم دامنه نمونه پروژه example.com است؛ در سرور واقعی باید آن را با دامنه خود جایگزین کنید.
نکته مهم: نسخه PHP را صرفاً بر اساس جدیدترین نسخه موجود انتخاب نکنید. ابتدا نیازمندی‌های پروژه را در فایل composer.json و مستندات نسخه Laravel بررسی کنید.
مرحله اول: اتصال به سرور Ubuntu
در ویندوز می‌توانید از Windows Terminal یا PowerShell برای اتصال SSH استفاده کنید.
ssh username@SERVER_IP
در این دستور، username نام کاربر سرور و SERVER_IP آدرس IP سرور است.
پس از اتصال، نسخه سیستم‌عامل را بررسی کنید:
lsb_release -a
سپس فهرست بسته‌های سیستم را به‌روزرسانی کنید:
sudo apt update
sudo apt upgrade
قبل از اجرای به‌روزرسانی‌های گسترده روی سرور Production، از سازگاری آن‌ها با سرویس‌های فعال مطمئن شوید و در صورت امکان نسخه پشتیبان تهیه کنید.
مرحله دوم: نصب Nginx
Nginx درخواست‌های HTTP را دریافت می‌کند و فایل‌های عمومی پروژه را ارائه می‌دهد. برای فایل‌های PHP نیز درخواست‌ها را به PHP-FPM ارسال می‌کند.
برای نصب Nginx دستور زیر را اجرا کنید:
sudo apt install nginx
وضعیت سرویس را بررسی کنید:
sudo systemctl status nginx
در صورت نیاز، سرویس را فعال و اجرا کنید:
sudo systemctl enable --now nginx
اگر فایروال UFW فعال است، دسترسی HTTP و HTTPS را مطابق سیاست امنیتی سرور مجاز کنید. برای مثال:
sudo ufw allow 'Nginx Full'
پیش از تغییر قوانین فایروال، مطمئن شوید دسترسی SSH شما مسدود نمی‌شود.
مرحله سوم: نصب PHP و افزونه‌های موردنیاز Laravel
Laravel برای اجرا به PHP و مجموعه‌ای از افزونه‌های موردنیاز وابستگی‌های پروژه احتیاج دارد.
ابتدا نسخه موردنیاز پروژه را مشخص کنید. سپس نسخه سازگار PHP و بسته‌های آن را از مخازن معتبر نصب کنید.
برای نمونه، اگر پروژه شما با PHP 8.3 سازگار است و این نسخه در مخازن سیستم موجود است، دستور زیر نمونه‌ای از نصب بسته‌های موردنیاز خواهد بود:
sudo apt install php8.3-fpm php8.3-cli php8.3-mysql \
php8.3-mbstring php8.3-xml php8.3-curl \
php8.3-zip php8.3-bcmath php8.3-intl
بسته‌های موردنیاز ممکن است بر اساس نسخه Laravel و وابستگی‌های پروژه متفاوت باشند. اگر نسخه PHP موردنیاز در مخازن پیش‌فرض Ubuntu موجود نیست، باید از منبع معتبر و سازگار با نسخه سیستم‌عامل استفاده کنید.
نسخه PHP را بررسی کنید:
php -v
وضعیت PHP-FPM را نیز بررسی کنید:
sudo systemctl status php8.3-fpm
اگر نسخه دیگری نصب کرده‌اید، نام سرویس را متناسب با همان نسخه تغییر دهید.
مرحله چهارم: نصب Composer
Composer ابزار مدیریت وابستگی‌های PHP است. Laravel و بسیاری از کتابخانه‌های مورد استفاده در پروژه‌های آن از طریق Composer مدیریت می‌شوند.
برای نصب Composer، از دستورالعمل رسمی آن استفاده کنید و فایل اجرایی را پس از بررسی صحت آن در مسیر مناسب قرار دهید.
پس از نصب، نسخه Composer را بررسی کنید:
composer --version
در محیط Production، هنگام نصب وابستگی‌ها معمولاً از دستور زیر استفاده می‌شود:
composer install --no-dev --optimize-autoloader
این دستور وابستگی‌های ثبت‌شده در composer.lock را نصب می‌کند، بسته‌های توسعه‌ای را کنار می‌گذارد و بارگذاری خودکار کلاس‌ها را بهینه می‌کند.
تفاوت مهم: در استقرار پروژه موجود، معمولاً باید از composer install استفاده کنید، نه composer update. دستور update ممکن است نسخه وابستگی‌ها را تغییر دهد و فایل قفل وابستگی‌ها را به‌روزرسانی کند.
مرحله پنجم: انتقال پروژه Laravel به سرور
برای انتقال کد پروژه چند روش رایج وجود دارد:
- دریافت کد از مخزن Git
- انتقال فایل‌ها با SFTP
- استفاده از فرایند استقرار خودکار CI/CD
اگر از Git استفاده می‌کنید، ابتدا Git را نصب کنید:
sudo apt install git
سپس پروژه را در مسیر مناسب دریافت کنید. برای نمونه:
cd /var/www
sudo git clone YOUR_REPOSITORY_URL example-app
در این مثال، YOUR_REPOSITORY_URL باید با آدرس مخزن واقعی پروژه جایگزین شود.
برای کارهای روزمره بهتر است از یک کاربر مشخص برای مدیریت پروژه استفاده کنید و از اجرای بی‌دلیل Composer یا دستورات Artisan با کاربر root خودداری کنید.
نکته امنیتی: فایل .env نباید به‌صورت عمومی در مخزن Git قرار بگیرد. همچنین پوشه vendor را معمولاً نیازی نیست از سیستم توسعه منتقل کنید، زیرا وابستگی‌ها را می‌توان در سرور با Composer نصب کرد.
مرحله ششم: تنظیم فایل .env
Laravel تنظیمات محیط اجرا را معمولاً از فایل .env می‌خواند. این تنظیمات شامل اطلاعات پایگاه داده، کلید برنامه، آدرس سایت و سایر متغیرهای محیطی هستند.
در محیط Production باید مقادیر مناسب را تنظیم کنید. نمونه زیر صرفاً برای نشان‌دادن ساختار فایل است:
APP_NAME="Example App"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://example.com
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=example_app
DB_USERNAME=example_user
DB_PASSWORD=CHANGE_THIS_PASSWORD
اگر پایگاه داده روی سرور دیگری قرار دارد، باید مقدار DB_HOST را متناسب با آن تغییر دهید.
اگر از قبل کلید برنامه در محیط توسعه تولید شده است، آن را در استقرار جدید به‌درستی مدیریت کنید. در پروژه‌ای که داده‌های رمزنگاری‌شده قبلی دارد، تغییر بی‌برنامه APP_KEY می‌تواند باعث از دسترس خارج‌شدن آن داده‌ها شود.
برای پروژه جدیدی که هنوز کلید برنامه ندارد، می‌توانید پس از آماده‌شدن وابستگی‌ها اجرا کنید:
php artisan key:generate
در محیط Production حتماً مقدار APP_DEBUG را روی false قرار دهید؛ نمایش جزئیات خطاها به کاربران می‌تواند اطلاعات حساس برنامه را افشا کند.
مرحله هفتم: ساخت پایگاه داده و کاربر MySQL
اگر MySQL روی همان سرور نصب شده است، باید پایگاه داده و کاربر مخصوص برنامه را ایجاد کنید.
برای ورود به محیط مدیریت MySQL:
sudo mysql
سپس نمونه دستورهای زیر را با رمز عبور امن و اختصاصی خود اجرا کنید:
CREATE DATABASE example_app
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
CREATE USER 'example_user'@'localhost'
IDENTIFIED BY 'CHANGE_THIS_PASSWORD';
GRANT ALL PRIVILEGES ON example_app.*
TO 'example_user'@'localhost';
FLUSH PRIVILEGES;
سپس از محیط MySQL خارج شوید:
EXIT;
مقدارهای پایگاه داده در فایل .env باید با مقادیر واقعی ایجادشده مطابقت داشته باشند.
اگر از PostgreSQL یا پایگاه داده‌ای روی سرور جداگانه استفاده می‌کنید، باید تنظیمات اتصال را مطابق همان سرویس انجام دهید.
مرحله هشتم: نصب وابستگی‌های پروژه
به مسیر پروژه بروید:
cd /var/www/example-app
سپس وابستگی‌های PHP را نصب کنید:
composer install --no-dev --optimize-autoloader
برای اجرای این دستور، فایل composer.lock باید در پروژه موجود باشد و نیازمندی‌های پروژه با نسخه PHP سرور سازگار باشند.
اگر برنامه از Vite برای مدیریت فایل‌های فرانت‌اند استفاده می‌کند، باید فایل‌های نهایی CSS و JavaScript نیز ساخته و در مسیر مورد انتظار پروژه قرار گرفته باشند. این کار معمولاً در محیط ساخت با Node.js انجام می‌شود:
npm ci
npm run build
این دستورات باید در محیطی اجرا شوند که Node.js و npm سازگار با پروژه نصب شده باشند. در بسیاری از فرایندهای استقرار، ساخت فایل‌های فرانت‌اند در مرحله Build انجام می‌شود و فقط خروجی نهایی به سرور منتقل می‌شود.
مرحله نهم: تنظیم مجوزهای فایل‌ها
Laravel برای ثبت گزارش‌ها، فایل‌های کش و برخی داده‌های اجرایی به دسترسی نوشتن در پوشه‌های مشخصی نیاز دارد.
مهم‌ترین مسیرها عبارت‌اند از:
storage/
bootstrap/cache/
وب‌سرور و فرایند PHP-FPM باید بتوانند در این مسیرها بنویسند. روش تنظیم مالکیت به کاربری که PHP-FPM با آن اجرا می‌شود و ساختار استقرار شما بستگی دارد.
در پیکربندی رایج Ubuntu، کاربر وب‌سرور ممکن است www-data باشد. در این صورت، پس از بررسی مالکیت فایل‌ها و سیاست دسترسی پروژه، می‌توانید از تنظیمی مشابه زیر استفاده کنید:
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R u+rwX,g+rwX storage bootstrap/cache
اگر فرایند Deploy با کاربر جداگانه اجرا می‌شود، باید دسترسی‌ها را طوری طراحی کنید که هم استقرار کد و هم اجرای برنامه بدون مشکل انجام شوند.
از تنظیم مجوز 777 برای کل پروژه خودداری کنید؛ چنین تنظیمی معمولاً غیرضروری است و می‌تواند امنیت فایل‌ها را کاهش دهد.
مرحله دهم: اجرای Migrationها
پس از تنظیم فایل .env و اطمینان از اتصال به پایگاه داده، باید ساختار جداول موردنیاز برنامه ایجاد یا به‌روزرسانی شود.
برای مشاهده وضعیت Migrationها:
php artisan migrate:status
برای اجرای Migrationهای جدید:
php artisan migrate --force
پارامتر --force برای اجرای Migration در محیط Production استفاده می‌شود تا تأیید تعاملی محیط Production مانع اجرا نشود.
نکته مهم: قبل از اجرای Migration روی سرور اصلی، تغییرات آن را بررسی کنید و از پایگاه داده نسخه پشتیبان بگیرید. بعضی Migrationها ممکن است باعث تغییر یا حذف داده‌ها شوند.
مرحله یازدهم: تنظیم Nginx برای Laravel
اکنون باید مشخص کنیم Nginx درخواست‌های دامنه را به کدام پوشه و سرویس ارسال کند.
یک فایل تنظیمات برای دامنه ایجاد کنید:
sudo nano /etc/nginx/sites-available/example.com
محتوای نمونه:
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
root /var/www/example-app/public;
index index.php index.html;
charset utf-8;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
try_files $uri =404;
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
در این تنظیمات باید نام دامنه، مسیر پروژه و نسخه PHP-FPM را متناسب با سرور خود تغییر دهید.
ریشه وب‌سرور باید روی پوشه public باشد، نه ریشه اصلی پروژه. این کار از دسترسی مستقیم وب به فایل‌هایی مانند .env جلوگیری می‌کند.
اکنون تنظیمات سایت را فعال کنید:
sudo ln -s /etc/nginx/sites-available/example.com \
/etc/nginx/sites-enabled/example.com
پیش از بارگذاری مجدد Nginx، صحت تنظیمات را بررسی کنید:
sudo nginx -t
اگر پیام موفقیت دریافت کردید، Nginx را بارگذاری مجدد کنید:
sudo systemctl reload nginx
اگر فایل تنظیمات پیش‌فرض Nginx با دامنه یا پروژه شما تداخل دارد، آن را با دقت بررسی کنید؛ حذف یا غیرفعال‌کردن آن باید متناسب با وضعیت سایر سایت‌های سرور انجام شود.
مرحله دوازدهم: تنظیم DNS و فعال‌سازی HTTPS
برای دسترسی کاربران از طریق دامنه، رکورد DNS دامنه باید به IP سرور اشاره کند. اگر از www نیز استفاده می‌کنید، آن را مطابق سیاست دامنه تنظیم کنید.
پس از اینکه دامنه به سرور اشاره کرد و دسترسی HTTP برقرار شد، می‌توانید برای فعال‌سازی HTTPS از ابزارهایی مانند Certbot و گواهی معتبر TLS استفاده کنید.
در Ubuntu، روش نصب Certbot به نسخه سیستم‌عامل و شیوه نصب Nginx بستگی دارد؛ بنابراین دستورالعمل رسمی و سازگار با سرور خود را دنبال کنید.
پس از نصب گواهی، مطمئن شوید:
- سایت از طریق HTTPS باز می‌شود.
APP_URLدر فایل.envبا آدرس HTTPS هماهنگ است.- تنظیمات مربوط به Proxy یا Load Balancer، در صورت وجود، صحیح هستند.
- تمدید گواهی TLS به‌درستی انجام می‌شود.
مرحله سیزدهم: پاک‌کردن کش و بهینه‌سازی Laravel
پس از استقرار کد و تنظیم فایل محیطی، می‌توانید کش‌های موردنیاز را پاک کنید:
php artisan optimize:clear
سپس در صورت آماده‌بودن تنظیمات Production، کش تنظیمات و مسیرها را بسازید:
php artisan config:cache
php artisan route:cache
php artisan view:cache
این دستورات می‌توانند زمان آماده‌سازی برخی بخش‌های برنامه را کاهش دهند؛ اما باید ابتدا مطمئن شوید برنامه با محدودیت‌های کش سازگار است. برای مثال، فایل‌های پیکربندی نباید در زمان اجرا به‌صورت نامناسب از متغیرهای محیطی خارج از مرحله پیکربندی استفاده کنند.
اگر پس از تغییر .env با رفتار غیرمنتظره‌ای مواجه شدید، وضعیت کش تنظیمات را بررسی کنید و فرایند پاک‌سازی و بازسازی کش را با دقت انجام دهید.
مرحله چهاردهم: بررسی وضعیت پروژه پس از Deploy
پس از تکمیل مراحل بالا، سایت را در مرورگر باز کنید و بخش‌های مهم برنامه را آزمایش کنید.
برای بررسی وضعیت سرویس‌ها:
sudo systemctl status nginx
sudo systemctl status php8.3-fpm
برای مشاهده خطاهای Laravel، فایل‌های گزارش داخل مسیر storage/logs را بررسی کنید. گزارش‌های Nginx نیز معمولاً در مسیر زیر قرار دارند:
/var/log/nginx/
مواردی که باید بررسی شوند عبارت‌اند از:
- صفحه اصلی و مسیرهای مهم سایت
- اتصال به پایگاه داده
- ورود و ثبت‌نام کاربران
- بارگذاری و نمایش فایل‌ها
- ارسال ایمیل و اعلان‌ها
- اجرای Queueها و وظایف زمان‌بندی‌شده، در صورت استفاده
- عملکرد صفحات پس از فعال‌سازی کش
- دسترسی صحیح به HTTPS
اگر برنامه از Queue Worker یا Task Scheduling استفاده می‌کند، باید آن‌ها را نیز جداگانه راه‌اندازی کنید. اجرای وب‌سایت به‌تنهایی به معنی فعال‌بودن همه وظایف پس‌زمینه Laravel نیست.
نکات امنیتی مهم هنگام Deploy لاراول
استقرار موفق فقط به بالا آمدن سایت محدود نمی‌شود. برای آماده‌سازی یک برنامه امن، موارد زیر را نیز رعایت کنید:
- مقدار
APP_DEBUGرا در Production رویfalseقرار دهید. - فایل
.envو اطلاعات محرمانه را در مخزن عمومی قرار ندهید. - ریشه وب‌سرور را روی پوشه
publicتنظیم کنید. - دسترسی فایل‌ها و پوشه‌ها را به حداقل لازم محدود کنید.
- سیستم‌عامل، PHP و بسته‌های نرم‌افزاری را به‌صورت برنامه‌ریزی‌شده به‌روزرسانی کنید.
- برای پایگاه داده و فایل‌های مهم، نسخه پشتیبان تهیه و بازیابی آن را آزمایش کنید.
- از اجرای برنامه با کاربر
rootخودداری کنید. - برای دامنه گواهی TLS معتبر و تنظیمات HTTPS داشته باشید.
- قبل از اجرای Migrationهای حساس، اثر آن‌ها روی داده‌های موجود را بررسی کنید.
- گزارش‌های برنامه و سرویس‌ها را به‌صورت دوره‌ای بررسی کنید.
خطاهای رایج هنگام Deploy لاراول روی Ubuntu
خطای 502 Bad Gateway
این خطا ممکن است به دلیل متوقف‌بودن PHP-FPM، اشتباه‌بودن مسیر Socket یا ناهماهنگی تنظیمات Nginx ایجاد شود.
وضعیت PHP-FPM را بررسی کنید:
sudo systemctl status php8.3-fpm
همچنین مطمئن شوید مقدار fastcgi_pass با مسیر Socket واقعی نسخه PHP نصب‌شده مطابقت دارد.
خطای 500 Internal Server Error
خطای 500 می‌تواند دلایل مختلفی داشته باشد؛ از خطاهای کد برنامه تا تنظیمات ناقص محیطی یا دسترسی فایل‌ها.
ابتدا فایل‌های گزارش Laravel و Nginx را بررسی کنید. مطمئن شوید .env به‌درستی تنظیم شده و پوشه‌های storage و bootstrap/cache قابل‌نوشتن هستند.
خطای اتصال به پایگاه داده
مقادیر اتصال در فایل .env، وضعیت سرویس MySQL و مجوزهای کاربر پایگاه داده را بررسی کنید. اگر Laravel از کش تنظیمات استفاده می‌کند، ممکن است پس از تغییر فایل .env لازم باشد کش تنظیمات را پاک کنید.
اجرا نشدن فایل‌های CSS و JavaScript
اگر پروژه از Vite استفاده می‌کند، بررسی کنید فایل‌های Build تولید شده‌اند و در مسیر صحیح قرار دارند. همچنین تنظیمات APP_URL، مسیر فایل‌های عمومی و خروجی Build را بررسی کنید.
جمع‌بندی
برای Deploy لاراول روی Ubuntu باید محیط اجرای PHP را آماده کنید، وابستگی‌های پروژه را نصب کنید، تنظیمات محیطی و پایگاه داده را انجام دهید و وب‌سرور را روی پوشه public پیکربندی کنید. پس از آن، اجرای Migrationها، تنظیم دسترسی فایل‌ها، فعال‌سازی HTTPS و بررسی گزارش‌ها به آماده‌شدن برنامه برای استفاده کاربران کمک می‌کند.
به یاد داشته باشید که مراحل این مقاله یک مسیر پایه برای استقرار پروژه Laravel با Nginx و PHP-FPM هستند. پروژه‌های بزرگ‌تر ممکن است به فرایند CI/CD، Queue Worker، Redis، مدیریت امن Secretها، مانیتورینگ و معماری استقرار پیشرفته‌تری نیاز داشته باشند.
سوالات متداول
آیا برای Deploy لاراول حتماً باید از Ubuntu استفاده کنیم؟
خیر. Laravel روی سیستم‌عامل‌ها و محیط‌های مختلف قابل اجراست. Ubuntu یکی از گزینه‌های رایج برای سرورهای لینوکسی است؛ اما می‌توانید از توزیع‌های دیگر لینوکس یا محیط‌های کانتینری نیز استفاده کنید.
برای اجرای Laravel روی Ubuntu به Apache نیاز داریم یا Nginx؟
هر دو وب‌سرور می‌توانند برای اجرای Laravel استفاده شوند. در این مقاله از Nginx به همراه PHP-FPM استفاده کردیم. انتخاب نهایی به معماری، نیازمندی‌ها و تجربه تیم فنی بستگی دارد.
آیا بعد از Deploy باید Queue Worker را اجرا کنیم؟
اگر پروژه از Queue برای پردازش ایمیل‌ها، اعلان‌ها یا کارهای پس‌زمینه استفاده می‌کند، باید Worker مناسب را نیز راه‌اندازی کنید. در محیط Production معمولاً از ابزار مدیریت فرایند برای زنده نگه‌داشتن Worker استفاده می‌شود.
آیا اجرای php artisan migrate --force روی سرور امن است؟
این دستور برای اجرای Migration در محیط Production کاربرد دارد، اما امن‌بودن آن به محتوای Migration و آمادگی پایگاه داده بستگی دارد. پیش از اجرا، تغییرات را بررسی و از داده‌ها نسخه پشتیبان تهیه کنید.
آیا می‌توان Deploy لاراول را خودکار کرد؟
بله. با ابزارهای CI/CD می‌توان مراحلی مانند دریافت کد، نصب وابستگی‌ها، ساخت فایل‌های فرانت‌اند، اجرای تست‌ها و انتشار نسخه جدید را خودکار کرد. فرایند خودکار باید مدیریت Secretها، بازگشت به نسخه قبلی و اجرای کنترل‌شده Migrationها را نیز در نظر بگیرد.
