Laravel

Chạy Laravel trên ZoPanel bằng trình cài một chạm hoặc Git deploy: thư mục gốc, .env và APP_KEY, migration, scheduler, queue, Redis và lưu trữ cố định.

Cập nhật 09/10/2026 · 8 phút đọc

Laravel chạy như một website PHP: nginx phục vụ thư mục public của dự án, còn PHP chạy trong pool PHP-FPM riêng của tài khoản. ZoPanel có hai cách dựng: trình cài một chạm tạo dự án Laravel mới trống, còn Git deploy build repository của bạn thành các bản release được đưa lên không gián đoạn. Dùng trình cài để thử Laravel hoặc bắt đầu dự án ngay trên máy chủ; dùng Git deploy cho ứng dụng bạn phát triển ở nơi khác.

Yêu cầu

• Phiên bản PHP mà bản Laravel của bạn hỗ trợ, đã cài ở Runtime. Laravel 13 cần PHP 8.3 trở lên, Laravel 12 cần PHP 8.2 trở lên (chính sách hỗ trợ).
• Composer, do quản trị viên cài ở Runtime → Composer.
• Gói hosting còn chỗ cho một database (MariaDB hoặc PostgreSQL, xem Cơ sở dữ liệu).
• Với Git deploy, gói phải bật Git deploy & ứng dụng; với trình cài, gói phải bật Cài ứng dụng & công cụ WordPress.

Chọn cách triển khai

Cài một chạm

1. Tạo website PHP hoặc Laravel (Website → Thêm website) với PHP 8.2 trở lên.
2. Trong tab Tổng quan, ở thẻ Ứng dụng, bấm Laravel.
3. Nhập Tên website (dùng làm APP_NAME) rồi bấm Cài đặt.

ZoPanel chạy composer create-project laravel/laravel bằng phiên bản PHP của website, tạo database MariaDB, sinh .env từ .env.example (APP_ENV=production, APP_DEBUG=false, APP_URL, DB_CONNECTION=mysql, DB_HOST=localhost cùng thông tin database mới), rồi chạy php artisan key:generate --force, php artisan migrate --force và php artisan storage:link. Thư mục gốc web thành public_html/public với quy tắc rewrite Laravel. Chi tiết và lỗi thường gặp: Ứng dụng PHP.

Sửa .env bằng Quản lý file hoặc qua SSH. File .env.example mặc định của Laravel lưu session, cache và job trong hàng đợi vào database; các bảng này được tạo ở lần migration đầu tiên.

Deploy từ Git

1. Ở Website → Thêm website, chọn Git deploy, nhập Địa chỉ repository và Nhánh. Với website có sẵn, dùng tab Deploy của website.
2. ZoPanel nhận diện Laravel khi repository có file artisan hoặc composer.json yêu cầu laravel/framework.
3. Khai báo cấu hình trong Biến môi trường (xem bên dưới) rồi bấm Lưu & deploy lại.

Kết quả nhận diện:

Khi package.json có script build, lệnh npm ci && npm run build (hoặc npm install) được thêm vào đầu lệnh build để biên dịch asset Vite. Khi đó máy chủ cần cài một phiên bản Node.js ở Runtime.

Muốn sửa lệnh, tắt Tự nhận diện trong thẻ Build & chạy, sửa trường cần đổi rồi bấm Lưu & deploy.

ZoPanel tự đặt gì cho Laravel

Mỗi lần Git deploy ứng dụng Laravel, ZoPanel điền các Biến môi trường sau nếu bạn chưa tự đặt:

Log deploy ghi "Sessions and cache use the account's Redis" hoặc "Sessions and cache use files (Redis not available: …)". Muốn giữ driver riêng, hãy tự đặt SESSION_DRIVER; khi đó ZoPanel không đụng tới thiết lập session, cache và Redis.

Quan trọng: giữ nguyên APP_KEY khi ứng dụng đã chạy thật. Đổi khoá sẽ đăng xuất mọi người dùng và không giải mã được dữ liệu đã mã hoá.

Biến môi trường và .env

Với Git deploy, .env là file lưu trữ cố định tại domains/<tên-miền>/shared/.env, được liên kết vào mọi bản release. Mỗi lần deploy, các Biến môi trường được gộp vào file này: dòng nào đặt một biến của panel thì được cập nhật tại chỗ, biến còn thiếu được thêm vào cuối, còn mọi dòng (và chú thích) bạn tự thêm đều được giữ nguyên. Vì vậy:

