Dify 高级部署实践：.env 自定义配置、Grafana 指标监控与 Kubernetes/Terraform/云平台部署方案-二趣网

Dify 高级部署实践：.env 自定义配置、Grafana 指标监控与 Kubernetes/Terraform/云平台部署方案

【免费下载链接】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 仓库中的高级部署文档（docs/sl-SI/ADVANCED_SETUP.md，其英文版见 docs/ADVANCED_SETUP.md），讲解自托管 Dify 时的三类进阶操作：如何在不破坏默认部署的前提下定制docker/.env与 Compose 配置、如何用 Grafana 结合 PostgreSQL 做指标监控，以及如何通过社区 Helm Chart、Terraform、AWS CDK、Sealos 等方案完成 Kubernetes 与云平台的部署。读完本文，你可以独立完成从“改一个环境变量到换向量数据库”再到“上 K8s 高可用架构”的完整进阶部署链路。

自定义配置：以 .env 为中心的三层配置体系

高级部署文档给出的核心操作指令是：需要定制配置时，修改docker/.env文件，参照.env.example中的注释更新对应值；如有必要还可调整docker-compose.yaml（如镜像版本、端口映射、卷挂载）；任何修改完成后，在docker目录下重新执行docker compose up -d。

结合当前仓库，这套“基础默认 + 本地覆盖 + 主题化高级配置”的三层结构在 docker/README.md 中有明确定义：

