Vercel Celery worker 배포: Daemons 설정과 실행 조건 확인

상황별 바로가기: 사용 가능 조건 · instances 설정 · 작업이 실행되지 않을 때 · 재배포·작업 중복 점검

Vercel은 2026년 10월 15일 Daemons 공개 베타를 발표했습니다. 장기 실행 컨테이너를 웹 앱과 같은 프로젝트에 배포하고 지정한 인스턴스 수를 유지하는 기능입니다. 이 글은 공식 설정 분석과 오프라인 프로브 검증을 다루며, 원격 배포 성공기는 아닙니다. 공개 베타 발표

이번 예제의 경로는 Python producer → 외부 TLS Redis broker → Daemons의 Celery worker입니다. 웹 요청을 처리하는 쪽은 작업을 발행하고, worker는 큐를 소비합니다. Redis 서버나 결과 저장소를 worker 컨테이너 안에 함께 설치하지 않습니다. Daemons 자체는 외부에서 들어오는 HTTP·TCP 요청을 받는 서버가 아닙니다.

먼저 확인할 플랜·베타 제약과 broker 조건

Hobby를 포함한 모든 플랜에서 각 플랜의 쿼터 안에서 사용할 수 있습니다. 이를 무료·무제한 실행으로 해석하지 마세요. 특히 Hobby는 Active CPU 쿼터를 모두 쓰면 팀의 daemon이 중지될 수 있으므로, 대기 시간이 길다는 이유만으로 사용량 점검을 생략해서는 안 됩니다. 현재 플랜별 쿼터·중지 조건

확인 항목	현재 조건과 준비
실행 환경	Production 전용. Preview에서는 worker가 실행되지 않음
확장	인스턴스 수를 수동 지정. 자동 확장 미지원
로컬 파일	임시 저장소. 업무 상태는 외부 DB·객체 저장소 등에 보관
네트워크 진입	인바운드 HTTP·TCP 미지원. worker가 외부 broker에 연결
개발 명령	vercel dev는 daemon을 실행하지 않음. 로컬에서는 이미지로 시험
프로젝트 Root Directory	하위 폴더로 지정한 프로젝트는 현재 Daemons 추가 미지원
컨테이너	Dockerfile·Containerfile 필요. 실행 아키텍처는 Linux amd64

위 표는 베타 제한 문서 기준입니다. 특히 모노레포의 프로젝트 Root Directory와 아래 설정의 worker/는 다른 항목입니다. 기존 프로젝트를 그대로 쓸 수 있는지 먼저 판단하세요.

이 글은 native Redis TCP 프로토콜을 제공하는 외부 TLS Redis를 broker로 선택합니다. rediss 접속 주소·인증·인증서 신뢰·네트워크 허용·큐 관련 권한·연결 수 제한을 준비하세요. REST API 주소를 Redis 접속 URL로 대신 넣을 수는 없습니다. 메시지 보존과 eviction 정책도 확인합니다. Celery Redis 연결 조건

1단계: 버전을 고정한 Celery Dockerfile 준비

Celery Daemons 예제 ZIP을 풀면 다음 구조가 나옵니다. 기존 앱에 적용할 때에는 파일을 필요한 위치에 병합하고 기존 vercel.json을 덮어쓰지 마세요.

vercel.json
README.txt
worker/
  Dockerfile
  .dockerignore
  requirements.txt
  app.py
  send_probe.py
  test_probe.py

예제는 Python 3.12.15의 slim-bookworm 이미지와 digest, Celery 5.6.3·Redis 클라이언트 6.4.0을 지정합니다. 전이 패키지 버전도 requirements.txt에 명시했습니다. 이미지 버전·아키텍처는 Python 공식 이미지, Celery 배포 정보는 공식 PyPI 페이지와 대조했습니다. 이 버전 조합으로 실제 이미지 빌드를 완료했다는 뜻은 아닙니다.

FROM python:3.12.15-slim-bookworm@sha256:34386ef0cb081344d7ec1c103ba398e6e9f64e9ab3a1509accc92a4e24a07258
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir --disable-pip-version-check -r requirements.txt
COPY app.py send_probe.py ./
USER 65532:65532
STOPSIGNAL SIGTERM
CMD ["celery", "-A", "app:app", "worker", "--loglevel=INFO", "--concurrency=1", "--queues=daemon-probe", "--hostname=probe@%h"]

