Post-Processing Worker

Post-Processing Worker는 ai-node-agent가 S3 raw/ prefix에 업로드한 생성 결과물(이미지/비디오)을 후처리하고, S3 creations/ prefix에 최종 원본/썸네일/preview를 저장한 뒤 백엔드에 최종 결과를 통지하는 비동기 백그라운드 서비스입니다.

1. 아키텍처 및 워크플로우

전체 프로세스는 비동기 메시징 큐(SQS)를 통해 느슨하게 결합(Loosely Coupled)되어 있습니다.

ai-node-agent: ComfyUI workflow 실행이 완료되면 raw output을 S3 raw/ prefix에 업로드하고, 후처리 SQS에 메시지를 발행합니다.
Post-Processing Worker:
- SQS 메시지 폴링: TARGET_ENV에 해당하는 후처리 SQS 큐를 지속적으로 모니터링하여 ai-node-agent로부터 전달되는 후처리 작업 메시지를 수신합니다.
- 환경 식별: 수신된 SQS 메시지 본문의 env 필드(예: local, dev, production)를 기반으로 현재 작업을 처리할 환경을 식별합니다.
- S3 raw 파일 다운로드: 식별된 환경에 해당하는 media bucket의 raw/ prefix에서 원본 파일을 다운로드합니다.
- 후처리 수행: 다운로드한 파일의 종류에 따라 최적화된 후처리를 수행합니다.
  - 이미지: Pillow 라이브러리를 사용하여 썸네일 이미지를 생성합니다.
  - 비디오: ffmpeg를 사용하여 정적 썸네일과 웹 미리보기용 MP4 파일(H.264 코덱, 오디오 제거, 리사이징, Faststart)을 생성합니다.
- S3 final 파일 업로드: 후처리된 최종 결과물과 썸네일(또는 미리보기 영상)을 식별된 환경에 해당하는 media bucket의 creations/ prefix에 업로드합니다.
- S3 raw 파일 삭제: 최종 업로드가 완료되면 raw/ prefix에 있던 원본 파일을 삭제합니다. 실패나 중단에 대비해 raw/ lifecycle도 안전망으로 둡니다.
- 백엔드 상태 업데이트: 백엔드 API를 호출하여 해당 creationId의 상태를 COMPLETED로 업데이트하고, S3에 저장된 최종 파일 및 썸네일(미리보기)의 경로를 전달합니다.
Backend API: 워커로부터 결과 등록 또는 실패 기록 요청을 받아 DB 상태와 Redis progress 상태를 동기화하고, 클라이언트에게 WebSocket 이벤트를 전송합니다.

2. LocalStack 의존성 제거

post-processing-worker는 LocalStack에 대한 의존성을 두지 않고, AWS SDK(boto3)를 통해 실제 AWS SQS 및 S3 서비스와 직접 통신합니다. local 개발 환경에서도 cloud SQS/S3를 사용하여 prod와 같은 queue/storage 동작을 검증합니다.

3. 환경별 구성 (Environment Configuration)

환경별 실행부와 managed resource 경계는 다음과 같습니다.

구분	Local	Development (Dev)	Production (Prod)
실행 위치	MacBook Docker Compose	EC2 Docker Compose	Kubernetes
인증 방식	local/dev IAM credential	IAM role 또는 access key	IRSA (IAM Roles for Service Accounts)
SQS Queue	`vivid-ai-post-processing-worker-queue-local`	`vivid-ai-post-processing-worker-queue-dev`	`vivid-ai-post-processing-worker-queue-prod`
S3 Media Bucket	local media bucket	dev media bucket	prod media bucket
Backend URL	`http://backend:3000/api` 또는 `http://host.docker.internal:3000/api`	EC2 내부 Docker network 또는 dev backend URL	Kubernetes Service DNS 또는 public domain

현재 코드의 환경 변수명은 S3_TEMP_BUCKET_*, S3_PERMANENT_BUCKET_*로 남아 있습니다. 단일 media bucket을 쓰는 환경에서는 두 값을 같은 bucket 이름으로 지정하고, raw/와 creations/ prefix로 역할을 분리합니다. 자세한 S3 기준은 S3 media bucket 설정을 따릅니다.

3.1. Production 환경: IRSA (보안 강화)

Prod 환경에서는 보안을 위해 장기(Long-term) Access Key를 사용하지 않고, OIDC(OpenID Connect) 기반의 IRSA를 사용합니다.

ServiceAccount: post-processing-worker-sa-prod
IAM Role: vivid-ai-prod-worker-role
작동 원리:
1. Kubernetes 파드 생성 시 AWS Identity Token이 주입됩니다.
2. boto3 라이브러리가 이를 감지하고 sts:AssumeRoleWithWebIdentity를 호출하여 임시 자격 증명을 얻습니다.
3. .dockerignore를 통해 .env 파일(로컬 키 포함)이 이미지에 포함되지 않도록 관리합니다.

