1. 项目概述.env文件在Dify里的真正分量先交代一个背景Dify这个开源LLM应用开发平台不管是本地跑起来做演示还是上生成服务器做生产部署核心入口就是docker目录下的.env文件。我第一次接触Dify时最头疼的就是这个文件——变量多、注释少、官方文档又分散明明每个键看上去都认识真要用起来一个SECRET_KEY没配对整个服务就起不来。折腾几天之后我干脆自己把所有配置项逐个注释了一遍整理成了一份带功能说明的对照表后来团队里新同事上手Dify靠这份注释半小时就能把环境搞定。如果你也正在研究Dify或者正准备从docker compose up -d这一步开始那这篇文章就是给你准备的。我不会通篇念官方文档而是把.env文件按功能拆开告诉你每个配置项是干什么用的、不配会有什么后果、哪些值是我实际踩坑后建议你直接照抄的。先看整体结构。Dify项目是一个多服务组合API服务、Web前端、Worker异步任务、Sandbox代码执行器外挂PostgreSQL、Redis、向量数据库再联动各种外部模型API。这套联动关系全部靠.env里的一个个键值对串联说它是Dify的“总控制台”一点不为过。理解了.env不只是会填配置更是真正理解Dify各模块之间怎么协作。2. 配置项功能拆解每个键到底在控制什么2.1 入口层配置端口、调试开关和密钥进入.env文件最先看到的是几个基础选项。这里我先给出一份实测过的初始值再逐项解释EXPOSE_NGINX_PORT80 EXPOSE_NGINX_SSL_PORT443 NGINX_PORT80 NGINX_ENABLE_CERTBOTfalse NGINX_SSL_CERT_FILENAME NGINX_SSL_CERT_KEY_FILENAMEEXPOSE_NGINX_PORT控制的是宿主机上哪个端口映射到容器内的Nginx等于你访问Dify的入口。比如你改成8080那么浏览器里访问的就是http://服务器IP:8080。NGINX_ENABLE_CERTBOT是做HTTPS证书自动申请用的你在内网测试且没有绑定域名前一定保持false否则容器反复尝试申请证书日志能刷出满屏错误。接着往下走SECRET_KEYyour-secret-key这是整个.env文件里优先级最高的键。它用来给session、用户密码、数据加密做签名。官方常见做法是直接用openssl rand -base64 42生成一个随机串。每次重新部署时这里的值不能变变了的话所有已登录用户的session会立即失效数据库里加密过的字段可能也会出问题。DEPLOY_ENVPRODUCTION DEBUGfalseDEPLOY_ENV有两个取值PRODUCTION和DEVELOPMENT。两者的区别在于是否启用调试接口和若干开发辅助功能。我个人的建议是如果你不是在改Dify源码就一律PRODUCTION。我见过有人为了看异常栈把DEBUG设成true挂到公网后接口响应体直接把堆栈信息裸露给前端这等于把内部结构拱手送人。LOG_LEVELINFO日志等级按DEBUG INFO WARNING ERROR CRITICAL排列。生产环境用INFO足够排查具体问题时可以临时调到DEBUG问题定位完再改回来。这个键很容易被忽略但它直接决定了日志量级——DEBUG级别短时间就能写出几个G的文件。2.2 数据库与缓存配置PostgreSQL和Redis的真实角色Dify的主数据库用的是PostgreSQL这是所有工作流、用户数据、应用配置、对话记录的持久化存储。.env里对应的配置块长这样DB_USERNAMEpostgres DB_PASSWORDpostgres DB_HOSTdb DB_PORT5432 DB_DATABASEdify这里最常见的错误是直接把宿主机的localhost填进DB_HOST。容器网络里PostgreSQL服务在compose网络内的服务名就叫db所以默认值是db而不是127.0.0.1。如果你改了compose文件里的服务名这里要跟着改。DB_DATABASE默认是dify如果你想一机多部署就得开新的数据库实例并把这里对应的库名改掉。Redis那边是缓存和消息队列REDIS_HOSTredis REDIS_PORT6379 REDIS_PASSWORDdifyai123456 REDIS_DB0 REDIS_USE_SSLfalse REDIS_USERNAME比较有意思的是REDIS_USERNAME。较新版本的Redis 6支持ACL用户体系如果你用的是Redis 6以下的版本千万不要填用户名否则认证直接失败。REDIS_PASSWORD默认值在docker-compose文件里有对应但如果你在生产环境还沿用这个默认密码等于把缓存数据裸奔。还要提醒一句REDIS_DB建议固定为一个业务专用的编号别跟其他应用抢同一个库。我见过有团队在同一个Redis实例上既跑Dify又跑别的系统结果别的系统误用了FLUSHALLDify的队列和缓存被一锅端。2.3 向量存储配置选型、参数与语义化Dify的核心卖点是RAG检索增强生成向量数据库就是它的记忆中枢。.env里的相关配置通过两类键控制一类指定存储类型一类指定连接参数。VECTOR_STOREweaviateVECTOR_STORE可选值有很多weaviate、qdrant、milvus、pgvector、opensearch、elasticsearch、chroma等。你选定一种Dify启动时会自动拉取对应的向量库组件。默认值是weaviate。当年我第一次部署时只知道它默认用weaviate直到数据量上来后发现查询变慢才意识到向量存储选型对检索速度的影响巨大。以Weaviate为例连接参数长这样WEAVIATE_ENDPOINThttp://weaviate:8080 WEAVIATE_API_KEYWVf4Dhnkth6UcDD3 WEAVIATE_BATCH_SIZE100WEAVIATE_BATCH_SIZE控制批量写入向量时每批的文档条数默认100如果文档特别大改成50反而更稳。如果你选的是Qdrant对应的QDRANT_URLhttp://qdrant:8080 QDRANT_API_KEYqdrant我看过很多模板复制粘贴出错的案例选了VECTOR_STOREqdrant却把weaviate的配置留着其他类型的配置也杂在一起。Dify启动时只会读取VECTOR_STORE对应的那组配置但多出来的不报错看起来一切正常等你切换到另一类向量库时旧配置和新配置混杂查了半天的错才找到问题。选型建议方面单机测试用weaviate或chroma最省事数据量到千万级向量后再考虑qdrant或milvus如果团队本来就在用pgvector把它作为默认值也可以少维护一种数据库。功能需求如过滤、混合检索再叠加考虑。2.4 文件存储配置本地与对象存储的取舍Dify支持把上传的附件、生成的文档存到本地或S3兼容对象存储。这个配置在实际项目里非常关键很多人初期没注意等服务器磁盘满了才发现所有文件都堆在本地。STORAGE_TYPElocal STORAGE_LOCAL_PATHstorageSTORAGE_TYPE有两个主流取值local和s3。local模式是把文件写到容器内的/app/api/storage目录默认通过数据卷映射到宿主机。如果部署规模不大、流量也一般local够用。但注意多节点水平扩展时local模式会让每台机器的文件各存各的负载均衡一转发用户上次上传的图片在另一台机器上就找不到了。这时候就要上S3。S3模式对应的配置STORAGE_TYPEs3 S3_ENDPOINThttps://s3.example.com S3_BUCKET_NAMEdify-storage S3_ACCESS_KEYyour-access-key S3_SECRET_KEYyour-secret-key S3_REGIONauto S3_ADDRESS_STYLEautoS3_ENDPOINT既可以填云厂商的S3终端也可以填自建的MinIO地址。S3_ADDRESS_STYLE决定请求URL用的是路径风格/bucket/key还是虚拟主机风格bucket.endpoint/keyMinIO默认要设置成path或auto否则会报签名不匹配。2.5 模型接入配置OpenAI式的体系与多供应商兼容Dify本身不训练模型它通过API调用各家模型。.env里最大的配置块就是这些模型密钥。OPENAI_API_KEYyour-openai-api-key OPENAI_API_BASE_URLhttps://api.openai.com OPENAI_API_ORG_IDOPENAI_API_BASE_URL该填什么取决于你用的是官方接口、兼容网关、还是第三方中转。国内使用场景里这个值经常被换成兼容OpenAI协议的中转地址。这里不想展开太多但有一点必须提醒OPENAI_API_ORG_ID在大多数情况下不用填填了反而会跟API Key冲突导致认证报错403。我遇到过一次排查了半天最后发现是多余的OPENAI_API_ORG_ID在干扰。还可以看看另外几组模型配置AZURE_OPENAI_API_KEY AZURE_OPENAI_API_BASE_URL AZURE_OPENAI_API_VERSION2024-06-01 AZURE_OPENAI_API_INSTANCE_NAME AZURE_OPENAI_API_DEPLOYMENT_NAMEAzure OpenAI的配置多出实例名和部署名换算逻辑跟OpenAI官方不同。如果你用AzureAZURE_OPENAI_API_BASE_URL通常长这样https://your-resource.openai.azure.comDEPLOYMENT_NAME指的是你在Azure Model Deployments里起的模型别名不是模型本身的名字。Dify官方文档在各模型页有说明这里不逐家展开。在.env文件里如果某个键留空Dify运行时在“设置-模型供应商”界面可以再填也允许空白占位。它不会因为密钥为空就崩掉但能力列表里对应模型会显示未配置。我的建议是.env里先配最少可运行的一套模型比如OpenAI或兼容接口其他模型的密钥通过平台界面再补。这样既保证部署能快速完成又不用在配置文件里堆一大堆用不上的密钥。3. 实操过程从零配置一份可运行的.env文件3.1 配置前要准备的三样东西动手之前先把这三样备齐域名或服务器IP地址。如果只是本地测试用IP即可。一套可用的模型API Key至少保证能调用对话模型。数据库密码和向量库密钥自己先想好。虽然Dify的docker-compose文件自带默认值但生产环境必须改掉默认密码。从代码仓库拉下项目后进入docker目录会看到一个.env.example文件。第一步不是直接改文件而是先复制一份cp .env.example .env.env.example是官方维护的完整模板里面的每个键都有英文注释。初看挺全但你直接照抄会踩坑因为example模板为了兼容性很多值都留空或给了弱默认值比如默认密码、空密钥。直接跑起来能通但安全状态非常脆弱。3.2 按顺序配置的完整步骤我习惯按下面这个顺序填配置每填完一条心里都有数它对应的是哪个模块第一生成SECRET_KEYopenssl rand -base64 42把输出粘贴到SECRET_KEY后面。这个步骤没有捷径有人偷懒直接填your-secret-key后果是每次启动会话都失效还有安全风险。第二确定部署模式和端口DEPLOY_ENVPRODUCTION DEBUGfalse EXPOSE_NGINX_PORT80如果80端口被占了改成8080或别的空闲端口。改完以后访问入口就是http://IP:端口。第三数据库与Redis把默认密码全部换掉DB_PASSWORD换成自己的强密码 REDIS_PASSWORD换成另一套强密码注意DB_USERNAME如果一直是postgres那数据库里默认超级用户的名字就是它。如果你想用别的用户名需要同步修改docker-compose里PostgreSQL初始化时创建的账号.env单方面改不会生效。第四向量库配置保持默认选型VECTOR_STOREweaviate WEAVIATE_ENDPOINThttp://weaviate:8080 WEAVIATE_API_KEY换掉默认值 WEAVIATE_BATCH_SIZE100如果你机器资源紧张可以把batch size调到20减少单次写入的内存压力代价是导入速度慢一些。第五文件存储STORAGE_TYPElocal STORAGE_LOCAL_PATHstorage先保持本地存储上线后再考虑S3。第六模型APIOPENAI_API_KEY你的key OPENAI_API_BASE_URL你的接口地址家庭镜像或官方都可第七邮件配置如果你要用到邮箱验证码或密码找回功能MAIL_TYPEsmtp MAIL_OPENAI_API_KEY MAIL_DEFAULT_SEND_EMAIL_ADDRESS MAIL_DEFAULT_SEND_EMAIL_NAMEDify不配邮件大部分功能不影响但注册时的验证邮件发不出去会被系统当成未知错误。我的经验是测试阶段先用MAIL_TYPEresend之类的服务临时顶一下真要长期跑还是老老实实配SMTP。3.3 启动与验证配置完毕执行docker compose up -d第一次启动会拉取大量镜像耗时取决于带宽。看到所有容器状态为healthy后打开浏览器访问地址进入账号初始化和登录页面就说明基础环境通了。这里有个细节Dify首次登录时会要求你设置管理员邮箱和密码这一步通过Web界面完成。很多人以为要写在.env里其实不需要。管理员账号信息存在数据库里。验证模型是否接通可以新建一个应用选一个模型测试对话。如果报错先回头检查对应的API密钥和BASE_URL两个键一起错的情况比我预想的多得多。4. 常见问题与排查技巧实录4.1 容器启动失败日志提示端口占用症状docker compose up -d后服务起不来错误信息里出现port is already allocated。排查思路先看是哪个容器占用了端口。docker ps -a netstat -tulpn | grep 端口号解决就两条路要么停掉占用端口的服务要么改.env里的EXPOSE_NGINX_PORT。改端口最省事改动成本最低。注意改了之后还要检查防火墙和云安全组否则外部访问还是不通。4.2 页面能打开但登录后一直转圈这个坑十有八九出在Redis配置上。Dify使用Redis保存会话数据如果REDIS_PASSWORD和compose里实际初始化的Redis密码不一致API服务能起监听但会话数据写不进去前端页面就一直转圈。docker exec -it docker-redis-1 redis-cli -a 你的密码 ping如果返回PONG说明配置没问题如果不通检查.env里的密码跟compose里的REDIS_PASSWORD环境变量是否一致。很多时候你改了.env的密码但忘了改docker-compose.yaml里Redis服务初始化时的默认密码两边就不同步对齐。4.3 模型调用报401或404401基本是API Key不对404多半是OPENAI_API_BASE_URL指向的资源路径不对。我在实际项目中遇到过一种情况接口地址末尾多了一个斜杠或者把/v1路径重复拼接Dify在调用时会自动拼上路径你填多了就404。排查时在服务器上先用curl直接打一遍接口确认密钥和地址本身是通的curl -X POST https://你的接口地址/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的key \ -d {model:gpt-3.5-turbo,messages:[{role:user,content:hello}]}能正常返回再回来看Dify配置。这一步能用最少的变量把问题边界划清楚。4.4 上传的文件在界面上看不到或无法访问如果STORAGE_TYPElocal且换了STORAGE_LOCAL_PATH要注意这个路径是Dify容器内部的路径compose文件里必须把这个路径映射到宿主机。光改.env里的路径容器里没有对应挂载就会出现文件写到容器临时层、容器一重建文件就消失的诡异情况。常规配置下docker-compose里的示例卷映射是- ./volumes/storage:/app/api/storage你改成STORAGE_LOCAL_PATH/app/api/storage然后确保宿主机目录存在。如果还不行多半是映射目录权限不足Dify写不了文件报Permission denied。4.5 .env修改后不生效这是最容易被忽视的docker compose不会自动读取.env的变更。你改完.env必须重建容器docker compose up -d --force-recreate有些服务光重建还不行得把对应容器删掉后再启动docker compose down docker compose up -ddown会连容器带网络一起清掉数据卷默认保留所以不会丢数据。4.6 配置项速查表配置文件名作用常见故障SECRET_KEYsession签名与数据加密改动后session失效DEPLOY_ENV生产/开发模式开发模式下调试接口暴露EXPOSE_NGINX_PORT宿主机访问端口端口冲突、防火墙未开DB_HOST数据库服务名或地址误填localhost无法连接REDIS_PASSWORDRedis认证密码与compose不一致导致登录转圈VECTOR_STORE向量数据库类型修改后需重建全部embeddingSTORAGE_TYPE文件存储类型多实例时本地文件不一致OPENAI_API_BASE_URL模型接口地址多余/缺少路径导致404MAIL_DEFAULT_SEND_EMAIL_ADDRESS发件人地址未配置导致邮件发送失败5. 安全加固与后续扩展建议.env文件本质上是明文保存密钥的地方。我在实际项目中多走了一步把.env加入.gitignore并单独维护一个.env.production用于生产环境。密钥只在部署服务器上保存不进入代码仓库。对需要团队协作的场景密钥分发通过专用的机密管理平台处理而不是在聊天群里传文件。顺着这个思路还有几个可以直接落地的小建议。第一SECRET_KEY、DB_PASSWORD、REDIS_PASSWORD、各API Key全部换掉默认值。这个做起来不麻烦但很多人直接在默认模板上跑一旦暴露到公网攻击者用默认口令就能进去。第二公网部署必须启用HTTPS。.env里若NGINX_ENABLE_CERTBOTtrue则需配域名内网环境建议反代配合证书。不配HTTPSAPI Key在链路上都是明文传输抓包就能看到。第三定期检查升级。Dify迭代快安全修复也多。升级前先备份数据库和存储目录这个动作能让你在出问题时快速回退。第四如果想在.env里配多套模型备用直接把全部平台的Key都填上也没问题。Dify模型供应商的设计是“一个供应商一套凭据”设置好以后应用里随便切换模型来源不必修改应用本身。我个人的倾向是Dify的.env配置不属于“一次配置永久不管”它与Dify的版本绑定。每次升级版本先对比.env.example和当前.env看是否新增了配置项。不少新功能上线一定要对应的配置支持少了某个键界面上功能就是灰色的。把.env当成随版本迭代的活文档来维护上线才能少踩坑。6. 我的一些实操体会玩Dify这一年多.env始终是我遇到故障时最先打开的文件。说句实话Dify的问题一半出在配置另一半出在模型API而配置问题里.env占绝大多数。这就是为什么我愿意花篇幅把每个键都讲清楚。如果你刚接触Dify按我上面的配置顺序走一遍基础环境半小时内能起得来。如果过程中踩到我没列出的问题优先看容器日志docker compose logs -f api日志里每一条报错其实都指向具体的配置项顺着线索一层层排除大多数问题都能在半小时内定位。配置这种东西不怕看不明白就怕不愿意看日志蒙着改越改越乱。最后再说一个细节.env文件里不要加中文注释以外的多余符号别顺手加个引号包裹值。Docker Compose解析环境变量时引号会被当成值的一部分直接导致数据库连接串错误。不少“莫名其妙连不上数据库”的问题源头就是一行多余引号。这些细节没有出现在任何官方文档里都是我一遍遍试错试出来的写在这里希望对后来的人有用。