CMD는 Celery를 포그라운드에서 직접 실행하는 배열 형식입니다. 셸에서 백그라운드로 띄우는 &나 별도 HTTP 서버는 필요하지 않습니다. Celery가 종료 신호를 직접 받도록 두고, Celery 자체의 SIGTERM 처리를 임의의 Python 신호 핸들러로 덮어쓰지 않습니다. Celery 시작·종료 방식

app.py는 전용 daemon-probe 큐에서 UUID 형식의 job_id와 0~90초 대기 시간만 받는 점검 작업입니다. 실제 이메일·AI API 호출·DB 변경을 수행하지 않으며 결과 backend도 설정하지 않았습니다. 발행과 worker 실행을 구분해 관찰하기 위한 프로브입니다. app.py 원문 · 패키지 버전 목록

2단계: 최상위 daemons에 instances 지정

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "daemons": {
    "celery-worker": {
      "root": "worker/",
      "entrypoint": "Dockerfile",
      "instances": { "iad1": 1 },
      "resources": { "requests": { "memory": "1Gi" } },
      "terminationGracePeriodSeconds": 60
    }
  }
}

현재 확인한 발표 예시도 instances를 사용합니다. 다른 코드에 replicas가 남아 있다면 공개 스키마에서 deprecated로 표시하며 instances가 있으면 replicas를 무시한다는 점을 확인하세요. 두 이름을 병기하지 않고 instances 하나로 정리합니다. 공식 JSON 스키마

설정	이 예제에서의 의미
root	vercel.json 기준 소스 폴더 worker/
entrypoint	root 안에서 빌드할 Dockerfile. Python 실행 모듈 이름이 아님
instances.iad1	iad1 리전에 컨테이너 인스턴스 1개
CMD의 --concurrency=1	각 Celery worker의 작업 동시 처리 슬롯 1개
terminationGracePeriodSeconds	SIGTERM 이후 종료 유예를 이 예제에서 60초로 지정

인스턴스 수와 Celery 동시성은 서로 다른 설정입니다. 리전을 여러 개로 늘리면 전체 worker 수도 합산해야 합니다. iad1은 예시이며 broker 위치와 지원 리전을 함께 검토하세요. command를 생략했으므로 이미지의 CMD를 사용합니다. 별도 command를 지정하면 이미지의 ENTRYPOINT·CMD를 대체하므로 명령을 중복 관리하지 않는 편이 확인하기 쉽습니다. 설정 필드 기준

종료 유예 기본값은 확인 시점에 설정 문서가 10초, JSON 스키마가 30초로 서로 다르게 표시합니다. 실제 기본 동작을 추정하지 않고 이 예제에서는 60초를 명시했습니다. 운영 작업의 길이와 복구 방식에 맞춰 값을 정하고 실제 종료 기록으로 확인하세요.

3단계: Production 환경변수와 로컬 시험 분리

Vercel 프로젝트의 Environment Variables에서 CELERY_BROKER_URL을 Production에 설정합니다. 로컬용 파일을 만들거나 Development 변수를 내려받은 것만으로 Production에 적용되지는 않습니다. 환경변수를 바꾼 뒤에는 새 Production 배포로 반영해야 합니다. 환경별 변수 설정 · daemon 변수 반영 방식

# 실제 비밀값을 넣기 전의 URL 형태입니다.
CELERY_BROKER_URL=rediss://USER:ENCODED_PASSWORD@BROKER_HOST:6379/0?ssl_cert_reqs=required

공급자가 제공한 TLS 주소·포트·DB 번호와 인증 정보를 사용하고, 비밀번호의 URL 특수문자는 인코딩합니다. 이 예제는 rediss와 인증서 검증을 요구합니다. 자격증명을 Dockerfile의 ARG·ENV나 코드에 쓰지 마세요. ZIP의 .dockerignore는 .env 파일 등이 이미지에 섞이지 않도록 구성했습니다.

Docker가 있는 환경에서는 ZIP 루트에 비공개 .env.worker 파일을 준비하고 다음처럼 시험할 수 있습니다. 이 명령은 실제 broker에 접속하므로 별도 시험용 broker·큐를 사용합니다.