• khai báo thông tin database, email, API key trong Biến môi trường, hoặc dán cả file bằng Dán .env;
• bạn cũng có thể sửa shared/.env trong Quản lý file: các dòng của bạn vẫn còn sau lần deploy sau, nhưng biến nào cũng được đặt trong panel sẽ lấy giá trị của panel. Xoá một biến trong panel không xoá dòng của nó trong .env; hãy xoá cả ở đó;
• lệnh build chạy php artisan config:cache, nên biến vừa đổi chỉ có hiệu lực sau khi deploy lại. Lưu & deploy lại làm cả hai việc.

PHP-FPM không nhận trực tiếp các biến này: Laravel đọc chúng từ .env, vì vậy hãy giữ .env trong Đường dẫn lưu trữ cố định.

Ví dụ cấu hình database (MariaDB, user và database tạo ở Cơ sở dữ liệu):

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=alice_shop
DB_USERNAME=alice_shop
DB_PASSWORD=mat-khau-cua-ban

Vì cấu hình được cache, chỉ gọi env() bên trong các file config/*.php, đúng như tài liệu cấu hình của Laravel yêu cầu.

Migration

Git deploy không tự chạy migration. Hãy thêm vào cuối lệnh build (tắt Tự nhận diện trước):

php artisan storage:link --force 2>/dev/null; php artisan config:cache && php artisan route:cache && php artisan view:cache && php artisan migrate --force

Bước build chạy trước khi bản mới được đưa lên, trong lúc bản cũ vẫn phục vụ khách trên cùng database. Hãy viết migration sao cho bản đang chạy vẫn hoạt động được (thêm cột trước khi code dùng tới, xoá cột ở bản phát hành sau).

Storage và đường dẫn lưu trữ cố định

• storage được dùng chung giữa các bản release: file tải lên trong storage/app/public, log và cache của framework được giữ qua mọi lần deploy. Ở lần deploy đầu, thư mục storage trong repository được sao chép sang shared/storage.
• php artisan storage:link (trong lệnh build) tạo public/storage, nên file lưu trên disk public được nginx phục vụ trực tiếp (tài liệu filesystem).
• Thư mục khác cần giữ lại giữa các bản, ví dụ public/uploads, hãy thêm vào Đường dẫn lưu trữ cố định.

Một bản release được đưa lên như thế nào

1. Code được lấy về thư mục mới trong releases/, storage và .env được liên kết vào.
2. Lệnh cài đặt và lệnh build chạy dưới quyền tài khoản hosting, trong giới hạn CPU và RAM của tài khoản.
3. current được chuyển sang bản mới trong một bước, thư mục gốc web là current/public, và PHP-FPM được reload nhẹ nhàng.

Nếu cài đặt hoặc build lỗi, current giữ nguyên và bản cũ tiếp tục chạy. Các bản release giữ 5 bản build gần nhất; Rollback chuyển về một trong số đó (database không được rollback). Xem Git deploy.

Scheduler và queue

Website PHP không có tiến trình chạy liên tục, nên hãy chạy scheduler của Laravel bằng Cron Job (tài liệu scheduling). Tạo một job chạy mỗi phút (* * * * *):

cd /home/alice/domains/example.com/current && /usr/bin/php8.3 artisan schedule:run >> /dev/null 2>&1

Với bản cài một chạm, thay current bằng public_html; dùng đúng phiên bản PHP của website. Lệnh cron không được chứa ký tự %. Xem Cron Job.

Job trong hàng đợi:

• Git deploy đặt QUEUE_CONNECTION=sync: job chạy ngay trong request, không cần worker, phù hợp với job nhẹ.
• Muốn xử lý nền, đặt QUEUE_CONNECTION=database (hoặc redis) và xử lý hàng đợi bằng scheduler hoặc một cron job, ví dụ mỗi phút:

cd /home/alice/domains/example.com/current && /usr/bin/php8.3 artisan queue:work --stop-when-empty --max-time=55 >> /dev/null 2>&1

--stop-when-empty và --max-time giúp worker thoát trước lần chạy kế tiếp (tài liệu queue). Sau mỗi lần deploy, lần chạy cron tiếp theo dùng code mới.

Xử lý sự cố

Xem thêm

• Git deploy
• Ứng dụng PHP
• Website và PHP
• Cron Job
• Cơ sở dữ liệu
• Tài liệu deploy Laravel