Bài 2 Làm chủ Supervisor cho Laravel Queue: Thực chiến cài đặt, viết file cấu hình .conf và quản lý Production

Chào anh em đã quay lại với series làm chủ Supervisor! Ở bài học trước, chúng ta đã thấu hiểu lý do tại sao ứng dụng Laravel Production bắt buộc phải có một process manager "bảo kê" cho hệ thống Queue [cite: 19].

Trong bài học thứ hai này, chúng ta sẽ xắn tay áo lên và đi thẳng vào phần thực hành: cài đặt Supervisor trên Ubuntu, thiết lập file cấu hình chuẩn production, và làm chủ các câu lệnh quản lý hàng ngày.

1. Cài đặt Supervisor trên hệ điều hành Ubuntu/Debian

Supervisor được viết bằng Python và có sẵn trong kho lưu trữ (repository) mặc định của các hệ điều hành nhân Linux dòng Ubuntu/Debian. Anh em mở terminal và chạy các lệnh sau:

# Cập nhật lại danh sách gói phần mềm
sudo apt update

# Cài đặt Supervisor
sudo apt install supervisor -y

Sau khi cài đặt xong, service của Supervisor sẽ tự động chạy ngầm. Anh em có thể kiểm tra trạng thái của nó bằng lệnh:

sudo systemctl status supervisor

Nếu thấy trạng thái hiển thị là active (running), hệ thống của chúng ta đã sẵn sàng!

2. Cấu trúc thư mục file cấu hình của Supervisor

Các file cấu hình dịch vụ do Supervisor quản lý thường được đặt tại đường dẫn:

/etc/supervisor/conf.d/

Tại đây, chúng ta sẽ tạo một file cấu hình riêng biệt cho project Laravel của mình (ví dụ: laravel-worker.conf). Việc tách riêng file cấu hình giúp hệ thống quản lý gọn gàng, dễ deploy tự động thông qua CI/CD (GitHub Actions, GitLab CI).

3. Viết file cấu hình .conf chuẩn chỉnh cho Laravel Queue Worker

Anh em tạo file cấu hình bằng trình soạn thảo yêu thích (ví dụ: nano hoặc vim):

sudo nano /etc/supervisor/conf.d/laravel-worker.conf

Sau đó, dán nội dung mẫu tối ưu sau đây vào file (nhớ thay đổi đường dẫn /var/www/my-project và user hệ thống cho khớp với môi trường của anh em nhé):

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/my-project/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=4
redirect_stderr=true
stdout_logfile=/var/www/my-project/storage/logs/supervisor.log
stopwaitsecs=3600

🔍 Giải phẫu chi tiết từng tham số quan trọng:

• [program:laravel-worker]: Tên định danh của tiến trình trên Supervisor.
• process_name=%(program_name)s_%(process_num)02d: Cách đặt tên cho các tiến trình con khi chạy đa luồng (numprocs > 1). Kết quả sinh ra sẽ là laravel-worker_01, laravel-worker_02,...
• command: Câu lệnh thực thi để chạy queue worker. Ở đây mình dùng driver là redis, thời gian nghỉ khi queue trống là 3 giây, tối đa thử lại 3 lần (--tries=3), và tự khởi động lại worker sau mỗi 1 tiếng (--max-time=3600) để giải phóng triệt để bộ nhớ RAM (tránh lỗi memory leak).
• autostart=true: Tự động chạy các worker này ngay khi hệ thống (Ubuntu) khởi động lại.
• autorestart=true: Cấu hình cốt lõi giúp Supervisor tự động "hồi sinh" worker ngay lập tức nếu nó bị crash hoặc chết giữa chừng.
• user=www-data: Chạy worker dưới quyền của user hệ thống (thường là www-data hoặc user sở hữu source code), tránh chạy bằng quyền root gây rủi ro bảo mật.
• numprocs=4: Chạy song song 4 tiến trình worker cùng lúc để tăng tốc độ xử lý hàng đợi (throughput).
• redirect_stderr=true & stdout_logfile: Gom toàn bộ log lỗi và log thông thường ghi thẳng vào file log của Laravel để dễ bề debug.
• stopwaitsecs=3600: Thời gian tối đa (tính bằng giây) chờ một job đang chạy dở phải hoàn thành trước khi buộc phải tắt worker (rất quan trọng khi bạn chạy lệnh supervisorctl restart để deploy code mới).

4. Kích hoạt và Quản lý Supervisor hàng ngày

Sau khi tạo và lưu file cấu hình xong, chúng ta cần thông báo cho Supervisor cập nhật lại danh sách tiến trình bằng bộ lệnh sau:

• Bước 1: Nạp file cấu hình mới

  sudo supervisorctl reread
  

• Bước 2: Cập nhật và khởi chạy tiến trình

  sudo supervisorctl update
  

• Bước 3: Kiểm tra trạng thái các worker

  sudo supervisorctl status
  

Anh em sẽ thấy danh sách 4 worker (laravel-worker:laravel-worker_00, laravel-worker_01,...) hiển thị trạng thái RUNNING màu xanh mướt!

💡 Các câu lệnh "gối đầu giường" khi deploy code:

Mỗi lần anh em push code mới lên production có dính dáng đến Queue, đừng quên restart lại worker để Laravel nhận code mới:

• Khởi động lại toàn bộ worker của project:

  sudo supervisorctl restart laravel-worker:*
  

• Dừng tất cả worker:

  sudo supervisorctl stop laravel-worker:*
  

• Xem lịch sử log realtime (nếu cần trace lỗi):

  tail -f /var/www/my-project/storage/logs/supervisor.log
  

Tóm tắt Bài 2

• Chúng ta đã cài đặt thành công Supervisor lên môi trường Ubuntu.
• Tự tay xây dựng một file cấu hình .conf tối ưu, chịu tải cao với đa tiến trình (numprocs) và cơ chế chống memory leak.
• Nắm vững bộ lệnh vận hành cốt lõi phục vụ cho công việc deploy hàng ngày.
• Hẹn gặp lại anh em ở Bài 3: Chúng ta sẽ bàn về các Best Practices nâng cao, cách xử lý tín hiệu khi deploy không làm gián đoạn job đang chạy, và mẹo giám sát hệ thống Queue thông minh hơn!