docker build --platform=linux/amd64 -t vercel-celery-probe worker/
docker run --rm --name celery-probe --env-file .env.worker vercel-celery-probe

다른 터미널의 같은 폴더에서 작업 하나를 발행합니다.

docker run --rm --env-file .env.worker vercel-celery-probe python send_probe.py --seconds 2

로컬 시험 성공은 Vercel 원격 네트워크·배포·종료 동작의 증거를 대신하지 않습니다. Preview가 없는 베타에서 원격 시험이 필요하면, 별도 시험 프로젝트의 Production에 시험 broker를 연결하는 방식으로 운영 작업과 구분하세요.

4단계: 배포 상태보다 작업 ID의 흐름 확인

설정·이미지·Production 변수를 검토한 뒤 의도한 프로젝트를 Production으로 배포합니다. CLI를 사용한다면 실제 프로젝트 연결을 확인한 루트에서 다음 명령을 사용합니다. Production 배포 옵션

vercel --version
vercel deploy --prod

프로젝트 Daemons에서 celery-worker를 확인하고, Logs에서 source가 daemon인 기록과 해당 이름으로 필터링합니다. stdout·stderr는 이 경로로 수집됩니다. 설정을 바꿨는데 인스턴스 수가 그대로라면 dashboard의 scaling override도 확인하세요. 이 override는 재배포 후에도 남을 수 있습니다. 로그와 수동 확장 관리

단계	실제 환경에서 확보할 자료	아직 확인하지 못한 것
배포 준비·인스턴스 실행	배포·이미지·worker 이름·broker 연결 상태	작업 전달·처리 성공
producer의 submitted	발행한 task_id·job_id	worker의 수신·완료
worker 수신·started	같은 task_id와 job_id·시각·worker 식별	완료·업무 효과
worker completed	같은 식별자의 완료 시각·중복 횟수	실제 서비스의 이메일·DB 등 별도 업무 결과

이 프로브에는 result backend가 없으므로 AsyncResult의 저장 상태를 완료 근거로 삼지 않습니다. 실제 서비스에 결과 조회가 필요하면 외부 결과 저장소나 업무 DB를 별도로 설계해야 합니다. 배포 승인과 롤백의 경계를 정할 때에는 AI 에이전트 CI/CD 배포 승인·롤백 안내를 참고할 수 있습니다.

worker는 켜졌는데 작업이 실행되지 않을 때

다음은 배포 조건과 예제 코드를 바탕으로 정리한 진단 순서입니다. 먼저 마지막으로 확인한 단계를 찾고 그다음 경계만 조사하세요. 원격 장애를 재현한 로그는 아닙니다.

관측한 상황	먼저 대조할 항목	다음 확인
worker 자체가 나타나지 않음	Production 배포인지, 프로젝트 Root Directory·쿼터 조건	지원 조건과 배포의 daemon 항목 확인
broker 연결이 실패하거나 시간 초과	Production 변수 반영 배포, native Redis 주소·포트·TLS·인증·네트워크 허용	비밀값을 가린 연결 오류와 broker 측 연결 기록 대조
submitted는 있지만 worker 수신이 없음	producer와 worker가 같은 broker·DB 번호·큐를 쓰는지	예제의 daemon-probe 큐와 실행한 배포·worker 로그 대조
수신·started 뒤 completed가 없음	같은 task_id의 예외·종료·재전달 기록	종료·재전달 점검으로 진행
AsyncResult만 보고 대기 중으로 판단	result backend 설정 여부	이 예제는 backend가 없으므로 task_id·job_id별 로그로 판정

수신 여부가 불분명할 때 같은 업무를 반복 발행하면 원래의 전달 문제와 발행 중복이 섞입니다. 먼저 기존 식별자의 흐름을 확인하고, 재시험은 별도 시험 작업으로 기록하세요.

5단계: 종료·재전달과 업무 중복을 나눠 점검

Celery는 일반적으로 SIGTERM을 받으면 실행 중인 작업을 마치는 warm shutdown을 수행합니다. 그러나 플랫폼의 유예 시간보다 오래 걸리면 강제 종료될 수 있습니다. 배포 중에는 이전 버전과 새 버전이 잠시 함께 실행될 수도 있으므로, 새 프로세스가 실행됐다는 사실만으로 이전 작업의 처리가 끝났다고 판단하지 마세요. Celery 종료 신호 · Vercel 교체 순서

