Điều Khiển Hàng Đợi Laravel Thần Tốc Với Redis, Docker & FrankenPHP (Kèm Horizon!)

Lê Lân

06/07/2025

Quản Lý Hàng Đợi Laravel Với Redis, Docker và FrankenPHP: Hướng Dẫn Toàn Diện

Mở Đầu

Quản lý hàng đợi trong Laravel là kỹ thuật then chốt giúp ứng dụng xử lý các tác vụ nền một cách hiệu quả, không làm ảnh hưởng đến trải nghiệm người dùng.

Trong bài viết này, chúng ta sẽ tìm hiểu cách triển khai và quản lý hàng đợi trong Laravel sử dụng Redis làm driver, chạy trên môi trường Docker với FrankenPHP làm web server. Đây là giải pháp tối ưu giúp bạn xử lý các tác vụ bất đồng bộ như gửi email, xử lý file hoặc các công việc nặng khác mà không ảnh hưởng trực tiếp đến tốc độ phản hồi của ứng dụng web.

Bạn sẽ được hướng dẫn chi tiết từng bước từ việc cấu hình Redis, tạo và phân phát công việc (Job), chạy worker xử lý hàng đợi cùng cách tích hợp Laravel Horizon — một công cụ giám sát và quản lý hàng đợi nổi bật — trong môi trường Dockerized. Bài viết phù hợp với những ai đã có hiểu biết cơ bản về Laravel queues hoặc đang muốn áp dụng queue queue hiệu quả trong dự án của mình.

Yêu Cầu Tiền Đề

Trước khi bắt đầu, hãy đảm bảo rằng máy tính của bạn đã cài đặt:

Docker

Docker Compose

Composer

Những công cụ này sẽ tạo nền tảng giúp bạn xây dựng, vận hành và quản lý các dịch vụ Laravel cùng Redis một cách trơn tru.

Bắt Đầu Với Môi Trường Laravel, Redis và Docker

Bạn có thể khởi tạo một ứng dụng Laravel mới hoặc clone demo repository đã được cấu hình sẵn với Redis và Docker dùng FrankenPHP. Bài viết tập trung vào việc sử dụng file docker-compose.yml từ repo này để làm ví dụ.

Những lệnh cơ bản để setup ban đầu:

composer install
cp .env.example .env
docker compose build --no-cache
docker compose up -d
docker compose run --rm artisan key:generate

Điều này giúp bạn chuẩn bị môi trường Laravel chạy trên Docker với Redis.

Cấu Hình Redis Làm Queue Driver Trong Laravel

Mở file .env trong dự án Laravel và thay đổi cấu hình hàng đợi như sau:

QUEUE_CONNECTION=redis
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379

Giải thích:

QUEUE_CONNECTION=redis giúp Laravel sử dụng Redis làm driver hàng đợi.

REDIS_HOST=redis trùng với tên service Redis trong docker-compose.yml .

Các thông số khác là mặc định cho container Redis.

⚠️ Bảo mật Redis: Dù trong môi trường phát triển, thiết lập trên có thể chấp nhận được, nhưng khi lên production bạn cần:

Kích hoạt mật khẩu cho Redis.

Chỉ mở cổng Redis cho mạng tin cậy.

Không để Redis trực tiếp truy cập từ internet.

Xem thêm tài liệu Redis Docker Hub: https://hub.docker.com/_/redis

Tạo Và Phân Phối Một Job Đơn Giản

Để minh họa, chúng ta sẽ tạo một job ghi thông báo vào file log.

Tạo job sử dụng Artisan:

docker compose run --rm artisan make:job LogMessageJob

Mở file app/Jobs/LogMessageJob.php và chỉnh sửa handle() như sau:

<?php
namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\Queueable;
use Illuminate\Support\Facades\Log;

class LogMessageJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable;

    public function __construct()
    {
        // Có thể truyền dữ liệu ở đây nếu cần
    }

    public function handle(): void
    {
        Log::info('LogMessageJob executed successfully', [
            'timestamp' => now(),
        ]);
    }
}

Phân phối (dispatch) job trong route routes/web.php :

use Illuminate\Support\Facades\Route;

Route::get('/log-message', function () {
    dispatch(new \App\Jobs\LogMessageJob());
    return 'Job dispatched!';
});

Khi truy cập đường dẫn /log-message , job sẽ được thêm vào hàng đợi Redis.

Kiểm Tra Và Chạy Worker Xử Lý Job

