> LARAVEL 13.x DOCS

Giao diện

Triển khai (Deployment) ​

Giới thiệu (Introduction) ​

Khi bạn đã sẵn sàng triển khai ứng dụng Laravel lên production, có một số điều quan trọng bạn có thể làm để đảm bảo ứng dụng chạy hiệu quả nhất có thể. Trong tài liệu này, chúng tôi sẽ đề cập một số điểm khởi đầu tuyệt vời để đảm bảo ứng dụng Laravel được triển khai đúng cách.

Yêu cầu Server (Server Requirements) ​

Laravel framework có một vài yêu cầu hệ thống. Bạn cần đảm bảo web server có phiên bản PHP tối thiểu và các extensions sau:

  • PHP >= 8.2
  • Ctype PHP Extension
  • cURL PHP Extension
  • DOM PHP Extension
  • Fileinfo PHP Extension
  • Filter PHP Extension
  • Hash PHP Extension
  • Mbstring PHP Extension
  • OpenSSL PHP Extension
  • PCRE PHP Extension
  • PDO PHP Extension
  • Session PHP Extension
  • Tokenizer PHP Extension
  • XML PHP Extension

Cấu hình Server (Server Configuration) ​

Nginx ​

Nếu triển khai ứng dụng trên server chạy Nginx, bạn có thể sử dụng file cấu hình sau làm điểm khởi đầu. Hầu hết sẽ cần tùy chỉnh tùy theo cấu hình server.

Hãy đảm bảo web server chuyển tất cả requests đến file public/index.php. Bạn không bao giờ nên di chuyển file index.php đến thư mục gốc project, vì phục vụ ứng dụng từ thư mục gốc sẽ lộ nhiều file cấu hình nhạy cảm ra internet:

nginx
server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    root /srv/example.com/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

FrankenPHP ​

FrankenPHP cũng có thể được dùng để phục vụ ứng dụng Laravel. FrankenPHP là server ứng dụng PHP hiện đại được viết bằng Go. Để phục vụ ứng dụng Laravel bằng FrankenPHP, bạn chỉ cần gọi lệnh php-server:

bash
frankenphp php-server -r public/

Để tận dụng các tính năng mạnh mẽ hơn của FrankenPHP, như tích hợp Laravel Octane, HTTP/3, nén hiện đại, hoặc khả năng đóng gói ứng dụng Laravel thành file binary độc lập, hãy tham khảo tài liệu FrankenPHP cho Laravel.

Quyền thư mục (Directory Permissions) ​

Laravel cần quyền ghi vào thư mục bootstrap/cache và storage, vì vậy bạn nên đảm bảo process owner của web server có quyền ghi vào các thư mục này.

Tối ưu hóa (Optimization) ​

Khi triển khai ứng dụng lên production, có nhiều file nên được cache, bao gồm cấu hình, events, routes và views. Laravel cung cấp lệnh Artisan optimize tiện lợi sẽ cache tất cả các file này. Lệnh này thường nên được gọi như một phần của quy trình triển khai:

bash
php artisan optimize

Lệnh optimize:clear có thể được dùng để xóa tất cả file cache do lệnh optimize tạo ra cũng như tất cả keys trong cache driver mặc định:

bash
php artisan optimize:clear

Cache cấu hình (Caching Configuration) ​

Khi triển khai lên production, bạn nên chạy lệnh config:cache trong quy trình triển khai:

bash
php artisan config:cache

Lệnh này gộp tất cả file cấu hình Laravel thành một file cached duy nhất, giảm đáng kể số lần framework phải truy cập filesystem khi tải giá trị cấu hình.

QUAN TRỌNG

Nếu chạy lệnh config:cache trong quy trình triển khai, bạn nên đảm bảo chỉ gọi hàm env từ bên trong file cấu hình. Sau khi cấu hình đã được cache, file .env sẽ không được tải và tất cả gọi hàm env cho biến .env sẽ trả về null.

Cache Events (Caching Events) ​

Bạn nên cache ánh xạ (mappings) event-to-listener được tự động phát hiện trong quy trình triển khai:

bash
php artisan event:cache