프로브는 late ACK와 task_reject_on_worker_lost를 켰고 Redis visibility timeout을 120초로 지정했습니다. 이는 제한된 시험을 위한 선택입니다. 모든 예외의 자동 재시도나 정확히 한 번 실행을 보장하지 않으며, 반복 크래시에서는 재전달 루프가 생길 수 있습니다. Redis의 재전달이 지연되는 조건도 함께 봐야 합니다. ACK·worker lost 설정 · Redis 재전달·visibility timeout

1. 2초짜리 작업으로 정상 수신·완료를 먼저 확인합니다.
2. 별도 중단 시험에서는 90초짜리 프로브를 발행하고 재배포 전후의 식별자·시각을 기록합니다.
3. 배포 시작 시각 대신 실제 종료 신호 시점과 그때 남아 있던 작업 시간을 확인합니다. 빌드 중 작업이 이미 끝났다면 중단 시험으로 분류하지 않습니다.
4. 정상 종료인지 유예 초과인지, 같은 task_id가 다시 수신됐는지와 redelivered 표식을 대조합니다. 표식이 없다는 이유만으로 재전달이 없었다고 단정하지 않습니다.
5. 같은 job_id의 completed 횟수를 세고 발행 중복·재전달·업무 효과 중복을 나눠 기록합니다.

send_probe.py에서 같은 job_id를 지정해 다시 발행하면 새 Celery task_id가 생깁니다. 같은 업무 ID를 붙였다는 사실만으로 중복 실행이 제거되지는 않습니다. 프로브는 로그와 대기만 수행하지만, 실제 이메일·결제·DB 작업에는 외부 DB의 고유 제약이나 제공자의 멱등성 키 등 업무에 맞는 중복 방지와 실패 격리 절차가 필요합니다. Celery 작업의 멱등성·재전달 조건

지원하지 않는 요구와 이 글의 검증 범위

요청을 직접 받는 HTTP 서버는 Functions·Services 쪽으로, 영구 상태는 외부 저장소로 분리합니다. Preview마다 worker가 필요하거나 큐 길이에 따른 자동 확장이 필수라면, 현 베타를 그대로 적용하기보다 해당 요구를 지원하는 별도 worker 실행 환경을 검토해야 합니다.

검색에서 보이는 2024년 9월의 Celery 실행 불가 답변은 당시 서버리스 함수의 실행 조건을 설명합니다. 현재 Daemons 베타의 지원 여부는 위 조건표와 최신 공식 문서를 기준으로 판단하세요.

편집부는 Celery 5.6.3을 임시 로컬 환경에 설치해 오프라인 테스트 4개를 통과했습니다. task 본문을 eager 방식으로 실행하며 소켓 사용을 막았고, 식별자 기록·입력 검증·동일 업무 ID의 반복 실행을 확인했습니다. 로컬 Python은 3.9.6이며, Docker 이미지의 Python 3.12 실행·Redis 전달·Vercel 배포·종료·재전달은 검증하지 않았습니다.

Daemons Celery 배포 점검표는 버전·설정·실제 수신·완료·중단 결과를 기록하는 빈 양식입니다. 베타 지원 조건과 스키마가 바뀌면 다시 확인한 날짜와 예제 버전을 함께 갱신하세요.

자주 묻는 질문

기존 HTTP Function에서 Celery를 실행하는 것과 무엇이 다른가요?

Function은 HTTP 요청 처리를, Daemons의 worker는 외부 큐를 계속 소비하는 프로세스를 담당합니다. 웹 요청에서 작업을 발행하는 것과 worker 자체를 계속 실행하는 것은 구분해야 합니다.

Preview에서도 worker가 실행되나요?

현재 공개 베타는 Production만 지원합니다. vercel dev도 daemon을 실행하지 않습니다. 로컬 이미지 시험과 별도 시험 프로젝트의 Production 검증을 나눠 진행하세요.

배포 도중 worker가 종료되면 작업 중복을 어떻게 확인하나요?

task_id·업무 job_id별 수신·시작·완료 시각과 재전달 표식을 대조하세요. ACK 설정과 broker의 대기·보존 상태도 함께 확인합니다. 실제 업무 효과를 외부 저장소에서 확인해야 중복 처리를 판단할 수 있습니다.