Dify 自托管进阶部署：环境变量定制、Grafana 监控与 Kubernetes / 云原生落地

本文基于 Dify 仓库的 docs/ADVANCED_SETUP.md 展开，覆盖自托管部署中的三类进阶主题：如何定制 Docker Compose 的环境变量配置（.env 与 docker/envs/ 两级配置的加载优先级）、如何用 Grafana 以 PostgreSQL 为数据源构建应用级监控看板，以及如何通过 Helm Chart、Terraform、AWS CDK 等工具把 Dify 部署到 Kubernetes 与各云平台。读完本文，你将掌握从"改配置重启"到"生产级多副本、上云"的完整进阶路径，并能对照仓库源码理解每一项配置的实际作用。

一、定制配置：修改 docker/.env 后重启

进阶部署的第一站是配置定制。按照 docs/ADVANCED_SETUP.md 的说明：

如果需要定制配置，请编辑 docker/.env。启动所需的基础默认值位于 docker/.env.example，可选的进阶变量按主题拆分在 docker/envs/ 目录下。修改任何内容后，从 docker 目录重新执行 docker compose up -d。

这条流程在仓库中的实际结构是这样的：

cd docker
cp .env.example .env        # 首次部署：复制基础模板
# 按需复制进阶配置（去掉 .example 后缀）：
# cp envs/core-services/shared.env.example envs/core-services/shared.env
docker compose up -d         # 使配置生效

.env.example 的文件头注释明确了两级配置的分工（见 docker/.env.example）：

# Essential defaults for Docker Compose deployments.
# Only include variables required for services to start.
# Do not add optional variables to this file.
#
# For a default deployment, copy this file to .env and run:
#   docker compose up -d
#
# Optional and provider-specific variables live under docker/envs/.
# Copy an optional *.env.example file beside itself without the
# .example suffix when you need those advanced settings.
# Values in docker/.env take precedence over docker/envs/*.env files.

