Docker Compose를 이용한 Dify 배포: Unbuffered SSE & Multi-Model Gateway Integration

langgenius/dify를 에이전트 워크플로우 오케스트레이션(agentic workflow orchestration)을 위해 테스트할 때, 공식 Docker Compose 설정은 빠르게 실행되게 해줍니다. 하지만 프로덕션 배포에서는 두 가지 실제 문제점(friction points)에 부딪히게 됩니다: 리버스 프록시 뒤에서 스트리밍 응답이 깨짐과 Claude/GPT/DeepSeek의 개별 API 키를 관리하는 것이 복잡함입니다. 여기는 이 두 문제를 모두 해결하는 검증된 설정 방법입니다.

스트리밍 문제 (The Streaming Problem)

Dify의 에이전트 실행 및 RAG 파이프라인은 Server-Sent Events (SSE)를 통해 응답을 스트리밍합니다. 기본 Nginx/Caddy 버퍼링(buffering)이 이를 방해합니다:

# 증상: 완료될 때까지 출력이 없고, 모든 것이 한 번에 쏟아져 나옴
curl -N https://dify.yourdomain.com/v1/chat-messages \
  -H "Authorization: Bearer app-xxx" \
...

이 문제를 해결하려면 두 가지 계층이 필요합니다: 조기 트래픽을 방지하기 위한 Docker healthcheck와 명시적인 프록시 언버퍼링(proxy unbuffering)입니다.

프로덕션 Docker Compose

version: '3.8'
services:
  dify-api:
...

Caddy Unbuffered Streaming 설정

dify.yourdomain.com {
    reverse_proxy dify-web:3000 {
        header_up X-Real-IP {remote_host}
...

다중 모델 게이트웨이 통합 (Multi-Model Gateway Integration)

Dify의 모델 제공자 설정(model provider settings)에서 별도의 Anthropic/OpenAI/DeepSeek 키를 관리하는 대신, Docker 환경을 구성하여 단일 릴레이(relay)를 통해 라우팅하도록 합니다:

# .env
OPENAI_API_BASE=https://b-lost.com/v1
OPENAI_API_KEY=blost_xxx  # 모든 모델에 접근 가능한 단일 키

이제 Dify의 모델 설정 UI에서 자격 증명을 다시 입력할 필요 없이 gpt-4o, claude-sonnet-3-7, 또는 deepseek-chat을 선택할 수 있습니다. 게이트웨이가 라우팅, 캐싱 및 장애 조치(failover)를 처리합니다.

검증 (Verification)

# 스트리밍이 end-to-end로 작동하는지 테스트
curl -N https://dify.yourdomain.com/v1/chat-messages \
  -H "Authorization: Bearer app-xxx" \
...

프로덕션 체크리스트 (Production Checklist)

• ✅ Healthchecks는 조기 트래픽을 방지하여 (시작 시 502 에러 방지) 합니다.
• ✅ flush_interval -1은 SSE 스트림이 버퍼링되지 않도록 보장합니다.
• ✅ Postgres, Redis 및 Dify 스토리지를 위한 영구 볼륨(Persistent volumes)을 사용합니다.
• ✅ 게이트웨이는 프롬프트 캐싱과 함께 다중 공급자 접근을 통합합니다.
• ✅ Caddy를 통한 HTTPS 자동 갱신 기능을 제공합니다.

이 설정은 Dify의 에이전트 워크플로우와 RAG 파이프라인을 프로덕션급 스트리밍 안정성과 간소화된 API 키 관리로 구동합니다. 버퍼링 지연도 없고, 자격 증명(credential) 분산도 없습니다.