دسته بندی:

نصب لاراول در CentOS، AlmaLinux و Rocky Linux — راهنمای کامل

نصب لاراول در CentOS، AlmaLinux و Rocky Linux — راهنمای کامل

حدود ۱۰ دقیقه مطالعه

سروری با CentOS دارید و می‌خواهید یک پروژهٔ لاراول را روی آن بالا بیاورید، اما بیشتر آموزش‌هایی که پیدا می‌شود هنوز از git clone و service httpd restart می‌گویند و نتیجه‌اش صفحهٔ سفید، خطای ۵۰۰ یا Forbidden است. این راهنما مسیر درست و امروزی نصب لاراول روی CentOS و جانشین‌های آن (AlmaLinux و Rocky Linux) را از آماده‌سازی سرور تا اجرای موفق در مرورگر پوشش می‌دهد.

لاراول (Laravel) یکی از فریم‌ورک‌ها برای توسعه و ساخت وب سایت به زبان PHP است. لاراول بسیار انعطاف‌پذیر است و تغییر عملکرد بسیاری از بخش‌های آن بدون نیاز به تغییر کدهای اصلی امکان‌پذیر است. همچنین لاراول برای مدیریت نیازمندی‌ها (dependency) از Composer استفاده می‌کند؛ به همین دلیل Composer اولین ابزاری است که باید روی سرور نصب شود.

لوگوی فریم‌ورک لاراول

پیش‌نیازها

سیستم‌عامل: CentOS 7 در ۳۰ ژوئن ۲۰۲۴ و CentOS 8 در پایان سال ۲۰۲۱ به پایان پشتیبانی رسیدند و دیگر به‌روزرسانی امنیتی دریافت نمی‌کنند. اگر سرور تازه‌ای راه‌اندازی می‌کنید، AlmaLinux 9 یا Rocky Linux 9 را انتخاب کنید؛ هر دو جانشین مستقیم و باینری‌سازگار CentOS هستند و دستورهای این مقاله برای همین خانواده نوشته شده است.

هشدار برای CentOS 7: دستورهای این مقاله را عیناً روی CentOS 7 اجرا نکنید. CentOS 7 نه دستور dnf را به‌صورت پیش‌فرض دارد و نه سازوکار ماژول‌ها (dnf module) را؛ بستهٔ remi-release-9 مخصوص نسخهٔ ۹ است و نصب آن روی CentOS 7 پیکربندی مخازن را خراب می‌کند؛ بستهٔ ابزار SELinux هم آنجا policycoreutils-python نام دارد نه policycoreutils-python-utils. روی CentOS 7 باید از yum، از remi-release-7.rpm و از فعال‌کردن مخزن نسخهٔ PHP موردنظر با yum-config-manager استفاده کنید، و توجه داشته باشید که نسخه‌های جدید PHP لزوماً برای EL7 بسته‌بندی نشده‌اند. راه درست، مهاجرت به AlmaLinux یا Rocky است.

مدیر بسته: در CentOS 7 دستور yum استفاده می‌شد. در AlmaLinux/Rocky و CentOS 8 به بعد جانشین آن dnf است؛ yum هنوز به‌عنوان یک لینک به dnf کار می‌کند اما در نوشتن اسکریپت‌های جدید از dnf استفاده کنید.

نسخهٔ PHP: در متن‌های قدیمی نوشته شده «PHP نسخهٔ ۵ و ۶ یا بالاتر». PHP 6 هرگز منتشر نشد و PHP 5 سال‌هاست پشتیبانی نمی‌شود. لاراول ۱۰ حداقل به PHP 8.1 و لاراول ۱۱ و بالاتر به PHP 8.2 یا جدیدتر نیاز دارند. پیش از شروع، نسخهٔ موردنیاز نسخه‌ای از لاراول که می‌خواهید نصب کنید را در مستندات رسمی بررسی کنید.

افزونه‌های PHP: علاوه بر OpenSSL، PDO، Mbstring و Tokenizer که در راهنماهای قدیمی ذکر می‌شد، لاراول به Ctype، cURL، DOM، Fileinfo، Filter، Hash، PCRE، Session و XML هم نیاز دارد.

دسترسی: دسترسی root یا sudo، به‌همراه یک وب‌سرور (در این مقاله Apache) و در صورت نیاز پروژه، یک دیتابیس مانند MariaDB یا MySQL.

گام ۱: نصب مخزن‌ها و PHP

