آموزش اجرای Laravel روی Apache؛ نصب و تنظیم وب‌سرور

لاراول یکی از فریم‌ورک‌های محبوب PHP برای توسعه وب‌سایت‌ها، فروشگاه‌های اینترنتی، پنل‌های مدیریتی و API است. برای اجرای یک پروژه Laravel روی سرور، علاوه بر نصب PHP و وابستگی‌های پروژه، باید وب‌سرور نیز به‌درستی پیکربندی شود.

یکی از وب‌سرورهای پراستفاده برای اجرای پروژه‌های PHP، Apache است. این وب‌سرور در بسیاری از سرورهای لینوکسی و سرویس‌های میزبانی اشتراکی استفاده می‌شود و با تنظیمات صحیح می‌توان پروژه‌های Laravel را روی آن اجرا کرد.

در این مقاله یاد می‌گیریم چگونه یک پروژه Laravel را روی Apache اجرا کنیم، مسیر ریشه سایت را تنظیم کنیم، ماژول‌های موردنیاز را فعال کنیم و خطاهای رایج هنگام استقرار پروژه را برطرف کنیم.

Apache چیست و چه نقشی در اجرای Laravel دارد؟

Apache یک وب‌سرور است که درخواست‌های HTTP و HTTPS کاربران را دریافت می‌کند و بر اساس تنظیمات خود، پاسخ مناسب را ارائه می‌دهد.

در یک پروژه Laravel، Apache درخواست‌های کاربران را به نقطه ورودی برنامه، یعنی فایل index.php در پوشه public، هدایت می‌کند. سپس PHP کد برنامه را اجرا می‌کند و Laravel پاسخ نهایی را تولید می‌کند.

برای اجرای صحیح Laravel روی Apache، معمولاً به این موارد نیاز داریم:

• وب‌سرور Apache
• نسخه سازگار PHP و افزونه‌های موردنیاز پروژه
• Composer برای نصب وابستگی‌های PHP
• پایگاه داده، در صورت نیاز پروژه
• فعال بودن ماژول mod_rewrite
• تنظیم صحیح مسیر DocumentRoot

نکته مهم این است که ریشه سایت باید به پوشه public پروژه Laravel اشاره کند، نه پوشه اصلی پروژه. پوشه اصلی شامل فایل‌هایی مانند .env است که نباید مستقیماً از طریق وب قابل دسترسی باشند.

۱. نصب Apache و PHP روی Ubuntu

در این آموزش از Ubuntu به‌عنوان سیستم‌عامل سرور استفاده می‌کنیم. اگر Apache و PHP از قبل نصب شده‌اند، می‌توانید این مرحله را رد کنید.

ابتدا فهرست بسته‌ها را به‌روزرسانی کنید:

sudo apt update

سپس Apache و PHP را نصب کنید. دستور زیر یک نمونه برای PHP 8.3 است؛ نسخه PHP باید با نیازمندی‌های نسخه Laravel و وابستگی‌های پروژه شما سازگار باشد.

sudo apt install apache2 php8.3 libapache2-mod-php8.3 \

php8.3-cli php8.3-mbstring php8.3-xml \

php8.3-curl php8.3-zip php8.3-bcmath \

php8.3-mysql unzip

اگر از PostgreSQL استفاده می‌کنید، ممکن است به افزونه php8.3-pgsql نیاز داشته باشید. افزونه‌های لازم را بر اساس پایگاه داده و وابستگی‌های پروژه نصب کنید.

پس از نصب، وضعیت Apache را بررسی کنید:

sudo systemctl status apache2

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

sudo systemctl enable apache2

حالا با وارد کردن IP سرور در مرورگر، باید صفحه پیش‌فرض Apache یا پاسخ وب‌سرور را مشاهده کنید؛ البته به شرط آنکه فایروال و تنظیمات شبکه اجازه دسترسی بدهند.

۲. انتقال پروژه Laravel به سرور

فرض می‌کنیم پروژه ما در مسیر زیر قرار دارد:

/var/www/example-app

ساختار اصلی پروژه باید به شکل زیر باشد:

example-app/

