Dify 환경 변수
Dify 환경 변수 (Environment Variables)
Dify는 기본 설정 그대로도 바로 동작해요. 배포를 커스터마이즈하려면 해당 파일의 환경 변수를 수정하면 됩니다.
- 필수 시작 값은
docker/.env에 있어요. 배포 때docker/.env.example에서 복사해 만든 파일이죠. 이 값을 직접 수정합니다. - 선택 사항 또는 제공자별 설정은
docker/envs/아래에 템플릿이 있어요. 기본값을 덮어쓰려면 해당 템플릿을 복사한 뒤(.example접미사를 떼고) 사본을 수정합니다. 예:
cd dify/docker
cp envs/vectorstores/milvus.env.example envs/vectorstores/milvus.env
docker/.env의 값이 docker/envs/*.env 파일의 값보다 우선해요.
공통 변수 (Common Variables)
이 URL 변수들은 Dify의 각 서비스 주소를 설정해요. Nginx 뒤의 단일 도메인 배포(Docker Compose 기본 구성)에서는 이 값들을 비워둬도 시스템이 들어오는 요청에서 자동 감지해요. 커스텀 도메인, 도메인 분리 배포, 또는 리버스 프록시를 쓸 때 이 값들을 구성하면 됩니다.
CONSOLE_API_URL
기본값: (비어 있음) Dify 백엔드 API의 공개 URL이에요. OAuth 로그인(GitHub, Google), Notion 통합, OAuth가 필요한 플러그인을 쓸 때 설정하세요. 이런 기능들은 인증 후 사용자를 돌려보낼 절대 콜백 URL이 필요해요. 또한 보안(HTTPS 전용) 쿠키 사용 여부도 결정합니다. 예: https://api.console.dify.ai
SERVER_CONSOLE_API_URL
기본값: http://api:5001 웹 프론트엔드 컨테이너가 서버 측 요청에 쓰는 콘솔 API 주소예요. 공개 도메인이 아니라 내부 Docker 네트워크를 통해 API에 직접 닿아요. 이 변수는 Python 백엔드가 아닌 웹 프론트엔드 컨테이너만 사용하며, 브라우저 요청은 여전히 CONSOLE_API_URL로 갑니다. 비워두면 CONSOLE_API_URL로 폴백해요. API 서비스가 다른 내부 주소에 있다고 판단될 때만 바꾸세요.
CONSOLE_WEB_URL
기본값: (비어 있음) Dify 콘솔 프론트엔드의 공개 URL이에요. 모든 시스템 이메일(초대, 비밀번호 재설정, 알림)의 링크를 만들고, OAuth 로그인 후 사용자를 콘솔로 돌려보내는 데 쓰여요. CONSOLE_CORS_ALLOW_ORIGINS가 설정되지 않았다면 기본 CORS 허용 오리진 역할도 합니다. 비워두면 이메일 링크가 깨져요. 단일 도메인 배포라도 이메일 기능을 쓴다면 설정하세요. 예: https://console.dify.ai
SERVICE_API_URL
기본값: (비어 있음) Dify 콘솔에서 개발자에게 보여주는 API Base URL이에요. 개발자가 코드에 복사해 Dify API를 호출하는 주소죠. 비워두면 현재 요청에서 자동 감지합니다(예: http://localhost/v1). 서버를 여러 주소로 접근할 수 있을 때 일관된 URL을 보장하려면 설정하세요. 예: https://api.dify.ai
APP_API_URL
기본값: (비어 있음) 웹앱 프론트엔드(게시된 앱)용 백엔드 API URL이에요. 이 변수는 Python 백엔드가 아니라 웹 프론트엔드 컨테이너만 사용해요. 비워두면 Docker 이미지가 기본값 http://127.0.0.1:5001을 씁니다. 예: https://api.app.dify.ai
APP_WEB_URL
기본값: (비어 있음) 게시된 웹앱이 접근되는 공개 URL이에요. 워크플로의 Human Input 노드에 필요하죠. 이메일 알림의 폼 링크가 {APP_WEB_URL}/form/{token} 형태로 만들어져요. 비워두면 Human Input 이메일 전달에 유효한 폼 링크가 포함되지 않아요. 예: https://app.dify.ai
TRIGGER_URL
기본값: http://localhost 웹훅·통합 트리거 엔드포인트의 공개 접근 URL이에요. 외부 시스템이 이 주소로 워크플로를 호출합니다. Dify는 {TRIGGER_URL}/triggers/webhook/{id} 같은 트리거 콜백 URL을 만들고 콘솔에 표시해요. 트리거가 외부 시스템에서 동작하려면, 이 주소가 그들이 도달할 수 있는 공개 도메인이나 IP를 가리켜야 해요.
FILES_URL
기본값: (비어 있음. CONSOLE_API_URL로 폴백) 파일 미리보기·다운로드 링크의 base URL이에요. Dify는 모든 파일(업로드 문서, 도구 출력, 워크스페이스 로고)에 대해 서명된 시간 제한 URL을 만들고 프론트엔드와 멀티모달 모델에 전달해요. 파일 처리 플러그인을 쓰거나 파일 URL을 전용 도메인에 두고 싶을 때 설정하세요. FILES_URL과 CONSOLE_API_URL 둘 다 비어 있으면 파일 미리보기가 동작하지 않아요. 예: https://upload.example.com 또는 http://<your-ip>:5001
INTERNAL_FILES_URL
기본값: (비어 있음. FILES_URL로 폴백) Docker 네트워크 내 서비스들(예: plugin daemon, PDF/Word 추출기) 간 통신에 쓰는 파일 접근 URL이에요. 이 내부 서비스들은 FILES_URL이 Nginx나 공개 도메인을 거치면 그 외부 URL에 닿지 못할 수 있어요. 비워두면 내부 서비스는 FILES_URL을 씁니다. 내부 서비스가 외부 URL에 못 닿을 때 설정하세요. 예: http://api:5001
FILES_ACCESS_TIMEOUT
기본값: 300(5분) 서명된 파일 URL이 유효한 시간(초)이에요. 이 시간이 지나면 URL이 거부되고 파일을 다시 요청해야 해요. 오래 걸리는 프로세스에는 늘리고, 보안을 더 단단히 하려면 줄이세요.
ENABLE_COLLABORATION_MODE
기본값: true 워크플로 캔버스에서 실시간 협업을 활성화해요: 동시 편집, 캔버스 내 댓글, @멘션. localhost가 아닌 다른 호스트에서 Dify에 접속한다면, 브라우저가 닿을 수 있는 WebSocket URL로 NEXT_PUBLIC_SOCKET_URL을 설정하세요(CORS 구성 참고). 기본값 ws://localhost는 로컬 전용 설정에서만 동작해요. 협업을 끄려면 false로 설정하세요. Docker Compose에서는 COMPOSE_PROFILES에서 collaboration도 제거해야 해요. 그렇지 않으면 전용 api_websocket 컨테이너가 계속 떠 있지만 트래픽을 받지 못해요. 자체 리버스 프록시를 쓴다면 /socket.io/에 대해 Upgrade와 Connection 헤더를 전달하세요(번들된 nginx 템플릿은 이미 이걸 합니다). API 레플리카를 여러 개 돌린다면 sticky 세션이 필요해요.
시스템 인코딩 (System Encoding)
서버 구성 (Server Configuration)
로깅 (Logging)
일반 (General)
SECRET_KEY
기본값: (.env.example에 미리 채워져 있음. 프로덕션에서는 반드시 교체) 세션 쿠키 서명, JWT 인증 토큰, 파일 URL 서명(HMAC-SHA256), 타사 OAuth 자격 증명 암호화(AES-256)에 쓰여요. 첫 실행 전에 강력한 키를 생성하세요.
INIT_PASSWORD
기본값: (비어 있음) 최초 설정의 선택적 보안 게이트예요. 설정하면 /install 페이지가 관리자 계정을 만들기 전에 이 비밀번호를 요구해서, 서버가 노출돼 있어도 승인되지 않은 설정을 막아줘요. 설정이 끝나면 이 변수는 더 이상 효과가 없어요. 최대 길이: 30자.
토큰·요청 제한 (Token & Request Limits)
컨테이너 시작 구성 (Container Startup Configuration)
Docker 이미지나 Docker Compose로 시작할 때만 적용돼요.
MODE
기본값: worker(워커 서비스에 배송된 값. 변수를 완전히 지우면 컨테이너는 API 서버를 실행) dify-api 이미지가 컨테이너 시작 시 무엇으로 실행될지를 정해요. 각 환경 예시 파일 3개는 자기 서비스를 위한 값을 고정합니다: worker.env.example의 worker, api.env.example의 api, worker-beat.env.example의 beat. 허용 값은 다음과 같아요.
api(그 외의 빈·인식 못 하는 값 포함): API 서버worker: Celery 태스크 소비자beat: 예약 태스크 디스패처job: Flask CLI 명령 하나를 실행하고 종료migration:MIGRATION_ENABLED=true와 함께 쓰면 DB를 마이그레이션하고 종료
번들된 Compose 파일은 서비스별로 올바른 값을 지정하므로, Kubernetes 같은 커스텀 구성에서만 직접 설정하면 돼요. 잘못된 값은 잘못된 프로세스를 실행하게 됩니다. 워커가 없으면 인덱싱과 메일 태스크가 영원히 큐에 쌓여요.
API 도구 구성 (API Tool Configuration)
데이터베이스 구성 (Database Configuration)
데이터베이스는 기본적으로 PostgreSQL을 써요. OceanBase, MySQL, seekdb도 지원합니다.
연결 풀 (Connection Pool)
Dify가 데이터베이스 연결 풀을 관리하는 방식을 제어해요. 기본값은 대부분의 배포에서 잘 동작합니다.
PostgreSQL 성능 튜닝
이 값들은 PostgreSQL 컨테이너에 시작 인자로 전달돼요. Dify 애플리케이션이 아니라 데이터베이스 서버를 구성하죠.
MySQL 성능 튜닝
이 값들은 MySQL 컨테이너에 시작 인자로 전달돼요. Dify 애플리케이션이 아니라 데이터베이스 서버를 구성하죠.
Redis 구성
Dify를 Redis 인스턴스에 연결하도록 구성해요. Dify는 standalone(기본), Sentinel, Cluster 세 가지 배포 모드를 지원합니다.
Redis SSL 구성
REDIS_USE_SSL=true일 때만 적용돼요. 이 설정들은 URL이 rediss:// 스킴을 쓸 때 Celery 브로커에서도 함께 쓰여요.
Redis Sentinel 모드
Sentinel은 고가용성을 위해 자동 마스터 발견과 페일오버를 제공해요. Cluster 모드와 상호 배타적이에요.
Redis Cluster 모드
Cluster 모드는 여러 Redis 노드에 자동 샤딩을 제공해요. Sentinel 모드와 상호 배타적이에요.
Redis 연결 복원력 (Connection Resilience)
Redis 연결의 클라이언트 측 재시도·타임아웃·헬스체크 동작을 조정해요. 기본값은 보수적이니, 네트워크 지연이 큰 클라우드나 WAN 배포에서는 타임아웃을 늘리세요.
Celery 구성
데이터셋 인덱싱, 이메일 전송, 예약 작업에 쓰이는 백그라운드 태스크 큐를 구성해요.
CELERY_BROKER_URL
기본값: redis://:difyai123456@redis:6379/1 Celery 메시지 브로커용 Redis 연결 URL이에요. 직접 연결 형식:
Sentinel 모드 형식(여러 노드는 세미콜론으로 구분):
CORS 구성
프론트엔드의 크로스 도메인 접근 정책을 제어해요.
Dify CLI와 프로그래매틱 API
/openapi/v1/* 서피스는 사용자 범위의 프로그래매틱 API로, Dify CLI(difyctl)와 다른 클라이언트가 OAuth 베어러 토큰으로 인증하는 대상이에요. 기본적으로 비활성화돼 있고, 배포에서 CLI를 쓰려면 OPENAPI_ENABLED와 ENABLE_OAUTH_BEARER를 둘 다 true로 설정하세요.
파일 스토리지 구성 (File Storage Configuration)
Dify가 업로드 파일, 데이터셋 문서, 암호화 키를 저장할 위치를 구성해요. 각 스토리지 타입은 자기만의 자격 증명 변수가 있어요. 사용 중인 것 하나만 구성하면 됩니다.
STORAGE_TYPE
기본값: opendal 파일 스토리지 백엔드를 선택해요. 지원 값: opendal, s3, azure-blob, aliyun-oss, google-storage, huawei-obs, volcengine-tos, tencent-cos, baidu-obs, oci-storage, supabase, clickzetta-volume, local(지원 중단. 내부적으로 파일시스템 스킴으로 OpenDAL 사용).
아카이브 스토리지 (Archive Storage)
워크플로 실행 로그 보관용 별도 S3 호환 스토리지예요. archive-workflow-runs 유지보수 명령이 선택한 기준점보다 오래된 실행을 월간 Parquet 번들로 묶고, 그 아카이브에서 생성한 CSV 내보내기는 내보내기 버킷에 단계적으로 배치돼요.
벡터 데이터베이스 구성 (Vector Database Configuration)
지식 베이스 임베딩 저장과 유사도 검색에 쓰는 벡터 데이터베이스를 구성해요. 각 제공자는 자기만의 자격 증명 변수 세트가 있어요. 사용 중인 것 하나만 구성하면 됩니다.
VECTOR_STORE
기본값: weaviate 벡터 데이터베이스 백엔드를 선택해요. 데이터셋에 이미 인덱스가 있으면, 이 설정보다 데이터셋에 저장된 타입이 우선해요. Docker Compose에서 제공자를 바꾸면 COMPOSE_PROFILES가 이 값에 따라 일치하는 컨테이너를 자동으로 시작해요. 지원 값: weaviate, oceanbase, seekdb, qdrant, milvus, myscale, relyt, pgvector, pgvecto-rs, chroma, opensearch, oracle, tencent, elasticsearch, elasticsearch-ja, analyticdb, couchbase, vikingdb, opengauss, tablestore, vastbase, tidb, tidb_on_qdrant, baidu, lindorm, huawei_cloud, upstash, matrixone, clickzetta, alibabacloud_mysql, iris, hologres.
지식 구성 (Knowledge Configuration)
어노테이션 임포트 (Annotation Import)
모델 구성 (Model Configuration)
Sentry 구성
Sentry는 오류 추적과 성능 모니터링을 제공해요. 각 서비스는 오류 보고를 분리하기 위해 자기만의 DSN을 가져요.
Notion 통합 구성
Dify를 지식 베이스 데이터 소스로 Notion에 연결해요. 통합 자격 증명은 https://www.notion.so/my-integrations에서 얻을 수 있어요.
메일 구성 (Mail Configuration)
Dify는 계정 초대, 비밀번호 재설정, 로그인 코드, Human Input 노드 알림에 이메일을 보내요. 지원하는 세 제공자 중 하나를 구성하세요. 이메일 링크는 CONSOLE_WEB_URL이 설정돼 있어야 동작합니다. — 공통 변수 참고.
기타 구성 (Other Configuration)
콘솔 기능 (Console Features)
인증과 계정 (Authentication and Accounts)
기본적으로 로그인은 이메일+비밀번호 방식이고, 새 계정은 워크스페이스 초대나 최초 설정 마법사에서 만들어져요. 아래 토글들은 그걸 완화하거나 강화해요.
LLMOps 트레이스 전달
앱 실행의 트레이스가 백그라운드 태스크로 구성된 LLMOps 제공자(Langfuse, LangSmith, Arize/Phoenix 등)에 전달돼요. 이 변수들은 일시적 실패 시의 재시도를 관리해요.
인덱싱 (Indexing)
신규 사용자 기본값 (New User Defaults)
워크플로 생성 (Workflow Generation)
토큰·초대 (Token & Invitation)
모든 토큰 만료 변수는 Redis에 저장된 1회용 토큰이 얼마나 유효한지를 제어해요. 만료 후 사용자는 새 토큰을 요청해야 해요.
코드 실행 샌드박스 (Code Execution Sandbox)
이 설정들은 API와 Worker가 샌드박스에 어떻게 연결할지 알려줘요. 샌드박스는 Code 노드(Python, JavaScript)와 Template Transform(Jinja2) 코드를 격리된 환경에서 실행하는 별도 서비스예요.
코드·템플릿 출력 제한 (Code and Template Output Limits)
API와 Worker가 Code·Template Transform 노드가 반환한 출력에 이 제한을 적용해요. 샌드박스 서비스는 읽지 않아요. 변경 사항은 샌드박스가 아니라 API와 Worker를 재시작하면 적용돼요.
워크플로 런타임 (Workflow Runtime)
워크플로 스토리지 저장소 (Workflow Storage Repository)
워크플로 실행 데이터를 처리할 백엔드 구현체를 선택해요. 기본 SQLAlchemy 저장소는 모든 것을 데이터베이스에 저장해요. 대체 구현(예: Celery, Logstore)은 서로 다른 스토리지 전략에 쓸 수 있어요.
GraphEngine 워커 풀
워크플로 로그 정리 (Workflow Log Cleanup)
HTTP Request 노드
워크플로에서 외부 API를 호출하는 HTTP Request 노드를 구성해요.
웹훅 (Webhook)
SSRF 보호
Dify의 모든 외부 발신 HTTP 요청(HTTP 노드, 이미지 다운로드 등)은 내부/사설 IP 범위로의 요청을 차단하는 프록시를 거쳐요. Server-Side Request Forgery(SSRF) 공격을 막는 거예요.
에이전트 구성 (Agent Configuration)
웹 프론트엔드 서비스
이 변수들은 Next.js 웹 프론트엔드 컨테이너만 사용하고, Python 백엔드에는 영향을 주지 않아요.
NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW
기본값: true Go to Anything 명령 팔레트에서 /create와 /refine 슬래시 명령을 활성화해요. 이 명령들은 자연어 설명에서 Workflow·Chatflow 앱을 생성하고 다듬어줘요. 숨기려면 false로 설정하세요.
New Agent (Beta)
New Agent는 Docker Compose 배포에서 추가 서비스(에이전트 백엔드, 샌드박스, 샌드박스용 전용 이그레스 프록시)로 실행돼요. 모두 docker compose up으로 자동 시작되죠. 기본적으로 활성화되어 있고, 대부분의 설정은 기존 Compose 값에서 파생되므로 보통 아래 변수들만 신경 쓰면 돼요.
DIFY_AGENT_SERVER_SECRET_KEY
기본값: (.env.example에 개발 키가 미리 채워져 있음. 프로덕션에서는 반드시 교체) 에이전트 백엔드가 내부 토큰(샌드박스 에이전트가 백엔드로 다시 인증하는 베어러 토큰 포함)의 키를 파생하는 데 쓰는 루트 시크릿이에요. 공개된 개발 키가 기본으로 배송되므로 스택은 즉시 동작하지만, 그 키를 아는 사람은 그 토큰을 위조할 수 있어요. 프로덕션 사용 전에 교체하세요. 값은 정확히 32바이트로 디코딩되는 패딩 없는 base64url 텍스트여야 해요. 잘못된 값이면 에이전트 백엔드가 시작을 거부합니다. 생성 명령:
DIFY_AGENT_API_TOKEN
기본값: (.env.example에 개발 토큰이 미리 채워져 있음. 프로덕션에서는 반드시 교체) Dify API가 에이전트 백엔드의 run API를 호출할 때 제시하는 베어러 토큰이에요. Compose는 같은 값을 두 서비스에 모두 전달하므로 한 번 설정하면 일치를 유지해요. 공개된 개발 토큰이 기본으로 배송되므로 스택은 즉시 동작하지만, 에이전트 백엔드에 닿을 수 있고 토큰을 아는 사람은 실행을 시작할 수 있어요. 프로덕션 사용 전에 랜덤 값으로 교체하세요.
NEXT_PUBLIC_ENABLE_AGENT_V2
기본값: true 웹 UI에 New Agent를 표시해요: 메인 내비게이션의 Agents 항목과 워크플로 노드 선택기의 New Agent 노드죠. false로 설정하면 숨기고 클래식 Agent 노드로 폴백해요. 여전히 폴백으로 동작하는 ENABLE_AGENT_V2를 대체합니다.
AGENT_BACKEND_BASE_URL
기본값: http://agent_backend:5050 API가 에이전트 백엔드에 닿는 주소예요. Docker Compose에서는 기본값을 유지하세요. 나머지 변수들은 번들 서비스를 구성하거나 기존 Compose 값에서 파생되므로 보통 변경할 필요가 없어요.
데이터베이스 서비스 (Database Service)
Docker Compose에서 데이터베이스 컨테이너 자체를 직접 구성해요.
샌드박스 서비스 (Sandbox Service)
샌드박스는 코드 노드(Python, JavaScript, Jinja2)를 실행하는 격리된 서비스예요. 보안을 위해 네트워크 접근을 끌 수 있어요.
Nginx 리버스 프록시
Certbot 구성
SSRF 프록시
내부/사설 네트워크로의 요청을 차단하는 Squid 기반 SSRF 프록시 컨테이너를 구성해요.
Docker Compose
이 변수들은 docker/.env에 남아 있어요. Docker Compose가 컨테이너 시작 전에 프로파일을 선택하고 포트를 노출하는 데 쓰기 때문이에요.
ModelProvider·도구 위치 구성
앱 인터페이스에서 사용 가능한 도구와 모델 제공자, 그리고 표시 순서를 커스터마이즈해요. 항목 사이에 공백 없는 콤마 구분 값을 사용하세요.
플러그인 데몬 구성 (Plugin Daemon Configuration)
플러그인 데몬은 플러그인 라이프사이클(설치, 실행, 업그레이드)을 관리하는 별도 서비스예요. API는 HTTP로 통신합니다.
크리에이터 센터 구성 (Creator Center Configuration)
Creator Center(creators.dify.ai)는 사용자가 Dify 앱을 템플릿으로 업로드하는 제출 포털이에요. 제출된 템플릿은 검토를 거쳐 승인되면 Dify Marketplace에 등재돼요. 콘솔의 Publish to Marketplace 액션은 앱의 DSL을 내보내 사용자 대신 Creator Center에 업로드합니다. 사용자 관점의 흐름은 Publish Apps to Marketplace를 참고하세요.
OTLP / OpenTelemetry 구성
OpenTelemetry는 분산 트레이싱과 메트릭 수집을 제공해요. 활성화하면 Dify가 Flask를 계측하고 텔레메트리 데이터를 OTLP 컬렉터로 내보냅니다.
기타 (Miscellaneous)
예약 태스크 구성 (Scheduled Tasks Configuration)
Dify는 Celery Beat로 구성 가능한 스케줄의 백그라운드 유지보수 태스크를 실행해요.
레코드 보존·정리 (Record Retention & Cleanup)
오래된 레코드를 어떻게 정리할지 제어해요. BILLING_ENABLED가 활성화되면 정리는 유예 기간이 있는 sandbox 티어 테넌트를 대상으로 해요. 빌링이 비활성화(셀프호스팅)되면 보존 기간 내 모든 레코드에 정리가 적용됩니다.
Aliyun SLS Logstore 구성
워크플로 실행 로그를 데이터베이스 대신 외부에 저장하기 위한 Aliyun Simple Log Service 선택적 통합이에요. logstore 구현을 쓰도록 저장소 구성 변수를 설정하면 활성화돼요.
이벤트 버스 구성 (Event Bus Configuration)
API와 Celery 워커 간 Redis 기반 이벤트 전송이에요.
벡터 데이터베이스 서비스 구성 (Vector Database Service Configuration)
벡터 데이터베이스 컨테이너 자체를 구성해요(Dify 클라이언트 연결이 아니라). 선택한 VECTOR_STORE에 해당하는 변수만 관련이 있어요.
플러그인 데몬 스토리지 구성 (Plugin Daemon Storage Configuration)
플러그인 데몬은 플러그인 패키지를 서로 다른 스토리지 백엔드에 저장할 수 있어요. PLUGIN_STORAGE_TYPE에 맞는 제공자만 구성하세요.