4. 환경 변수 설정 (Configuration)

post-processing-worker는 .env 파일을 통해 환경 변수를 로드하며, Kubernetes 환경에서는 Deployment 설정을 통해 주입됩니다.

# 타겟 환경 (local, dev, prod/production)
# 이 값에 따라 어떤 SQS 큐를 폴링할지 결정하고 S3 버킷 이름을 결정합니다.
TARGET_ENV=local

# AWS 자격 증명 (Local/Dev 환경에서만 사용, Prod는 IRSA 권장)
AWS_ACCESS_KEY_ID=your_aws_access_key_id
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
AWS_REGION=ap-northeast-2 # SQS 및 S3 버킷이 위치한 리전

# SQS 후처리 큐 URL (환경별)
# ai-node-agent가 이 큐로 후처리 요청 메시지를 보냅니다.
SQS_POST_PROCESSING_QUEUE_LOCAL=https://sqs.ap-northeast-2.amazonaws.com/your_aws_account_id_local/vivid-ai-post-processing-worker-queue-local
SQS_POST_PROCESSING_QUEUE_DEV=https://sqs.ap-northeast-2.amazonaws.com/your_aws_account_id_dev/vivid-ai-post-processing-worker-queue-dev
SQS_POST_PROCESSING_QUEUE_PROD=https://sqs.ap-northeast-2.amazonaws.com/your_aws_account_id_prod/vivid-ai-post-processing-worker-queue-prod

# S3 버킷 이름 (환경별)
# AI 노드 에이전트가 생성한 raw/ 파일을 저장
S3_TEMP_BUCKET_LOCAL_NAME=<local-media-bucket-name>
S3_TEMP_BUCKET_DEV_NAME=<dev-media-bucket-name>
S3_TEMP_BUCKET_PROD_NAME=<prod-media-bucket-name>

# 후처리된 최종 결과물 파일을 creations/에 저장
# 단일 media bucket 구성에서는 TEMP/PERM 값을 같은 bucket으로 둡니다.
S3_PERMANENT_BUCKET_LOCAL_NAME=<local-media-bucket-name>
S3_PERMANENT_BUCKET_DEV_NAME=<dev-media-bucket-name>
S3_PERMANENT_BUCKET_PROD_NAME=<prod-media-bucket-name>

# 백엔드 API URL (상태 업데이트용)
BACKEND_API_URL=http://backend:3000/api

# worker tuning
POST_PROCESSING_MAX_WORKERS=4
SQS_VISIBILITY_TIMEOUT_SECONDS=900
FFMPEG_TIMEOUT_SECONDS=300

5. 배포 및 운영

Docker 빌드 (Prod)

# .dockerignore가 .env를 제외하는지 반드시 확인
docker build --no-cache -t post-processing-worker-vivid-ai-prod .
docker tag post-processing-worker-vivid-ai-prod:latest 234657229332.dkr.ecr.ap-northeast-1.amazonaws.com/post-processing-worker-vivid-ai-prod:latest
docker push 234657229332.dkr.ecr.ap-northeast-1.amazonaws.com/post-processing-worker-vivid-ai-prod:latest

Kubernetes 배포

# Secret, SA, Deployment 순차 적용
kubectl apply -f post-processing-worker-secrets-prod.yaml
kubectl apply -f post-processing-worker-service-account-prod.yaml
kubectl apply -f post-processing-worker-deployment-prod.yaml

6. 실행 방법 (Local Development)

post-processing-worker는 Docker 컨테이너로 실행됩니다. local에서는 backend, ComfyUI, ai-node-agent, Redis, Postgres와 함께 Docker Compose로 띄우는 구성을 기본으로 합니다.

docker-compose up --build

7. 확장 원칙

post-processing-worker는 ai-node-agent와 별도 컨테이너/Pod로 유지합니다. 생성 orchestration과 ffmpeg/Pillow 후처리는 병목 특성이 다르기 때문에, queue와 worker replica를 분리해두면 image job, video job, preview generation을 독립적으로 조절할 수 있습니다.

초기 권장값은 다음과 같습니다.

image post-processing: 3-5 workers
video post-processing: 1-2 workers
SQS visibility timeout: ffmpeg timeout보다 길게 설정

1. 아키텍처 및 워크플로우​

2. LocalStack 의존성 제거​

3. 환경별 구성 (Environment Configuration)​

3.1. Production 환경: IRSA (보안 강화)​

4. 환경 변수 설정 (Configuration)​

5. 배포 및 운영​

Docker 빌드 (Prod)​

Kubernetes 배포​

6. 실행 방법 (Local Development)​

7. 확장 원칙​