├── app/

├── bootstrap/

├── config/

├── database/

├── public/

│   ├── index.php

│   └── .htaccess

├── resources/

├── routes/

├── storage/

├── vendor/

├── .env

├── artisan

└── composer.json

این ساختار نمونه است و ممکن است بسته به نسخه Laravel یا ابزارهای پروژه تفاوت‌هایی داشته باشد.

پروژه را می‌توانید با Git، ابزار انتقال فایل یا فرایند استقرار خودتان به سرور منتقل کنید.

نکته امنیتی: پوشه اصلی پروژه را به‌عنوان ریشه سایت معرفی نکنید. اگر Apache به‌جای public به مسیر اصلی پروژه اشاره کند، احتمال افشای فایل‌های حساس وجود دارد.

۳. نصب وابستگی‌های Laravel

وارد مسیر پروژه شوید:

cd /var/www/example-app

سپس وابستگی‌های PHP را برای محیط عملیاتی نصب کنید:

composer install --no-dev --optimize-autoloader

این دستور فرض می‌کند فایل composer.lock پروژه موجود است. استفاده از این فایل باعث می‌شود نسخه‌های وابستگی‌ها مطابق نسخه‌های ثبت‌شده در پروژه نصب شوند.

اگر پروژه از Vite برای مدیریت فایل‌های CSS و JavaScript استفاده می‌کند، در محیط مناسب وابستگی‌های فرانت‌اند را نصب و فایل‌های نهایی را تولید کنید:

npm ci

npm run build

در صورت استفاده از ابزار دیگری مانند Bun، باید دستورات متناسب با همان ابزار را اجرا کنید.

تنظیم فایل محیطی

در محیط عملیاتی، فایل .env باید شامل تنظیمات صحیح برنامه باشد. برای مثال:

APP_ENV=production

APP_DEBUG=false

APP_URL=https://example.com

اطلاعات پایگاه داده، تنظیمات ایمیل و سایر مقادیر موردنیاز را نیز تکمیل کنید.

اگر فایل .env وجود ندارد، آن را از فایل نمونه پروژه ایجاد کنید. کلید برنامه را فقط در صورتی تولید کنید که هنوز تنظیم نشده است:

php artisan key:generate

روی پروژه‌ای که قبلاً راه‌اندازی شده است، بدون دلیل کلید موجود را تغییر ندهید؛ این کار ممکن است باعث غیرقابل‌خواندن شدن داده‌های رمزگذاری‌شده قبلی شود.

۴. فعال‌سازی mod_rewrite در Apache

Laravel برای هدایت درخواست‌ها به فایل public/index.php از قواعد بازنویسی URL استفاده می‌کند. در نصب‌های معمول Apache، این کار با ماژول mod_rewrite و فایل .htaccess انجام می‌شود.

برای فعال‌سازی ماژول، اجرا کنید:

sudo a2enmod rewrite

اگر فایل پیکربندی Apache تغییر کرده است، قبل از بارگذاری مجدد، صحت تنظیمات را بررسی کنید:

sudo apache2ctl configtest

اگر نتیجه Syntax OK بود، سرویس را بارگذاری مجدد کنید:

sudo systemctl reload apache2

فعال‌سازی ماژول به‌تنهایی کافی نیست؛ باید تنظیمات Virtual Host نیز اجازه استفاده از قواعد .htaccess را بدهند.

۵. ساخت Virtual Host برای پروژه Laravel

Virtual Host به Apache اجازه می‌دهد دامنه مشخصی را به یک پروژه یا وب‌سایت مشخص متصل کند.

برای ساخت فایل تنظیمات دامنه، دستور زیر را اجرا کنید:

sudo nano /etc/apache2/sites-available/example.com.conf

سپس تنظیمات زیر را وارد کنید. در این مثال فرض شده دامنه example.com است و پروژه در مسیر /var/www/example-app قرار دارد.

<VirtualHost *:80>

    ServerName example.com

    ServerAlias www.example.com



    DocumentRoot /var/www/example-app/public



    <Directory /var/www/example-app/public>

        Options -Indexes +FollowSymLinks

        AllowOverride All

        Require all granted

    </Directory>



    ErrorLog ${APACHE_LOG_DIR}/example-app-error.log

    CustomLog ${APACHE_LOG_DIR}/example-app-access.log combined