也就是说，仓库坚持一个原则：根级 .env 只放启动必需的变量，可选的、供应商特定的、服务特定的变量一律下沉到 docker/envs/ 按主题归档。这一设计在 docker/README.md 的 "Overview of .env, .env.example, and envs/" 一节中被再次强调：不要把可选或供应商相关变量塞进根级 .env.example，而应放进对应的 envs/*.env.example。

1.1 docker/envs/ 的主题化目录结构

当前仓库中 docker/envs/ 实际包含四个主题分组：

目录	内容	典型文件
core-services/	API、Worker、Web、Plugin Daemon、Sandbox 等核心服务配置	shared.env.example、api.env.example、worker.env.example、web.env.example、plugin-daemon.env.example
databases/	数据库与缓存	db-postgres.env.example、db-mysql.env.example、redis.env.example
vectorstores/	18 种向量数据库各自一份配置	milvus.env.example、qdrant.env.example、pgvector.env.example 等
infrastructure/	Nginx、SSRF 代理、etcd、MinIO、Certbot 等基础设施	nginx.env.example、ssrf-proxy.env.example

此外还有两份不属于子目录的主题文件：envs/security.env.example 与 envs/middleware.env.example（后者用于开发场景的中间件组合）。

1.2 源码层面的加载顺序与优先级

从源码结构看，配置优先级并非口头约定，而是直接写死在 Compose 文件中。docker/docker-compose.yaml 顶部用 YAML anchor（x-shared-api-worker-config）统一定义了 env_file 列表，其中每个 envs/ 文件都标注 required: false（文件不存在时跳过），而根级 .env 是列表中的最后一项：

# docker/docker-compose.yaml（节选）
x-shared-api-worker-config: &shared-api-worker-config
  env_file:
    - path: ./envs/core-services/shared.env
      required: false
    - path: ./envs/core-services/api.env
      required: false
    - path: ./envs/security.env
      required: false
    - path: ./envs/databases/db-postgres.env
      required: false
    # ... 各向量库、基础设施配置（共 20 余项，均 required: false）
    - ./.env

Docker Compose 的 env_file 语义是列表中后出现的文件覆盖先出现的，因此 .env 的取值优先级最高——这与 docker/README.md "Docker Compose reads envs/*.env files when present, then reads .env last so values in .env take precedence" 的说明完全一致。

需要注意，docker-compose.yaml 文件头有明确警告：

# 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-compose.yaml，配置入口应当始终是 .env 与 envs/ 下的文件，Compose 文件由仓库根目录下的 docker/generate_docker_compose 工具基于 docker-compose-template.yaml 生成。

1.3 进阶场景常用的关键变量

以下是从 docker/.env.example 中整理、对生产定制最有价值的一组变量（含默认值与用途），修改后执行 docker compose up -d 即可生效：

服务地址与入口

变量	默认值	说明
CONSOLE_API_URL / CONSOLE_WEB_URL	空	控制台 API / Web 的对外 URL
SERVICE_API_URL / APP_API_URL / APP_WEB_URL	空	服务 API 与应用侧 API/Web URL
SERVER_CONSOLE_API_URL	http://api:5001	Web 服务端请求使用的内部 API 地址，标准 Compose 部署保持默认
FILES_URL / INTERNAL_FILES_URL	空	文件下载/预览的公网与内网基址
TRIGGER_URL	http://localhost	触发器回调地址

运行时与并发

变量	默认值	说明
SECRET_KEY	空（自动生成）	会话/JWT/文件 URL 签名密钥；留空时 Dify 会在存储目录生成持久密钥
LOG_LEVEL / DEBUG / FLASK_DEBUG	INFO / false / false	日志级别与调试开关
SERVER_WORKER_AMOUNT / SERVER_WORKER_CLASS	1 / gevent	Gunicorn 工作进程数与类型
CELERY_WORKER_AMOUNT	4	Celery 并发 worker 数；CELERY_AUTO_SCALE=true 时可配合 CELERY_MAX_WORKERS / CELERY_MIN_WORKERS 弹性伸缩
GUNICORN_TIMEOUT	360	Gunicorn 请求超时（秒）

数据库与缓存

变量	默认值	说明
DB_TYPE	postgresql	postgresql 或 mysql，同时决定 Compose profile（见下文 1.4）
DB_USERNAME / DB_PASSWORD / DB_HOST / DB_PORT / DB_DATABASE	postgres / difyai123456 / db_postgres / 5432 / dify	PostgreSQL 连接信息
SQLALCHEMY_POOL_SIZE / SQLALCHEMY_MAX_OVERFLOW	30 / 10	SQLAlchemy 连接池大小
REDIS_HOST / REDIS_PASSWORD / REDIS_DB	redis / difyai123456 / 0	Redis 连接信息；REDIS_KEY_PREFIX 可为 Redis 键、topic、流统一加命名空间前缀
CELERY_BROKER_URL	redis://:difyai123456@redis:6379/1	Celery 消息代理

存储与向量库

变量	默认值	说明
STORAGE_TYPE / OPENDAL_SCHEME / OPENDAL_FS_ROOT	opendal / fs / storage	默认本地文件存储；切换到 S3、Azure Blob 等后端时使用 envs/ 中对应文件
VECTOR_STORE	weaviate	向量库类型，可切换为 milvus、qdrant、pgvector、opensearch 等
WEAVIATE_ENDPOINT / WEAVIATE_API_KEY	http://weaviate:8080 / 内置开发密钥	默认 Weaviate 连接配置

安全相关（生产必改）

变量	默认值	说明
WEB_API_CORS_ALLOW_ORIGINS / CONSOLE_CORS_ALLOW_ORIGINS	*	跨域白名单，生产建议收紧
SSRF_PROXY_ALLOW_PRIVATE_IPS	空（拒绝私网）	需要让 HTTP 请求节点/工具访问内网地址时，填入允许的 CIDR 段，如 172.21.0.0/16,10.0.0.0/8
DIFY_AGENT_API_TOKEN / DIFY_AGENT_SERVER_SECRET_KEY	开发默认值	文件内注释明确提示"生产环境请替换"，可用 python -c 'import secrets; print(secrets.token_urlsafe(32))' 生成
PLUGIN_DAEMON_KEY / PLUGIN_DIFY_INNER_API_KEY	内置开发密钥	插件守护进程与 API 内部通信密钥

完整的可选变量还有登录方式（ENABLE_EMAIL_CODE_LOGIN、ENABLE_SOCIAL_OAUTH_LOGIN）、文件上传限制（UPLOAD_FILE_SIZE_LIMIT 等）、工作流限额（WORKFLOW_MAX_EXECUTION_TIME、WORKFLOW_MAX_EXECUTION_STEPS）、插件市场开关（MARKETPLACE_ENABLED）等，均按主题分散在 envs/core-services/shared.env.example 等文件中。

1.4 用 VECTOR_STORE 与 DB_TYPE 切换服务组合

.env.example 的最后一行揭示了服务组合的自动切换机制：

COMPOSE_PROFILES=${VECTOR_STORE:-weaviate},${DB_TYPE:-postgresql},collaboration

从源码结构看，docker-compose.yaml 中每个可选服务（各向量库、db_mysql、api_websocket、certbot 等）都声明了自己的 profiles，只有出现在 COMPOSE_PROFILES 中的服务才会随 docker compose up -d 启动。例如默认部署实际拉起的向量库与数据库服务就是 weaviate 与 db_postgres；改成 VECTOR_STORE=milvus、DB_TYPE=mysql 后，启动的就是 qdrant 之外的另一组服务。collaboration profile 控制专用的 websocket 服务（api_websocket），如需停用可从 COMPOSE_PROFILES 中移除该值。

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

当你长期维护一份从 .env.example 复制的完整 .env，升级 Dify 后可以用仓库提供的单向同步脚本 docker/dify-env-sync.sh（对应实现为 docker/dify-env-sync.py）把新增变量安全合并进 .env。根据 docker/README.md 的说明：

• 同步是单向的：只从 .env.example 到 .env，.env 中已有值绝不会被自动覆盖；
• 执行前会自动把当前 .env 备份到 env-backup/ 目录（带时间戳文件名）；
• 会展示差异以及从 .env.example 中被移除的变量，供人工审查。

chmod +x dify-env-sync.sh   # 首次使用
./dify-env-sync.sh

适用时机：升级到引入新变量的版本后、或 .env 已经积累大量自定义值时。

二、用 Grafana 监控指标

docs/ADVANCED_SETUP.md 给出的监控方案是：向 Grafana 导入 Dify 官方社区看板，以 Dify 的 PostgreSQL 数据库为数据源，从而以应用（apps）、租户（tenants）、消息（messages）等粒度监控运行指标：

Import the dashboard to Grafana, using Dify's PostgreSQL database as data source, to monitor metrics in granularity of apps, tenants, messages, and more.

官方看板为社区贡献项目 dify-grafana-dashboard（作者 @bowenliang123），仓库文档原文附有该项目链接，可在其项目主页获取看板 JSON 后导入 Grafana。

由于数据源是业务数据库本身，这套方案对自托管部署非常友好：不需要在 API 侧额外暴露 Prometheus 端点，只需让 Grafana 的数据源指向 docker/.env.example 中 DB_HOST/DB_PORT/DB_DATABASE 对应的 PostgreSQL（默认 db_postgres:5432/dify），即可直接查询 apps、tenants、messages 等表统计活跃度与用量。使用前提与限制是：

• 该路径依赖关系型数据库中的业务数据，反映的是"用量/活跃度"类指标；
• 进程级的 trace、metric（如请求延迟、队列深度）请走 OpenTelemetry 路线——即 envs/core-services/shared.env.example 中的 ENABLE_OTEL=true 加 OTLP_BASE_ENDPOINT（默认 http://localhost:4318），配合 OTEL_SAMPLING_RATE、OTEL_BATCH_EXPORT_SCHEDULE_DELAY 等调参项接入你自己的 Collector；
• QUEUE_MONITOR_THRESHOLD（默认 200）与 QUEUE_MONITOR_ALERT_EMAILS 提供了队列积压邮件告警，可视为监控的补充手段。

三、部署到 Kubernetes

若需要高可用部署，docs/ADVANCED_SETUP.md 指出社区贡献了多个 Helm Chart 与 YAML 方案，可将 Dify 部署到 Kubernetes。原文列出的社区资源（链接见原文档）：

Helm Chart

• @LeoQuote（douban/charts）的 Dify Chart
• @BorisPolonsky 的 dify-helm
• @magicsong 的 ai-charts

K8s YAML

• @Winson-030 的 dify-kubernetes
• @wyy-holding 的 dify-k8s
• @Zhoneym 的 DifyAI-Kubernetes（支持 Dify v1.6.0 的较新方案）

选型建议（从仓库结构推断）：Docker Compose 中通过 COMPOSE_PROFILES 切换向量库/数据库的做法，在 K8s 上等价于"部署时选择一组 StatefulSet/Deployment"，因此社区 Chart 通常也会把 VECTOR_STORE、DB_TYPE 抽象成 values 选项；选用时应确认 Chart 支持的 Dify 版本与当前仓库版本匹配（如 @Zhoneym 方案明确标注支持 v1.6.0），并复用本文第一节整理的变量语义来填写 values。

3.1 Terraform 一键上云

同一文档还收录了 Terraform 部署方案：

• Azure：@nikawang 的 dify-azure-terraform（Azure 全局区域）
• Google Cloud：@sotazum（DeNA）的 dify-google-cloud-terraform

两者均以"一条命令拉起整套依赖（含向量库、对象存储、数据库）"为目标，适合把 Dify 作为 IaC 的一部分纳入团队云资源管理。

3.2 AWS：CDK 部署

• @KevinZhao 的 AWS CDK 方案（基于 EKS）
• @tmokmss 的 AWS CDK 方案（基于 ECS）

两者同为 AWS CDK 实现，差异在于运行时是 Kubernetes（EKS）还是托管容器（ECS），可按团队既有运维栈选择。

3.3 阿里云与 Azure 托管方案

• 阿里云计算巢（Computing Nest）：通过计算巢服务目录一键部署 Dify 社区版；
• 阿里云数据管理（DMS）：通过阿里云 DMS 一键部署 Dify；
• AKS + Azure DevOps Pipeline：@LeoZhang 提供基于 Helm Chart 的 Azure DevOps 流水线，一键部署 Dify 到 AKS。

四、小结与仓库入口索引

进阶部署的主线可以概括为三层：

1. 配置层——一切定制从 docker/.env 出发，按主题把可选变量下沉到 docker/envs/，用 VECTOR_STORE、DB_TYPE 控制 COMPOSE_PROFILES 切换服务组合，改完 docker compose up -d 生效；升级时用 docker/dify-env-sync.sh 做单向变量同步。
2. 可观测层——业务指标用 Grafana + PostgreSQL 看板；进程级指标用 ENABLE_OTEL 走 OTLP 通道；队列积压用 QUEUE_MONITOR_* 变量兜底。
3. 平台层——K8s 用户选社区 Helm Chart / YAML，云用户选 Terraform / CDK / 计算巢 / 计算巢 DMS / AKS Pipeline，均为社区与云厂商贡献方案，注意核对版本兼容性。

继续深入的仓库入口：

• docker/README.md：Compose 部署、中间件开发模式（docker-compose.middleware.yaml）与迁移说明
• docker/.env.example：启动必需变量全集
• docker/envs/：按主题拆分的进阶配置（core-services / databases / vectorstores / infrastructure）
• docker/docker-compose.yaml：由模板自动生成的最终 Compose 文件（只读参考，勿手改）
• docs/ADVANCED_SETUP.md：本文的原始文档