Variabilele de mediu ale Dify self-hosted: referință în Dify: fluxuri agentice, Knowledge și self-hosting: explicație și exemple

Dify funcționează cu setările implicite. Valorile esențiale stau în docker/.env, creat din docker/.env.example. Setările opționale sau specifice unui furnizor au șabloane în docker/envs/: copiezi șablonul fără sufixul .example și îl editezi. Valorile din docker/.env au prioritate. După modificare repornești stiva cu docker compose down și docker compose up -d; după un upgrade compari fiecare .env.example cu .env-ul corespunzător.

Unele variabile au reguli de plasare. DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN și SSRF_PROXY_ALLOW_PRIVATE_IPS funcționează doar din docker/.env. PASSWORD_PEPPER se pune în docker/envs/core-services/api.env, nu în docker/.env, pentru că Compose transmite .env și către worker, plugin daemon, agent backend, frontend și sandbox.

Variabilele URL (CONSOLE_API_URL, CONSOLE_WEB_URL, SERVICE_API_URL, APP_WEB_URL, FILES_URL) pot rămâne goale într-o instalare pe un singur domeniu în spatele Nginx; Dify le deduce din cerere. Le setezi pentru domenii proprii, frontend și backend pe subdomenii diferite, OAuth, Notion, e-mailuri (fără CONSOLE_WEB_URL, linkurile din e-mail sunt greșite) sau formularele Human Input trimise prin e-mail (APP_WEB_URL). TRIGGER_URL este implicit http://localhost și trebuie schimbat ca webhook-urile să fie accesibile din exterior.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
`SECRET_KEY`	Semnează sesiuni, JWT și URL-uri de fișiere și criptează credențialele OAuth ale pluginurilor. Generează-l cu `openssl rand -base64 42` înainte de prima pornire; schimbarea ulterioară deloghează toți utilizatorii și face ilizibile credențialele OAuth.
`INIT_PASSWORD`	Parolă cerută de pagina `/install` înainte de crearea contului de administrator (cel mult 30 de caractere).
`PASSWORD_PEPPER`	Secret amestecat în parolele de autentificare. Se setează înainte de crearea contului admin; schimbarea lui cu conturi existente le invalidează parolele.
`KEY_PROVIDER_TYPE`	`local` (implicit) sau `azure-keyvault`, pentru cheile care criptează credențialele workspace-urilor. Se alege înainte de primul workspace.
`CONSOLE_API_URL / CONSOLE_WEB_URL`	URL-urile publice ale API-ului consolei și ale consolei web (OAuth, Notion, linkuri în e-mailuri, CORS).
`SERVICE_API_URL`	URL-ul de bază afișat dezvoltatorilor pentru Service API; gol = dedus din cerere (de exemplu `http://localhost/v1`).
`APP_WEB_URL / TRIGGER_URL`	Adresa aplicațiilor web publicate (linkurile formularelor Human Input) și adresa publică a triggerelor: `{TRIGGER_URL}/triggers/webhook/{id}`.
`DB_TYPE`	`postgresql` (implicit), `mysql`, `oceanbase`, `seekdb`; plus `DB_HOST`, `DB_PORT`, `DB_USERNAME`, `DB_PASSWORD`, `DB_DATABASE`.
`STORAGE_TYPE`	Implicit `opendal`; altele: `s3`, `azure-blob`, `google-storage`, `aliyun-oss` etc. (`local` este depreciat).
`VECTOR_STORE`	Implicit `weaviate`; peste 30 de valori, între care `qdrant`, `milvus`, `pgvector`, `elasticsearch`, `opensearch`, `chroma`. O bază deja indexată își păstrează tipul.
`COMPOSE_PROFILES`	Implicit `${VECTOR_STORE:-weaviate},${DB_TYPE:-postgresql},collaboration`: pornește containerele potrivite pentru vector store și baza de date.
`EXPOSE_NGINX_PORT / EXPOSE_NGINX_SSL_PORT`	Porturile gazdei pentru Nginx: 80 și 443.
`NGINX_HTTPS_ENABLED`	Cu `true`, pui certificatul și cheia în `./nginx/ssl/` (`dify.crt`, `dify.key`) și treci URL-urile publice pe `https://`.
`UPLOAD_FILE_SIZE_LIMIT / UPLOAD_FILE_BATCH_LIMIT`	15 MB pe document și 5 fișiere pe încărcare, implicit.
`ETL_TYPE`	`dify` (txt, md, pdf, html, xlsx, docx, csv) sau `Unstructured` (adaugă doc, ppt, pptx, eml, msg, xml, epub; cere `UNSTRUCTURED_API_URL`).
`TOP_K_MAX_VALUE`	Valoarea maximă pentru `top_k` la căutarea în baza de cunoștințe; implicit 10.
`APP_MAX_EXECUTION_TIME / WORKFLOW_MAX_EXECUTION_TIME`	3600 de secunde fiecare; se măresc împreună.
`WORKFLOW_MAX_EXECUTION_STEPS / MAX_TREE_DEPTH`	500 de execuții de noduri pe rulare; 50 de noduri pe un drum.
`MAX_PARALLEL_LIMIT / LOOP_NODE_MAX_COUNT / WORKFLOW_CALL_MAX_DEPTH`	10 ramuri paralele; 100 de repetări Loop; 5 niveluri de workflow imbricat.
`SANDBOX_WORKER_TIMEOUT / SANDBOX_ENABLE_NETWORK`	15 secunde pe execuție de cod; acces la rețea din cod (implicit `true`, prin proxy-ul SSRF).
`CODE_MAX_STRING_LENGTH / CODE_MAX_STRING_ARRAY_LENGTH / CODE_MAX_DEPTH`	400.000 de caractere; 30 de elemente; adâncime 5, pentru ieșirile nodului Code.
`HTTP_REQUEST_NODE_MAX_TEXT_SIZE / HTTP_REQUEST_NODE_MAX_BINARY_SIZE`	1 MB pentru răspunsuri text, 10 MB pentru binare.
`SSRF_PROXY_ALLOW_PRIVATE_IPS / SSRF_PROXY_ALLOW_PRIVATE_DOMAINS`	IP-uri, intervale CIDR sau nume de gazdă private pe care proxy-ul SSRF le lasă să treacă (de exemplu un Firecrawl intern).
`WEBHOOK_REQUEST_BODY_MAX_SIZE`	10 MB pentru payload-ul unui Webhook Trigger; peste limită, răspuns 413.
`MAX_TOOLS_NUM / MAX_ITERATIONS_NUM`	10 unelte simultan și 99 de iterații pentru agenți.
`DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN`	Obligatoriu din 1.18.0 (`openssl rand -base64 32`), doar în `docker/.env`; fără el, agent backend și sandbox-ul repornesc continuu.
`DIFY_AGENT_SERVER_SECRET_KEY / DIFY_AGENT_API_TOKEN`	Vin cu valori de dezvoltare publice; se înlocuiesc în producție.
`NEXT_PUBLIC_ENABLE_AGENT_V2 / NEXT_PUBLIC_ENABLE_AGENT_V2_IN_CHATFLOW`	Implicit `true` și `false`: afișează noul Agent; al doilea îl adaugă și în Chatflow.
`MARKETPLACE_ENABLED / FORCE_VERIFYING_SIGNATURE / PIP_MIRROR_URL`	Marketplace, verificarea semnăturii pluginurilor, mirror PyPI pentru dependențele pluginurilor.
`CHECK_UPDATE_URL`	Implicit `https://updates.dify.ai`; gol dezactivează verificarea versiunilor noi (util în rețele izolate).
`ENABLE_COLLABORATION_MODE`	Implicit `true`: editare simultană pe canvas. Pe altă gazdă decât localhost setezi `NEXT_PUBLIC_SOCKET_URL`.

