Deploy Laravel, PHP lên cloud với MySQL, queue worker, scheduler
Để deploy app Laravel lên ZoCloud, bạn tạo project, thêm database MySQL (MariaDB), đặt các biến APP_KEY, DB_HOST… bằng biến tham chiếu, rồi deploy từ GitHub hoặc bằng zo deploy. ZoCloud tự nhận ra Laravel, chạy composer install, build tài nguyên Vite nếu có, và phục vụ thư mục public bằng Apache trên máy chủ tại Việt Nam. Queue worker và scheduler là hai service nữa chạy từ cùng repo, không cần Supervisor hay crontab.
ZoCloud build app PHP thế nào
| Dự án | Nhận diện khi | Thư mục phục vụ |
|---|---|---|
| Laravel | có laravel/framework trong composer.json hoặc file artisan |
public |
| Symfony | có symfony/framework-bundle |
public |
| PHP dùng Composer | có composer.json |
public nếu có public/index.php, không thì gốc repo |
| PHP thuần | có index.php |
gốc repo |
Với Laravel, ZoCloud:
- Chạy
composer install --no-dev --optimize-autoloader --no-interaction. Phiên bản PHP lấy từ ràng buộcphptrongcomposer.json. - Nếu
package.jsoncó scriptbuild, chạy thêmnpm ci && npm run buildđể biên dịch tài nguyên Vite, rồiphp artisan storage:link. - Phục vụ bằng Apache với
.htaccess(mod_rewrite) bật sẵn, nghe trên biếnPORT. - Mỗi lần container khởi động, chạy
php artisan config:cache && php artisan route:cache && php artisan view:cachevới biến môi trường thật.
Ảnh build có sẵn các extension hay dùng như pdo_mysql, pdo_pgsql, intl, bcmath, gd, zip, opcache. Kiểm tra trước trên máy:
zo detect
Bước 1: Tạo project và database MySQL
- Đăng ký, xác minh e-mail, hoàn tất thiết lập (nạp tiền vào ví hoặc kết nối GitHub).
- Project → Tạo project (ví dụ
shop), chọn Vị trí. - Trên canvas, Thêm → MySQL (MariaDB), đặt Tên là
mysql, bấm Tạo. - Cần queue nhanh hoặc cache: Thêm → Redis (Valkey), đặt tên
cache.
Bằng CLI:
zo db create mysql -engine mysql
zo db create cache -engine valkey
Database chạy trong mạng riêng, chỉ app cùng environment truy cập được, sao lưu mỗi đêm, mã hoá, bản chính lưu tại Việt Nam. Chi tiết ở hosting MySQL.
Bước 2: Biến môi trường thay cho file .env
zo CLI không bao giờ gửi file .env* lên (trừ .env.example), và bạn cũng không nên commit .env. Laravel đọc thẳng biến môi trường, nên chỉ cần đặt biến cho service.
Tạo APP_KEY trên máy:
php artisan key:generate --show
Mở service, tab Biến môi trường → Sửa dạng .env, dán:
APP_NAME=Shop
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:...
APP_URL=https://www.example.vn
LOG_CHANNEL=stderr
DB_CONNECTION=mysql
DB_HOST=${{mysql.DB_HOST}}
DB_PORT=${{mysql.DB_PORT}}
DB_DATABASE=${{mysql.DB_DATABASE}}
DB_USERNAME=${{mysql.DB_USERNAME}}
DB_PASSWORD=${{mysql.DB_PASSWORD}}
REDIS_URL=${{cache.REDIS_URL}}
QUEUE_CONNECTION=redis
CACHE_STORE=redis
SESSION_DRIVER=redis
${{mysql.DB_HOST}} là biến tham chiếu: database MySQL của ZoCloud có sẵn các biến kiểu Laravel (DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD) và giá trị tự cập nhật nếu database đổi máy chủ hay mật khẩu. Laravel bản cũ dùng CACHE_DRIVER thay cho CACHE_STORE.
Ba lưu ý:
LOG_CHANNEL=stderrđể log Laravel hiện ở tab Log, thay vì nằm trongstorage/logscủa container.- Session và cache để
redis(hoặcdatabase) để mọi bản chạy dùng chung; kiểufilesẽ lệch khi bạn chạy 2 bản. - ZoCloud đứng trước app như một proxy HTTPS. Để Laravel sinh URL
https://đúng, tin proxy trongbootstrap/app.php(Laravel 11 trở lên):
->withMiddleware(function (Middleware $middleware) {
$middleware->trustProxies(at: '*');
})
Biến có hiệu lực từ lần deploy sau. Xem thêm biến môi trường và file .env.
Bước 3: Deploy
Từ GitHub: Thêm → Từ repo GitHub, thẻ GitHub, chọn repo, đặt Tên service là web, để trống Lệnh chạy, bấm Tạo và deploy. Bật Tự deploy khi push ở tab Cấu hình.
Từ máy:
curl -fsSL https://app.zocloud.io/install.sh | sh
zo login
zo deploy -to myorg/shop/web
zo bỏ qua .git, node_modules và các mẫu trong .gitignore; thư mục vendor thường đã nằm trong .gitignore nên Composer cài lại trên máy build.
Bước 4: Chạy migration khi deploy
Đặt file zocloud.json ở gốc repo. Trường prestart thay lệnh khởi động mặc định, nên giữ lại các lệnh cache:
{
"deploy": {
"prestart": "php artisan migrate --force --isolated && php artisan config:cache && php artisan route:cache && php artisan view:cache",
"health_path": "/up"
}
}
/up là route kiểm tra sức khoẻ có sẵn từ Laravel 11; bản cũ hơn thì tự thêm một route trả 200. Cờ --isolated dùng khoá trong cache để chỉ một tiến trình chạy migration một lúc, hữu ích vì worker build từ cùng repo cũng chạy prestart.
Bước 5: Queue worker
- Thêm → Từ repo GitHub, chọn cùng repo, đặt Tên service là
queue. - Lệnh chạy:
php artisan queue:work --tries=3 --max-time=3600. - Tạo xong, tab Cấu hình → Loại service → Worker, rồi deploy lại.
- Dán cùng bộ biến như service
web. Biến dùng cho nhiều service (ví dụAPP_KEY) có thể đặt một lần ở Cài đặt project → Biến chung rồi tham chiếu bằng${{shared.APP_KEY}}.
Worker không có cổng, không có địa chỉ công khai. --max-time để worker tự thoát định kỳ và được khởi động lại sạch sẽ.
Bước 6: Scheduler (cron của Laravel)
Laravel muốn schedule:run chạy mỗi phút, còn Cron job của ZoCloud có khoảng cách tối thiểu giữa hai lần chạy. Cách gọn nhất là thêm một service Worker nữa (tên scheduler) với Lệnh chạy:
php artisan schedule:work
Lệnh này chạy liên tục và gọi các tác vụ trong routes/console.php (hoặc app/Console/Kernel.php) đúng giờ. Đặt múi giờ app là Asia/Ho_Chi_Minh trong config/app.php nếu lịch của bạn theo giờ Việt Nam.
Tác vụ thưa (báo cáo 7 giờ sáng, dọn dữ liệu hằng đêm) thì dùng service loại Cron job: Lịch chạy (cron) 0 7 * * * (giờ Việt Nam), Lệnh chạy php artisan report:daily. Tab Lần chạy hiện mã thoát và log; Chạy ngay để thử. Xem thêm cron job và worker nền.
Bước 7: Lưu file upload (storage)
Mỗi lần deploy là một container mới, nên file ghi vào storage/app sẽ mất. Có hai cách:
Cách 1 (nên dùng): bucket S3. Thêm → Object storage (S3), tên files. Cài league/flysystem-aws-s3-v3, rồi đặt biến:
FILESYSTEM_DISK=s3
AWS_ACCESS_KEY_ID=${{files.S3_ACCESS_KEY_ID}}
AWS_SECRET_ACCESS_KEY=${{files.S3_SECRET_ACCESS_KEY}}
AWS_DEFAULT_REGION=${{files.S3_REGION}}
AWS_BUCKET=${{files.S3_BUCKET}}
AWS_ENDPOINT=${{files.S3_ENDPOINT}}
AWS_USE_PATH_STYLE_ENDPOINT=true
Web, queue và scheduler đều thấy cùng file, và web chạy được nhiều bản. Xem object storage S3 tại Việt Nam.
Cách 2: volume. Tab Cấu hình → Volume → Thêm volume, Đường dẫn trong container /var/www/html/storage/app, nhập Dung lượng (MB), rồi deploy lại. Volume được sao lưu mỗi đêm cùng các bản dày mỗi vài phút, nhưng service có volume chỉ chạy 1 bản và worker không đọc được volume của service web.
Bước 8: Tên miền và kiểm tra
Tab Tên miền → nhập www.example.vn → Thêm, tạo bản ghi CNAME theo giá trị portal hiện; HTTPS được cấp tự động khi DNS đúng (tên miền riêng có từ gói Hobby). Sau đó bật tường lửa ở Cấu hình → Bảo mật, để Chỉ ghi nhận vài ngày rồi chuyển Chặn.
Lỗi thường gặp với Laravel
| Hiện tượng | Cách xử lý |
|---|---|
Lỗi 500, log báo No application encryption key |
Thiếu APP_KEY: đặt biến rồi deploy lại |
| Đổi biến mà app vẫn dùng giá trị cũ | Biến có hiệu lực từ lần deploy sau; bấm Deploy |
Link, CSS sinh ra http:// |
Thiếu trustProxies hoặc APP_URL sai |
SQLSTATE[HY000] [2002] |
Thiếu biến DB_*, hoặc database ở environment khác |
| CSS, JS của Vite 404 | package.json thiếu script build: ZoCloud chỉ build tài nguyên khi có script này |
Xem log trực tiếp: zo logs -f, hoặc chỉ lỗi 5xx: zo logs -stream http -status 5xx.
Bạn có thể thử toàn bộ trên gói Dùng thử (2 service, 1 database); một app Laravel đủ web, queue, scheduler, MySQL và Valkey thì cần gói Hobby (5 service, 2 database, 119.000 đ/tháng chưa VAT) trở lên. Đọc thêm hướng dẫn app, database và zo CLI.
Câu hỏi thường gặp
ZoCloud chạy Laravel bằng gì?
ZoCloud nhận ra Laravel qua composer.json hoặc file artisan, chạy composer install, build tài nguyên front-end nếu package.json có script build, rồi phục vụ thư mục public bằng Apache trên cổng PORT. Khi container khởi động, nó chạy config:cache, route:cache và view:cache.
File .env của Laravel đặt ở đâu?
zo CLI không gửi file .env lên. Bạn dán nội dung vào tab Biến môi trường bằng Sửa dạng .env; Laravel đọc thẳng biến môi trường nên không cần file .env trên máy chủ.
Chạy queue worker và scheduler của Laravel thế nào?
Tạo thêm service từ cùng repo, đổi Loại service thành Worker và đặt Lệnh chạy là php artisan queue:work. Scheduler cũng là một Worker với lệnh php artisan schedule:work.
Ảnh người dùng tải lên có mất khi deploy lại không?
Có, nếu chỉ ghi vào ổ đĩa của container. Hãy lưu vào bucket S3 của ZoCloud (disk s3 của Laravel) hoặc gắn volume vào thư mục storage/app.