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.2`envs/`目录：按主题拆分的高级配置

当前仓库中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.example`
vectorstores/	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.example`
security.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_OTEL=true并配置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_URL：API 与前端对外的公网地址，部署到域名时必须填写正确，否则登录回调、分享链接会失效；
SERVER_CONSOLE_API_URL：Web 端服务端请求使用的内部 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：默认PRODUCTION；
LOG_LEVEL、DEBUG、FLASK_DEBUG：日志与调试开关；
MIGRATION_ENABLED：是否在启动时执行数据库迁移，默认true。

Web 服务与 Celery 工作进程

DIFY_BIND_ADDRESS/DIFY_PORT：默认0.0.0.0:5001；
SERVER_WORKER_AMOUNT、SERVER_WORKER_CLASS（默认gevent）、SERVER_WORKER_CONNECTIONS、GUNICORN_TIMEOUT：API 服务的 Gunicorn 工作进程规模与超时；
API_WEBSOCKET_WORKER_AMOUNT/API_WEBSOCKET_WORKER_CLASS/API_WEBSOCKET_WORKER_CONNECTIONS：WebSocket 专用工作进程，默认单进程、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_PASSWORD：Redis 连接参数；
REDIS_KEY_PREFIX：可选的全局命名空间前缀，作用于 Redis 键、Topic、Stream 与 Celery 传输产物，多实例共用一套 Redis 时尤其有用；
CELERY_BROKER_URL：Celery 消息 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_URI）；
WEB_API_CORS_ALLOW_ORIGINS、CONSOLE_CORS_ALLOW_ORIGINS：跨域白名单。

注册与协作行为（shared.env.example）

envs/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 查询这些表即可得到业务维度的统计；
链路追踪层（OpenTelemetry）：Dify 自带 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 Chart	@LeoQuote	早期较流行的 dify Helm Chart
Helm Chart	@BorisPolonsky	独立维护的 dify-helm
Helm Chart	@magicsong	收录于 ai-charts 集合
YAML	@Winson-030	纯 YAML 清单
YAML	@wyy-holding	纯 YAML 清单
YAML	@Zhoneym	明确支持 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 一键部署到云平台

Azure：@nikawang 的 Azure Terraform 方案，可一键将 Dify 部署到 Azure 全球区域；
Google Cloud：@sotazum（DeNA 团队）的 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 Management（DMS）：阿里云 DMS 提供 Dify 邀请制预览的一键部署能力。

3.4 使用 Azure DevOps Pipeline 部署到 AKS

@LeoZhang 提供了面向 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_ENABLED=true时启动日志应显示迁移完成；
向量库连通：修改VECTOR_STORE后创建知识库并索引文档，验证 providers/vdb/ 中对应客户端能正常读写；
升级场景：先运行 dify-env-sync.sh 同步新增变量并人工复核备份目录，再docker compose up -d滚动重启。

整体而言，Dify 的进阶部署遵循“变量入.env与envs/，拓扑才动 Compose/K8s 清单”的分工原则：日常调优止步于环境变量层即可获得绝大多数定制能力，而高可用与云原生交付则交给文档中列出的社区 Helm/Terraform/CDK 生态方案。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Dify 进阶部署指南：自定义配置、Grafana 监控与 Kubernetes/云平台部署实践