개발

라라벨 큐 기능 적용해보기

May 9, 2025

라라벨 큐(Queue)
1. env 파일 설정 변경
2. 큐용 job 테이블 생성
3. 큐 워커 실행
슈퍼바이저(Supvervisor) 설치
큐 실행 테스트

최근에 백단에서 비동기로 처리할 일이 있어서 이리저리 알아보다가 라라벨에선 이럴때 큐 기능을 사용하면 된다고 정보를 얻게되었다.

큐 기능자체가 있던건 알고있었는데, 제대로 써본적이없어서 이번기회에 한번 알아보았다.

라라벨 큐(Queue)

큐는 우리가 운영체제나 프로세스 구조를 배우면서 배우는 그 '큐'가 맞다.

먼저 들어간놈이 먼저 나오는 FIFO 형식의 프로세스 처리구조를 가지고있어 예약 대기 작업을 처리하는데 자주 이용이된다.

라라벨도 기본적으론 큐를 지원하는데 기본 큐 드라이버가 sync 로 설정되어있다.

즉 메모리상에서 즉시 실행되는 방식으로 사실상 프로세스 내부에서 동기처리로 작업되는 경우라 상상하는 그런 큐로써의 동작은 하지 않는다.

실제로 비동기 처리로 프로세스와 별개로 큐를 처리하려면 큐 드라이버를 database 로 변경해주고 큐가 들여다볼 job 테이블을 구현해놓아야한다.

당연히 관련 코드는 라라벨에서 제공하므로 아래와 같은 순서로 쉽게 큐 드라이버 환경을 구성해볼 수 있다.

1. env 파일 설정 변경

라라벨의 여러 환경설정값을 세팅하는 .env 파일을 열어 큐 드라이버를 아래와 같이 바꿔준다.

QUEUE_CONNECTION=databaseCopy

그리고 이 env 설정이 라라벨 프로젝트에 적용되도록 터미널(CLI)로 들어가 라라벨 프로젝트에서 아래 명령어를 통해 설정값을 적용해준다.

php artisan config:cacheCopy

2. 큐용 job 테이블 생성

그리고 큐테이블을 생성해야하는데, 관련 생성 청사진은 라라벨 패키지에서 지원하므로 이를 꺼내와서 마이그레이션 작업을 진행해준다.

php artisan queue:table
php artisan migrateCopy

3. 큐 워커 실행

이후 큐가 job 테이블을 감시하면서 작업을 수행시키려면 터미널에서 아래와 같은 명령어로 워커를 실행시키면 된다.

php artisan queue:workCopy

이 워커는 터미널이 열려있는 상태에서 감시&작업대기상태로 계속 유지되며 터미널을 종료하면 워커도 같이 종료가 된다.

이를 라이브 서버에서 상시로 적용하고 싶으면 우분투(리눅스)의 경우에는 슈퍼바이저라는 패키지를 통해 워커를 실행시킬 수 있다.

슈퍼바이저(Supvervisor) 설치

sudo apt update
sudo apt install supervisorCopy

우분투의경우 apt로 쉽게 슈퍼바이저를 설치할 수 있다.

설치가 완료된이후 아래 명령어를 통해 슈퍼바이저에서 사용할 설정파일을 생성해주자.

sudo nano /etc/supervisor/conf.d/laravel-queue.confCopy

[program:laravel-queue]
process_name=%(program_name)s
command=php /var/www/web/artisan queue:work --sleep=3 --tries=3 --timeout=90
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/html/storage/logs/laravel-queue.logCopy

user=www-data 는 우분투에서 해당 프로세스를 실행시키는 주체를 뜻하는것이므로 일반적으로 웹서버 권한으로 실행시키므로 www-data로 작성해두는것이 좋다.

필요에 따라 현재 접속계정명으로 바꿔도 되는데, 이러면 관련 파일의 권한설정도 더불어 해줘야할것이다.

슈퍼바이저의 실행로그는 stdout_logfile의 경로에 저장된다.

필요에 따라 바꿔주면될것이다. (가끔 저 로그파일이 과도한 권한 root:www-data로 생성될때가 있는데, chmod 777, chown www-data:www-data로 로그파일의 권한을 변경해주면 실행기록이 잘 남게된다.)

이후 슈퍼바이저를 아래와 같이 시작해주고 실행여부를 확인해볼 수 있다.

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-queue

sudo supervisorctl status
laravel-queue        RUNNING   pid 1234, uptime 0:01:23 #실행결과Copy

큐 실행 테스트

위의 방식대로 큐 드라이버를 설정하면 이를 테스트해보는 일만 남았다.

php artisan make:job TestQueueJobCopy

위 명령어로 테스트용 큐잡을 하나 생성해준다.

<?php

namespace App\Jobs;

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

class TestQueueJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    /**
     * Create a new job instance.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Execute the job.
     *
     * @return void
     */
    public function handle()
    {
        Log::info('TestQueueJob 실행됨!');
    }
}
Copy

그리고 라라벨 로그로 기록을 남기는 job을 구현해둔다.

이 작업을 실행시키기위해 터미널로 이동한 후 라라벨 프로젝트에 경로를 두고 tinker를 실행시킨다.

php artisan tinker
>>> dispatch(new \App\Jobs\TestQueueJob());Copy

그리고 위와같이 dispatch 메소드로 해당 작업을 실행시켜준다.

그러면 라라벨 로그 파일에 아래와 같이 로그가 찍히면 제대로 큐가 작동하는것임을 확인할 수 있다.

[2025-05-09 12:29:43] production.INFO: TestQueueJob 실행됨!Copy

이와 더불어 큐 로그에도 아래와 같이 실행 여부가 찍혀나오게된다.

[2025-05-09 12:25:06][1] Processing: App\Jobs\TestQueueJob
[2025-05-09 12:25:06][1] Processed:  App\Jobs\TestQueueJob
[2025-05-09 12:25:51][2] Processing: App\Jobs\TestQueueJob
[2025-05-09 12:25:51][2] Processed:  App\Jobs\TestQueueJob
[2025-05-09 12:26:21][3] Processing: App\Jobs\TestQueueJob
[2025-05-09 12:26:21][3] Processed:  App\Jobs\TestQueueJob
[2025-05-09 12:27:00][4] Processing: App\Jobs\TestQueueJob
[2025-05-09 12:27:00][4] Processed:  App\Jobs\TestQueueJob
[2025-05-09 12:27:15][6] Processing: App\Jobs\TestQueueJob
[2025-05-09 12:27:15][6] Processed:  App\Jobs\TestQueueJob
[2025-05-09 12:29:43][7] Processing: App\Jobs\TestQueueJob
[2025-05-09 12:29:43][7] Processed:  App\Jobs\TestQueueJobCopy