</VirtualHost>

در این تنظیمات:

• ServerName دامنه اصلی سایت را مشخص می‌کند.
• ServerAlias نام‌های جایگزین مانند نسخه www را مشخص می‌کند.
• DocumentRoot مسیر فایل‌هایی است که Apache برای سایت ارائه می‌دهد.
• AllowOverride All اجازه می‌دهد قواعد موردنیاز در .htaccess اعمال شوند.
• Options -Indexes از نمایش فهرست فایل‌های پوشه‌ها جلوگیری می‌کند.
• ErrorLog و CustomLog مسیر فایل‌های ثبت خطا و درخواست‌ها را تعیین می‌کنند.

اگر سایت فقط با دامنه اصلی در دسترس است، می‌توانید ServerAlias را حذف کنید. همچنین باید مطمئن شوید رکوردهای DNS دامنه به IP همین سرور اشاره می‌کنند.

فعال‌سازی Virtual Host

پس از ذخیره فایل، سایت را فعال کنید:

sudo a2ensite example.com.conf

در صورت عدم نیاز به سایت پیش‌فرض Apache، می‌توانید آن را غیرفعال کنید:

sudo a2dissite 000-default.conf

این دستور را فقط زمانی اجرا کنید که مطمئن باشید سایت پیش‌فرض برای سرویس دیگری موردنیاز نیست.

در پایان، تنظیمات را بررسی و Apache را بارگذاری مجدد کنید:

sudo apache2ctl configtest

sudo systemctl reload apache2

۶. بررسی فایل .htaccess لاراول

در نصب استاندارد Laravel، فایل .htaccess داخل پوشه public قرار دارد. این فایل درخواست‌هایی را که به فایل یا پوشه واقعی اشاره نمی‌کنند، به index.php هدایت می‌کند.

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

<IfModule mod_rewrite.c>

    <IfModule mod_negotiation.c>

        Options -MultiViews -Indexes

    </IfModule>



    RewriteEngine On



    RewriteCond %{HTTP:Authorization} .

    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]



    RewriteCond %{REQUEST_FILENAME} !-d

    RewriteCond %{REQUEST_FILENAME} !-f

    RewriteRule ^ index.php [L]

</IfModule>

اگر فایل پیش‌فرض Laravel موجود است، معمولاً نیازی به جایگزین کردن آن ندارید. قبل از تغییر، نسخه فعلی را بررسی کنید و قواعد غیرضروری را حذف نکنید.

این نکته نیز مهم است که قواعد .htaccess فقط در صورتی اعمال می‌شوند که تنظیمات Virtual Host اجازه آن را بدهند؛ به همین دلیل در نمونه قبلی از AllowOverride All استفاده کردیم.

۷. تنظیم مجوزهای فایل‌ها و پوشه‌ها

Laravel برای ذخیره فایل‌های موقت، گزارش‌ها، کش و فایل‌های تولیدشده به دسترسی نوشتن در بعضی مسیرها نیاز دارد.

دو مسیر مهم عبارت‌اند از:

storage/

bootstrap/cache/

در نصب متداول Ubuntu، کاربر اجرای Apache و PHP ممکن است www-data باشد. بااین‌حال، قبل از تغییر مالکیت یا مجوزها، کاربر واقعی اجرای PHP را بررسی کنید.

برای نمونه، اگر پروژه با ساختار مالکیت مناسب در اختیار کاربر استقرار قرار دارد و فقط این دو مسیر باید برای وب‌سرور قابل‌نوشتن باشند، می‌توانید از مجوزهای گروهی استفاده کنید:

sudo chown -R deploy:www-data /var/www/example-app/storage

sudo chown -R deploy:www-data /var/www/example-app/bootstrap/cache



sudo chmod -R ug+rwX /var/www/example-app/storage

sudo chmod -R ug+rwX /var/www/example-app/bootstrap/cache