docker/.env.example：仅包含启动默认部署所必需的变量（essential startup defaults）。文件头部注释明确要求不要向其中添加可选变量（docker/.env.example）；
docker/.env：本地启动值，由.env.example复制而来，承载你的本地修改；
docker/envs/*.env.example：按主题分组的可选高级配置。需要时去掉.example后缀复制为同名文件即可生效。

一个关键的优先级规则：Docker Compose 先读取envs/*.env文件，最后读取.env，因此.env中的值优先级最高（docker/README.md）。这解释了.env.example头部注释“docker/.env的值覆盖docker/envs/*.env”的含义（docker/.env.example）。

docker/envs/ 目录的主题化组织

当前仓库将高级配置拆分为四个子目录，按主题就近管理，避免单个巨型 env 文件：

docker/envs/core-services/：api.env.example、worker.env.example、worker-beat.env.example、web.env.example、sandbox.env.example、plugin-daemon.env.example、dify-agent.env.example等核心服务变量，其中 shared.env.example 是 API/Worker 共享配置（系统开关、Sentry、邮件、工作流限制、SSRF 代理、存储后端、向量库连接等）；
docker/envs/databases/：db-postgres.env.example、db-mysql.env.example、redis.env.example；
docker/envs/vectorstores/：17 种向量库的独立配置模板，包括weaviate、qdrant、milvus、pgvector、opensearch、elasticsearch、chroma、couchbase、oceanbase、oracle、seekdb等；
docker/envs/infrastructure/：nginx、certbot、ssrf-proxy、etcd、minio、milvus-standalone等基础设施变量；
另有根级 middleware.env.example 与 security.env.example。

根 .env.example 中的关键启动变量

.env.example 是 300 行左右的可运行基线，以下是 docker/README.md 归纳的各配置组与典型变量，取值范围与默认值以仓库文件为准：

配置组	关键变量（默认值取自 .env.example）	说明
服务 URL	`CONSOLE_API_URL`、`CONSOLE_WEB_URL`、`SERVICE_API_URL`、`APP_API_URL`、`APP_WEB_URL`、`FILES_URL`、`INTERNAL_FILES_URL`	控制台/API/前端/文件的公网与内网基础地址；`SERVER_CONSOLE_API_URL`保持默认`http://api:5001`，仅在服务需经其他内网地址访问 API 时修改
运行时与安全	`SECRET_KEY`（空）、`INIT_PASSWORD`（空）、`DEPLOY_ENV=PRODUCTION`	`SECRET_KEY`留空时 Dify 会在存储目录自动生成并持久化密钥；建议生产环境显式设置强密钥
日志与 Worker	`LOG_LEVEL=INFO`、`DEBUG=false`、`FLASK_DEBUG=false`、`SERVER_WORKER_AMOUNT=1`、`CELERY_WORKER_AMOUNT=4`、`GUNICORN_TIMEOUT=360`	Gunicorn/Celery 的进程数与超时；`CELERY_AUTO_SCALE`、`CELERY_MAX_WORKERS`/`MIN_WORKERS`用于弹性伸缩
数据库	`DB_TYPE=postgresql`、`DB_USERNAME=postgres`、`DB_PASSWORD=difyai123456`、`DB_HOST=db_postgres`、`SQLALCHEMY_POOL_SIZE=30`	生产环境务必修改默认密码；`SQLALCHEMY_*`控制连接池，`POSTGRES_MAX_CONNECTIONS=200`等调优 PostgreSQL 自身
Redis 与 Celery	`REDIS_HOST=redis`、`REDIS_PORT=6379`、`REDIS_DB=0`、`REDIS_KEY_PREFIX`（空）	`REDIS_KEY_PREFIX`可为 Redis 键、Topic、Stream 及 Celery 传输产物统一加命名空间前缀，便于多实例共存
存储	`STORAGE_TYPE=opendal`、`OPENDAL_SCHEME=fs`、`OPENDAL_FS_ROOT=storage`	默认本地文件系统；S3/Azure Blob/GCS/阿里云 OSS 等对象存储后端从`envs/`对应文件配置
向量数据库	`VECTOR_STORE=weaviate`、`WEAVIATE_ENDPOINT`、`WEAVIATE_API_KEY`	通过`VECTOR_STORE`一键切换，见下文
协作模式	`ENABLE_COLLABORATION_MODE=true`、`COMPOSE_PROFILES`	从`COMPOSE_PROFILES`中移除`collaboration`即可停掉专用 websocket 服务

切换向量数据库：VECTOR_STORE + Compose Profile 联动

向量库切换是高级配置中最高频的操作。默认部署内置 Weaviate，从源码结构看其联动机制是：shared.env.example中的 profile 表达式会根据VECTOR_STORE与DB_TYPE自动激活对应服务（docker/envs/core-services/shared.env.example）：

# docker/envs/core-services/shared.env.example 第 464 行 COMPOSE_PROFILES=${VECTOR_STORE:-weaviate},${DB_TYPE:-postgresql},collaboration

实操步骤（依据 docker/README.md）：

将.env中的VECTOR_STORE改为目标库名（如milvus、pgvector、qdrant、opensearch）；
按需复制对应模板：cp docker/envs/vectorstores/milvus.env.example docker/envs/vectorstores/milvus.env，再在其中填写MILVUS_URI等连接参数；
重新执行docker compose up -d。

当前仓库 docker/envs/vectorstores/ 支持的选项包括chroma、couchbase、elasticsearch、iris、matrixone、milvus、myscale、oceanbase、opengauss、opensearch、oracle、pgvecto-rs、pgvector、qdrant、seekdb、vastbase、weaviate等 17 种，覆盖自建与云托管两类形态。

关于“直接改 docker-compose.yaml”的重要提示

sl-SI 文档提到“可能需要调整 docker-compose.yaml 文件（镜像版本、端口映射、卷挂载等）”。需要结合当前仓库结构补充一点：仓库中的 docker-compose.yaml 是由generate_docker_compose自动生成的，文件头部带有明确警告：

# ================================================================== # WARNING: This file is auto-generated by generate_docker_compose # Do not modify this file directly. Instead, update the .env.example # or docker-compose-template.yaml and regenerate this file. # ==================================================================

因此从源码结构看，更稳妥的定制路径是：镜像版本、环境变量引用等改动落到docker/.env.example或 docker-compose-template.yaml 后重新生成；纯运行期参数（端口暴露、URL、密码等）则优先通过.env/envs/*.env覆盖。端口类需求大多可借助EXPOSE_NGINX_PORT、EXPOSE_NGINX_SSL_PORT等变量完成（见 shared.env.example）。

Dify Docker Compose 服务拓扑（源自仓库 docker 目录的部署结构图）：

版本升级时的环境变量同步

升级到新版本后.env.example可能引入新的必要变量。仓库提供 dify-env-sync.sh（含 Python 版 dify-env-sync.py）做单向同步：.env.example→.env，绝不自动覆盖你已有的自定义值。其行为规范见 docker/README.md：

变更前先把.env备份到env-backup/目录（带时间戳文件名，如.env.backup_20231218_143022）；
只同步.env.example中新增的变量，展示被移除变量供人工复核；

# 首次使用赋予执行权限 chmod +x dify-env-sync.sh # 执行同步 ./dify-env-sync.sh

适用场景：升级 Dify 后维护完整.env、.env.example更新了大量新变量、或.env规模大且高度定制。若从docker-legacy迁移，docker/README.md 还提醒需把对ssrf_proxy/squid.conf、nginx/conf.d/default.conf等文件的旧自定义映射回新的.env体系，并做好数据库与缓存数据迁移。

用 Grafana 监控 Dify 指标

文档的第二部分给出了指标监控方案：在 Grafana 中导入社区仪表盘，使用 Dify 的 PostgreSQL 数据库作为数据源，即可按应用（apps）、租户（tenants）、消息（messages）等粒度监控运行指标。社区仪表盘项目为 @bowenliang123 的dify-grafana-dashboard（仓库外部贡献，以 PostgreSQL 为查询源，因此前提是 Grafana 能连通你的 PostgreSQL 实例）。

从源码结构看，Dify 自身也内置了两条可观测性通道，可与 Grafana 方案互补：

OpenTelemetry 通道：复制docker/envs/core-services/shared.env.example为shared.env，设置ENABLE_OTEL=true并配置OTLP_BASE_ENDPOINT即可接入 OTLP 采集端点，其余OTEL_*参数（采样率、批量导出间隔、队列上限等）在同文件中调节（docker/README.md、shared.env.example）：

变量	默认值	含义
`ENABLE_OTEL`	`false`	是否在 api 中启用 OpenTelemetry 采集器
`OTLP_BASE_ENDPOINT`	`http://localhost:4318`	OTLP 导出端点
`OTEL_EXPORTER_TYPE`	`otlp`	导出器类型
`OTEL_SAMPLING_RATE`	`0.1`	采样率
`OTEL_BATCH_EXPORT_SCHEDULE_DELAY`	`5000`	批量导出调度延迟（ms）
`OTEL_MAX_QUEUE_SIZE`/`OTEL_MAX_EXPORT_BATCH_SIZE`	`2048`/`512`	导出队列与批大小上限
`OTEL_METRIC_EXPORT_INTERVAL`	`60000`	指标导出间隔（ms）

队列监控告警：QUEUE_MONITOR_THRESHOLD=200、QUEUE_MONITOR_ALERT_EMAILS、QUEUE_MONITOR_INTERVAL=30控制 Celery 队列积压阈值与邮件告警（shared.env.example），对应实现见 api/schedule/queue_monitor_task.py。

高可用部署：Kubernetes 与社区 Helm Chart

文档指出：若需要高可用（highly available）配置，社区贡献了 Helm Chart 与 YAML 文件，可把 Dify 部署到 Kubernetes。sl-SI 文档列举的资源（均为仓库外部项目，使用时需自行核对与当前 Dify 版本的兼容性）：

方案	贡献者/项目	说明
Helm Chart	@LeoQuote（douban/charts 中的 dify）	社区 Helm Chart
Helm Chart	@BorisPolonsky（dify-helm）	社区 Helm Chart
YAML 文件	@Winson-030（dify-kubernetes）	原生 K8s YAML
YAML 文件	@wyy-holding（dify-k8s）	原生 K8s YAML
YAML 文件	@Zhoneym（DifyAI-Kubernetes）	标注支持 Dify v1.6.0

云平台一键部署：Terraform 与 AWS CDK

Terraform 部署

文档提供了两条 Terraform 路径，用于把 Dify“一键”部署到云平台：

Azure Global：@nikawang 的dify-azure-terraform；
Google Cloud：@sotazum（DeNA 组织）的dify-google-cloud-terraform。

AWS CDK 部署

通过 AWS CDK（Cloud Development Kit）部署到 AWS，文档列出了两种架构路线：

EKS 路线：@KevinZhao 的 AWS 示例方案（solution-for-deploying-dify-on-aws）；
ECS 路线：@tmokmss 的 dify-self-hosted-on-aws。

阿里云方案

Alibaba Cloud Computing Nest（计算巢）：通过计算巢服务实例页面一键创建 Dify 社区版实例；
Alibaba Cloud Data Management（DMS）：官方提供的 Dify 邀请制预览（invitational preview）一键部署入口。

其他托管路线

AKS + Azure DevOps Pipeline：@LeoZhang 贡献的 Helm Chart，可经 Azure DevOps Pipeline 一键部署到 AKS（Azure Kubernetes Service）；
Sealos：通过 Sealos App Store 一键部署 Dify。

适用前提与小结

所有docker compose操作的前提是系统已安装 Docker 且Docker Compose ≥ v2.24.0（docker/README.md）；
修改配置后统一在docker目录执行docker compose up -d生效；.env覆盖envs/*.env，envs/内先加载、.env最后加载；
docker-compose.yaml属自动生成产物，定制请走.env.example/docker-compose-template.yaml再重新生成（generate_docker_compose）；
K8s、Terraform、CDK、Sealos 等均为仓库外部社区/云厂商资源，仓库只记录其存在与入口，版本适配性需在使用前自行验证；
升级 Dify 后建议先跑dify-env-sync.sh对齐新增必要变量，再重启 Compose 栈。

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

企业官网建设流程全解析