ابتدا مخزن EPEL را نصب کنید:

dnf install epel-release

EPEL به‌تنهایی نسخهٔ روز PHP را نمی‌آورد. ابتدا ببینید مخازن رسمی چه نسخه‌هایی در اختیار می‌گذارند:

dnf module list php

اگر نسخهٔ موردنیاز شما در فهرست بود، همان را فعال کنید. در غیر این صورت از مخزن Remi استفاده کنید (عدد ۹ را با نسخهٔ اصلی سیستم‌عامل خود جایگزین کنید و نسخهٔ PHP را متناسب با نسخهٔ لاراول انتخاب کنید):

dnf install https://rpms.remirepo.net/enterprise/remi-release-9.rpm
dnf module reset php
dnf module enable php:remi-8.3
dnf install php php-cli php-fpm php-common php-mbstring php-xml php-curl php-zip php-bcmath php-gd php-intl php-opcache php-mysqlnd

سپس نصب را تأیید کنید:

php -v
php -m

خروجی دستور دوم باید شامل openssl، PDO، mbstring، tokenizer، ctype، curl، dom، fileinfo و xml باشد (نام‌ها در خروجی php -m به همین شکل و با همین حروف بزرگ و کوچک چاپ می‌شوند).

گام ۲: نصب Composer

روش کوتاه، نصب مستقیم در مسیر اجرایی سیستم است:

curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
composer -V

در راهنماهای قدیمی سه دستور جداگانه (curl … | php، سپس mv composer.phar /usr/local/bin/composer و chmod +x /usr/local/bin/composer) نوشته می‌شد؛ نتیجه یکی است اما دستور بالا همان کار را در یک مرحله انجام می‌دهد.

روش امن‌تر و توصیه‌شده این است که پیش از اجرا، درستی فایل نصب‌کننده را با checksum رسمی بسنجید. Composer برای این کار از SHA-384 استفاده می‌کند و مقدار hash با هر انتشار تغییر می‌کند، بنابراین آن را از صفحهٔ دانلود رسمی Composer بردارید و با خروجی زیر مقایسه کنید:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
sha384sum composer-setup.php

در صورت مطابقت، php composer-setup.php را اجرا و سپس فایل موقت را حذف کنید. اگر مطابقت نداشت، فایل را دور بریزید و اجرایش نکنید.

گام ۳: ساخت پروژهٔ لاراول

روش قدیمی، یعنی git clone کردن مخزن laravel/laravel، دیگر توصیه نمی‌شود؛ شاخهٔ اصلی آن مخزن نسخهٔ در حال توسعه است، فایل .env ندارد و تاریخچهٔ git پروژهٔ شما را آلوده می‌کند. روش درست، ساخت پروژه با Composer است.

Composer را با کاربر root اجرا نکنید؛ خودِ Composer هم دربارهٔ آن هشدار می‌دهد، چون اسکریپت‌های بسته‌ها با دسترسی کامل اجرا می‌شوند. پس ابتدا یک کاربر معمولی بسازید، پوشهٔ پروژه را به نام او ایجاد کنید و سپس دستور را با همان کاربر اجرا کنید:

useradd -m deploy
install -d -o deploy -g deploy /var/www/myapp
su - deploy -c 'cd /var/www/myapp && composer create-project laravel/laravel .'

این دستور آخرین نسخهٔ پایدار سازگار با PHP نصب‌شدهٔ شما را می‌آورد، وابستگی‌ها را نصب می‌کند، فایل .env را از روی .env.example می‌سازد و کلید اپلیکیشن را هم تولید می‌کند.

گام ۴: فایل .env و کلید رمزنگاری

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

cp .env.example .env
php artisan key:generate

خروجی چیزی شبیه به این است:

Application key set successfully.

یک اصلاح مهم: برخلاف آنچه در آموزش‌های قدیمی آمده، لازم نیست (و نباید) کلید را دستی داخل config/app.php بنویسید. دستور key:generate خودش مقدار APP_KEY را در فایل .env ذخیره می‌کند و config/app.php آن را با env('APP_KEY') می‌خواند. نوشتن کلید داخل config/app.php باعث می‌شود کلید رمزنگاری وارد مخزن git شود که یک نشت امنیتی جدی است. کلیدهای امروزی هم با پیشوند base64: ذخیره می‌شوند. مقدار cipher در همان فایل به‌صورت پیش‌فرض AES-256-CBC است و نیازی به تغییر دستی آن ندارید.