در این مثال، deploy نام فرضی کاربر استقرار است؛ آن را با کاربر واقعی سرور جایگزین کنید. این روش نیازمند آن است که کاربر PHP عضو گروه مناسب باشد و تنظیمات گروهی پروژه نیز درست انجام شده باشد.

از اجرای chmod -R 777 روی کل پروژه خودداری کنید. این کار دسترسی بیش از حد ایجاد می‌کند و مشکل مجوزها را به شیوه‌ای ناامن پنهان می‌کند.

۸. تنظیمات پایگاه داده و اجرای Migration

اگر پروژه از پایگاه داده استفاده می‌کند، اطلاعات اتصال را در فایل .env تنظیم کنید. برای مثال، تنظیمات MySQL می‌تواند به شکل زیر باشد:

DB_CONNECTION=mysql

DB_HOST=127.0.0.1

DB_PORT=3306

DB_DATABASE=example_db

DB_USERNAME=example_user

DB_PASSWORD=your_secure_password

نام پایگاه داده، کاربر و رمز عبور باید با مقادیر واقعی سرور مطابقت داشته باشند. برای امنیت بیشتر، از کاربری استفاده کنید که فقط دسترسی‌های موردنیاز همان پایگاه داده را دارد.

پیش از اجرای Migration در محیط عملیاتی، از پایگاه داده نسخه پشتیبان بگیرید و تغییرات Migration را بررسی کنید. سپس در صورت اطمینان، اجرا کنید:

php artisan migrate --force

گزینه --force برای تأیید اجرای Migration در محیط production استفاده می‌شود؛ این گزینه جایگزین بررسی و تهیه نسخه پشتیبان نیست.

۹. فعال‌سازی HTTPS

برای استفاده از HTTPS، باید گواهی SSL معتبر روی دامنه نصب شود. در Ubuntu می‌توانید از Certbot برای پیکربندی گواهی‌های Let's Encrypt استفاده کنید.

ابتدا ابزارهای موردنیاز را نصب کنید:

sudo apt install certbot python3-certbot-apache

سپس، پس از تنظیم DNS دامنه و اطمینان از دسترسی HTTP از بیرون سرور، گواهی را دریافت کنید:

sudo certbot --apache -d example.com -d www.example.com

اگر سایت از دامنه www استفاده نمی‌کند یا آن دامنه به سرور اشاره ندارد، نام آن را از دستور حذف کنید.

بعد از نصب SSL، مقدار APP_URL را در فایل .env روی آدرس HTTPS قرار دهید:

APP_URL=https://example.com

در صورت نیاز، کش تنظیمات Laravel را پاک و دوباره ایجاد کنید.

۱۰. بهینه‌سازی Laravel برای محیط عملیاتی

پس از تنظیم سرور و اطمینان از عملکرد صحیح برنامه، می‌توانید کش‌های متناسب با محیط production را ایجاد کنید.

ابتدا در صورت نیاز کش‌های قبلی را پاک کنید:

php artisan optimize:clear

سپس کش تنظیمات، مسیرها و Viewها را بسازید:

php artisan config:cache

php artisan route:cache

php artisan view:cache

اگر پروژه از Routeهایی استفاده می‌کند که با محدودیت‌های route:cache سازگار نیستند، ابتدا مشکل را برطرف کنید؛ در غیر این صورت، ایجاد کش مسیرها ممکن است با خطا مواجه شود.

این دستورات را پس از تغییر تنظیمات یا مسیرهای برنامه، به‌عنوان بخشی از فرایند استقرار به‌درستی مدیریت کنید.

۱۱. خطاهای رایج اجرای Laravel روی Apache

در جدول زیر چند خطای متداول و روش بررسی آن‌ها را می‌بینید.

مشاهده گزارش خطاهای Apache

برای مشاهده خطاهای عمومی Apache می‌توانید از دستور زیر استفاده کنید:

sudo tail -f /var/log/apache2/error.log

اگر برای سایت فایل گزارش اختصاصی تعریف کرده‌اید، همان فایل را بررسی کنید:

sudo tail -f /var/log/apache2/example-app-error.log