Kiểm tra trạng thái hàng đợi

Chạy lệnh sau để quan sát số job trong queue mặc định:

docker compose run --rm artisan queue:monitor default

Kết quả sẽ hiển thị số lượng job đang chờ xử lý.

Xử lý job ngay tức thì

docker compose run --rm artisan queue:work --once

Lệnh này sẽ xử lý 1 job trong queue rồi thoát. Bạn có thể kiểm tra file log tại storage/logs/laravel.log để xác nhận job đã chạy thành công.

Chạy worker ở chế độ nền với Docker

Chỉnh sửa file docker-compose.yml để thêm service worker:

worker:
  image: laravel-app
  volumes:
    - ".:/app"
  working_dir: /app
  command: "frankenphp php-cli artisan queue:work"
  depends_on:
    - redis
    - mysql

Sau đó khởi động worker:

docker compose up -d worker

Vietnamese users can check logs live:

docker compose logs -f worker

Lúc này, khi bạn truy cập /log-message tiếp tục, job sẽ được worker xử lý nền mà không làm gián đoạn dịch vụ web.

Mẹo nhỏ: Bạn có thể chạy nhiều worker để tăng độ chịu tải và xử lý song song.

Tích Hợp Laravel Horizon Với FrankenPHP

Giới thiệu về Horizon

Laravel Horizon cung cấp dashboard trực quan cho việc quản lý và giám sát hàng đợi Redis, bao gồm thông tin về các worker, job, retry, failed job,…

Cài đặt Horizon

Chạy:

composer require laravel/horizon
docker compose run --rm artisan horizon:install

Vấn đề khi chạy Horizon với FrankenPHP

FrankenPHP không thiết lập hằng số PHP_BINARY, dẫn đến lỗi Permission denied khi Horizon cố gắng khởi chạy worker hoặc supervisor.

Khi ta chạy:

docker compose run --rm artisan horizon

Bị lỗi:

sh: 1: exec: : Permission denied

Cách khắc phục

Thêm đoạn mã override command trong AppServiceProvider.php :

use Laravel\Horizon\SupervisorCommandString;
use Laravel\Horizon\WorkerCommandString;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        SupervisorCommandString::$command = 'exec /usr/local/bin/frankenphp php-cli artisan horizon:supervisor';
        WorkerCommandString::$command = 'exec /usr/local/bin/frankenphp php-cli artisan horizon:work';
    }
}

Điều này giúp Horizon sử dụng đúng binary PHP trong môi trường FrankenPHP.

Thêm Horizon service trong Docker Compose

Cấu hình docker-compose.yml :

horizon:
  image: laravel-app
  volumes:
    - ".:/app"
  working_dir: /app
  command: "frankenphp php-cli artisan horizon"
  healthcheck:
    test: ["CMD", "frankenphp", "php-cli", "artisan", "horizon:status"]
    timeout: 10s
    retries: 3
  depends_on:
    - redis
    - mysql

Khởi chạy Horizon:

docker compose up -d horizon

Truy cập dashboard Horizon tại: http://localhost/horizon

Kết Luận

Bằng cách sử dụng Redis làm hàng đợi trong Laravel cùng môi trường Docker với FrankenPHP, bạn có thể dễ dàng tách các tác vụ nền khỏi luồng xử lý chính, giúp ứng dụng của bạn duy trì hiệu năng và khả năng mở rộng tốt hơn.

Việc tích hợp Laravel Horizon càng làm tăng khả năng giám sát và quản lý hàng đợi chuyên nghiệp hơn, rất phù hợp cho các ứng dụng có nhu cầu xử lý nhiều job bất đồng bộ.

Hãy thử áp dụng thiết lập này trong dự án của bạn và tận dụng sức mạnh của Docker cũng như FrankenPHP để phát triển ứng dụng Laravel hiện đại, hiệu quả!

Tham Khảo

Laravel Official Queues Documentation: https://laravel.com/docs/12.x/queues

FrankenPHP GitHub Discussions: https://github.com/dunglas/frankenphp/discussions/1477

Docker Redis Hub: https://hub.docker.com/_/redis

Laravel Horizon Documentation: https://laravel.com/docs/12.x/horizon

Demo Repository: https://github.com/Repox/laravel-frankenphp-docker

Bài viết "Getting Started with FrankenPHP and Laravel" trên DEV.to: https://dev.to/blog/getting-started-with-frankenphp-and-laravel/