چون .env رمز دیتابیس و کلید اپلیکیشن را نگه می‌دارد، آن را برای همه خواندنی نگذارید:

chmod 640 /var/www/myapp/.env

در همین فایل، اطلاعات دیتابیس (DB_DATABASE، DB_USERNAME، DB_PASSWORD) و آدرس سایت (APP_URL) را هم تنظیم کنید و در صورت داشتن جدول، مهاجرت‌ها را با همان کاربر deploy اجرا کنید:

php artisan migrate

گام ۵: مالکیت و سطح دسترسی فایل‌ها

در راهنماهای قدیمی chown -R USER.USER و chmod -R 755 روی کل پروژه پیشنهاد می‌شد. جداکنندهٔ نقطه در chown نگارش قدیمی است و امروز از دونقطه استفاده می‌شود؛ مهم‌تر اینکه لاراول فقط به دو مسیر نیاز به نوشتن دارد، نه به کل پروژه:

chown -R deploy:apache /var/www/myapp
find /var/www/myapp -type d -exec chmod 755 {} ;
find /var/www/myapp -type f -exec chmod 644 {} ;
chmod -R 775 /var/www/myapp/storage /var/www/myapp/bootstrap/cache

دقت کنید که دستور دوم بیتِ اجرا را از همهٔ فایل‌ها برمی‌دارد و ابزارهای داخل vendor/bin از کار می‌افتند. پس بلافاصله آن‌ها را برگردانید:

chmod +x /var/www/myapp/artisan
find /var/www/myapp/vendor/bin -type f -exec chmod +x {} ;

با این ساختار، کد متعلق به کاربر استقرار است و وب‌سرور فقط در storage و bootstrap/cache اجازهٔ نوشتن دارد. هرگز chmod -R 777 اجرا نکنید.

گام ۶: پیکربندی Apache

رایج‌ترین اشتباه در نصب لاراول این است که DocumentRoot به ریشهٔ پروژه اشاره کند. ریشهٔ سایت باید پوشهٔ public باشد، وگرنه فایل .env و کل کد از طریق مرورگر قابل دسترسی می‌شود. فایلی مانند /etc/httpd/conf.d/myapp.conf بسازید:

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/myapp/public

    <Directory /var/www/myapp/public>
        AllowOverride All
        Options -Indexes +FollowSymLinks
        Require all granted
    </Directory>

    ErrorLog /var/log/httpd/myapp-error.log
    CustomLog /var/log/httpd/myapp-access.log combined
</VirtualHost>

دستور Require all granted نگارش Apache 2.4 است. اگر با سروری بسیار قدیمی روی Apache 2.2 کار می‌کنید، معادل آن Order allow,deny به‌همراه Allow from all بود؛ این دستورها در Apache 2.4 منسوخ شده‌اند و بدون ماژول mod_access_compat کار نمی‌کنند. روی سرورهای امروزی از فرم Require استفاده کنید.

مقدار AllowOverride All لازم است تا فایل .htaccess لاراول (که مسیرها را به index.php هدایت می‌کند) خوانده شود. ماژول mod_rewrite هم باید فعال باشد؛ در بسته‌های رسمی Apache روی این توزیع‌ها به‌صورت پیش‌فرض بارگذاری می‌شود.

پیش از اعمال، درستی پیکربندی را بررسی کنید و تا وقتی خروجی Syntax OK نگرفتید سرویس را ری‌استارت نکنید:

httpd -t

گام ۷: SELinux و فایروال

روی CentOS و مشتقات آن SELinux به‌صورت پیش‌فرض در حالت enforcing است و همین باعث می‌شود با وجود درست بودن مجوزها، لاراول نتواند در storage بنویسد. برچسب مناسب را ست کنید:

dnf install policycoreutils-python-utils
semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/myapp/storage(/.*)?"
semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/myapp/bootstrap/cache(/.*)?"
restorecon -Rv /var/www/myapp

اگر پروژه به دیتابیسی روی سرور دیگر وصل می‌شود، این هم لازم است (برای دیتابیس محلی روی همان سرور معمولاً نیازی نیست):

setsebool -P httpd_can_network_connect_db 1

راه‌حل «SELinux را غیرفعال کن» را نپذیرید؛ برچسب‌گذاری درست چند دقیقه بیشتر طول نمی‌کشد. در نهایت پورت‌ها را در فایروال باز کنید. پیش از --reload مطمئن شوید سرویس ssh در همان zone فعال است، وگرنه ارتباط خودتان با سرور قطع می‌شود:

firewall-cmd --list-all
firewall-cmd --permanent --add-service=http
firewall-cmd --permanent --add-service=https
firewall-cmd --reload

گام ۸: راه‌اندازی مجدد سرویس‌ها و بررسی نتیجه

دستور service httpd restart که در آموزش‌های قدیمی آمده مربوط به دوران SysVinit است. در CentOS 7 به بعد و در AlmaLinux و Rocky Linux از systemd استفاده می‌شود:

systemctl enable --now php-fpm httpd
systemctl restart php-fpm httpd
systemctl status httpd --no-pager

روی Ubuntu و Debian نام سرویس Apache به‌جای httpd مقدار apache2 است.

حالا نصب را راستی‌آزمایی کنید. دستور زیر نسخهٔ لاراول، نسخهٔ PHP، وضعیت کش‌ها و درایورهای فعال را نشان می‌دهد:

php artisan about
curl -I -H "Host: example.com" http://127.0.0.1

هدر Host را از این جهت می‌فرستیم که درخواست به همان VirtualHost برسد، نه به سایت پیش‌فرض سرور. پاسخ باید 200 OK باشد و صفحهٔ خوش‌آمدگویی لاراول در مرورگر بالا بیاید. اگر چیزی درست نبود، لاگ‌ها اولین جای مراجعه هستند:

tail -n 50 /var/www/myapp/storage/logs/laravel.log
tail -n 50 /var/log/httpd/myapp-error.log

خطاهای رایج و راه‌حل

  • خطای ۴۰۳ Forbidden یا دیده‌شدن فهرست فایل‌ها: DocumentRoot به ریشهٔ پروژه اشاره می‌کند نه به public.
  • صفحهٔ سفید یا خطای ۵۰۰: معمولاً مجوز نوشتن روی storage یا برچسب SELinux. پیام دقیق در laravel.log یا لاگ خطای Apache است.
  • پیام The stream or file storage/logs/laravel.log could not be opened: گام‌های ۵ و ۷ را دوباره اجرا کنید.
  • پیام No application encryption key has been specified: فایل .env وجود ندارد یا APP_KEY خالی است؛ گام ۴ را تکرار کنید.
  • همهٔ مسیرها به‌جز صفحهٔ اصلی خطای ۴۰۴ می‌دهند: AllowOverride All تنظیم نشده یا mod_rewrite فعال نیست.
  • توقف Composer با خطای حافظه: دستور را به شکل COMPOSER_MEMORY_LIMIT=-1 composer install اجرا کنید.

آماده‌سازی برای محیط production

پیش از انتشار، در فایل .env مقدار APP_ENV=production و APP_DEBUG=false را تنظیم کنید. باز گذاشتن APP_DEBUG روی سرور واقعی، متغیرهای محیطی و مسیرهای داخلی را در صفحهٔ خطا به بازدیدکننده نشان می‌دهد. سپس:

composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache

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

توجه کنید که پس از config:cache، فراخوانی env() در هر جایی خارج از پوشهٔ config مقدار null برمی‌گرداند؛ بنابراین همهٔ متغیرها را از طریق فایل‌های config بخوانید. پس از هر تغییر در .env هم باید کش را با php artisan config:clear پاک و دوباره بسازید.

چه زمانی این روش را به کار نبرید

این مسیر برای سرور اختصاصی یا VPS با دسترسی root نوشته شده است. روی هاست اشتراکی معمولاً دسترسی SSH محدود است، اجرای Composer ممکن نیست و امکان تغییر DocumentRoot وجود ندارد؛ در آن حالت باید پروژه را روی سیستم خودتان build کنید و فقط خروجی را آپلود کنید، به این صورت که محتوای پوشهٔ public در public_html و بقیهٔ پروژه در پوشه‌ای خارج از دسترس وب قرار گیرد. همچنین اگر سرور شما با کنترل‌پنل (cPanel یا DirectAdmin) مدیریت می‌شود، فایل‌های پیکربندی Apache را دستی ویرایش نکنید؛ تغییرات با اولین بازسازی پیکربندی از بین می‌رود و باید از قابلیت‌های خود کنترل‌پنل استفاده کنید.

آموزش‌های مرتبط

خدمات مرتبط آنلاین سرور

ارسال نظر