برای مشاهده گزارش‌های Laravel نیز می‌توانید از این دستور استفاده کنید:

tail -f /var/www/example-app/storage/logs/laravel.log

مسیر و نام فایل گزارش Laravel ممکن است بسته به نسخه و تنظیمات برنامه متفاوت باشد. هنگام بررسی خطاها، مقدار APP_DEBUG را در محیط عملیاتی روی false نگه دارید و اطلاعات حساس را در اختیار کاربران سایت قرار ندهید.

۱۲. بررسی نهایی قبل از انتشار سایت

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

• [ ] دامنه به IP صحیح سرور اشاره می‌کند.
• [ ] ریشه سایت روی پوشه public تنظیم شده است.
• [ ] نسخه PHP و افزونه‌های موردنیاز پروژه نصب شده‌اند.
• [ ] ماژول mod_rewrite فعال است.
• [ ] فایل .htaccess و تنظیمات Virtual Host صحیح هستند.
• [ ] فایل .env در معرض دسترسی عمومی نیست.
• [ ] مجوزهای storage و bootstrap/cache صحیح هستند.
• [ ] اتصال پایگاه داده و Migrationها بررسی شده‌اند.
• [ ] فایل‌های CSS و JavaScript ساخته شده‌اند.
• [ ] HTTPS فعال است و گواهی معتبر دارد.
• [ ] APP_DEBUG=false تنظیم شده است.
• [ ] گزارش خطاها و فرایند پشتیبان‌گیری بررسی شده‌اند.

پرسش‌های متداول

آیا Laravel روی Apache اجرا می‌شود؟

بله. Laravel می‌تواند روی Apache اجرا شود، به شرط آنکه نسخه PHP، افزونه‌های موردنیاز، تنظیمات وب‌سرور و مسیر ریشه سایت به‌درستی پیکربندی شده باشند.

آیا برای اجرای Laravel روی Apache به فایل .htaccess نیاز داریم؟

در پیکربندی رایج Apache، فایل .htaccess داخل پوشه public برای هدایت درخواست‌ها به index.php استفاده می‌شود. اگر قواعد معادل را مستقیماً در تنظیمات اصلی Apache تعریف کنید، ممکن است به .htaccess نیاز نداشته باشید؛ اما تنظیمات بازنویسی باید به‌درستی پیاده‌سازی شوند.

تفاوت اجرای Laravel روی Apache و Nginx چیست؟

هر دو وب‌سرور می‌توانند Laravel را اجرا کنند، اما شیوه پیکربندی آن‌ها متفاوت است. Apache معمولاً می‌تواند از .htaccess استفاده کند، درحالی‌که Nginx قواعد مسیریابی را از فایل‌های تنظیمات خودش می‌خواند و از .htaccess پشتیبانی نمی‌کند.

آیا می‌توان Laravel را روی هاست اشتراکی اجرا کرد؟

بله، اگر هاست از نسخه سازگار PHP و نیازمندی‌های پروژه پشتیبانی کند و امکان تنظیم صحیح Document Root یا قراردادن فایل‌های عمومی در مسیر مناسب را فراهم کند. جزئیات اجرا به محدودیت‌های شرکت میزبانی بستگی دارد.

جمع‌بندی

برای اجرای Laravel روی Apache، مهم‌ترین کارها نصب وابستگی‌های مناسب، فعال‌سازی mod_rewrite، ساخت Virtual Host و تنظیم DocumentRoot روی پوشه public هستند. پس از آن باید مجوزهای فایل‌ها، اتصال پایگاه داده، HTTPS و تنظیمات production را بررسی کنید.

اگر این مراحل را به‌درستی انجام دهید، می‌توانید پروژه Laravel خود را روی سرور Ubuntu مجهز به Apache اجرا کنید و با بررسی گزارش‌ها، مشکلات احتمالی را سریع‌تر تشخیص دهید.

در سی‌ام‌اس نویس می‌توانید آموزش‌های مرتبط با Laravel، PHP و مدیریت سرور را دنبال کنید تا با مراحل توسعه و استقرار پروژه‌های واقعی بیشتر آشنا شوید.