Cache Routes (Caching Routes) ​

Nếu xây dựng ứng dụng lớn với nhiều routes, bạn nên chạy lệnh route:cache trong quy trình triển khai:

bash
php artisan route:cache

Lệnh này thu gọn tất cả đăng ký route thành một lệnh gọi method duy nhất trong file cached, cải thiện hiệu suất đăng ký route khi có hàng trăm routes.

Cache Views (Caching Views) ​

Khi triển khai lên production, bạn nên chạy lệnh view:cache:

bash
php artisan view:cache

Lệnh này pre-compile tất cả Blade views để chúng không bị compile theo yêu cầu, cải thiện hiệu suất của mỗi request trả về view.

Tải lại Services (Reloading Services) ​

GỢI Ý

Khi triển khai trên Laravel Cloud, không cần sử dụng lệnh reload, vì việc tải lại mượt mà tất cả services được xử lý tự động.

Sau khi triển khai phiên bản mới, bất kỳ long-running services nào như queue workers, Laravel Reverb hoặc Laravel Octane đều nên được tải lại/khởi động lại để sử dụng code mới. Laravel cung cấp lệnh Artisan reload để kết thúc các services này:

bash
php artisan reload

Nếu không sử dụng Laravel Cloud, bạn nên cấu hình process monitor thủ công để phát hiện khi reloadable processes thoát và tự động khởi động lại chúng.

Chế độ Debug (Debug Mode) ​

Tùy chọn debug trong file cấu hình config/app.php quyết định lượng thông tin lỗi được hiển thị cho người dùng. Mặc định, tùy chọn này được thiết lập theo giá trị biến APP_DEBUG trong file .env.

CẢNH BÁO

Trong môi trường production, giá trị này phải luôn là false. Nếu biến APP_DEBUG được đặt thành true trên production, bạn có nguy cơ lộ các giá trị cấu hình nhạy cảm cho người dùng cuối.

Route Health Check (The Health Route) ​

Laravel bao gồm route health check tích hợp sẵn có thể dùng để giám sát trạng thái ứng dụng. Trong production, route này có thể được dùng để báo cáo trạng thái cho uptime monitor, load balancer hoặc hệ thống điều phối (orchestration) như Kubernetes.

Mặc định, route health check được phục vụ tại /up và sẽ trả về HTTP response 200 nếu ứng dụng đã khởi động mà không có exceptions. Ngược lại, HTTP response 500 sẽ được trả về. Bạn có thể cấu hình URI cho route này trong file bootstrap/app:

php
->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/status',
)

Khi có HTTP requests đến route này, Laravel cũng sẽ dispatch event DiagnosingHealth, cho phép bạn thực hiện các health check bổ sung. Trong listener cho event này, bạn có thể kiểm tra trạng thái database hoặc cache. Nếu phát hiện vấn đề, bạn chỉ cần throw exception từ listener.

Triển khai với Laravel Cloud hoặc Forge ​

Laravel Cloud ​

Nếu muốn nền tảng triển khai được quản lý hoàn toàn, tự động mở rộng (auto-scaling), được tối ưu cho Laravel, hãy xem Laravel Cloud. Laravel Cloud là nền tảng triển khai mạnh mẽ, cung cấp managed compute, databases, caches và object storage.

Khởi chạy ứng dụng Laravel trên Cloud và tận hưởng sự đơn giản có khả năng mở rộng. Laravel Cloud được tinh chỉnh bởi những người tạo ra Laravel để hoạt động mượt mà với framework.

Laravel Forge ​

Nếu bạn muốn tự quản lý server nhưng chưa thoải mái với việc cấu hình tất cả dịch vụ cần thiết, Laravel Forge là nền tảng quản lý VPS server cho ứng dụng Laravel.

Laravel Forge có thể tạo server trên nhiều nhà cung cấp hạ tầng như DigitalOcean, Linode, AWS và nhiều hơn. Ngoài ra, Forge cài đặt và quản lý tất cả công cụ cần thiết để xây dựng ứng dụng Laravel mạnh mẽ, như Nginx, MySQL, Redis, Memcached, Beanstalk và nhiều hơn.