Exemple practice și scenarii reale

Exemplul 1: HTTPS pe un domeniu propriu

# docker/.env
NGINX_HTTPS_ENABLED=true
# certificatul în docker/nginx/ssl/dify.crt și cheia în docker/nginx/ssl/dify.key
CONSOLE_API_URL=https://dify.example.com
CONSOLE_WEB_URL=https://dify.example.com
APP_WEB_URL=https://dify.example.com
TRIGGER_URL=https://dify.example.com

Exemplul 2: Milvus în locul Weaviate

Bazele de cunoștințe deja indexate rămân pe vector store-ul cu care au fost create.

cd dify/docker
cp envs/vectorstores/milvus.env.example envs/vectorstores/milvus.env
# în docker/.env:  VECTOR_STORE=milvus
docker compose down
docker compose up -d

Exemplul 3: Acces la un serviciu din rețeaua internă

# docker/.env — doar gazdele necesare, nu toată rețeaua
SSRF_PROXY_ALLOW_PRIVATE_IPS=192.168.0.189
SSRF_PROXY_ALLOW_PRIVATE_DOMAINS=firecrawl.internal

Greșeli frecvente și capcane

Editezi .env.example în loc de .env. Compose citește .env; șablonul se suprascrie la upgrade.
Lași valorile din .env.example pentru SECRET_KEY, DIFY_AGENT_SERVER_SECRET_KEY, DIFY_AGENT_API_TOKEN și PLUGIN_DIFY_INNER_API_KEY. Sunt publice în repo; ultima este singura autentificare a API-ului intern pentru pluginuri.
Treci de la local la azure-keyvault (sau invers) pe o instanță cu credențiale salvate. Credențialele criptate cu un furnizor nu pot fi decriptate de celălalt.
Lași TRIGGER_URL=http://localhost și configurezi webhook-uri în servicii externe. Ele nu pot ajunge la localhost-ul serverului tău.

`Variabilele de mediu ale Dify self-hosted: referință` în Dify: fluxuri agentice, Knowledge și self-hosting