Dify 进阶部署指南:自定义配置、Grafana 监控与 Kubernetes/云平台部署实践 Dify 进阶部署指南自定义配置、Grafana 监控与 Kubernetes/云平台部署实践【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify本文基于 Dify 仓库的进阶部署文档系统讲解 Dify 自托管场景下的三大进阶主题如何通过.env与envs/目录体系深度自定义部署配置、如何以 PostgreSQL 为数据源接入 Grafana 做指标监控、以及面向高可用与云原生场景的 Kubernetes、Terraform、AWS CDK 等部署路径。读完本文你能够独立完成 Dify 的自定义参数调优并为自己所在的云环境选择正确的生产级部署方案。一、自定义配置.env、.env.example与envs/目录体系进阶部署文档的第一要务是自定义配置当你需要修改 Dify 的部署行为时应参考 .env.example 文件并在你自己的.env文件中更新相应变量值此外根据你的环境与需求你可能还需要调整docker-compose.yaml文件例如修改镜像版本、重新映射端口、或挂载不同的数据卷。关键操作原则任何变更完成后都必须重新执行docker-compose up -d在docker目录下写作docker compose up -d使配置生效。完整的环境变量清单可参考 Dify 官方文档的 environments 页面此处不附外链以仓库内文件为准。1.1 三层配置文件的设计仓库 Docker 部署说明 对这套配置体系有更完整的定义它实际上把配置分成了三层docker/.env.example包含启动默认部署所必需的变量essential startup defaults。文件头部注释明确写着“只包含服务启动所需的变量不要把可选变量加进来”docker/.env本地启动文件。默认部署时直接从.env.example复制而来承载你的本地自定义值docker/envs/*.env.example按主题theme分组的可选高级配置。一个容易踩坑的细节Docker Compose 会先读取envs/*.env文件最后读取.env因此.env中的值优先级最高见 docker/.env.example 头部注释与 docker/README.md。1.2envs/目录按主题拆分的高级配置当前仓库中docker/envs/下实际存在以下分组可用文件管理器直接查看目录/文件内容core-services/api.env.example、worker.env.example、worker-beat.env.example、web.env.example、dify-agent.env.example、plugin-daemon.env.example、sandbox.env.example、local-sandbox.env.example、shared.env.example等核心服务配置databases/db-postgres.env.example、db-mysql.env.example通过DB_TYPE切换与redis.env.examplevectorstores/17 种向量库的独立配置weaviate、milvus、qdrant、pgvector、opensearch、elasticsearch、chroma、couchbase、oracle、oceanbase、seekdb等infrastructure/nginx.env.example、ssrf-proxy.env.example、minio.env.example、certbot.env.example、etcd.env.example、milvus-standalone.env.examplesecurity.env.example各外部服务的密钥与 API Key向量库 Token、SMTP/邮件服务密钥、SLS 日志密钥等middleware.env.example仅用于开发场景的中继件环境配置使用方式统一把需要的*.env.example复制为去掉.example后缀的同名文件放在同目录Compose 即会加载它。例如启用 OpenTelemetry 的推荐步骤是引自 docker/README.md将envs/core-services/shared.env.example复制为envs/core-services/shared.env设置ENABLE_OTELtrue并配置OTLP_BASE_ENDPOINT按需调优同一文件中的其他OTEL_*参数。1.3 根.env.example中的关键参数详解以下是 docker/.env.example当前共 300 行中值得重点关注、且对生产部署影响最大的参数按功能分组服务 URL 类CONSOLE_API_URL/CONSOLE_WEB_URL/SERVICE_API_URL/APP_API_URL/APP_WEB_URLAPI 与前端对外的公网地址部署到域名时必须填写正确否则登录回调、分享链接会失效SERVER_CONSOLE_API_URLWeb 端服务端请求使用的内部 API 地址标准 Compose 部署应保持默认http://api:5001仅当服务需通过其他内部地址访问 API 时才修改FILES_URL/INTERNAL_FILES_URL文件下载与预览的公网/内部基地址ENDPOINT_URL_TEMPLATE、NEXT_PUBLIC_SOCKET_URL、TRIGGER_URL触发器端点模板与 WebSocket 地址。运行时与安全SECRET_KEY用于签发会话、JWT 与文件 URL 的密钥。留空时 Dify 会自动在存储目录中生成并持久化一个密钥无需手动设置INIT_PASSWORD初始化密码DEPLOY_ENV默认PRODUCTIONLOG_LEVEL、DEBUG、FLASK_DEBUG日志与调试开关MIGRATION_ENABLED是否在启动时执行数据库迁移默认true。Web 服务与 Celery 工作进程DIFY_BIND_ADDRESS/DIFY_PORT默认0.0.0.0:5001SERVER_WORKER_AMOUNT、SERVER_WORKER_CLASS默认gevent、SERVER_WORKER_CONNECTIONS、GUNICORN_TIMEOUTAPI 服务的 Gunicorn 工作进程规模与超时API_WEBSOCKET_WORKER_AMOUNT/API_WEBSOCKET_WORKER_CLASS/API_WEBSOCKET_WORKER_CONNECTIONSWebSocket 专用工作进程默认单进程、1000 连接CELERY_WORKER_AMOUNT默认 4、CELERY_WORKER_CLASS、CELERY_AUTO_SCALE、CELERY_MAX_WORKERS/CELERY_MIN_WORKERS后台任务 Worker 规模COMPOSE_WORKER_HEALTHCHECK_INTERVAL/COMPOSE_WORKER_HEALTHCHECK_TIMEOUT控制 Compose 健康检查节奏。数据层DB_TYPE默认postgresql、DB_USERNAME、DB_PASSWORD、DB_HOST、DB_PORT、DB_DATABASE关系数据库连接参数REDIS_HOST/REDIS_PORT/REDIS_PASSWORDRedis 连接参数REDIS_KEY_PREFIX可选的全局命名空间前缀作用于 Redis 键、Topic、Stream 与 Celery 传输产物多实例共用一套 Redis 时尤其有用CELERY_BROKER_URLCelery 消息 broker。存储与向量库STORAGE_TYPE、OPENDAL_SCHEME、OPENDAL_FS_ROOT默认本地文件存储S3、Azure Blob、GCS 等可选后端通过envs/下对应文件配置VECTOR_STORE向量数据库类型如weaviate、milvus、opensearch。切换向量库时除修改该变量外还应复制 docker/envs/vectorstores/ 中对应数据库的.env.example并填入端点、端口与认证信息如WEAVIATE_ENDPOINT、MILVUS_URIWEB_API_CORS_ALLOW_ORIGINS、CONSOLE_CORS_ALLOW_ORIGINS跨域白名单。注册与协作行为shared.env.exampleenvs/core-services/shared.env还控制着一批系统特性开关例如MARKETPLACE_ENABLED、ENABLE_EMAIL_CODE_LOGIN、ENABLE_EMAIL_PASSWORD_LOGIN、ENABLE_SOCIAL_OAUTH_LOGIN、ALLOW_REGISTER、ALLOW_CREATE_WORKSPACE、ENABLE_COLLABORATION_MODE配合 Compose profilecollaboration控制独立 WebSocket 服务是否启用。1.4 升级时用dify-env-sync.sh安全同步新变量Dify 版本升级时.env.example或envs/下可能新增变量。如果你维护了一份从.env.example复制的完整.env仓库提供了可选的一向同步工具见 docker/README.md 与 dify-env-sync.sh# 授予执行权限首次 chmod x dify-env-sync.sh # 执行同步 ./dify-env-sync.sh其行为边界很明确单向从.env.example同步到.env同步前先把当前.env备份到env-backup/目录带时间戳文件名只追加新变量、绝不覆盖你已有的自定义值并展示.env.example中已被移除的变量供人工复核。适用时机升级到引入新变量的新版本、或.env文件较大且高度定制时。1.5 修改 Compose 文件本身当环境变量不足以表达你的需求时如替换镜像版本、调整端口映射、挂载卷才需要直接修改 docker/docker-compose.yaml。注意仓库还提供了两个补充文件docker-compose.middleware.yaml仅启动数据库/缓存/Weaviate 等中间件用于开发 Dify 本体时使用需配合middleware.env与docker-compose.e2b.yaml。修改后同样以docker compose up -d应用。二、使用 Grafana 做指标监控进阶部署文档给出的监控方案是将 Dify 的 PostgreSQL 数据库作为 Grafana 的数据源导入社区 Dashboard即可在应用apps、租户tenants、消息messages等粒度上监控指标。社区贡献者 bowenliang123 维护了一个现成的 Dify Grafana Dashboard 仓库可直接导入使用该 Dashboard 以 PostgreSQL 为数据源无需额外埋点即可看到业务层指标。从仓库源码结构看这套方案与 Dify 的可观测性设计是互补的两层业务指标层Grafana PostgreSQL应用、租户、消息等实体及其运行记录都持久化在 PostgreSQL 中Grafana 通过 SQL 查询这些表即可得到业务维度的统计链路追踪层OpenTelemetryDify 自带 OTEL 支持配置项即上文提到的ENABLE_OTEL与OTLP_BASE_ENDPOINT相关实现集中在 api/extensions/otel/ 目录配置入口在 docker/envs/core-services/shared.env.example。如果你已有 Jaeger/Tempo 等后端可与 Grafana 组合成“业务指标 分布式追踪”的完整可观测栈。实操步骤概括在 Grafana 中新增数据源类型选 PostgreSQL主机指向 Dify 的db_postgres或你的外部 PostgreSQL账号使用.env中的DB_USERNAME/DB_PASSWORD库名为DB_DATABASE默认dify下载社区 Dashboard 的 JSON 后导入按面板提示选择变量租户/应用即可下钻查看。三、Kubernetes 部署面向高可用的生产路径如果你需要高可用HA部署官方仓库的 Docker Compose 方案不再是最佳载体此时应选择社区维护的 Helm Chart 或 YAML 清单。进阶部署文档列举的社区项目如下均为社区贡献、非主仓库的一部分使用前请自行评估其维护状态与版本兼容性类型维护者说明Helm ChartLeoQuote早期较流行的 dify Helm ChartHelm ChartBorisPolonsky独立维护的 dify-helmHelm Chartmagicsong收录于 ai-charts 集合YAMLWinson-030纯 YAML 清单YAMLwyy-holding纯 YAML 清单YAMLZhoneym明确支持 Dify v1.6.0 的 YAML 方案选型建议优先选择明确声明支持你目标 Dify 版本的方案。移植到 K8s 时要特别留意 Compose 方案中的几个“隐藏依赖”docker/nginx/ 网关模板、docker/ssrf_proxy/出站请求隔离代理、docker/certbot/HTTPS 证书自动续期以及COMPOSE_PROFILES机制控制的可选服务如协作模式 WebSocket 服务这些组件在 K8s 中都需要以对应资源Ingress、Sidecar、Job 等复刻而不是简单忽略。3.1 使用 Terraform 一键部署到云平台Azurenikawang 的 Azure Terraform 方案可一键将 Dify 部署到 Azure 全球区域Google CloudsotazumDeNA 团队的 GCP Terraform 方案。Terraform 的价值在于把 PostgreSQL、Redis、向量库、对象存储、计算节点与网络策略一并纳入 IaC 管理适合需要审计与可重复交付的团队。3.2 使用 AWS CDK 部署EKS 路线KevinZhao 基于 AWS 官方样例aws-samples/solution-for-deploying-dify-on-aws的 EKS 部署方案ECS 路线tmokmss 基于 aws-samples/dify-self-hosted-on-aws 的 ECS 部署方案。CDK 用 TypeScript/Python 等高级语言定义云基础设施与 Terraform 相比更适合已有 CDK 工程规范、希望把 Dify 纳入既有 IaC 代码库的团队。3.3 阿里云方案Alibaba Cloud Computing Nest计算巢通过计算巢服务市场可一键创建 Dify 社区版实例Alibaba Cloud Data ManagementDMS阿里云 DMS 提供 Dify 邀请制预览的一键部署能力。3.4 使用 Azure DevOps Pipeline 部署到 AKSLeoZhang 提供了面向 AKS 的 Helm Chart 与 Azure DevOps Pipeline 集成可在 Azure 侧实现“代码合入 → 构建镜像 → 部署 AKS”的完整一键 CI/CD 流程。3.5 使用 Sealos 部署Sealos App Store 收录了 Dify 应用支持一键拉起含 Kubernetes 与全部依赖的 Dify 集群适合快速验证生产拓扑。四、落地后的自检清单无论采用上述哪条路径变更后都建议按以下顺序验证对应仓库可查的依据配置生效在docker目录执行docker compose ps确认所有服务healthy确认.env中修改的变量已出现在容器环境里docker compose exec api printenv | grep 变量名数据库迁移MIGRATION_ENABLEDtrue时启动日志应显示迁移完成向量库连通修改VECTOR_STORE后创建知识库并索引文档验证 providers/vdb/ 中对应客户端能正常读写升级场景先运行 dify-env-sync.sh 同步新增变量并人工复核备份目录再docker compose up -d滚动重启。整体而言Dify 的进阶部署遵循“变量入.env与envs/拓扑才动 Compose/K8s 清单”的分工原则日常调优止步于环境变量层即可获得绝大多数定制能力而高可用与云原生交付则交给文档中列出的社区 Helm/Terraform/CDK 生态方案。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考