环境变量 - Dify Docs

本文档由 AI 自动翻译。如有任何不准确之处，请参考英文原版。

配置文件

Docker Compose 从三类文件中读取 Dify 的设置。

docker/.env：作用于整个部署的设置（如 Compose profile 和对外发布的端口）以及共享凭据。新部署从 docker/.env.example 复制创建此文件。
.defaults 文件（位于 docker/envs/ 下）：自带的默认值，由各服务自动加载。不要修改这些文件：每次发布新版本都会更新它们。
本地 .env 文件（位于 docker/envs/ 下）：你的覆盖值，作用于加载这些文件的服务。Git 会忽略这些文件，因此检出新版本后，它们仍保留在原处。

从源码运行 Dify 时，变量改在 api/.env 和 web/.env.local 中设置，中间件容器的变量则写在 docker/middleware.env 中。

设置变量

找到对应文件

大多数变量写在 docker/envs/ 下的本地 .env 文件中，以下两类则写在 docker/.env 中：

Compose 在加载任何服务文件之前读取的设置，如 COMPOSE_PROFILES 和 VECTOR_STORE。
共享凭据，确保用到同一凭据的所有服务拿到相同的值：
- PLUGIN_DAEMON_KEY 和 PLUGIN_DIFY_INNER_API_KEY：分别使用不同的强密钥。
- DIFY_AGENT_API_TOKEN 和 DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN：分别使用不同的强密钥。
- SANDBOX_API_KEY 和 CODE_EXECUTION_API_KEY：设为相同的值。两者不一致时，代码执行节点和模板转换节点会失败并返回 HTTP 401。

其他变量先在 docker/envs/ 中搜索变量名，再按搜索结果处理：

搜到一个 .defaults 文件：编辑其第一条注释中写明的本地文件。该文件尚不存在时，先将 .defaults 文件复制为该文件名。
搜到多个 .defaults 文件：编辑所有用到该变量的服务都会加载的那个本地文件，否则各服务拿到的值会不一致。
搜到 .env.example 模板（如 envs/security.env.example）：将其复制为去掉 .example 后缀的同名文件。跳过 envs/middleware.env.example，只有源码开发使用的独立中间件栈才会读取它。

docker/.env 和本地文件设置了同一变量时，以 docker/.env 中的值为准，例外情况详见优先级。

修改设置值

在本地文件中修改需要的值；可选设置只为要用的那几项取消注释。

保留 Container variable mappings 下的各行不变。每一行负责把你编辑的设置传给容器实际读取的变量名。

如需恢复自带的默认值，删除该行或将其注释掉，不要只把值清空。CELERY_WORKER_AMOUNT= 这样的空赋值仍会用空值覆盖默认值；写在 docker/.env 中的空赋值还会让本地文件中的值失效。

应用修改

在 dify/docker 中验证配置，并重建受影响的容器：

docker compose config --quiet
docker compose up -d

要用 up -d，不能用 docker compose restart：restart 会沿用容器原有的环境变量。运行 docker compose config 可查看解析后的值，其输出包含密钥，需妥善保管。完整示例详见自定义，示例最后会检查运行中的服务。如需更新到新版本，同时不丢失本地文件、密钥和数据，按升级操作。

优先级

同一变量在多处设置时，服务最终使用哪个值，取决于该服务是否加载 docker/.env：

加载 docker/.env 的服务
其他服务

API、WebSocket API、Worker、Beat、Web、代码执行沙箱、插件守护进程和 Agent 后端按以下顺序查找，采用第一个找到的值：

docker/.env
该服务的本地 .env 文件
该服务的 .defaults 文件
程序内置的默认值

.defaults 文件中 Container variable mappings 注释下的变量，始终从另一项设置取值。直接设置它们不会生效，写在 docker/.env 中也一样；需要修改时，改它们取值的那项设置。

Nginx、数据库、Redis、向量数据库及其他辅助服务不加载 docker/.env。有本地 .env 文件的服务，变量就写在该文件中。只有 .defaults 文件从 docker/.env 读取的设置例外：docker/.env 中的值会传给服务，并覆盖本地文件中的值。

如果某个值不来自上述任何文件，再检查以下两处：

运行 Compose 的 Shell 中导出的变量：对于 ${...} 形式的值，它优先于 docker/.env
Compose 文件中该服务的 environment: 条目（如 MODE: api）：它优先于所有环境变量文件

通用变量

这些 URL 变量用于配置 Dify 各服务的访问地址。对于 Nginx 后的单域名部署（默认 Docker Compose 配置），这些变量可以留空，系统会从请求中自动检测。当使用自定义域名、多域名部署或反向代理时，需要配置这些变量。

CONSOLE_API_URL

默认值：（空） Dify 后端 API 的公开 URL。如果你使用 OAuth 登录（GitHub、Google）、Notion 集成或任何需要 OAuth 的插件，请设置此变量；这些功能需要绝对回调 URL 才能在授权后将用户重定向回来。此变量还决定是否使用安全（仅 HTTPS）Cookie。示例：https://api.console.dify.ai

SERVER_CONSOLE_API_URL

默认值：http://api:5001 Web 前端容器在服务端发起请求时所使用的 Console API 地址，经由 Docker 内部网络直接访问，而非通过你的公网域名。此变量仅由 Web 前端容器使用，不影响 Python 后端；浏览器端请求仍使用 CONSOLE_API_URL。若留空，则回退到 CONSOLE_API_URL。仅当 API 服务的内部访问地址不同时才需修改。

CONSOLE_WEB_URL

默认值：（空） Dify 控制台前端的公开 URL。用于构建所有系统邮件（邀请、密码重置、通知）中的链接，以及 OAuth 登录后将用户重定向回控制台。如果未设置 CONSOLE_CORS_ALLOW_ORIGINS，此变量也作为默认的 CORS 允许来源。如果为空，邮件链接将无法正常工作；即使在单域名部署中，使用邮件功能时也需要设置此变量。示例：https://console.dify.ai

SERVICE_API_URL

默认值：（空）在 Dify 控制台中展示给开发者的 API Base URL，即他们复制到代码中用于调用 Dify API 的 URL。如果为空，将从当前请求自动检测（例如 http://localhost/v1）。当你的服务器可通过多个地址访问时，设置此变量以确保 URL 一致。示例：https://api.dify.ai

APP_API_URL

默认值：（空） Web 应用前端（已发布应用）的后端 API URL。此变量仅由 Web 前端容器使用，不影响 Python 后端。如果为空，Docker 镜像默认使用 http://127.0.0.1:5001。示例：https://api.app.dify.ai

APP_WEB_URL

默认值：（空）已发布 Web 应用的公开访问 URL。工作流中的 人工输入节点 需要此变量；邮件通知中的表单链接以 {APP_WEB_URL}/form/{token} 格式构建。如果为空，人工输入邮件将不包含有效的表单链接。示例：https://app.dify.ai

TRIGGER_URL

默认值：http://localhost Webhook 和集成触发端点的公开访问 URL。外部系统使用此地址来调用你的工作流。Dify 构建触发回调 URL 格式为 {TRIGGER_URL}/triggers/webhook/{id} 并在控制台中展示。要使触发器能从外部系统正常工作，此变量必须指向它们可以访问的公共域名或 IP 地址。

FILES_URL

默认值：（空；回退到 CONSOLE_API_URL）文件预览和下载链接的基础 URL。Dify 为所有文件（上传的文档、工具输出、工作空间 Logo）生成签名的限时 URL，并提供给前端和多模态模型使用。如果你使用文件处理插件，或希望文件 URL 使用专用域名，请设置此变量。如果 FILES_URL 和 CONSOLE_API_URL 都为空，文件预览将无法工作。示例：https://upload.example.com 或 http://<your-ip>:5001

INTERNAL_FILES_URL

默认值：（空；回退到 FILES_URL） Docker 网络内部服务间通信使用的文件访问 URL（例如插件守护进程、PDF/Word 提取器）。这些内部服务可能无法通过 Nginx 或公共域名访问外部的 FILES_URL。如果为空，内部服务使用 FILES_URL。当内部服务无法访问外部 URL 时，请设置此变量。示例：http://api:5001

FILES_ACCESS_TIMEOUT

默认值：300（5 分钟）签名文件 URL 的有效时长（秒）。超过此时间后 URL 将被拒绝，文件需要重新请求。对于长时间运行的流程可以增大此值；对于更严格的安全要求可以减小此值。

ENABLE_COLLABORATION_MODE

默认值：true 启用工作流画布的实时协作功能：多人同时编辑、画布评论以及 @ 提及。如果用户通过 localhost 以外的主机访问 Dify，将 NEXT_PUBLIC_SOCKET_URL 设置为浏览器可访问的 WebSocket URL（参见 CORS 配置）。默认值 ws://localhost 仅适用于本地访问场景。如需禁用协作功能，将此值设为 false。使用 Docker Compose 时，还需从 COMPOSE_PROFILES 中移除 collaboration，否则专用的 api_websocket 容器会持续运行但无任何流量。如果使用自己的反向代理，需在 /socket.io/ 路径上转发 Upgrade 与 Connection 请求头（Dify 自带的 nginx 模板已包含此配置）。多 API 副本部署需启用会话保持（sticky sessions）。如果协作者编辑大型工作流时编辑器反复断开重连，可调高 WEBSOCKET_MAX_HTTP_BUFFER_SIZE。

系统编码

变量	默认值	说明
`LANG`	`C.UTF-8`	系统区域设置，确保使用 UTF-8 编码。
`LC_ALL`	`C.UTF-8`	覆盖所有类别的区域设置。
`PYTHONIOENCODING`	`utf-8`	Python I/O 编码。

服务器配置

日志

变量	默认值	说明
`LOG_LEVEL`	`INFO`	最低日志级别。控制所有处理器（文件 + 控制台）的日志记录内容。级别从低到高：`DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL`。
`LOG_OUTPUT_FORMAT`	`text`	`text` 输出包含时间戳、级别、线程和追踪 ID 的可读格式。`json` 输出结构化 JSON，适用于日志聚合工具（ELK、Datadog 等）。
`LOG_FILE`	`/app/logs/server.log`	日志文件路径。设置后启用基于文件的日志记录，并自动轮转。目录会自动创建。为空时日志仅输出到控制台。
`LOG_FILE_MAX_SIZE`	`20`	日志文件轮转前的最大大小（MB）。超过后当前文件重命名为 `.1`，并创建新文件。
`LOG_FILE_BACKUP_COUNT`	`5`	保留的轮转日志文件数量。使用默认配置时最多存在 6 个文件：当前文件加 5 个备份。
`LOG_DATEFORMAT`	`%Y-%m-%d %H:%M:%S`	文本格式日志的时间戳格式（strftime 代码）。JSON 格式忽略此设置。
`LOG_TZ`	`UTC`	日志时间戳的时区（pytz 格式，例如 `Asia/Shanghai`）。仅适用于文本格式，JSON 始终使用 UTC。同时设置 Celery 的任务调度时区。

常规

变量	默认值	说明
`DEBUG`	`false`	启用详细日志记录：工具执行详情、完整 LLM 提示和响应、应用启动耗时。适用于本地开发；不建议在生产环境使用，因为可能在日志中暴露敏感数据。
`FLASK_DEBUG`	`false`	标准 Flask 调试模式标志。Dify 未主动使用；`DEBUG` 是主要控制变量。
`ENABLE_REQUEST_LOGGING`	`false`	为每个 HTTP 请求记录一条紧凑的访问日志（`METHOD PATH STATUS DURATION TRACE_ID`）。当 `LOG_LEVEL` 同时设为 `DEBUG` 时，还会以 JSON 格式记录完整的请求和响应体。
`DEPLOY_ENV`	`PRODUCTION`	在 Sentry 和 OpenTelemetry 中标记监控数据，以便按环境过滤错误和追踪。也作为 `X-Env` 响应头发送。不改变应用行为。
`DEPLOYMENT_EDITION`	`COMMUNITY`	部署运行的版本：`COMMUNITY`、`ENTERPRISE` 或 `CLOUD`。保持默认值即可。此变量替代旧的 `EDITION`，后者已不再读取。原值为 `SELF_HOSTED` 时，改用 `COMMUNITY`。
`MIGRATION_ENABLED`	`true`	为 `true` 时，容器启动时自动运行数据库架构迁移（`flask upgrade-db`）。仅限 Docker。如果你单独运行迁移，请设为 `false`。对于源码启动，需手动运行 `flask db upgrade`。
`CHECK_UPDATE_URL`	`https://updates.dify.ai`	控制台通过此 URL 检查 Dify 的新版本。设为空可禁用，适用于离线环境或防止外部 HTTP 调用。
`OPENAI_API_BASE`	`https://api.openai.com/v1`	遗留变量。Dify 自身代码未主动使用。如果存在于环境中，可能会被 OpenAI Python SDK 读取。

SECRET_KEY

默认值：（空；自动生成并保存在配置的存储中）为认证令牌和文件 URL 签名，并加密系统级 OAuth 客户端凭据。此变量为空时，Dify 会复用配置的存储中 .dify_secret_key 文件内的密钥；如果密钥不存在，则生成并保存一个。使用自带的文件系统存储时，宿主机路径为 docker/volumes/app/storage/.dify_secret_key。非空的 SECRET_KEY 优先于已存储的密钥。如需自行提供密钥，生成一个高强度随机值，并在首次启动前设置：

openssl rand -base64 42

如果 Dify 无法保存生成的密钥，初始化会失败。为配置的存储提供写入权限，或显式设置密钥。

无论显式设置密钥，还是将其保存在持久化存储中，升级和恢复时都应保留同一个密钥。更改密钥会使现有认证令牌和已签名的文件 URL 失效，还会导致 Dify 无法解密已有的系统级 OAuth 客户端凭据。恢复原密钥即可重新访问这些凭据。

PASSWORD_PEPPER

默认值：（空）服务端密钥，Dify 会将其混入成员的登录密码。这样即使数据库泄露，仅凭其中的数据也无法破解密码。留空则一切照旧。如需启用，请在首次安装时、创建管理员账户之前设置此变量。取值应为高熵随机值，例如用以下命令生成：

openssl rand -base64 32

使用 Docker Compose 部署时，在 docker/envs/core-services/api.env 中设置。不要写在 docker/.env 中，因为 Compose 也会把该文件中的变量传给 Worker、插件守护进程、Agent 后端、Web 前端和代码沙箱。源码部署则在 api/.env 中设置。

已有账户后再设置、修改或移除该值，这些账户用现有密码登录时都会提示密码无效。若是误操作，改回原值即可，其间未重置的密码都会恢复可用。请像保管 SECRET_KEY 一样妥善保管该值。

已有账户的部署若要启用，事后需确保每位成员都能重新登录：

在 API 容器中运行 flask reset-password，逐个重置账户密码。完整命令详见重置管理员密码。
让成员通过「忘记密码」邮件自行重置密码，前提是已配置邮件发送。
如果启用了 ENABLE_EMAIL_CODE_LOGIN，成员也可改用邮件验证码登录。

KEY_PROVIDER_TYPE

默认值：local 决定 Dify 把加密存储凭证（模型供应商 API 密钥、工具凭证等工作空间机密）所用的密钥保存在哪里：

local：为每个工作空间生成一对 RSA 密钥，私钥保存在 STORAGE_TYPE 对应的存储后端中。
azure-keyvault：将每个工作空间的 RSA 密钥保存在 Azure Key Vault 中，私钥不会离开 Key Vault。Dify 通过 DefaultAzureCredential（托管身份、环境变量或 Azure CLI 登录）完成认证。

在创建第一个工作空间前确定密钥提供方。两种提供方加密的凭证互不兼容，在已存有凭证的部署上切换会导致这些凭证无法解密，只能重新录入。

变量	默认值	说明
`AZURE_KEYVAULT_VAULT_URL`	（空）	Key Vault 实例 URL。`KEY_PROVIDER_TYPE` 为 `azure-keyvault` 时必填，缺失会导致 API 服务无法启动。示例：`https://your-vault-name.vault.azure.net`
`AZURE_KEYVAULT_KEY_SIZE`	`2048`	Dify 在 Key Vault 中为工作空间新建密钥时使用的 RSA 密钥长度（位）。仅在创建新密钥时生效，已有密钥保持原长度。
`AZURE_KEYVAULT_ROTATION_INTERVAL_DAYS`	（空）	设置后（最小值 7），新建的工作空间密钥会附带 Key Vault 自动轮换策略，每 N 天轮换一次。旧版本密钥保持可用，轮换前加密的凭证无需重新加密即可继续解密。留空则自行在 Azure 中管理轮换。

INIT_PASSWORD

默认值：（空）首次安装时的可选安全门控。设置后，/install 页面在创建管理员账户前需要输入此密码，防止服务器暴露时被未授权设置。安装完成后此变量不再生效。最大长度：30 个字符。

令牌与请求限制

变量	默认值	说明
`ACCESS_TOKEN_EXPIRE_MINUTES`	`60`	登录会话的访问令牌有效时长（分钟）。过期后浏览器使用刷新令牌静默刷新，用户不会被登出。
`REFRESH_TOKEN_EXPIRE_DAYS`	`30`	用户无需重新输入凭证即可保持登录的时长（天）。如果用户在此期间未访问，则需要重新登录。
`APP_MAX_EXECUTION_TIME`	`3600`	应用执行的最大运行时间（秒），超时后终止。属于外层限制，与 `WORKFLOW_MAX_EXECUTION_TIME` 配合使用：两者默认均为一小时，此变量作用于应用队列层面，另一个作用于工作流引擎层面。如果工作流需要更多时间，请同时增大两者。如果你使用 Agent，请让这两个外层限制不低于 Agent 的运行时限（`DIFY_AGENT_RUN_TIMEOUT_SECONDS`），否则 Agent 运行会被提前截断。
`APP_DEFAULT_ACTIVE_REQUESTS`	`0`	每个应用的默认并发请求限制，在应用未在 UI 中设置自定义限制时使用。`0` 表示不限制。有效限制取此值与 `APP_MAX_ACTIVE_REQUESTS` 的较小值。
`APP_MAX_ACTIVE_REQUESTS`	`0`	每个应用的全局并发请求上限。如果应用自定义设置超过此值，将被覆盖。`0` 表示不限制。
`WEBSOCKET_MAX_HTTP_BUFFER_SIZE`	`10485760`	协作 WebSocket 接受的单条消息大小上限，单位为字节（默认 10 MiB）。保存大型工作流时，如果工作流图超过此上限，导致连接反复断开，可调高此值。在处理 `/socket.io/` 的 API 进程上设置，Docker Compose 部署中对应 `api_websocket` 容器。

容器启动配置

仅在使用 Docker 镜像或 Docker Compose 启动时生效。

变量	默认值	说明
`DIFY_BIND_ADDRESS`	`0.0.0.0`	API 服务器绑定的网络接口。`0.0.0.0` 监听所有接口；设为 `127.0.0.1` 限制为仅本地访问。
`DIFY_PORT`	`5001`	API 服务器监听端口。
`SERVER_WORKER_AMOUNT`	`1`	Gunicorn 工作进程数。使用 gevent（默认）时，每个工作进程通过 greenlet 处理多个并发连接，因此 1 通常足够。对于同步工作进程，使用 `(2 x CPU 核心数) + 1`。参考文档。
`SERVER_WORKER_CLASS`	`gevent`	Gunicorn 工作进程类型。保持默认值；其他值会破坏 psycopg2 和 gRPC 补丁。
`SERVER_WORKER_CONNECTIONS`	`10`	每个工作进程的最大并发连接数。仅适用于异步工作进程（gevent）。如果在高负载下遇到连接拒绝或响应缓慢，尝试增大此值。
`GUNICORN_TIMEOUT`	`360`	如果工作进程在此秒数内没有响应，Gunicorn 将终止并重启它。设为 360（6 分钟）以支持用于流式 LLM 响应的长连接 SSE。
`GUNICORN_KEEP_ALIVE`	`10`	API 服务器（Gunicorn）保留空闲连接的秒数，在此期间下一个请求可复用该连接。
`API_WEBSOCKET_WORKER_AMOUNT`	`1`	仅适用于 Docker Compose。专用 `api_websocket` 容器中服务实时协作的 Gunicorn 工作进程数。协作事件通过 Redis 在各工作进程间同步，因此在编辑流量较大、单个工作进程占满一个 CPU 核心时，可放心调高此值。
`API_WEBSOCKET_WORKER_CLASS`	`geventwebsocket.gunicorn.workers.GeventWebSocketWorker`	仅适用于 Docker Compose。专用 `api_websocket` 容器的工作进程类型。保持默认值；其他值会破坏 WebSocket 支持。
`API_WEBSOCKET_WORKER_CONNECTIONS`	`1000`	仅适用于 Docker Compose。每个 `api_websocket` 工作进程可同时接受的 WebSocket 连接数上限。每个打开的工作流编辑器标签页占用一个连接，因此默认值下每个工作进程最多支持 1000 个并发编辑会话；如有更多需求，可调高此值或增加工作进程。
`API_WEBSOCKET_GUNICORN_TIMEOUT`	`360`	仅适用于 Docker Compose。`api_websocket` 工作进程在此秒数内无响应时，Gunicorn 会将其重启。默认值 360 秒（6 分钟）适用于长时间保持的 WebSocket 连接。
`CELERY_WORKER_CLASS`	（空；默认为 gevent）	Celery 工作进程类型，与 `SERVER_WORKER_CLASS` 有相同的 gevent 补丁要求。强烈不建议修改。
`CELERY_WORKER_AMOUNT`	`4`	Celery 工作进程数。仅在禁用自动扩缩时使用。资源受限的 VM 可适当降低；若需弹性吞吐，建议启用 `CELERY_AUTO_SCALE` 而非仅调高此值。
`CELERY_AUTO_SCALE`	`false`	启用动态自动扩缩。启用后，Celery 监控队列深度，在 `CELERY_MIN_WORKERS` 和 `CELERY_MAX_WORKERS` 之间动态创建/销毁工作进程。
`CELERY_MAX_WORKERS`	（空；默认为 CPU 数量）	自动扩缩启用时的最大工作进程数。
`CELERY_MIN_WORKERS`	（空；默认为 1）	自动扩缩启用时的最小工作进程数。
`COMPOSE_WORKER_HEALTHCHECK_DISABLED`	`true`	禁用 Docker Compose 对 Celery Worker 容器的健康检查。默认禁用，因为在繁忙 Worker 上执行 `celery inspect ping` 开销较大。设为 `false` 可启用。仅在 Docker Compose 部署中生效。
`COMPOSE_WORKER_HEALTHCHECK_INTERVAL`	`30s`	Celery Worker 健康检查的间隔时间。仅在 `COMPOSE_WORKER_HEALTHCHECK_DISABLED=false` 时生效。接受 Docker Compose 的时间格式（如 `30s`、`1m`）。
`COMPOSE_WORKER_HEALTHCHECK_TIMEOUT`	`30s`	单次 Celery Worker 健康检查的超时时间。仅在 `COMPOSE_WORKER_HEALTHCHECK_DISABLED=false` 时生效。

MODE

默认值：按服务而定（Docker Compose 中为 api、worker 或 beat）决定 dify-api 镜像在容器启动时运行的进程。自带的 Compose 文件在各服务的 environment 中设置 MODE，该值优先于 env 文件中的值。可选值：

api（空值或无法识别的值同样生效）：API 服务
worker：Celery 任务消费进程
beat：定时任务调度进程
job：执行一条 Flask CLI 命令后退出
migration：配合 MIGRATION_ENABLED=true，完成数据库迁移后退出

只有 Kubernetes 等自定义部署才需要设置。配置错误会让容器运行错误的进程：没有 worker 时，索引和邮件任务会一直排队。

API 工具配置

变量	默认值	说明
`API_TOOL_DEFAULT_CONNECT_TIMEOUT`	`10`	API 工具节点调用外部 API 时建立 TCP 连接的最大等待时间（秒）。
`API_TOOL_DEFAULT_READ_TIMEOUT`	`60`	API 工具节点从外部 API 接收响应数据的最大等待时间（秒）。

数据库配置

数据库默认使用 PostgreSQL，也支持 OceanBase、MySQL 和 seekdb。首次启动前选定数据库：更换数据库类型时，Dify 不会迁移已存储的数据。要使用自带的 MySQL 和 Weaviate 启动全新部署，在 docker/.env 中设置：

DB_TYPE=mysql
DB_HOST=db_mysql
DB_PORT=3306
DB_USERNAME=root
COMPOSE_PROFILES=weaviate,mysql,collaboration

如果使用其他向量数据库，将示例中的 weaviate 替换为它的 profile。首次启动前设置自定义的 DB_PASSWORD。之后如需修改密码，先在数据库服务器上修改，再相应更新 DB_PASSWORD。

变量	默认值	说明
`DB_TYPE`	`postgresql`	数据库类型。支持的值：`postgresql`、`mysql`、`oceanbase`、`seekdb`。TiDB 等 MySQL 兼容数据库可使用 `mysql`。
`DB_USERNAME`	`postgres`	数据库用户名。在连接字符串中进行 URL 编码，因此特殊字符可以安全使用。
`DB_PASSWORD`	`difyai123456`	数据库密码。在连接字符串中进行 URL 编码，因此 `@`、`:`、`%` 等字符可以安全使用。
`DB_HOST`	`db_postgres`	数据库服务器主机名。
`DB_PORT`	`5432`	数据库服务器端口。如果使用 MySQL，请设为 `3306`。
`DB_DATABASE`	`dify`	数据库名称。

连接池

这些变量控制 Dify 管理数据库连接池的方式。默认配置适用于大多数部署。

变量	默认值	说明
`SQLALCHEMY_POOL_SIZE`	`30`	连接池中保持的持久连接数。
`SQLALCHEMY_MAX_OVERFLOW`	`10`	连接池满时允许的额外临时连接数。使用默认设置时，最多可同时存在 40 个连接（30 + 10）。
`SQLALCHEMY_POOL_RECYCLE`	`3600`	在此秒数后回收连接，防止连接过期。
`SQLALCHEMY_POOL_TIMEOUT`	`30`	连接池耗尽时等待连接的时长。如果在此时间内没有连接释放，请求将超时失败。
`SQLALCHEMY_POOL_RESET_ON_RETURN`	`rollback`	SQLAlchemy 在连接归还连接池时执行的动作。`rollback` 在重用前清除未提交的事务状态；`commit` 则提交该状态。
`SQLALCHEMY_POOL_PRE_PING`	`false`	使用连接前通过轻量查询测试连接。防止「连接丢失」错误，但会增加少量延迟。建议在网络不稳定的生产环境中启用。
`SQLALCHEMY_POOL_USE_LIFO`	`false`	复用最近归还的连接（LIFO）而非均匀轮转（FIFO）。LIFO 使较少的连接保持「活跃」状态，可以减少开销。
`SQLALCHEMY_ECHO`	`false`	将所有 SQL 语句输出到日志。适用于调试查询问题。

PostgreSQL 性能调优

这些变量作为启动参数传递给 PostgreSQL 容器，配置的是数据库服务器，而非 Dify 应用。

变量	默认值	说明
`POSTGRES_MAX_CONNECTIONS`	`200`	最大数据库连接数。API 与 Celery 工作进程同时打开连接池时，建议至少保留 `SERVER_WORKER_AMOUNT × SERVER_WORKER_CONNECTIONS + CELERY_WORKER_AMOUNT + 余量` 的连接数，以避免出现 `too many connections` 错误。参考文档
`POSTGRES_SHARED_BUFFERS`	`128MB`	缓冲区共享内存。建议设为可用内存的 25%。参考文档
`POSTGRES_WORK_MEM`	`4MB`	每个数据库工作进程的工作内存。参考文档
`POSTGRES_MAINTENANCE_WORK_MEM`	`64MB`	维护操作预留的内存。参考文档
`POSTGRES_EFFECTIVE_CACHE_SIZE`	`4096MB`	查询规划器对有效缓存大小的估计值。参考文档
`POSTGRES_STATEMENT_TIMEOUT`	`0`	语句执行超时前的最大时长（毫秒）。`0` 表示不超时。参考文档
`POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT`	`0`	事务内空闲会话的最大时长（毫秒）。`0` 表示不超时。参考文档

MySQL 性能调优

这些变量作为启动参数传递给 MySQL 容器，配置的是数据库服务器，而非 Dify 应用。

变量	默认值	说明
`MYSQL_MAX_CONNECTIONS`	`1000`	最大 MySQL 连接数。
`MYSQL_INNODB_BUFFER_POOL_SIZE`	`512M`	InnoDB 缓冲池大小。建议值：专用 MySQL 服务器可用内存的 70～80%。参考文档
`MYSQL_INNODB_LOG_FILE_SIZE`	`128M`	InnoDB 日志文件大小。参考文档
`MYSQL_INNODB_FLUSH_LOG_AT_TRX_COMMIT`	`2`	事务提交时的 InnoDB 刷写日志方式。选项：`0`（不刷写）、`1`（刷写并同步）、`2`（刷写到操作系统缓存）。参考文档

Redis 配置

配置这些变量以将 Dify 连接到你的 Redis 实例。Dify 支持三种部署模式：单机（默认）、哨兵和集群。

变量	默认值	说明
`REDIS_HOST`	`redis`	Redis 服务器主机名。仅在单机模式下使用；启用哨兵或集群模式时忽略。
`REDIS_PORT`	`6379`	Redis 服务器端口。仅在单机模式下使用。
`REDIS_USERNAME`	（空）	Redis 6.0+ ACL 用户名。适用于所有模式（单机、哨兵、集群）。
`REDIS_PASSWORD`	`difyai123456`	Redis 认证密码。集群模式请使用 `REDIS_CLUSTERS_PASSWORD` 代替。
`REDIS_DB`	`0`	Redis 数据库编号（0～15）。仅适用于单机和哨兵模式。确保不与 Celery 的数据库冲突（在 `CELERY_BROKER_URL` 中配置；默认为 DB 1）。
`REDIS_KEY_PREFIX`	（空）	可选的全局前缀，应用于所有 Redis 键、Pub/Sub 频道、Redis Streams 名称以及 Celery broker 队列和结果后端键。Dify 会自动在前缀与键之间插入冒号，例如设为 `staging` 时实际写入的键形如 `staging:session:abc`。多个 Dify 实例共用同一 Redis 部署时（例如 staging 与 production），可借此前缀避免键冲突。留空则保持不加前缀的默认行为。为已有部署启用前缀会使此前以空前缀（或不同前缀）写入的键被遗留、无法再被读取。
`REDIS_USE_SSL`	`false`	启用 Redis 连接的 SSL/TLS。不会自动应用于哨兵协议。
`REDIS_MAX_CONNECTIONS`	（空）	Redis 连接池中的最大连接数。留空使用库默认值。如需要，可设置为与 Redis 服务器的 `maxclients` 匹配。
`REDIS_KEEPALIVE`	`true`	为 Redis 连接启用 TCP keepalive，以便及时发现被防火墙或负载均衡器静默断开的空闲连接并重新建立，而非在下次使用时才失败。
`REDIS_KEEPALIVE_IDLE`	`30`	连接空闲多少秒后发送第一个 TCP keepalive 探测包（`TCP_KEEPIDLE`）。在 `REDIS_KEEPALIVE=true` 时生效。
`REDIS_KEEPALIVE_INTERVAL`	`10`	两次 TCP keepalive 探测包之间的间隔秒数（`TCP_KEEPINTVL`）。在 `REDIS_KEEPALIVE=true` 时生效。
`REDIS_KEEPALIVE_COUNT`	`10`	连接被判定为失效前，允许未收到确认的探测包次数（`TCP_KEEPCNT`）。在 `REDIS_KEEPALIVE=true` 时生效。

Redis SSL 配置

仅在 REDIS_USE_SSL=true 时适用。当 Celery broker URL 使用 rediss:// 协议时，这些设置也适用于 Celery broker。

变量	默认值	说明
`REDIS_SSL_CERT_REQS`	`CERT_NONE`	证书验证级别：`CERT_NONE`（不验证）、`CERT_OPTIONAL`（可选验证）或 `CERT_REQUIRED`（完整验证）。
`REDIS_SSL_CA_CERTS`	（空）	用于验证 Redis 服务器的 CA 证书文件路径。
`REDIS_SSL_CERTFILE`	（空）	用于双向 TLS 认证的客户端证书路径。
`REDIS_SSL_KEYFILE`	（空）	用于双向 TLS 认证的客户端私钥路径。

Redis 哨兵模式

哨兵提供自动主节点发现和故障转移以实现高可用。与集群模式互斥。

变量	默认值	说明
`REDIS_USE_SENTINEL`	`false`	启用 Redis 哨兵模式。启用后 `REDIS_HOST`/`REDIS_PORT` 被忽略；Dify 连接到哨兵节点并查询当前主节点。
`REDIS_SENTINELS`	（空）	哨兵节点地址。格式：`<ip1>:<port1>,<ip2>:<port2>,<ip3>:<port3>`。这些是哨兵实例，而非 Redis 服务器。
`REDIS_SENTINEL_SERVICE_NAME`	（空）	哨兵监控的逻辑服务名称（在 `sentinel.conf` 中配置）。Dify 调用 `master_for(service_name)` 来发现当前主节点。
`REDIS_SENTINEL_USERNAME`	（空）	哨兵节点的认证用户名。与 `REDIS_USERNAME` 分开，后者用于 Redis 主/副本的认证。
`REDIS_SENTINEL_PASSWORD`	（空）	哨兵节点的认证密码。与 `REDIS_PASSWORD` 分开。
`REDIS_SENTINEL_SOCKET_TIMEOUT`	`0.1`	与哨兵节点通信的 Socket 超时（秒）。默认 0.1 秒假定快速本地网络。对于云/广域网部署，建议增大到 1.0～5.0 秒以防止间歇性超时。

Redis 集群模式

集群模式提供跨多个 Redis 节点的自动分片。与哨兵模式互斥。

变量	默认值	说明
`REDIS_USE_CLUSTERS`	`false`	启用 Redis 集群模式。
`REDIS_CLUSTERS`	（空）	集群节点。格式：`<ip1>:<port1>,<ip2>:<port2>,<ip3>:<port3>`
`REDIS_CLUSTERS_PASSWORD`	（空）	Redis 集群的密码。

Redis 连接健壮性配置

以下变量用于调节 Redis 连接的客户端重试、超时和健康检查行为。默认值较为保守；在网络延迟较高的云或广域网环境中，建议适当增大超时值。

变量	默认值	说明
`REDIS_RETRY_RETRIES`	`3`	单条 Redis 命令在出现瞬时故障（`ConnectionError`、`TimeoutError`、`socket.timeout`）时的最大重试次数。设为 `0` 可禁用重试。使用带抖动的指数退避策略。
`REDIS_RETRY_BACKOFF_BASE`	`1.0`	重试之间指数退避的基础延迟（秒）。
`REDIS_RETRY_BACKOFF_CAP`	`10.0`	重试之间退避延迟的上限（秒）。
`REDIS_SOCKET_TIMEOUT`	`5.0`	Redis 读/写操作的 Socket 超时（秒）。若在高负载下出现间歇性命令超时，可适当增大此值。
`REDIS_SOCKET_CONNECT_TIMEOUT`	`5.0`	建立 Redis 连接的 Socket 超时（秒）。
`REDIS_HEALTH_CHECK_INTERVAL`	`30`	对空闲连接执行客户端健康检查的时间间隔（秒）。设为 `0` 可禁用。集群模式下不生效（`redis-py` 会静默忽略该参数）。

Celery 配置

配置用于数据集索引、邮件发送和定时任务的后台任务队列。

CELERY_BROKER_URL

默认值：redis://:difyai123456@redis:6379/1 Celery 消息代理的 Redis 连接 URL。直连格式：

redis://<redis_username>:<redis_password>@<redis_host>:<redis_port>/<redis_database>

哨兵模式格式（多个节点用分号分隔）：

sentinel://<redis_username>:<redis_password>@<sentinel_host>:<sentinel_port>/<redis_database>

变量	默认值	说明
`CELERY_BACKEND`	`redis`	Celery 存储任务结果的位置。选项：`redis`（快速，内存存储）或 `database`（存储在主数据库中）。
`BROKER_USE_SSL`	`false`	当 `CELERY_BROKER_URL` 使用 `rediss://` 协议时自动启用。将 Redis SSL 证书设置应用于 broker 连接。
`CELERY_USE_SENTINEL`	`false`	为 Celery broker 启用 Redis 哨兵模式。
`CELERY_SENTINEL_MASTER_NAME`	（空）	哨兵服务名称（Master Name）。
`CELERY_SENTINEL_PASSWORD`	（空）	哨兵认证密码。与 `REDIS_SENTINEL_PASSWORD` 分开；如果缓存和任务队列使用不同的哨兵集群，两者可以不同。
`CELERY_SENTINEL_SOCKET_TIMEOUT`	`0.1`	连接哨兵的超时时间（秒）。
`CELERY_TASK_ANNOTATIONS`	`null`	为特定任务应用运行时设置（例如速率限制）。格式：JSON 字典。示例：`{"tasks.add": {"rate_limit": "10/s"}}`。大多数用户不需要此设置。

CORS 配置

控制前端的跨域访问策略。

变量	默认值	说明
`WEB_API_CORS_ALLOW_ORIGINS`	`*`	Web API 跨域请求的允许来源。示例：`https://dify.app`
`CONSOLE_CORS_ALLOW_ORIGINS`	`*`	控制台 API 跨域请求的允许来源。如果未设置，回退到 `CONSOLE_WEB_URL`。
`COOKIE_DOMAIN`	（空）	当前端和后端运行在不同子域上时，设为共享的顶级域名（例如 `example.com`）。这允许认证 Cookie 在子域间共享。为空时 Cookie 使用最安全的 `__Host-` 前缀，并锁定到单个域。
`NEXT_PUBLIC_COOKIE_DOMAIN`	（空）	跨子域 Cookie 的前端标志。设为 `1`（或任何非空值）启用，后端从 `COOKIE_DOMAIN` 读取实际域名。
`NEXT_PUBLIC_SOCKET_URL`	`ws://localhost`	浏览器进行实时协作时使用的 WebSocket 地址。默认值仅适用于在服务器本机上打开的浏览器。远程访问时，在 `docker/.env` 中添加此变量，值为 Dify 的地址（如 `wss://dify.example.com`），然后运行 `docker compose up -d`。HTTP 部署用 `ws://`，HTTPS 部署用 `wss://`；只填写协议、主机和端口，路径固定为 `/socket.io/`。
`NEXT_PUBLIC_BATCH_CONCURRENCY`	`5`	仅前端。控制 UI 在批量操作时发起的并发 API 调用数。

Dify CLI 与编程 API

/openapi/v1/* 是面向用户的编程 API，Dify CLI（difyctl）等客户端通过 OAuth Bearer Token 访问。该接口默认关闭：将 OPENAPI_ENABLED 和 ENABLE_OAUTH_BEARER 都设为 true 后，CLI 才能连接你的部署。

变量	默认值	说明
`OPENAPI_ENABLED`	`false`	`/openapi/v1/` 编程 API 的总开关，Dify CLI（`difyctl`）依赖该接口。为 `false` 时所有 `/openapi/v1/` 端点返回 404，`difyctl login` 无法开始。需与 `ENABLE_OAUTH_BEARER` 一同开启。
`ENABLE_OAUTH_BEARER`	`false`	为 `/openapi/v1/*` 绑定 OAuth Bearer 鉴权器，并控制设备流登录的批准端点。若只开启 `OPENAPI_ENABLED` 而此项为 `false`，`difyctl login` 会在批准环节收到 503。两者都为 `true` 时 CLI 才可用。
`OPENAPI_KNOWN_CLIENT_IDS`	`difyctl`	允许发起设备流登录的 OAuth 客户端 ID，逗号分隔。新增 ID 即可接入其他客户端，无需改代码；移除 `difyctl` 会让 CLI 登录报 `unsupported_client`。
`OAUTH_TTL_DAYS`	`14`	`difyctl login` 登录的有效天数，从登录时起算。可设为 1～365，超出范围时自动取最接近的边界值。修改后仅对新登录生效。
`OPENAPI_CORS_ALLOW_ORIGINS`	（空）	允许跨域调用 `/openapi/v1/*` 的浏览器来源，逗号分隔。为空表示全部拒绝：标准部署下没有影响，CLI 等非浏览器客户端也不受 CORS 限制。
`OPENAPI_RATE_LIMIT_PER_TOKEN`	`60`	每个 OAuth Bearer Token 在 `/openapi/v1/*` 上的每分钟请求上限，经 Redis 在多副本间共享。超限返回 429 并附 `Retry-After` 头。设为 `0` 可关闭限流。
`DEVICE_FLOW_APPROVE_RATE_LIMIT_PER_HOUR`	`10`	单个浏览器会话每小时可批准或拒绝的设备流登录次数。超出后批准请求返回 429，需等待窗口重置。不能设为 `0`。

文件存储配置

配置 Dify 存储上传文件、数据集文档和加密密钥的位置。每种存储类型有各自的凭证变量，仅配置你使用的那种。

STORAGE_TYPE

默认值：opendal 选择文件存储后端。支持的值：opendal、s3、azure-blob、aliyun-oss、google-storage、huawei-obs、volcengine-tos、tencent-cos、baidu-obs、oci-storage、supabase、clickzetta-volume、local（已弃用；内部使用 OpenDAL 的文件系统方案）。

OpenDAL（默认）

使用 Apache OpenDAL 的默认存储后端，一个支持众多存储服务的统一接口。Dify 自动扫描匹配 OPENDAL_<SCHEME>_* 的环境变量并传递给 OpenDAL。例如，使用 OPENDAL_SCHEME=s3 时，设置 OPENDAL_S3_ACCESS_KEY_ID、OPENDAL_S3_SECRET_ACCESS_KEY 等。

变量	默认值	说明
`OPENDAL_SCHEME`	`fs`	使用的存储服务。示例：`fs`（本地文件系统）、`s3`、`gcs`、`azblob`。

对于默认的 fs 方案：

变量	默认值	说明
`OPENDAL_FS_ROOT`	`storage`	本地文件系统存储的根目录。如不存在将自动创建。

有关所有可用方案及其配置选项，请参阅 OpenDAL 服务文档。

变量	默认值	说明
`S3_ENDPOINT`	（空）	S3 端点地址。非 AWS S3 兼容服务（MinIO 等）必填。
`S3_REGION`	`us-east-1`	S3 区域。
`S3_BUCKET_NAME`	`difyai`	S3 存储桶名称。
`S3_ACCESS_KEY`	（空）	S3 Access Key。使用 IAM 角色时不需要。
`S3_SECRET_KEY`	（空）	S3 Secret Key。使用 IAM 角色时不需要。
`S3_ADDRESS_STYLE`	`auto`	S3 寻址方式：`auto`、`path` 或 `virtual`。控制存储桶名称出现在 URL 路径中（`path`）还是作为子域名（`virtual`）。仅在 `S3_USE_AWS_MANAGED_IAM` 为 `false` 时生效。
`S3_USE_AWS_MANAGED_IAM`	`false`	使用 AWS IAM 角色（EC2 实例配置文件、ECS 任务角色）代替显式的 access key/secret key。启用后从实例元数据自动发现凭证。

Azure Blob

变量	默认值	说明
`AZURE_BLOB_ACCOUNT_NAME`	`difyai`	Azure 存储账户名称。
`AZURE_BLOB_ACCOUNT_KEY`	`difyai`	Azure 存储账户密钥。
`AZURE_BLOB_CONTAINER_NAME`	`difyai-container`	Azure Blob 容器名称。
`AZURE_BLOB_ACCOUNT_URL`	`https://<your_account_name>.blob.core.windows.net`	Azure Blob 账户 URL。

Google Cloud Storage

变量	默认值	说明
`GOOGLE_STORAGE_BUCKET_NAME`	（空）	Google Cloud Storage 存储桶名称。
`GOOGLE_STORAGE_SERVICE_ACCOUNT_JSON_BASE64`	（空）	Base64 编码的服务账号 JSON 密钥。

阿里云 OSS

变量	默认值	说明
`ALIYUN_OSS_BUCKET_NAME`	（空）	OSS 存储桶名称。
`ALIYUN_OSS_ACCESS_KEY`	（空）	OSS access key。
`ALIYUN_OSS_SECRET_KEY`	（空）	OSS secret key。
`ALIYUN_OSS_ENDPOINT`	`https://oss-ap-southeast-1-internal.aliyuncs.com`	OSS 端点。区域和端点参考。
`ALIYUN_OSS_REGION`	`ap-southeast-1`	OSS 区域。
`ALIYUN_OSS_AUTH_VERSION`	`v4`	OSS 认证版本。
`ALIYUN_OSS_PATH`	（空）	对象路径前缀。不要以 `/` 开头。参考文档。
`ALIYUN_CLOUDBOX_ID`	（空）	基于 CloudBox 的 OSS 部署的 CloudBox ID。

腾讯云 COS

变量	默认值	说明
`TENCENT_COS_BUCKET_NAME`	（空）	COS 存储桶名称。
`TENCENT_COS_SECRET_KEY`	（空）	COS secret key。
`TENCENT_COS_SECRET_ID`	（空）	COS secret ID。
`TENCENT_COS_REGION`	（空）	COS 区域，例如 `ap-guangzhou`。参考文档。
`TENCENT_COS_SCHEME`	（空）	访问 COS 的协议（`http` 或 `https`）。
`TENCENT_COS_CUSTOM_DOMAIN`	（空）	COS 访问的自定义域名。

OCI Object Storage

变量	默认值	说明
`OCI_ENDPOINT`	（空）	OCI 端点 URL。
`OCI_BUCKET_NAME`	（空）	OCI 存储桶名称。
`OCI_ACCESS_KEY`	（空）	OCI access key。
`OCI_SECRET_KEY`	（空）	OCI secret key。
`OCI_REGION`	`us-ashburn-1`	OCI 区域。

华为 OBS

变量	默认值	说明
`HUAWEI_OBS_BUCKET_NAME`	（空）	OBS 存储桶名称。
`HUAWEI_OBS_ACCESS_KEY`	（空）	OBS access key。
`HUAWEI_OBS_SECRET_KEY`	（空）	OBS secret key。
`HUAWEI_OBS_SERVER`	（空）	OBS 服务器 URL。参考文档。
`HUAWEI_OBS_PATH_STYLE`	`false`	使用路径风格 URL 代替虚拟主机风格。

火山引擎 TOS

变量	默认值	说明
`VOLCENGINE_TOS_BUCKET_NAME`	（空）	TOS 存储桶名称。
`VOLCENGINE_TOS_ACCESS_KEY`	（空）	TOS access key。
`VOLCENGINE_TOS_SECRET_KEY`	（空）	TOS secret key。
`VOLCENGINE_TOS_ENDPOINT`	（空）	TOS 端点 URL。参考文档。
`VOLCENGINE_TOS_REGION`	（空）	TOS 区域，例如 `cn-guangzhou`。

百度 OBS

变量	默认值	说明
`BAIDU_OBS_BUCKET_NAME`	（空）	百度 OBS 存储桶名称。
`BAIDU_OBS_ACCESS_KEY`	（空）	百度 OBS access key。
`BAIDU_OBS_SECRET_KEY`	（空）	百度 OBS secret key。
`BAIDU_OBS_ENDPOINT`	（空）	百度 OBS 服务器 URL。

Supabase

变量	默认值	说明
`SUPABASE_BUCKET_NAME`	（空）	Supabase 存储桶名称。
`SUPABASE_API_KEY`	（空）	Supabase API key。
`SUPABASE_URL`	（空）	Supabase 服务器 URL。

ClickZetta Volume

变量	默认值	说明
`CLICKZETTA_VOLUME_TYPE`	`user`	Volume 类型。选项：`user`（个人/小团队）、`table`（企业多租户）、`external`（数据湖集成）。
`CLICKZETTA_VOLUME_NAME`	（空）	外部 volume 名称（仅 `TYPE=external` 时必填）。
`CLICKZETTA_VOLUME_TABLE_PREFIX`	`dataset_`	Table volume 表前缀（仅 `TYPE=table` 时使用）。
`CLICKZETTA_VOLUME_DIFY_PREFIX`	`dify_km`	Dify 文件目录前缀，用于与其他应用隔离。

ClickZetta Volume 复用向量数据库部分配置的 CLICKZETTA_* 连接参数。

归档存储

用于归档工作流运行日志的独立 S3 兼容存储。archive-workflow-runs 维护命令将超过指定期限的工作流运行打包为按月的 Parquet 归档包；由归档生成的 CSV 导出文件暂存于导出存储桶。

变量	默认值	说明
`ARCHIVE_STORAGE_ENABLED`	`false`	启用工作流日志归档存储。
`ARCHIVE_STORAGE_ENDPOINT`	（空）	S3 兼容端点 URL。
`ARCHIVE_STORAGE_ARCHIVE_BUCKET`	（空）	归档工作流运行日志的存储桶。
`ARCHIVE_STORAGE_EXPORT_BUCKET`	（空）	存放由归档日志生成的临时 CSV 导出压缩包，可通过存储桶生命周期规则自动清理。
`ARCHIVE_STORAGE_ACCESS_KEY`	（空）	Access key。
`ARCHIVE_STORAGE_SECRET_KEY`	（空）	Secret key。
`ARCHIVE_STORAGE_REGION`	`auto`	存储区域。
`ARCHIVE_STORAGE_ADDRESS_STYLE`	`path`	归档存储的 S3 寻址方式，决定存储桶名称在请求 URL 中的位置。如果服务商拒绝路径式请求，改用 `virtual`。 `path`：存储桶名称放在路径中（`https://<endpoint>/<bucket>/...`） `virtual`：存储桶名称放在主机名中（`https://<bucket>.<endpoint>/...`） `auto`：由 S3 客户端决定归档存储桶和导出存储桶都受此设置影响，CSV 导出文件的下载链接也包括在内。此变量与 `S3_ADDRESS_STYLE` 分开设置，两者默认值不同。

向量数据库配置

配置向量数据库。知识库的嵌入存放在向量数据库中，用于相似性搜索。

VECTOR_STORE

默认值：weaviate 选择新建知识库使用的向量数据库。已有知识库仍使用建立索引时所在的数据库。支持的值：weaviate、oceanbase、seekdb、qdrant、milvus、myscale、relyt、pgvector、pgvecto-rs、chroma、opensearch、oracle、tencent、elasticsearch、elasticsearch-ja、analyticdb、couchbase、vikingdb、opengauss、tablestore、vastbase、tidb_vector、tidb_on_qdrant、baidu、lindorm、huawei_cloud、upstash、matrixone、clickzetta、alibabacloud_mysql、iris、hologres。以下自带提供商各有一个同名的 Compose profile：weaviate、qdrant、oceanbase、seekdb、couchbase、pgvector、pgvecto-rs、vastbase、chroma、iris、oracle、milvus、opensearch、opengauss、myscale、matrixone、elasticsearch 和 elasticsearch-ja。使用其他提供商或外部服务器时，不要启用自带服务的 profile。连接设置写在该提供商的本地 .env 文件中；没有本地文件的提供商，则写在 envs/core-services/api-worker.env 中。要切换到另一个自带提供商：

保留已有知识库所用的提供商

在 COMPOSE_PROFILES 中保留原提供商的 profile。如果原提供商不是 Weaviate，还要把它的 .defaults 文件复制为本地 .env 文件，例如将 qdrant.defaults 复制为 qdrant.env。elasticsearch-ja 与 elasticsearch 共用同一个 elasticsearch.env。只有当前选中的提供商的默认值会自动加载，不复制的话，已有知识库会失去连接。

选择新提供商

在 docker/.env 中设置 VECTOR_STORE，并将新提供商的 profile 加入 COMPOSE_PROFILES，然后运行 docker compose up -d。

OceanBase 和 seekdb 共用 OCEANBASE_* 设置，因此 Dify 同一时间只能连接其中一个。在这两者之间切换时，请迁移已有知识库，而不是同时保留两者。如需将已有知识库的数据迁移到新提供商，详见向量数据库迁移。如需修改提供商的连接设置，按设置变量操作。对于保存了用户密码的提供商，先在数据库中修改密码，再更新对应的客户端设置。

变量	默认值	说明
`VECTOR_INDEX_NAME_PREFIX`	`Vector_index`	向量数据库中集合名称的前缀。如果在多个 Dify 部署间共享向量数据库实例，请更改此值。

Weaviate

变量	默认值	说明
`WEAVIATE_ENDPOINT`	`http://weaviate:8080`	Weaviate REST API 端点。
`WEAVIATE_API_KEY`	（自带默认值中的开发密钥，生产环境必须替换）	API 和 Worker 向 Weaviate 认证时使用的 API 密钥。必须与 `WEAVIATE_AUTHENTICATION_APIKEY_ALLOWED_KEYS` 中的某一项一致。要开启身份认证，并让客户端与服务端的值保持一致，详见向量数据库服务配置。
`WEAVIATE_GRPC_ENDPOINT`	`grpc://weaviate:50051`	独立的 gRPC 端点，用于高性能二进制协议。批量操作显著更快。如未设置，将从 HTTP 端点推断。
`WEAVIATE_TOKENIZATION`	`word`	文本字段的分词方法。选项：`word`（按空格和标点分割）、`whitespace`（仅按空格分割）、`character`（字符级别，更适合中日韩语言）。

OceanBase / seekdb

两者均使用 OCEANBASE_* 变量。将 VECTOR_STORE 设为 oceanbase 或 seekdb，即可加载对应提供商的连接默认值。

变量	默认值	说明
`OCEANBASE_VECTOR_HOST`	`oceanbase` / `seekdb`	主机名或 IP 地址。自带默认值随 `VECTOR_STORE` 的选择变化。
`OCEANBASE_VECTOR_PORT`	`2881`	端口号。
`OCEANBASE_VECTOR_USER`	`root@test` / `root`	数据库用户名。自带默认值随 `VECTOR_STORE` 的选择变化。
`OCEANBASE_VECTOR_PASSWORD`	`difyai123456`	数据库密码。
`OCEANBASE_VECTOR_DATABASE`	`test`	数据库名称。
`OCEANBASE_CLUSTER_NAME`	`difyai`	集群名称（仅 Docker 部署）。
`OCEANBASE_MEMORY_LIMIT`	`6G`	OceanBase 内存限制（仅 Docker 部署）。
`SEEKDB_MEMORY_LIMIT`	`2G`	seekdb 内存限制（仅 Docker 部署）。
`OCEANBASE_ENABLE_HYBRID_SEARCH`	`false`	启用全文索引用于 BM25 查询，配合向量搜索使用。需要 OceanBase >= 4.3.5.1。启用后需重新创建集合。
`OCEANBASE_FULLTEXT_PARSER`	`ik`	全文解析器。内置：`ngram`、`beng`、`space`、`ngram2`、`ik`。外部（需要插件）：`japanese_ftparser`、`thai_ftparser`。

Qdrant

变量	默认值	说明
`QDRANT_URL`	`http://qdrant:6333`	Qdrant 端点地址。
`QDRANT_API_KEY`	`difyai123456`	Qdrant API 密钥。连接无需认证的外部服务器时，将其设为空值。
`QDRANT_CLIENT_TIMEOUT`	`20`	客户端超时（秒）。
`QDRANT_GRPC_ENABLED`	`false`	启用 gRPC 通信。
`QDRANT_GRPC_PORT`	`6334`	gRPC 端口。
`QDRANT_REPLICATION_FACTOR`	`1`	每个分片的副本数。

Milvus

变量	默认值	说明
`MILVUS_URI`	`http://milvus-standalone:19530`	Milvus URI。对于 Zilliz Cloud，使用 Public Endpoint。
`MILVUS_DATABASE`	`default`	数据库名称。
`MILVUS_TOKEN`	（空）	认证令牌。对于 Zilliz Cloud，使用 API Key。
`MILVUS_USER`	`root`	用户名。
`MILVUS_PASSWORD`	`Milvus`	密码。日后如需修改，先在 Milvus 中修改该用户的密码，再将此值改为相同的密码。
`MILVUS_ENABLE_HYBRID_SEARCH`	`true`	添加 BM25 稀疏索引，使全文搜索可与向量相似性搜索并用。需要 Milvus 2.5.0 或更高版本；服务器版本较低时，Dify 会自动跳过该索引，全文搜索不会返回任何结果。创建时没有该索引的集合需要重新创建，全文搜索才能生效。
`MILVUS_ANALYZER_PARAMS`	（空）	文本字段的分析器参数。
`MILVUS_SECURE`	`false`	为 Milvus 连接启用单向 TLS。启用后，客户端通过 TLS 加密的 gRPC 连接并验证服务器证书。
`MILVUS_SERVER_PEM_PATH`	（空）	容器内 Milvus 服务器证书（PEM）的路径，在启用 `MILVUS_SECURE` 时用于验证服务器。
`MILVUS_SERVER_NAME`	（空）	用于验证的服务器名称（TLS SNI，需与证书的 CN 或 SAN 匹配）。设置 `MILVUS_SERVER_PEM_PATH` 时必填。

MyScale

变量	默认值	说明
`MYSCALE_HOST`	`myscale`	MyScale 主机。
`MYSCALE_PORT`	`8123`	MyScale 端口。
`MYSCALE_USER`	`default`	用户名。
`MYSCALE_PASSWORD`	（空）	密码。
`MYSCALE_DATABASE`	`dify`	数据库名称。
`MYSCALE_FTS_PARAMS`	（空）	全文搜索参数。多语言支持参考。

Couchbase

变量	默认值	说明
`COUCHBASE_CONNECTION_STRING`	`couchbase://couchbase-server`	Couchbase 集群的连接字符串。
`COUCHBASE_USER`	`Administrator`	用户名。
`COUCHBASE_PASSWORD`	`password`	密码。
`COUCHBASE_BUCKET_NAME`	`Embeddings`	存储桶名称。
`COUCHBASE_SCOPE_NAME`	`_default`	Scope 名称。

Hologres

变量	默认值	说明
`HOLOGRES_HOST`	（空）	主机名。
`HOLOGRES_PORT`	`80`	端口号。
`HOLOGRES_DATABASE`	（空）	数据库名称。
`HOLOGRES_ACCESS_KEY_ID`	（空）	Access key ID（用作 PG 用户名）。
`HOLOGRES_ACCESS_KEY_SECRET`	（空）	Access key secret（用作 PG 密码）。
`HOLOGRES_SCHEMA`	`public`	Schema 名称。
`HOLOGRES_TOKENIZER`	`jieba`	文本字段的分词器。
`HOLOGRES_DISTANCE_METHOD`	`Cosine`	距离计算方法。
`HOLOGRES_BASE_QUANTIZATION_TYPE`	`rabitq`	量化类型。
`HOLOGRES_MAX_DEGREE`	`64`	HNSW 最大度数。
`HOLOGRES_EF_CONSTRUCTION`	`400`	HNSW ef_construction 参数。

PGVector

使用自带的 PGVector 时，客户端的用户名、密码和数据库名称都不要设置，它们会跟随向量数据库服务配置中的容器设置。连接外部服务器时需设置这三项。

变量	默认值	说明
`PGVECTOR_HOST`	`pgvector`	主机名。
`PGVECTOR_PORT`	`5432`	端口号。
`PGVECTOR_USER`	`postgres`	用户名。
`PGVECTOR_PASSWORD`	`difyai123456`	密码。
`PGVECTOR_DATABASE`	`dify`	数据库名称。
`PGVECTOR_MIN_CONNECTION`	`1`	最小连接池连接数。
`PGVECTOR_MAX_CONNECTION`	`5`	最大连接池连接数。
`PGVECTOR_PG_BIGM`	`false`	启用 pg_bigm 扩展用于全文搜索。

Vastbase

使用自带的 Vastbase 时，VASTBASE_USER 和 VASTBASE_PASSWORD 保持默认值即可：它们与 docker-compose.yaml 中的 VB_USERNAME 和 VB_PASSWORD 一致。连接外部服务器时，将二者设为该服务器的凭据。

变量	默认值	说明
`VASTBASE_HOST`	`vastbase`	主机名。
`VASTBASE_PORT`	`5432`	端口号。
`VASTBASE_USER`	`dify`	用户名。
`VASTBASE_PASSWORD`	`Difyai123456`	密码。
`VASTBASE_DATABASE`	`dify`	数据库名称。
`VASTBASE_MIN_CONNECTION`	`1`	最小连接池连接数。
`VASTBASE_MAX_CONNECTION`	`5`	最大连接池连接数。

PGVecto.RS

使用自带的 PGVecto.RS 时，客户端的用户名、密码和数据库名称都不要设置，它们会跟随向量数据库服务配置中的容器设置。连接外部服务器时需设置这三项。

变量	默认值	说明
`PGVECTO_RS_HOST`	`pgvecto-rs`	主机名。
`PGVECTO_RS_PORT`	`5432`	端口号。
`PGVECTO_RS_USER`	`postgres`	用户名。
`PGVECTO_RS_PASSWORD`	`difyai123456`	密码。
`PGVECTO_RS_DATABASE`	`dify`	数据库名称。

AnalyticDB

变量	默认值	说明
`ANALYTICDB_KEY_ID`	（空）	阿里云 access key ID。创建 AccessKey。
`ANALYTICDB_KEY_SECRET`	（空）	阿里云 access key secret。
`ANALYTICDB_REGION_ID`	`cn-hangzhou`	区域标识。
`ANALYTICDB_INSTANCE_ID`	（空）	实例 ID，例如 `gp-xxxxxx`。创建实例。
`ANALYTICDB_ACCOUNT`	（空）	账户名称。创建账户。
`ANALYTICDB_PASSWORD`	（空）	账户密码。
`ANALYTICDB_NAMESPACE`	`dify`	命名空间（schema）。如不存在将自动创建。
`ANALYTICDB_NAMESPACE_PASSWORD`	（空）	命名空间密码。创建新命名空间时使用。
`ANALYTICDB_HOST`	（空）	直连主机（替代基于 API 的访问）。
`ANALYTICDB_PORT`	`5432`	直连端口。
`ANALYTICDB_MIN_CONNECTION`	`1`	最小连接池连接数。
`ANALYTICDB_MAX_CONNECTION`	`5`	最大连接池连接数。

TiDB Vector

变量	默认值	说明
`TIDB_VECTOR_HOST`	`tidb`	主机名。
`TIDB_VECTOR_PORT`	`4000`	端口号。
`TIDB_VECTOR_USER`	（空）	用户名。
`TIDB_VECTOR_PASSWORD`	（空）	密码。
`TIDB_VECTOR_DATABASE`	`dify`	数据库名称。
`TIDB_VECTOR_ENABLE_FULLTEXT_SEARCH`	`false`	为 TiDB Vector 上的知识库解锁全文检索和混合检索两种检索方式。新建的知识库表会带有多语言全文索引；已有表会在下次索引文档时补建该索引。要求 TiDB 部署支持全文索引。

MatrixOne

变量	默认值	说明
`MATRIXONE_HOST`	`matrixone`	主机名。
`MATRIXONE_PORT`	`6001`	端口号。
`MATRIXONE_USER`	`dump`	用户名。
`MATRIXONE_PASSWORD`	`111`	密码。
`MATRIXONE_DATABASE`	`dify`	数据库名称。

Chroma

变量默认值说明
CHROMA_HOSTchromaChroma 服务器主机。
CHROMA_PORT8000Chroma 服务器端口。
CHROMA_TENANTdefault_tenant租户名称。
CHROMA_DATABASEdefault_database数据库名称。
CHROMA_AUTH_PROVIDERchromadb.auth.token_authn.TokenAuthClientProvider认证提供者类。
CHROMA_AUTH_CREDENTIALSdifyai123456认证凭据。使用自带的 Chroma 时不要设置，其值跟随 CHROMA_SERVER_AUTHN_CREDENTIALS。连接外部服务器时需设置。

变量	默认值	说明
`CHROMA_HOST`	`chroma`	Chroma 服务器主机。
`CHROMA_PORT`	`8000`	Chroma 服务器端口。
`CHROMA_TENANT`	`default_tenant`	租户名称。
`CHROMA_DATABASE`	`default_database`	数据库名称。
`CHROMA_AUTH_PROVIDER`	`chromadb.auth.token_authn.TokenAuthClientProvider`	认证提供者类。
`CHROMA_AUTH_CREDENTIALS`	`difyai123456`	认证凭据。使用自带的 Chroma 时不要设置，其值跟随 `CHROMA_SERVER_AUTHN_CREDENTIALS`。连接外部服务器时需设置。

Oracle

变量	默认值	说明
`ORACLE_USER`	`dify`	Oracle 用户名。
`ORACLE_PASSWORD`	`dify`	Oracle 密码。
`ORACLE_DSN`	`oracle:1521/FREEPDB1`	数据源名称。
`ORACLE_CONFIG_DIR`	`/app/api/storage/wallet`	Oracle 配置目录。
`ORACLE_WALLET_LOCATION`	`/app/api/storage/wallet`	自治数据库的 Wallet 位置。
`ORACLE_WALLET_PASSWORD`	`dify`	Wallet 密码。
`ORACLE_IS_AUTONOMOUS`	`false`	是否使用 Oracle 自治数据库。

AlibabaCloud MySQL

变量	默认值	说明
`ALIBABACLOUD_MYSQL_HOST`	`127.0.0.1`	主机名。
`ALIBABACLOUD_MYSQL_PORT`	`3306`	端口号。
`ALIBABACLOUD_MYSQL_USER`	`root`	用户名。
`ALIBABACLOUD_MYSQL_PASSWORD`	`difyai123456`	密码。
`ALIBABACLOUD_MYSQL_DATABASE`	`dify`	数据库名称。
`ALIBABACLOUD_MYSQL_MAX_CONNECTION`	`5`	最大连接池连接数。
`ALIBABACLOUD_MYSQL_HNSW_M`	`6`	HNSW M 参数。

Relyt

变量	默认值	说明
`RELYT_HOST`	`db`	主机名。
`RELYT_PORT`	`5432`	端口号。
`RELYT_USER`	`postgres`	用户名。
`RELYT_PASSWORD`	`difyai123456`	密码。
`RELYT_DATABASE`	`postgres`	数据库名称。

OpenSearch

在本地开发中使用自带的 OpenSearch 时，在 envs/vectorstores/opensearch.env 中设置 OPENSEARCH_VERIFY_CERTS=false，因为该镜像自带的是演示证书。生产环境和外部服务器应使用客户端信任的证书，并保持证书验证开启。

变量	默认值	说明
`OPENSEARCH_HOST`	`opensearch`	主机名。
`OPENSEARCH_PORT`	`9200`	端口号。
`OPENSEARCH_SECURE`	`true`	使用 HTTPS。
`OPENSEARCH_VERIFY_CERTS`	`true`	验证 OpenSearch HTTPS 连接的 TLS 证书。
`OPENSEARCH_AUTH_METHOD`	`basic`	`basic` 使用用户名/密码。`aws_managed_iam` 通过 Boto3 凭证使用 AWS SigV4 请求签名（适用于 AWS 托管的 OpenSearch 或 Serverless）。
`OPENSEARCH_USER`	`admin`	用户名。仅在 `basic` 认证下使用。
`OPENSEARCH_PASSWORD`	`Qazwsxedc!@#123`	密码。仅在 `basic` 认证下使用。使用自带的 OpenSearch 时不要设置，其值跟随 `OPENSEARCH_INITIAL_ADMIN_PASSWORD`。连接外部服务器时需设置。
`OPENSEARCH_AWS_REGION`	（空）	AWS 区域。使用 `aws_managed_iam` 认证时必填。
`OPENSEARCH_AWS_SERVICE`	（空）	AWS 服务类型：`es`（托管集群）或 `aoss`（OpenSearch Serverless）。使用 `aws_managed_iam` 认证时必填。

腾讯云向量数据库

变量	默认值	说明
`TENCENT_VECTOR_DB_URL`	`http://127.0.0.1`	访问地址。控制台。
`TENCENT_VECTOR_DB_API_KEY`	`dify`	API key。密钥管理。
`TENCENT_VECTOR_DB_TIMEOUT`	`30`	请求超时（秒）。
`TENCENT_VECTOR_DB_USERNAME`	`dify`	账户名称。账户管理。
`TENCENT_VECTOR_DB_DATABASE`	`dify`	数据库名称。创建数据库。
`TENCENT_VECTOR_DB_SHARD`	`1`	分片数量。
`TENCENT_VECTOR_DB_REPLICAS`	`2`	副本数量。
`TENCENT_VECTOR_DB_ENABLE_HYBRID_SEARCH`	`false`	启用混合搜索。稀疏向量文档。

Elasticsearch

无论使用 VECTOR_STORE=elasticsearch 还是 VECTOR_STORE=elasticsearch-ja，都从 elasticsearch.defaults 复制创建 envs/vectorstores/elasticsearch.env，在其中自定义连接。

变量	默认值	说明
`ELASTICSEARCH_HOST`	`elasticsearch`	主机名。
`ELASTICSEARCH_PORT`	`9200`	端口号。
`ELASTICSEARCH_USERNAME`	`elastic`	用户名。
`ELASTICSEARCH_PASSWORD`	`elastic`	密码。
`ELASTICSEARCH_USE_CLOUD`	`false`	切换到 Elastic Cloud 模式。为 `true` 时使用 `ELASTICSEARCH_CLOUD_URL` 和 `ELASTICSEARCH_API_KEY` 代替 host/port/username/password。
`ELASTICSEARCH_CLOUD_URL`	（空）	Elastic Cloud 端点 URL。`ELASTICSEARCH_USE_CLOUD=true` 时必填。
`ELASTICSEARCH_API_KEY`	（空）	Elastic Cloud API key。`ELASTICSEARCH_USE_CLOUD=true` 时必填。
`ELASTICSEARCH_VERIFY_CERTS`	`false`	验证 SSL 证书。
`ELASTICSEARCH_CA_CERTS`	（空）	CA 证书路径。
`ELASTICSEARCH_REQUEST_TIMEOUT`	`100000`	请求超时（毫秒）。
`ELASTICSEARCH_RETRY_ON_TIMEOUT`	`true`	超时后重试。
`ELASTICSEARCH_MAX_RETRIES`	`10`	最大重试次数。

百度向量数据库

变量	默认值	说明
`BAIDU_VECTOR_DB_ENDPOINT`	`http://127.0.0.1:5287`	端点 URL。
`BAIDU_VECTOR_DB_CONNECTION_TIMEOUT_MS`	`30000`	连接超时（毫秒）。
`BAIDU_VECTOR_DB_ACCOUNT`	`root`	账户名称。
`BAIDU_VECTOR_DB_API_KEY`	`dify`	API key。
`BAIDU_VECTOR_DB_DATABASE`	`dify`	数据库名称。
`BAIDU_VECTOR_DB_SHARD`	`1`	分片数量。
`BAIDU_VECTOR_DB_REPLICAS`	`3`	副本数量。
`BAIDU_VECTOR_DB_INVERTED_INDEX_ANALYZER`	`DEFAULT_ANALYZER`	倒排索引分析器。
`BAIDU_VECTOR_DB_INVERTED_INDEX_PARSER_MODE`	`COARSE_MODE`	倒排索引解析模式。
`BAIDU_VECTOR_DB_AUTO_BUILD_ROW_COUNT_INCREMENT`	`500`	触发 Baidu Vector DB 端自动重建索引的绝对行数增量阈值。与 `_RATIO` 共同生效，先触及任一阈值的条件即生效。
`BAIDU_VECTOR_DB_AUTO_BUILD_ROW_COUNT_INCREMENT_RATIO`	`0.05`	触发自动重建索引的相对增长比例阈值（新增行数/现有行数）。与上述绝对阈值取先到者。
`BAIDU_VECTOR_DB_REBUILD_INDEX_TIMEOUT_IN_SECONDS`	`300`	客户端等待索引重建完成的最长时间（秒）。超时后客户端调用会失败，但服务端重建仍可能继续完成；稍后重试查询通常即可成功。

VikingDB

变量	默认值	说明
`VIKINGDB_ACCESS_KEY`	（空）	Access key。
`VIKINGDB_SECRET_KEY`	（空）	Secret key。
`VIKINGDB_REGION`	`cn-shanghai`	区域。
`VIKINGDB_HOST`	`api-vikingdb.xxx.volces.com`	API 主机。替换为你所在区域的端点。
`VIKINGDB_SCHEME`	`http`	协议方案（`http` 或 `https`）。
`VIKINGDB_CONNECTION_TIMEOUT`	`30`	连接超时（秒）。
`VIKINGDB_SOCKET_TIMEOUT`	`30`	Socket 超时（秒）。

Lindorm

变量	默认值	说明
`LINDORM_URL`	`http://localhost:30070`	Lindorm 搜索引擎 URL。控制台。
`LINDORM_USERNAME`	`admin`	用户名。
`LINDORM_PASSWORD`	`admin`	密码。
`LINDORM_USING_UGC`	`true`	使用 UGC 模式。
`LINDORM_QUERY_TIMEOUT`	`1`	查询超时（秒）。

OpenGauss

变量	默认值	说明
`OPENGAUSS_HOST`	`opengauss`	主机名。
`OPENGAUSS_PORT`	`6600`	端口号。
`OPENGAUSS_USER`	`postgres`	用户名。
`OPENGAUSS_PASSWORD`	`Dify@123`	密码。
`OPENGAUSS_DATABASE`	`dify`	数据库名称。
`OPENGAUSS_MIN_CONNECTION`	`1`	最小连接池连接数。
`OPENGAUSS_MAX_CONNECTION`	`5`	最大连接池连接数。
`OPENGAUSS_ENABLE_PQ`	`false`	启用 PQ 加速。

华为云搜索

变量	默认值	说明
`HUAWEI_CLOUD_HOSTS`	`https://127.0.0.1:9200`	集群端点 URL。
`HUAWEI_CLOUD_USER`	`admin`	用户名。
`HUAWEI_CLOUD_PASSWORD`	`admin`	密码。

Upstash Vector

变量	默认值	说明
`UPSTASH_VECTOR_URL`	（空）	Upstash Vector 端点 URL。
`UPSTASH_VECTOR_TOKEN`	（空）	Upstash Vector API 令牌。

TableStore

变量	默认值	说明
`TABLESTORE_ENDPOINT`	`https://instance-name.cn-hangzhou.ots.aliyuncs.com`	端点地址。将 `instance-name` 替换为你的实例名称。
`TABLESTORE_INSTANCE_NAME`	（空）	实例名称。
`TABLESTORE_ACCESS_KEY_ID`	（空）	Access key ID。
`TABLESTORE_ACCESS_KEY_SECRET`	（空）	Access key secret。
`TABLESTORE_NORMALIZE_FULLTEXT_BM25_SCORE`	`false`	标准化全文 BM25 分数。

ClickZetta

变量	默认值	说明
`CLICKZETTA_USERNAME`	（空）	用户名。
`CLICKZETTA_PASSWORD`	（空）	密码。
`CLICKZETTA_INSTANCE`	（空）	实例名称。
`CLICKZETTA_SERVICE`	`api.clickzetta.com`	服务端点。
`CLICKZETTA_WORKSPACE`	`quick_start`	工作空间名称。
`CLICKZETTA_VCLUSTER`	`default_ap`	虚拟集群。
`CLICKZETTA_SCHEMA`	`dify`	Schema 名称。
`CLICKZETTA_BATCH_SIZE`	`100`	操作批量大小。
`CLICKZETTA_ENABLE_INVERTED_INDEX`	`true`	启用倒排索引。
`CLICKZETTA_ANALYZER_TYPE`	`chinese`	分析器类型。
`CLICKZETTA_ANALYZER_MODE`	`smart`	分析器模式。
`CLICKZETTA_VECTOR_DISTANCE_FUNCTION`	`cosine_distance`	距离函数。

InterSystems IRIS

变量	默认值	说明
`IRIS_HOST`	`iris`	主机名。
`IRIS_SUPER_SERVER_PORT`	`1972`	Super Server 端口。
`IRIS_USER`	`_SYSTEM`	用户名。
`IRIS_PASSWORD`	`Dify@1234`	密码。
`IRIS_DATABASE`	`USER`	数据库名称。
`IRIS_SCHEMA`	`dify`	Schema 名称。
`IRIS_CONNECTION_URL`	（空）	完整连接 URL（覆盖单独设置）。
`IRIS_MIN_CONNECTION`	`1`	最小连接池连接数。
`IRIS_MAX_CONNECTION`	`3`	最大连接池连接数。
`IRIS_TEXT_INDEX`	`true`	启用文本索引。
`IRIS_TEXT_INDEX_LANGUAGE`	`en`	文本索引语言。

知识库配置

变量	默认值	说明
`UPLOAD_FILE_SIZE_LIMIT`	`15`	文档上传的最大文件大小（MB），包括 PDF、Word 文档等。超过时用户会看到「文件过大」错误。不适用于图片、视频或音频，它们有各自的大小限制（见下文）。
`UPLOAD_FILE_BATCH_LIMIT`	`5`	前端每次上传批次允许的最大文件数。
`UPLOAD_FILE_EXTENSION_BLACKLIST`	（空）	禁止上传的文件扩展名安全黑名单。逗号分隔，小写，不含点号。示例：`exe,bat,cmd,com,scr,vbs,ps1,msi,dll`。为空允许所有类型。
`SINGLE_CHUNK_ATTACHMENT_LIMIT`	`10`	单个知识库段落（chunk）中可嵌入的最大图片数量。
`IMAGE_FILE_BATCH_LIMIT`	`10`	每次上传批次的最大图片文件数。
`ATTACHMENT_IMAGE_FILE_SIZE_LIMIT`	`2`	知识库索引过程中从外部 URL 获取图片的最大大小（MB）。超过此大小的图片将被跳过。不同于 `UPLOAD_IMAGE_FILE_SIZE_LIMIT`（适用于直接上传）。
`ATTACHMENT_IMAGE_DOWNLOAD_TIMEOUT`	`60`	知识库索引过程中从外部 URL 下载图片的超时时间（秒）。响应缓慢或无响应的图片服务器在此超时后将被放弃。
`ETL_TYPE`	`dify`	文档提取库。`dify` 支持 txt、md、pdf、html、xlsx、docx、csv。`Unstructured` 额外支持 doc、msg、eml、ppt、pptx、xml、epub（需要 `UNSTRUCTURED_API_URL`）。
`UNSTRUCTURED_API_URL`	（空）	Unstructured.io API 端点。`ETL_TYPE` 为 `Unstructured` 时必填。`.ppt` 文件支持也需要此设置。示例：`http://unstructured:8000/general/v0/general`。
`UNSTRUCTURED_API_KEY`	（空）	Unstructured.io 认证的 API key。
`SCARF_NO_ANALYTICS`	`true`	禁用 Unstructured 库的遥测/分析收集。
`TOP_K_MAX_VALUE`	`10`	知识库检索中用户可设置的 `top_k` 参数最大值（每次搜索返回的结果数）。
`DATASET_MAX_SEGMENTS_PER_REQUEST`	`0`	每个数据集 API 请求的最大段落数。`0` 表示不限制。

标注导入

变量	默认值	说明
`ANNOTATION_IMPORT_FILE_SIZE_LIMIT`	`2`	标注导入的最大 CSV 文件大小（MB）。超过时返回 HTTP 413。
`ANNOTATION_IMPORT_MAX_RECORDS`	`10000`	每次标注导入的最大记录数。超过的文件必须分批导入。
`ANNOTATION_IMPORT_MIN_RECORDS`	`1`	每次标注导入所需的最少有效记录数。
`ANNOTATION_IMPORT_RATE_LIMIT_PER_MINUTE`	`5`	每个工作空间每分钟的最大标注导入请求数。超过时返回 HTTP 429。
`ANNOTATION_IMPORT_RATE_LIMIT_PER_HOUR`	`20`	每个工作空间每小时的最大标注导入请求数。
`ANNOTATION_IMPORT_MAX_CONCURRENT`	`5`	每个工作空间的最大并发标注导入任务数。过期任务在 2 分钟后自动清理。

模型配置

变量	默认值	说明
`PLUGIN_BASED_TOKEN_COUNTING_ENABLED`	`false`	使用基于插件的 token 计数以实现精确用量跟踪。禁用时 token 计数返回 0（更快但成本跟踪不够精确）。

多模态配置

变量	默认值	说明
`MULTIMODAL_SEND_FORMAT`	`base64`	文件发送到多模态 LLM 的方式。`base64` 将文件数据嵌入请求（兼容性更好，支持离线，负载更大）。`url` 发送签名 URL 让模型获取（更快，请求更小，但模型必须能访问 `FILES_URL`）。
`UPLOAD_IMAGE_FILE_SIZE_LIMIT`	`10`	直接上传图片的最大文件大小（MB），支持 jpg、png、webp、gif、svg。
`UPLOAD_VIDEO_FILE_SIZE_LIMIT`	`100`	直接上传视频的最大文件大小（MB），支持 mp4、mov、mpeg、webm。
`UPLOAD_AUDIO_FILE_SIZE_LIMIT`	`50`	直接上传音频的最大文件大小（MB），支持 mp3、m4a、wav、amr、mpga。

所有上传大小限制还受 NGINX_CLIENT_MAX_BODY_SIZE（默认 100M）限制。如果你将任何上传限制增大到超过 100 MB，还需要相应增大 NGINX_CLIENT_MAX_BODY_SIZE，否则 Nginx 会以 413 错误拒绝上传。

Sentry 配置

Sentry 提供错误跟踪和性能监控。每个服务有各自的 DSN 以分离错误报告。

变量	默认值	说明
`API_SENTRY_DSN`	（空）	API 和 Worker 的 Sentry DSN。为空则禁用这些服务的 Sentry。
`API_SENTRY_TRACES_SAMPLE_RATE`	`1.0`	API 和 Worker 请求中进行追踪的比例（0.01 = 1%，1.0 = 100%）。追踪记录请求在各服务间的流转过程。`API_SENTRY_DSN` 为空时不生效。
`API_SENTRY_PROFILES_SAMPLE_RATE`	`1.0`	在已追踪的请求中，进行 CPU 和内存性能分析的比例。性能分析用于查看代码各部分的耗时。有效采样率为追踪采样率 × 此采样率。`API_SENTRY_DSN` 为空时不生效。
`WEB_SENTRY_DSN`	（空）	Web 前端的 Sentry DSN。为空则禁用 Web 前端的 Sentry。
`PLUGIN_SENTRY_ENABLED`	`false`	为插件守护进程启用 Sentry。还需设置 `PLUGIN_SENTRY_DSN`。
`PLUGIN_SENTRY_DSN`	（空）	插件守护进程的 Sentry DSN。
`SENTRY_DSN`	（空）	各容器读取的 Sentry DSN。使用 Docker Compose 时，改为设置各服务对应的 DSN：API 和 Worker 用 `API_SENTRY_DSN`，Web 前端用 `WEB_SENTRY_DSN`，插件守护进程用 `PLUGIN_SENTRY_DSN`。
`SENTRY_TRACES_SAMPLE_RATE`	`1.0`	API 和 Worker 请求中进行追踪的比例。使用 Docker Compose 时，改为设置 `API_SENTRY_TRACES_SAMPLE_RATE`。
`SENTRY_PROFILES_SAMPLE_RATE`	`1.0`	API 和 Worker 在已追踪的请求中进行性能分析的比例。使用 Docker Compose 时，改为设置 `API_SENTRY_PROFILES_SAMPLE_RATE`。

Notion 集成配置

将 Dify 连接到 Notion 作为知识库数据源。在 https://www.notion.so/my-integrations 获取集成凭证。

变量	默认值	说明
`NOTION_INTEGRATION_TYPE`	`public`	`public` 使用标准 OAuth 2.0（需要 HTTPS 重定向 URL，需要 CLIENT_ID + CLIENT_SECRET）。`internal` 使用直接集成令牌（支持 HTTP）。本地部署建议使用 `internal`。
`NOTION_CLIENT_SECRET`	（空）	OAuth 客户端密钥。`public` 集成必填。
`NOTION_CLIENT_ID`	（空）	OAuth 客户端 ID。`public` 集成必填。
`NOTION_INTERNAL_SECRET`	（空）	Notion 的直接集成令牌。`internal` 集成必填。

邮件配置

Dify 发送邮件用于账户邀请、密码重置、登录验证码和人工输入节点通知。配置三个支持的提供商之一。邮件链接需要设置 CONSOLE_WEB_URL，参见通用变量。

变量	默认值	说明
`MAIL_TYPE`	`resend`	邮件提供商：`resend`、`smtp` 或 `sendgrid`。
`MAIL_DEFAULT_SEND_FROM`	（空）	所有外发邮件的默认「发件人」地址。必填。

Resend

变量	默认值	说明
`RESEND_API_URL`	`https://api.resend.com`	Resend API 端点。用于自部署 Resend 或代理时覆盖。
`RESEND_API_KEY`	（空）	Resend API key。`MAIL_TYPE=resend` 时必填。

SMTP

三种 TLS 模式：隐式 TLS（SMTP_USE_TLS=true、SMTP_OPPORTUNISTIC_TLS=false，端口 465）、STARTTLS（SMTP_USE_TLS=true、SMTP_OPPORTUNISTIC_TLS=true，端口 587）或明文（SMTP_USE_TLS=false，端口 25）。

变量	默认值	说明
`SMTP_SERVER`	（空）	SMTP 服务器地址。
`SMTP_PORT`	`465`	SMTP 服务器端口。STARTTLS 模式使用 `587`。
`SMTP_USERNAME`	（空）	SMTP 用户名。IP 白名单服务器可留空。
`SMTP_PASSWORD`	（空）	SMTP 密码。IP 白名单服务器可留空。
`SMTP_USE_TLS`	`true`	启用 TLS。为 `true` 且 `SMTP_OPPORTUNISTIC_TLS=false` 时使用隐式 TLS（`SMTP_SSL`）。
`SMTP_OPPORTUNISTIC_TLS`	`false`	使用 STARTTLS（显式 TLS）代替隐式 TLS。必须与 `SMTP_USE_TLS=true` 配合使用。
`SMTP_LOCAL_HOSTNAME`	（空）	覆盖 SMTP HELO/EHLO 中发送的主机名。在 Docker 中当 SMTP 服务器拒绝容器主机名时必填（常见于 Google Workspace、Microsoft 365）。设为你的域名，例如 `mail.yourdomain.com`。

SendGrid

变量	默认值	说明
`SENDGRID_API_KEY`	（空）	SendGrid API key。`MAIL_TYPE=sendgrid` 时必填。

更多详情请参阅 SendGrid 文档。

其他配置

控制台功能

变量	默认值	说明
`ENABLE_LEARN_APP`	`true`	显示 Learn Dify 版块：探索页的教程模板、工作室中还没有应用时的入门面板，以及帮助菜单中的显示开关。设为 `false` 可同时隐藏三处。
`ENABLE_SKILL`	`true`	在主导航中显示 Skills 入口。设为 `false` 后，工作区界面中不再显示 Skills。此时 Dify CLI（`difyctl`）中的 `difyctl get skill` 等命令会失败，返回 503 `skills_disabled` 错误。

认证与账户

默认情况下，用户以邮箱和密码登录，新账户通过工作空间邀请或初始设置向导创建。以下开关可放宽或收紧这一策略。

变量	默认值	说明
`ENABLE_EMAIL_PASSWORD_LOGIN`	`true`	使用邮箱和密码登录控制台。关闭后，登录页不再显示密码表单，密码登录、密码重置和自助注册接口均返回 403。至少保留一种登录方式：若全部关闭，登录页会提示未配置认证方式，在改回设置前无人能登录。
`ENABLE_EMAIL_CODE_LOGIN`	`false`	使用邮件发送的 6 位一次性验证码登录，无需密码。需要先配置邮件发送（参见邮件配置），否则验证码无法送达。当 `ALLOW_REGISTER=true` 时，未注册邮箱输入验证码即可同时创建账户，相当于一条自助注册途径。
`EMAIL_CODE_LOGIN_TOKEN_EXPIRY_MINUTES`	`5`	登录验证码的有效时长（分钟）。过期的验证码会被拒绝，需重新获取。
`EMAIL_CODE_LOGIN_MAX_ATTEMPTS`	`5`	单个登录验证码允许的最大输错次数，超过后验证码失效，需重新获取。
`ENABLE_SOCIAL_OAUTH_LOGIN`	`false`	在控制台登录页显示 GitHub 和 Google 登录按钮。按钮需在 API 服务上配置相应的 GitHub 或 Google OAuth 应用凭据后才可用；只开启开关而未配置凭据时，登录会失败。首次 OAuth 登录仅在 `ALLOW_REGISTER=true` 时创建账户。
`ALLOW_REGISTER`	`false`	允许自助创建账户：在登录页显示注册链接（需同时启用密码登录），并允许首次邮箱验证码或 OAuth 登录时创建账户。保持 `false` 即为仅限邀请的部署，工作空间邀请和初始设置向导始终不受影响。
`ALLOW_CREATE_WORKSPACE`	`false`	为不属于任何工作空间的账户自动创建工作空间，作用于自助注册及邮箱验证码或 OAuth 登录。设为 `false` 时，这类账户需等待工作空间邀请。设置向导创建的管理员工作空间不受影响。
`ENABLE_CHANGE_EMAIL`	`true`	允许用户在账户设置页修改账户邮箱。修改流程通过邮件验证码确认，因此需要配置邮件发送。设为 `false` 可锁定账户邮箱，例如需要与外部目录保持一致时。

LLMOps 追踪投递

应用运行的追踪数据由后台任务投递给所配置的 LLMOps 供应商（Langfuse、LangSmith、Arize/Phoenix 等）。使用 Docker Compose 部署时，在 docker/envs/core-services/api-worker.env 中设置这些变量。

变量	默认值	说明
`OPS_TRACE_QUEUE`	`ops_trace_v2`	承载以下任务的 Celery 队列：追踪投递及其重试、Agent 追踪的导出与恢复、每日追踪清理，以及 E2B 沙箱用量计量。修改此值时，API、Worker 和 Celery Beat 需设为相同的值；任务发到没有 Worker 监听的队列，就不会运行。 Docker Compose 自带的 Worker 会自动监听该队列。如果你自行设置了 `CELERY_QUEUES` 或 `CELERY_WORKER_QUEUES`，或用自己的 `-Q` 列表启动 Worker，需将该队列加入其中，否则这些任务不会运行，追踪数据也无法送达你的追踪供应商。滚动升级时，按 Dify 仓库中的 Ops 追踪滚动升级说明操作。只能包含字母、数字、`_`、`.` 和 `-`。
`OPS_TRACE_EXPORT_MAX_ATTEMPTS`	`6`	追踪供应商暂时不可用时，Dify 发送一条追踪数据最多尝试的次数，首次发送也计算在内。供应商拒收的追踪数据不会重试。不能小于 1。两次尝试的间隔从 10 秒开始，每次翻倍，最长 10 分钟。按默认值，最后一次尝试约在首次发送 5 分钟后进行；如果供应商故障持续更久，可调高此值。此变量替代旧的 `OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES` 和 `OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS`，后两者已不再读取。不要照搬原来的重试次数：间隔每次翻倍，同样的尝试次数会耗时长得多。
`ENABLE_TRACE_PAYLOAD_SWEEP_TASK`	`true`	每天 03:30 运行一次 Celery Beat 清理任务，删除投递中断后遗留在存储中、且已超过 2 天的追踪数据。时间以 `LOG_TZ` 为准（未设置时为 UTC）。只有在你另行删除 Dify 存储中 `trace_payloads/` 下的旧文件时，才设为 `false`；否则这些文件会一直留在存储中。
`OPS_AGENT_TRACE_ENABLED`	`false`	设为 `true` 后，Agent 应用以及含新 Agent 节点的 Workflow、Chatflow 应用，其追踪数据会包含 Agent 的模型调用和工具调用。应用调用的工作流工具内部的 Agent 不在其中。还需将 `DIFY_AGENT_APPLICATION_TRACING_ENABLED` 设为 `true`。为 `false` 时，Agent、Workflow 和 Chatflow 应用的追踪设置中会提示 Agent 追踪不可用。各应用仍需单独开启追踪、配置供应商，并保持采集 Agent 内部过程开启（默认开启）。
`DIFY_AGENT_APPLICATION_TRACING_ENABLED`	`false`	Agent 后端一侧的开关，与 `OPS_AGENT_TRACE_ENABLED` 配套；两者都设为 `true` 才能追踪 Agent。在 `docker/envs/core-services/dify-agent.env` 中设置，不要写在 `api-worker.env`：Agent 后端不读取这个文件。开启后，如果 Agent 运行已由所在应用追踪，就会发往该应用的追踪供应商，不再进入轨迹导出。
`ENABLE_APPLICATION_TRACE_RECONCILE_TASK`	`true`	仅在 `OPS_AGENT_TRACE_ENABLED` 为 `true` 时生效。每 30 秒运行一次后台任务，重新发送仍在等待投递的 Agent 追踪数据，并在保留期（默认 7 天）结束后删除 Dify 自己存储的 Agent 追踪数据。已经发送到追踪供应商的数据不受影响。

索引

变量	默认值	说明
`INDEXING_MAX_SEGMENTATION_TOKENS_LENGTH`	`4000`	知识库文档分块时每个文本段落的最大 token 长度。值越大每个块保留的上下文越多；值越小提供更细的粒度。

新用户默认配置

变量	默认值	说明
`NEW_USER_DEFAULT_PLUGIN_IDS`	（空）	创建新工作空间时自动安装的 Marketplace 插件 ID，逗号分隔。
`NEW_USER_DEFAULT_MODELS`	（空）	为新工作空间预设的默认模型，逗号分隔，格式为 `model_type:provider:model`。仅在设置了 `NEW_USER_DEFAULT_PLUGIN_IDS` 时生效：其中的插件安装完成后，才会应用这些默认模型。

工作流生成

变量	默认值	说明
`WORKFLOW_GENERATION_TIMEOUT_MS`	`180000`	界面等待一次 `/create` 或 `/refine` 应用生成的时长。由 web 容器读取。
`WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS`	`6`	单次 `/create` 或 `/refine` 生成请求中，并发构建节点配置的 LLM 调用上限。

令牌与邀请

所有令牌过期变量控制存储在 Redis 中的一次性令牌的有效时长。过期后用户必须请求新令牌。

变量	默认值	说明
`INVITE_EXPIRY_HOURS`	`72`	工作空间邀请链接的有效时长（小时）。
`RESET_PASSWORD_TOKEN_EXPIRY_MINUTES`	`5`	密码重置令牌的有效时长（分钟）。
`EMAIL_REGISTER_TOKEN_EXPIRY_MINUTES`	`5`	邮箱注册令牌的有效时长（分钟）。
`CHANGE_EMAIL_TOKEN_EXPIRY_MINUTES`	`5`	更改邮箱令牌的有效时长（分钟）。
`OWNER_TRANSFER_TOKEN_EXPIRY_MINUTES`	`5`	工作空间所有者转让令牌的有效时长（分钟）。

代码执行沙箱

以下设置决定 API 和 Worker 如何连接沙箱，以运行代码执行节点、模板转换节点、Jinja2 提示词和内置 Code 工具。

变量	默认值	说明
`CODE_EXECUTION_ENDPOINT`	`http://sandbox:8194`	沙箱服务端点。
`CODE_EXECUTION_API_KEY`	`dify-sandbox`	沙箱认证的 API 密钥。必须与 `SANDBOX_API_KEY` 一致，在 `docker/.env` 中将两者设为相同的值。
`CODE_EXECUTION_SSL_VERIFY`	`true`	验证沙箱连接的 SSL。开发环境使用自签名证书时可禁用。
`CODE_EXECUTION_CONNECT_TIMEOUT`	`10`	连接超时（秒）。
`CODE_EXECUTION_READ_TIMEOUT`	`60`	读取超时（秒）。
`CODE_EXECUTION_WRITE_TIMEOUT`	`10`	写入超时（秒）。
`CODE_EXECUTION_POOL_MAX_CONNECTIONS`	`100`	到沙箱服务的最大并发 HTTP 连接数。
`CODE_EXECUTION_POOL_MAX_KEEPALIVE_CONNECTIONS`	`20`	沙箱连接池中保持的最大空闲连接数。
`CODE_EXECUTION_POOL_KEEPALIVE_EXPIRY`	`5.0`	空闲沙箱连接关闭前的等待秒数。

代码与模板输出限制

API 和 Worker 进程按这些限制检查代码执行节点和模板转换节点返回的输出，这些变量在 envs/core-services/api-worker.env 中设置。沙箱服务不会读取它们。

变量	默认值	说明
`CODE_MAX_NUMBER`	`9223372036854775807`	代码节点输出允许的最大数值（64 位有符号整数最大值）。
`CODE_MIN_NUMBER`	`-9223372036854775807`	代码执行节点输出允许的最小数值。
`CODE_MAX_STRING_LENGTH`	`400000`	代码节点输出的最大字符串长度。防止无限字符串生成导致的内存耗尽。
`CODE_MAX_DEPTH`	`5`	输出数据结构的最大嵌套深度。
`CODE_MAX_PRECISION`	`20`	输出中浮点数的最大小数位数。
`CODE_MAX_STRING_ARRAY_LENGTH`	`30`	字符串数组输出的最大元素数。
`CODE_MAX_OBJECT_ARRAY_LENGTH`	`30`	对象数组输出的最大元素数。
`CODE_MAX_NUMBER_ARRAY_LENGTH`	`1000`	数字数组输出的最大元素数。
`TEMPLATE_TRANSFORM_MAX_LENGTH`	`400000`	模板转换节点输出的最大字符长度。

工作流运行时

变量	默认值	说明
`WORKFLOW_MAX_EXECUTION_STEPS`	`500`	每次工作流运行的最大节点执行数。工具节点调用工作流工具时，工具内部的节点也计入。超过此值将终止工作流。
`WORKFLOW_MAX_EXECUTION_TIME`	`3600`	每次工作流运行的最大实际运行时间（秒）。超过此值将终止工作流。与 `APP_MAX_EXECUTION_TIME` 配对的外层限制（两者默认均为一小时）：请同时增大两者。如果你使用 Agent，还需保持不低于 Agent 的运行时限（`DIFY_AGENT_RUN_TIMEOUT_SECONDS`）。
`WORKFLOW_CALL_MAX_DEPTH`	`5`	嵌套工作流调用工作流的最大深度。防止无限递归。
`MAX_VARIABLE_SIZE`	`204800`	单个工作流变量的最大大小（字节，200 KB）。
`WORKFLOW_FILE_UPLOAD_LIMIT`	`10`	单个文件上传字段（如用户输入节点的 File List）中最大文件数设置的上限。节点面板的最大文件数滑块以此值为上限；调高此值可允许更大的单字段配置。
`WORKFLOW_NODE_EXECUTION_STORAGE`	`rdbms`	工作流节点执行记录的存储位置。`rdbms` 将所有内容存储在数据库中。`hybrid` 将新数据存储在对象存储中，并从两者读取。
`DSL_EXPORT_ENCRYPT_DATASET_ID`	`true`	导出 DSL 文件时加密数据集 ID。设为 `false` 以导出明文 ID，便于跨环境导入。

工作流存储仓库

这些变量选择处理工作流执行数据的后端实现。默认的 SQLAlchemy 仓库将所有内容存储在数据库中。也可使用其他实现（例如 Celery、Logstore）实现不同的存储策略。

变量	默认值	说明
`CORE_WORKFLOW_EXECUTION_REPOSITORY`	`core.repositories.sqlalchemy_workflow_execution_repository.SQLAlchemyWorkflowExecutionRepository`	工作流执行记录的仓库实现。
`CORE_WORKFLOW_NODE_EXECUTION_REPOSITORY`	`core.repositories.sqlalchemy_workflow_node_execution_repository.SQLAlchemyWorkflowNodeExecutionRepository`	工作流节点执行记录的仓库实现。
`API_WORKFLOW_RUN_REPOSITORY`	`repositories.sqlalchemy_api_workflow_run_repository.DifyAPISQLAlchemyWorkflowRunRepository`	工作流运行 API 操作的服务层仓库。
`API_WORKFLOW_NODE_EXECUTION_REPOSITORY`	`repositories.sqlalchemy_api_workflow_node_execution_repository.DifyAPISQLAlchemyWorkflowNodeExecutionRepository`	工作流节点执行 API 操作的服务层仓库。
`LOOP_NODE_MAX_COUNT`	`100`	循环节点的最大迭代次数。防止无限循环。
`MAX_PARALLEL_LIMIT`	`10`	工作流中并行分支的最大数量。
`GRAPH_ENGINE_MAX_WORKERS`	`10`	每个 GraphEngine 实例的工作线程数。

工作流日志清理

变量	默认值	说明
`WORKFLOW_LOG_CLEANUP_ENABLED`	`false`	启用每天凌晨 2:00 自动清理工作流执行日志。
`WORKFLOW_LOG_RETENTION_DAYS`	`30`	清理前保留工作流日志的天数。
`WORKFLOW_LOG_CLEANUP_BATCH_SIZE`	`100`	每次清理批次处理的日志条目数。根据系统性能调整。
`WORKFLOW_LOG_CLEANUP_SPECIFIC_WORKFLOW_IDS`	（空）	限制清理范围的工作流 ID 列表（逗号分隔）。为空时清理所有工作流日志。

HTTP 请求节点

这些变量配置工作流中用于调用外部 API 的 HTTP 请求节点。

变量	默认值	说明
`HTTP_REQUEST_NODE_MAX_TEXT_SIZE`	`1048576`	最大文本响应大小（字节，1 MB）。超过此大小的响应将被截断。
`HTTP_REQUEST_NODE_MAX_BINARY_SIZE`	`10485760`	最大二进制响应大小（字节，10 MB）。
`HTTP_REQUEST_NODE_SSL_VERIFY`	`true`	验证 SSL 证书。测试自签名证书时可禁用。
`HTTP_REQUEST_MAX_CONNECT_TIMEOUT`	`10`	用户在工作流编辑器中可设置的最大连接超时（秒）。每个节点的超时不能超过此值。
`HTTP_REQUEST_MAX_READ_TIMEOUT`	`600`	最大读取超时上限（秒）。
`HTTP_REQUEST_MAX_WRITE_TIMEOUT`	`600`	最大写入超时上限（秒）。

Webhook

变量	默认值	说明
`WEBHOOK_REQUEST_BODY_MAX_SIZE`	`10485760`	最大 webhook 负载大小（字节，10 MB）。超过的负载以 413 错误拒绝。

SSRF 防护

Dify 的所有出站 HTTP 请求（HTTP 节点、图片下载等）都通过代理路由，该代理阻止对内部/私有 IP 范围的请求，防止服务端请求伪造（SSRF）攻击。

变量	默认值	说明
`SSRF_PROXY_HTTP_URL`	`http://ssrf_proxy:3128`	HTTP 请求的 SSRF 代理 URL。
`SSRF_PROXY_HTTPS_URL`	`http://ssrf_proxy:3128`	HTTPS 请求的 SSRF 代理 URL。
`SSRF_POOL_MAX_CONNECTIONS`	`100`	SSRF HTTP 客户端连接池的最大并发连接数。
`SSRF_POOL_MAX_KEEPALIVE_CONNECTIONS`	`20`	SSRF 连接池中保持的最大空闲连接数。
`SSRF_POOL_KEEPALIVE_EXPIRY`	`5.0`	空闲 SSRF 连接关闭前的等待秒数。

Agent 配置

变量	默认值	说明
`MAX_TOOLS_NUM`	`10`	Agent 可同时使用的最大工具数。
`MAX_ITERATIONS_NUM`	`99`	每次 Agent 执行的最大推理迭代次数。防止 Agent 无限循环。

Web 前端服务

这些变量仅由 Next.js Web 前端容器使用，不影响 Python 后端。

变量	默认值	说明
`TEXT_GENERATION_TIMEOUT_MS`	`60000`	流式文本生成 UI 的前端超时。如果流中断超过此时间，UI 暂停渲染。
`ALLOW_INLINE_STYLES`	`false`	允许在用户生成的 Markdown 内容中使用内联 `style` 属性和 `<style>` 块。出于安全考虑默认禁用（内联样式可能被用于钓鱼攻击）。仅在需要来自可信来源的富样式内容时启用。
`ALLOW_UNSAFE_DATA_SCHEME`	`false`	允许渲染 `data:` 协议的 URL。出于安全考虑默认禁用。
`MAX_TREE_DEPTH`	`50`	单条执行路径中的最大节点数。超过此限制的工作流无法发布。调整仅对新发布的工作流生效。
`MARKDOWN_FORM_FIELD_NAME_EXTRA_CHARS`	（空）	应用在聊天回复中通过 Markdown 渲染表单时，表单字段 `name` 属性额外接受的字符。默认情况下，字段名必须以字母开头，可包含字母、数字、下划线和连字符；名称含其他字符的字段不会被渲染。将额外字符连成一个字符串填入，半角和全角字符均可。示例：`()！？`
`MARKDOWN_FORM_FIELD_NAME_MAX_LENGTH`	`128`	应用在聊天回复中通过 Markdown 渲染表单时，表单字段 `name` 属性的最大长度，名称超长的字段不会被渲染。与 `MARKDOWN_FORM_FIELD_NAME_EXTRA_CHARS` 配合使用，后者决定字段名可包含哪些字符。如果生成的字段名超过上限，导致渲染出的表单缺少字段，可调高此值。必须为正整数。

NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW

默认值：true 启用 Go to Anything 命令面板中的 /create 和 /refine 命令，这两个命令可根据自然语言描述生成和修改 Workflow 与 Chatflow 应用。设为 false 即可隐藏它们。

新版 Agent

新 Agent 在 Docker Compose 部署中以额外服务运行：一个 Agent 后端、一个沙箱，以及供沙箱使用的专用出站代理。设置好 DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN 后，它们都会随 docker compose up 启动。该功能默认启用，且大部分设置会从现有的 Compose 配置中自动推导，因此通常只需关注下面这几个变量。

DIFY_AGENT_SERVER_SECRET_KEY

默认值：（自带默认值中的开发密钥，生产环境必须替换） Agent 后端的根密钥，用于派生内部令牌所需的密钥。这些令牌包括沙箱内 Agent 回调后端时用于认证的 Bearer 令牌。自带的默认值是一个公开的开发密钥。任何知道该密钥的人都能伪造这些令牌，因此生产环境使用前务必替换。值必须是不带填充的 base64url 文本，且解码后恰好为 32 字节；值格式错误时，Agent 后端将拒绝启动。可用以下命令生成：

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

DIFY_AGENT_API_TOKEN

默认值：（自带默认值中的开发令牌，生产环境必须替换） Dify API 和 Worker 调用 Agent 后端运行接口时出示的 Bearer 令牌。在 docker/.env 中设置，确保 API、Worker 和 Agent 后端使用相同的值。自带的默认值是一个公开的开发令牌。任何能访问 Agent 后端且知道该令牌的人都能发起运行，因此生产环境使用前务必替换为自己的随机值。

DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN

默认值：（空；运行时后端为默认的 local 时必填） Agent 后端向内置沙箱证明身份时使用的共享密钥。没有令牌时，这两个服务一启动就会退出并反复重启，所以要在启动 Dify 之前设置好。生成一个令牌：

openssl rand -hex 32

在 docker/.env 中设置此值，确保 Agent 后端和内置沙箱（local_sandbox）使用相同的值。它替代了旧变量 DIFY_AGENT_SHELLCTL_AUTH_TOKEN：此变量未设置或为空时，Compose 仍会从 docker/.env 中读取旧变量。只在 envs/core-services/dify-agent.env 中设置的值不会生效。如果你的令牌设在那里，将其移到 docker/.env，然后在 dify/docker 中运行 docker compose up -d。

NEXT_PUBLIC_ENABLE_AGENT_V2

默认值：true（Docker Compose）在 Web 界面中显示新 Agent：主导航中的 Agents 项，以及 Workflow 应用节点选择器中的新 Agent 节点。它取代了旧设置 ENABLE_AGENT_V2，后者在当前 Compose 文件下不再起作用。在 docker/envs/core-services/web.env 中将其设为 false，可隐藏新 Agent 并回退到经典 Agent 节点；改回 true 即可重新显示。无论哪种情况，都要重建 web 容器，然后强制刷新浏览器：

docker compose up -d web

NEXT_PUBLIC_ENABLE_AGENT_V2_IN_CHATFLOW

默认值：false 设为 true 后，Chatflow 应用的节点选择器中也会出现新 Agent 节点。仅在 NEXT_PUBLIC_ENABLE_AGENT_V2 为 true 时生效。

UPLOAD_SKILL_FILE_SIZE_LIMIT

默认值：50 Skill 包（.zip 或 .skill）的最大大小，单位为 MB。无论将包上传到 Agent，还是导入 Skill 库，都受此限制。超过限制时会返回大小错误。若将其提高到 100 以上，还需同步提高 NGINX_CLIENT_MAX_BODY_SIZE，否则 Nginx 会以 413 错误拒绝上传。此变量只限制打包后的文件。包内的内容另有上限，以字节为单位设置：

变量	默认值	说明
`SKILL_PACKAGE_MAX_UNCOMPRESSED_BYTES`	`209715200`	Skill 包解压后的总大小上限，单位为字节（200 MB）。超限的包会被拒绝：上传到 Agent 时报 `archive_too_large`，导入 Skill 库时报 `skill_too_large`。
`SKILL_PACKAGE_MAX_ENTRIES`	`5000`	Skill 包内的条目数上限。无论上传到 Agent 还是导入 Skill 库，文件夹都计入条目数。超限的包会被拒绝，报 `too_many_entries` 或 `too_many_files`。
`SKILL_PACKAGE_MAX_SKILL_MD_BYTES`	`1048576`	包内 `SKILL.md` 的大小上限，单位为字节（1 MB），超限时报 `skill_md_too_large`。适用于上传到 Agent 的 Skill 和应用包内附带的 Skill，不适用于导入 Skill 库的 Skill。

Agent 包与应用包限制

这些限制适用于所有应用包（.ifpkg），不只针对 Agent：所有类型的应用默认都导出为这种格式。导出和导入时都会检查这些限制，无论包是以文件上传还是从 URL 导入。只要超出任一限制，整个导出或导入就会失败，需先调高超出的那项限制再重试。上传超过 100 MB 的包时，还需调高 NGINX_CLIENT_MAX_BODY_SIZE，否则 Nginx 会先拒绝请求。包内附带的每个 Skill 还须符合 Skill 限制：

导入时，超出 UPLOAD_SKILL_FILE_SIZE_LIMIT 的 Skill 会导致整个导入失败；超出某项 SKILL_PACKAGE_* 限制的 Skill 则会被跳过，导入完成时给出警告。要导入该 Skill，调高它超出的限制后重新导入包。
导出时，超出某项 SKILL_PACKAGE_* 限制的 Skill 会导致整个导出失败，调高该限制后才能导出。

变量	默认值	说明
`AGENT_PACKAGE_MAX_BYTES`	`536870912`	包的大小上限，单位为字节（512 MB），打包后和解压后的大小都会检查。解压后的大小包含附带 Skill 的内容。附带大文件、大型 Skill 或大型工作流的应用或 Agent 导出、导入失败时，可调高此值。
`AGENT_PACKAGE_MAX_MANIFEST_BYTES`	`5242880`	包内每个 YAML 文件的大小上限，单位为字节（5 MB）。这些文件包括清单文件，以及 Agent 包中的 Agent 配置。附带的 Skill 和文件计入 `AGENT_PACKAGE_MAX_BYTES`，因此只有 Agent 配置本身超过 5 MB 时才需调高此值。不适用于应用的 DSL，DSL 仍保持固定的 10 MB 上限。
`AGENT_PACKAGE_MAX_ENTRIES`	`5000`	包内的条目数上限：附带的每个 Skill、文件和图标各算一个，另有几个固定条目。附带数千个 Skill 和文件的应用或 Agent 导出、导入失败时，可调高此值。
`APP_PACKAGE_MAX_WORKFLOW_TOOLS`	`20`	包内可附带的工作流数量上限。应用以工作流工具的形式调用已发布的工作流时，导出该应用会一并附带这些工作流，以及它们进一步调用的工作流。调用大量工作流工具的应用导出、导入失败时，可调高此值。不能小于 1。

AGENT_BACKEND_BASE_URL

默认值：http://agent_backend:5050 API 访问 Agent 后端所用的地址。在 Docker Compose 中保持默认值即可。其余变量用于配置打包的服务，或从现有的 Compose 配置中推导，通常无需改动。

变量	默认值	说明
`DIFY_AGENT_REDIS_URL`	（空；由 `REDIS_PASSWORD` 推导）	Agent 后端存储运行状态的 Redis 连接；Compose 默认指向打包的 `redis` 的 2 号数据库。
`DIFY_AGENT_REDIS_PREFIX`	`dify-agent`	Agent 后端 Redis 键的前缀。
`DIFY_AGENT_SHUTDOWN_GRACE_SECONDS`	`30`	Agent 后端停止时，等待进行中的运行结束的时长（秒）。
`DIFY_AGENT_RUN_RETENTION_SECONDS`	`7200`	每次 Agent 运行的记录和事件流在 Redis 中保留的秒数，从最后一次写入算起（默认 2 小时）。调低可更早释放 Redis 内存，但连接中断后可回放事件的时间也会缩短。
`DIFY_AGENT_RUN_EVENT_STREAM_MAX_LENGTH`	`5000`	每次 Agent 运行的 Redis 事件流保留的事件数上限（近似值）。调低可减少单次运行占用的 Redis 内存。达到上限后，写入新事件会删除最旧的事件。连接中断后，已删除的事件无法回放。
`DIFY_AGENT_STREAM_TEXT_DELTA_COALESCING_ENABLED`	`true`	将模型连续输出的文本增量合并成批，再写入 Redis 并流式发送。保持启用可减少 Redis 写入次数和事件数量。设为 `false` 可单独发送每个增量。工具调用等非文本事件的内容和顺序不变。
`DIFY_AGENT_STREAM_TEXT_DELTA_FLUSH_INTERVAL_MS`	`100`	合并后的文本增量按此间隔发布，单位为毫秒。调低可更频繁地更新文本，调高则每批文本更多、批次数更少。此间隔并非严格的时间限制。达到 `DIFY_AGENT_STREAM_TEXT_DELTA_MAX_CHARS` 时可提前发布。最小值为 1。要关闭合并，将 `DIFY_AGENT_STREAM_TEXT_DELTA_COALESCING_ENABLED` 设为 `false`。
`DIFY_AGENT_STREAM_TEXT_DELTA_MAX_CHARS`	`4096`	一批文本增量达到此字符数后，无需等待刷新间隔即可发布。调低可让较小的批次更早发布。每个增量都会完整加入批次，因此一批的字符数可能超过此阈值。最小值为 1。
`DIFY_AGENT_RUN_TIMEOUT_SECONDS`	`3600`	单次 Agent 运行中，模型调用和工具执行的总时限。超时的运行会失败，错误为 `agent_run_limit_exceeded`。 API 侧的 `APP_MAX_EXECUTION_TIME` 与 `WORKFLOW_MAX_EXECUTION_TIME`（默认 `3600`）若设得低于此值，会更早终止运行。在 `local` 后端下，高于 1 小时的值会生效：如需更长的运行时间，同时调高此值和 API 侧的两项限制。在 `e2b` 后端下，沙箱自身的 `DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS`（上限 3600）仍然生效，因此 E2B 上的运行最长仍为 1 小时。此变量替代旧的 `AGENT_BACKEND_RUN_TIMEOUT_SECONDS`，后者已不再读取。
`AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS`	`30`	与 Agent 后端单个 SSE 连接的读取超时时间。
`AGENT_BACKEND_STREAM_MAX_RECONNECTS`	`3`	Agent 后端流中断后，API 判定运行失败前的最大重连次数。
`DIFY_AGENT_PLUGIN_DAEMON_URL`	（空；由 `PLUGIN_DAEMON_URL` 推导）	Agent 后端调用工具所经过的插件守护进程地址。
`DIFY_AGENT_PLUGIN_DAEMON_API_KEY`	（空；由 `PLUGIN_DAEMON_KEY` 推导）	插件守护进程的凭据。使用 Docker Compose 时，改为在 `docker/.env` 中设置 `PLUGIN_DAEMON_KEY`。
`DIFY_AGENT_OUTBOUND_HTTP_CONNECT_TIMEOUT`	`10`	Agent 服务对外 HTTP 调用（如工具与插件流量）的连接超时（秒）。
`DIFY_AGENT_OUTBOUND_HTTP_READ_TIMEOUT`	`600`	读取超时（秒）；默认较宽松，以便较慢的工具响应和大文件下载能够完成。
`DIFY_AGENT_OUTBOUND_HTTP_WRITE_TIMEOUT`	`30`	对外请求的写入超时（秒）。
`DIFY_AGENT_OUTBOUND_HTTP_POOL_TIMEOUT`	`10`	请求等待连接池空闲连接的时长（秒）。
`DIFY_AGENT_OUTBOUND_HTTP_MAX_CONNECTIONS`	`100`	Agent 服务对外 HTTP 的连接池大小。
`DIFY_AGENT_OUTBOUND_HTTP_MAX_KEEPALIVE_CONNECTIONS`	`20`	保留供复用的空闲连接数。
`DIFY_AGENT_OUTBOUND_HTTP_KEEPALIVE_EXPIRY`	`30`	空闲连接在关闭前保留的秒数。
`DIFY_AGENT_INNER_API_URL`	（空；由 `PLUGIN_DIFY_INNER_API_URL` 推导）	Agent 后端内部调用的 Dify API 地址。
`DIFY_AGENT_INNER_API_KEY`	（空；由 `PLUGIN_DIFY_INNER_API_KEY` 推导）	回调 Dify API 的插件接口时使用的凭据。必须与 API 服务的 `INNER_API_KEY_FOR_PLUGIN` 一致，而非 `INNER_API_KEY`。使用 Docker Compose 时，改为在 `docker/.env` 中设置 `PLUGIN_DIFY_INNER_API_KEY`。
`DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT`	`http://local_sandbox:5004`	内置沙箱服务的地址。它替代了旧变量 `DIFY_AGENT_SHELLCTL_ENTRYPOINT`：此变量未设置或为空时，Compose 仍会读取旧变量。
`EXPOSE_LOCAL_SANDBOX_PORT`	`5004`	源码部署所用的中间件栈将 Agent 沙箱发布到宿主机的端口，供从源码运行的 Agent 后端通过 `http://localhost:5004` 访问。在该栈的 `middleware.env` 中设置；改动后，需将 Agent 后端 `.env` 中的 `DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT` 指向新端口。仅适用于中间件栈。完整的 Compose 栈将沙箱保留在内部网络中。
`DIFY_AGENT_STUB_API_BASE_URL`	`http://agent_backend:5050/agent-stub`	沙箱内 Agent 回调 Agent 后端的地址。使用内置的 `local` 沙箱时保持默认值即可。在 `openshell` 后端下，沙箱无法解析 Compose 服务名。需将其设为沙箱可访问、且能路由到 Agent 后端 `/agent-stub` 路径的地址。 5050 端口还提供启动 Agent 运行的 API，因此只对外暴露这一路径，例如通过反向代理。
`DIFY_AGENT_SANDBOX_FILES_BASE_URL`	`http://api:5001`	沙箱内 Agent 进行文件传输时使用的 Dify API 地址。Docker Compose 部署保持默认即可；使用远程沙箱后端时，需填写可公网访问的 Dify 地址。
`AGENT_BACKEND_BINDING_FILE_DOWNLOAD_TIMEOUT_SECONDS`	`240`	API 从 Agent 沙箱取文件时的等待时长，超时则传输失败。应高于 Agent 侧的 `DIFY_AGENT_BINDING_FILE_DOWNLOAD_COMMAND_TIMEOUT_SECONDS`。
`AGENT_BACKEND_HOME_SNAPSHOT_TIMEOUT_SECONDS`	`45`	API 等待 Agent 后端传输 home snapshot（捕获、删除快照，以及启动需要恢复快照的运行）的时长。如果 home 环境较大的 Agent 在应用构建或启动运行时失败，可调大该值。
`DIFY_AGENT_BINDING_FILE_DOWNLOAD_COMMAND_TIMEOUT_SECONDS`	`210`	沙箱中负责输出该文件的命令可运行的时长。默认值低于 API 侧超时，以便先呈现 Agent 自身的错误。
`DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT`	`50`	沙箱中的 Agent 向 Dify 回传单个文件的大小上限（MiB），例如它为回复生成的文件。
`SHELLCTL_ENABLE_PATH_ISOLATION`	`true`	通过内核级 Landlock 机制限制沙箱可读写的路径。需要 Linux 5.13 及以上，并已启用 Landlock。自 1.18.0 起，如果 Landlock 无法生效，沙箱会拒绝执行任何命令。在 `docker/envs/core-services/local-sandbox.env` 中设置；`.env` 中的值不会传给沙箱容器。
`DIFY_AGENT_SHELL_REDACT_PATTERNS`	（空）	JSON 正则数组，命中的内容会在 Agent 读取命令行输出前被遮盖，用于保护 API 密钥等机密。Agent 的内部令牌始终会被遮盖。
`LOGFIRE_CONSOLE`	`false`	调试时设为 `true`，Agent 后端会把自身的请求、对外 HTTP 调用和 Redis 的 span 输出到容器日志。与轨迹导出无关，轨迹导出从不往这里输出。自 1.18.0 起，Agent 运行的 span 不再出现在此日志中；要跟踪 Agent 运行，请使用轨迹导出。

DIFY_AGENT_RUNTIME_BACKEND

默认值：local 选择 Agent 沙箱的运行位置：

local：使用内置沙箱容器。
e2b：每个 Agent 的沙箱运行在一台 E2B 云虚拟机中，隔离性比内置容器更强。
openshell：通过你自行运维的 NVIDIA OpenShell 网关，让沙箱运行在你自己的基础设施上。

此变量和两个回调地址（DIFY_AGENT_STUB_API_BASE_URL 与 DIFY_AGENT_SANDBOX_FILES_BASE_URL）都在 envs/core-services/dify-agent.env 中设置。每种远程后端各有一组专用变量：

E2B

docker/docker-compose.e2b.yaml 叠加文件用于测试 E2B，会使用一个独立的空 PostgreSQL 数据卷，不要将其应用到已有部署。

变量	默认值	说明
`DIFY_AGENT_E2B_API_KEY`	（空；回退到 `E2B_API_KEY`/`E2B_API_TOKEN`）	E2B 账户密钥；`e2b` 后端必填。
`DIFY_AGENT_E2B_TEMPLATE`	`difys-default-team/dify-agent-local-sandbox`	Agent 运行所用的 E2B 沙箱模板。
`EXPOSE_AGENT_BACKEND_PORT`	`15050`	`docker-compose.e2b.yaml` 叠加文件将 Agent 后端（容器端口 `5050`）发布到宿主机的端口。宿主机上 15050 已被占用时改用其他端口。
`DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS`	`3600`	单个 E2B 沙箱保持活跃的时长，覆盖一次完整的 Agent 运行。3600 同时是硬上限，更高的值会被拒绝。应不低于 `DIFY_AGENT_RUN_TIMEOUT_SECONDS`。若沙箱的活跃时长短于运行的允许时长，运行会在未超时的情况下失去沙箱。
`DIFY_AGENT_E2B_SHELLCTL_PORT`	`5004`	沙箱控制服务在 E2B 虚拟机内监听的端口。

OpenShell

切换到 openshell 前，需准备好以下各项：

OpenShell 网关，版本不低于 0.0.106，且 agent_backend 容器能访问到它。
网关凭证：Bearer 令牌、mTLS 客户端证书对，或两者兼有。Compose 未内置证书挂载，需自行将证书文件以只读方式挂载到 agent_backend，并确保 UID 1001 可读取。
网关可用来启动沙箱的运行时镜像。
一个共享卷，用于存放 Agent 跨对话保留的长期文件。该卷需在 Compose 之外创建，以免被 docker compose down -v 删除。如果部署要服务彼此不信任的租户，请为每个租户分别准备 OpenShell 工作空间和卷。多个租户共用一个卷时，无法可靠地阻止一个租户访问另一个租户的长期文件。
沙箱回连 Dify 的网络路径：
- 沙箱可访问的回调地址。
- 通往 Agent 后端 /agent-stub 路径的路由。基础 Compose 文件没有发布 Agent 后端的 5050 端口。这个端口同时承载启动 Agent 运行的 API，所以不要整个暴露，只暴露 /agent-stub 路径，比如通过反向代理。

按以下步骤切换到 OpenShell：

参照 OpenShell 配置指南搭建网关并完成上述准备，包括构建运行时镜像、初始化共享卷、挂载证书、Kubernetes 配置和冒烟测试。
在 envs/core-services/dify-agent.env 中将 DIFY_AGENT_RUNTIME_BACKEND 设为 openshell，并填写下表中的变量。
运行 docker compose up -d 重建 Agent 后端。必填值缺失或格式有误时，Agent 后端会拒绝启动。
运行一个 Agent，确认配置无误。Agent 后端要等到 Agent 运行时，或在 Agent 的构建对话中点击应用时，才会首次连接网关。因此端点、凭证或镜像配置有误，要到那时才会暴露出来，表现为运行失败或应用失败。

运行结束后，沙箱会继续在网关上运行，直到 Dify 将其移除。因此规划网关容量时，除了活跃的沙箱，也要算上空闲的沙箱。内置沙箱的出站代理不覆盖 OpenShell 沙箱。如需限制其网络访问，设置 DIFY_AGENT_OPENSHELL_EGRESS_ALLOW。

变量	默认值	说明
`DIFY_AGENT_OPENSHELL_GATEWAY_ENDPOINT`	（空）	使用 `openshell` 后端时必填，未设置时 Agent 后端无法启动。OpenShell 网关的地址，格式为 `host:port`，不带协议前缀。必须能从 `agent_backend` 容器内部访问。网关运行在 Docker 宿主机上时，使用 `host.docker.internal:<port>` 而非 `localhost`；在 Linux 上还需通过 `extra_hosts` 将该名称映射到宿主机。示例：`gateway.example.com:17670`
`DIFY_AGENT_OPENSHELL_BEARER_TOKEN`	（空）	Agent 后端向网关出示的 OIDC Bearer 令牌。根据网关的认证方式，使用此令牌、mTLS 客户端证书对，或两者同时使用。仅在启动时读取一次：轮换令牌后需重建 Agent 后端。
`DIFY_AGENT_OPENSHELL_TLS_CA_PATH`	（空）	签发网关证书的 CA 证书在 `agent_backend` 容器内的路径。`DIFY_AGENT_OPENSHELL_INSECURE` 为 `true` 时忽略。
`DIFY_AGENT_OPENSHELL_TLS_CLIENT_CERT_PATH`	（空）	mTLS 客户端证书在 `agent_backend` 容器内的路径。需与 `DIFY_AGENT_OPENSHELL_TLS_CLIENT_KEY_PATH` 同时设置或同时留空；只设置其一时，Agent 后端无法启动。
`DIFY_AGENT_OPENSHELL_TLS_CLIENT_KEY_PATH`	（空）	mTLS 客户端私钥在 `agent_backend` 容器内的路径。需与 `DIFY_AGENT_OPENSHELL_TLS_CLIENT_CERT_PATH` 同时设置或同时留空；只设置其一时，Agent 后端无法启动。
`DIFY_AGENT_OPENSHELL_INSECURE`	`false`	改用明文 gRPC 而非 TLS 连接网关，不使用 TLS 路径。若设置了 Bearer 令牌，仍会通过该连接发送。仅用于对接明文网关的本地开发。
`DIFY_AGENT_OPENSHELL_WORKSPACE`	`default`	Agent 后端创建和管理沙箱所在的 OpenShell 工作空间。这是网关上的命名空间，不是 Dify 工作空间。
`DIFY_AGENT_OPENSHELL_SANDBOX_IMAGE`	`docker.io/library/dify-agent-runtime:latest`	网关为每个沙箱启动的容器镜像。默认值即 OpenShell 配置指南中构建命令生成的标签。网关的计算驱动必须能取到该镜像，只放在运行 Dify 的 Docker 守护进程上还不够：将镜像加载到网关的 Docker 守护进程中，或推送到网关可拉取的镜像仓库，并在此填写对应的镜像引用。请显式设置此变量。若没有任何 env 文件设置它，Agent 后端会回退到 `langgenius/dify-agent-local-sandbox:latest`，该镜像可能版本较旧，无法在 OpenShell 下启动。
`DIFY_AGENT_OPENSHELL_DRIVER_CONFIG`	（空）	使用 `openshell` 后端时必填。网关的计算驱动会给每个沙箱应用一份 JSON 配置，这份配置必须把共享卷挂载到 `DIFY_AGENT_OPENSHELL_SHARED_MOUNT_PATH`。具体结构取决于驱动。 JSON 无效或为空对象时，Agent 后端无法启动。Dify 不检查挂载本身，即使共享卷挂载到了其他路径，Agent 后端也会照常启动，因此请仔细核对挂载目标。 Docker 驱动示例（单租户，例如本地开发）：`{"docker":{"mounts":[{"type":"volume","source":"dify-agent-shared","target":"/mnt/dify-agent-shared","read_only":false}]}}`
`DIFY_AGENT_OPENSHELL_SHARED_MOUNT_PATH`	`/mnt/dify-agent-shared`	共享卷在每个沙箱内的挂载位置，必须与 `DIFY_AGENT_OPENSHELL_DRIVER_CONFIG` 中的挂载目标一致。每次在 Agent 的构建对话中点击应用时，Agent 的长期文件都会保存到这里。必须为绝对路径，否则 Agent 后端无法启动。
`DIFY_AGENT_OPENSHELL_SHELLCTL_AUTH_TOKEN`	（空）	使用 `openshell` 后端时必填，未设置时 Agent 后端无法启动。Agent 后端会在每个沙箱内启动命令服务，并用这个共享密钥向该服务证明身份。可设为任意随机字符串。与保护内置沙箱的 `DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN` 相互独立。
`DIFY_AGENT_OPENSHELL_EGRESS_ALLOW`	（空）	沙箱允许连接的 `host:port` 端点，以逗号分隔，不带协议前缀或路径。留空时不下发网络策略，出站访问遵循网关的默认设置。设置后，沙箱只能访问列出的端点，除非列出相应主机，否则安装软件包、访问网页都会失败。需包含 `DIFY_AGENT_STUB_API_BASE_URL` 和 `DIFY_AGENT_SANDBOX_FILES_BASE_URL` 的主机，否则 Agent 运行无法回调 Dify。任一条目格式有误，Agent 后端都无法启动。示例：`agent.example.com:443,dify.example.com:443`
`DIFY_AGENT_OPENSHELL_SHELLCTL_PORT`	`5004`	命令服务在每个沙箱内监听的回环端口。Agent 后端经由网关访问该端口，无需开放端口。仅当运行时镜像已占用 5004 时才需修改。
`DIFY_AGENT_OPENSHELL_READY_TIMEOUT_SECONDS`	`300`	等待新建或重启的沙箱就绪的时长（秒）。如果网关繁忙、沙箱仍在启动时 Agent 运行就已失败，可调高此值。
`DIFY_AGENT_OPENSHELL_EXEC_TIMEOUT_SECONDS`	`120`	Agent 后端经由网关在沙箱中执行每条初始化命令的时限（秒），例如复制 Agent 的长期文件或启动命令服务。不限制 Agent 自身执行的命令。长期文件较大的 Agent 无法启动新会话时，可调高此值。

Agent 轨迹导出

想在已有的追踪后端中查看 Agent 做了什么，可开启轨迹导出。开启后，Agent 后端会通过 OTLP/HTTP 把 Agent 运行的追踪数据（包括模型请求和工具调用）发送到 OpenTelemetry 收集器。部署中所有工作空间的运行都发往同一个收集器。每个 span 都带有所属工作空间、应用、Agent、终端用户、对话、工作流运行和节点的 ID，因此可按 dify.app_id、dify.conversation.id 等属性，把追踪数据筛选到单个应用或单个对话。即使关闭内容导出，这些 ID 也会导出。轨迹导出独立于 API 和 Worker 的 OpenTelemetry 插桩。 LLMOps 追踪投递则会影响它。LLMOps 追踪投递需要应用开发者在每个应用中单独配置 Langfuse 等供应商。在其中开启 Agent 追踪后，已由所在应用追踪的运行只发往该应用的追踪供应商，其余 Agent 运行仍进入收集器。按以下步骤开启轨迹导出：

在 docker/envs/core-services/dify-agent.env 中，将 DIFY_AGENT_TRAJECTORY_ENABLED 设为 true，将 DIFY_AGENT_TRAJECTORY_OTLP_TRACES_ENDPOINT 设为收集器的 traces URL。凭证（如有）写在 DIFY_AGENT_TRAJECTORY_OTLP_HEADERS 中。 Agent 后端不读取 api-worker.env，因此这些变量写在其中不会生效。
运行 docker compose up -d 重建 Agent 后端。任一值无效时，Agent 后端都无法启动，修正之前 Agent 运行会一直失败。
让 Agent 执行一个会调用工具的任务，然后在追踪后端中查找服务名为 dify-agent-trajectory 的工具调用 span。

DIFY_AGENT_TRAJECTORY_INCLUDE_CONTENT 设为 true 时，收集器会收到所有工作空间的提示词、系统指令、模型回复，以及工具参数和结果。请像保护对话本身一样限制对收集器的访问。

变量	默认值	说明
`DIFY_AGENT_TRAJECTORY_ENABLED`	`false`	开启轨迹导出。需同时设置 `DIFY_AGENT_TRAJECTORY_OTLP_TRACES_ENDPOINT`；设为 `true` 却未设置端点时，Agent 后端无法启动。
`DIFY_AGENT_TRAJECTORY_OTLP_TRACES_ENDPOINT`	（空）	收集器 OTLP/HTTP traces 端点的完整 URL，需包含路径，会按原样使用。不支持 gRPC 端点。必须使用 `http` 或 `https`，且不能包含凭证或 `#` 片段，否则 Agent 后端无法启动。凭证应写在 `DIFY_AGENT_TRAJECTORY_OTLP_HEADERS` 中。示例：`https://collector.example.com/v1/traces`
`DIFY_AGENT_TRAJECTORY_OTLP_HEADERS`	`{}`	每次导出时随请求发送的请求头，格式为 JSON 对象，如 `{"Authorization":"Bearer <token>"}`。用于传递收集器凭证。值不是 JSON 时（如 `Authorization=Bearer <token>`），Agent 后端无法启动。
`DIFY_AGENT_TRAJECTORY_SERVICE_NAME`	`dify-agent-trajectory`	写入每个导出 span 的 `service.name`，可在追踪后端中据此筛选。不能为空。
`DIFY_AGENT_TRAJECTORY_INCLUDE_CONTENT`	`false`	设为 `true` 可在 span 中加入对话内容：提示词、系统指令、模型回复，以及工具参数和结果。二进制内容始终不会导出。不开启时，追踪数据只显示每次运行的步骤和耗时，看不到具体说了什么。需要弄清 Agent 为何如此回答或行动时再开启，且前提是收集器可以存放所有工作空间的对话。
`DIFY_AGENT_TRAJECTORY_TRACE_CONTEXT_MODE`	`isolated`	Agent span 与其他追踪的关系。`isolated` 为每次 Agent 运行开启新的追踪；`shared` 让 Agent span 加入当前追踪，并沿用其采样决策。除非 Agent 后端自身的遥测数据也发往这个追踪后端，否则保持 `isolated`。只有为此设置了 `LOGFIRE_TOKEN` 或标准的 `OTEL_EXPORTER_OTLP_*` 变量，才会出现这种情况。其他情况下使用 `shared`，可能导致追踪缺少根 span。
`DIFY_AGENT_TRAJECTORY_MAX_QUEUE_SIZE`	`2048`	等待导出的 span 数量上限。高负载下出现 span 丢失时，可调高此值。
`DIFY_AGENT_TRAJECTORY_MAX_EXPORT_BATCH_SIZE`	`512`	每次导出请求包含的 span 数量上限。不得超过 `DIFY_AGENT_TRAJECTORY_MAX_QUEUE_SIZE`，否则 Agent 后端无法启动。
`DIFY_AGENT_TRAJECTORY_SCHEDULE_DELAY_MS`	`5000`	两次批量导出之间的间隔（毫秒）。
`DIFY_AGENT_TRAJECTORY_EXPORT_TIMEOUT_MS`	`5000`	导出单个批次的时限（毫秒）。不影响发往收集器的每个 HTTP 请求的超时，后者固定为 5 秒。

数据库服务

这些变量直接在 Docker Compose 中配置数据库与 Redis 容器。标注「中间件栈」的行只适用于源码部署所启动的那套栈，在其 middleware.env 中设置；完整的 Compose 栈将这些服务保留在内部网络中。

变量	默认值	说明
`PGDATA`	`/var/lib/postgresql/data/pgdata`	容器内 PostgreSQL 数据目录。
`MYSQL_HOST_VOLUME`	`./volumes/mysql/data`	挂载为 MySQL 数据卷的宿主机路径。
`PGDATA_HOST_VOLUME`	`./volumes/db/data`	挂载为 PostgreSQL 数据卷的宿主机路径。中间件栈；完整的 Compose 栈直接挂载 `./volumes/db/data`。
`REDIS_HOST_VOLUME`	`./volumes/redis/data`	挂载为 Redis 数据卷的宿主机路径。中间件栈。
`EXPOSE_POSTGRES_PORT`	`5432`	中间件栈将 PostgreSQL 发布到宿主机的端口。
`EXPOSE_MYSQL_PORT`	`3306`	中间件栈将 MySQL 发布到宿主机的端口。
`EXPOSE_REDIS_PORT`	`6379`	中间件栈将 Redis 发布到宿主机的端口。

沙箱服务

sandbox 服务负责运行代码执行节点、模板转换节点、Jinja2 提示词和内置 Code 工具。如需替换默认 API 密钥，在 docker/.env 中将 SANDBOX_API_KEY 和 CODE_EXECUTION_API_KEY 设为同一个强密钥，然后运行 docker compose up -d。两者不一致时，代码执行节点和模板转换节点会失败并返回 HTTP 401。保持 SANDBOX_ENABLE_NETWORK=true。即使代码不发起任何网络调用，Dify 每次在沙箱中运行代码时也都会请求网络权限。设为 false 后，上述功能都会失败，并报错 network is disabled, please enable it in the configuration。沙箱中的代码无法直接访问互联网：对外的 HTTP 和 HTTPS 请求都要经过 SSRF 代理。但它仍可直接连接同一内部网络（ssrf_proxy_network）中的 API、Worker、插件守护进程等服务。如果代码不得访问这些服务，需自行隔离沙箱的网络。

变量	默认值	说明
`SANDBOX_API_KEY`	`dify-sandbox`	沙箱认证的 API 密钥。必须与 `CODE_EXECUTION_API_KEY` 一致，在 `docker/.env` 中将两者设为相同的值。
`SANDBOX_GIN_MODE`	`release`	沙箱服务模式：`release` 或 `debug`。
`SANDBOX_WORKER_TIMEOUT`	`15`	单次代码运行的最大执行时间（秒）。
`SANDBOX_ENABLE_NETWORK`	`true`	代码执行节点、模板转换节点、Jinja2 提示词和内置 Code 工具都需要此设置。保持为 `true`。
`SANDBOX_HTTP_PROXY`	`http://ssrf_proxy:3128`	用于 SSRF 防护的 HTTP 代理，供支持代理的客户端使用。
`SANDBOX_HTTPS_PROXY`	`http://ssrf_proxy:3128`	用于 SSRF 防护的 HTTPS 代理，供支持代理的客户端使用。
`SANDBOX_PORT`	`8194`	沙箱服务端口。修改后，还需更新 `docker/envs/core-services/api-worker.env` 中的 `CODE_EXECUTION_ENDPOINT`，使用相同端口。

Nginx 反向代理

变量	默认值	说明
`NGINX_SERVER_NAME`	`_`	Nginx 服务器名称。`_` 匹配任何主机名。
`NGINX_HTTPS_ENABLED`	`false`	启用 HTTPS。为 `true` 时将 SSL 证书和密钥放在 `./nginx/ssl/` 中。
`NGINX_PORT`	`80`	HTTP 端口。
`NGINX_SSL_PORT`	`443`	HTTPS 端口（仅在 `NGINX_HTTPS_ENABLED=true` 时使用）。
`NGINX_SSL_CERT_FILENAME`	`dify.crt`	`./nginx/ssl/` 中的 SSL 证书文件名。
`NGINX_SSL_CERT_KEY_FILENAME`	`dify.key`	`./nginx/ssl/` 中的 SSL 私钥文件名。
`NGINX_SSL_PROTOCOLS`	`TLSv1.2 TLSv1.3`	允许的 TLS 协议版本。
`NGINX_WORKER_PROCESSES`	`auto`	Nginx 工作进程数。`auto` 匹配 CPU 核心数。
`NGINX_CLIENT_MAX_BODY_SIZE`	`100M`	最大请求体大小。影响代理级别的文件上传限制。
`NGINX_KEEPALIVE_TIMEOUT`	`65`	Keepalive 超时（秒）。
`NGINX_PROXY_READ_TIMEOUT`	`3600s`	代理读取超时。设置较高（1 小时）以支持长时间运行的 SSE 流。
`NGINX_PROXY_SEND_TIMEOUT`	`3600s`	代理发送超时。
`NGINX_ENABLE_CERTBOT_CHALLENGE`	`false`	在 `/.well-known/acme-challenge/` 接受 Let’s Encrypt ACME 验证请求。启用以支持自动证书续期。
`NGINX_SOCKET_IO_UPSTREAM`	`api_websocket:5001`	Nginx 将 `/socket.io/` 流量转发到的上游地址。默认指向由 `collaboration` profile 启动的专用 `api_websocket` 容器。仅当 WebSocket 服务运行在 Docker Compose 之外时才需要修改。

启用 HTTPS 后，还需要将通用变量中的 URL 变量（例如 CONSOLE_API_URL、CONSOLE_WEB_URL）更新为使用 https://。

Certbot 配置

变量	默认值	说明
`CERTBOT_EMAIL`	（空）	Let’s Encrypt 用于证书通知的邮箱地址。
`CERTBOT_DOMAIN`	（空）	SSL 证书的域名。
`CERTBOT_OPTIONS`	（空）	额外的 certbot CLI 选项（例如 `--force-renewal`、`--dry-run`）。

RESPECT_XFORWARD_HEADERS_ENABLED

默认值：Docker Compose 部署为 true，源码部署为 false 开启后，Dify 会读取 API 前面那一层代理发来的 X-Forwarded-For 请求头，从中获取每个访问者的 IP 地址。 Docker Compose 部署位于 Cloudflare、负载均衡器或其他代理之后时，保持开启，并配置自带的 Nginx 信任你的代理。配置完成前，所有访问者都会显示为代理的地址，共用同一份限额，比如登录邮件的发送限额。

此变量开启时，凡是能直接连接 API 的来源，都可以任意指定 Dify 看到的地址。伪造的地址可以绕过按 IP 的限流，也会留在账户最近登录 IP 这类记录里。Docker Compose 没有发布 API 端口，但同一 Docker 网络中的其他容器（比如代码沙箱）仍然可以直接连接。把 Docker 网络设为 internal 也拦不住它们。只允许可信的调用方直接连接 API。如果这些容器运行着不可信的代码，请用网络或防火墙规则把它们隔离开。这些容器仍需发出的 API 请求，都要经过一个会重写 X-Forwarded-For 的网关。如已发布 API 端口，请把端口关掉，不要拿关闭此变量来代替。变量一旦关闭，所有访问者都会显示为 Nginx 的地址。

源码部署时，如果 API 前面只有一层代理，这层代理会设置 X-Forwarded-For，而且是访问 API 的唯一入口，就开启此变量。

SSRF 代理

这些变量配置基于 Squid 的 SSRF 代理容器，该容器阻止对内部/私有网络的请求。

变量	默认值	说明
`SSRF_HTTP_PORT`	`3128`	代理监听端口。
`EXPOSE_SSRF_PROXY_PORT`	`3128`	源码部署所用的中间件栈将代理的 `SSRF_HTTP_PORT` 发布到宿主机的端口。在该栈的 `middleware.env` 中设置；完整的 Compose 栈将代理保留在内部网络中。
`EXPOSE_SANDBOX_PORT`	`8194`	中间件栈将代理的沙箱端口（`SSRF_SANDBOX_PROXY_PORT`）发布到宿主机的端口，从源码运行的代码经代理访问沙箱。
`SSRF_COREDUMP_DIR`	`/var/spool/squid`	核心转储目录。
`SSRF_SANDBOX_PROXY_PORT`	`8194`	SSRF 代理用于将出站流量反向代理转发到沙箱服务的监听端口。
`SSRF_SANDBOX_PROXY_HOST`	`sandbox`	SSRF 代理转发到的沙箱服务主机名。
`SSRF_PROXY_ALLOW_PRIVATE_IPS`	（空）	以逗号分隔的私有 IP 地址或 CIDR 网段。HTTP 请求节点、工具，以及同步自 Web 站点（对接自部署的 Firecrawl 或 WaterCrawl 服务时）发往这些地址的请求，SSRF 代理会放行。如需放行主机名，改用 `SSRF_PROXY_ALLOW_PRIVATE_DOMAINS`。放行网段内的每个地址同样会向任意 HTTP 请求节点和工具开放，因此只列出 Dify 必须访问的主机，不要放行整个私有网络。在 `envs/infrastructure/ssrf-proxy.env` 中设置。示例：`192.168.0.189,10.0.20.0/29`
`SSRF_PROXY_ALLOW_PRIVATE_DOMAINS`	（空）	以逗号分隔的主机名，即使解析到私有地址，SSRF 代理也会放行。每个名称只匹配该主机本身；以点开头（如 `.corp.internal`）则还会匹配其所有子域名。与 `SSRF_PROXY_ALLOW_PRIVATE_IPS` 一样尽量缩小范围，并在 `envs/infrastructure/ssrf-proxy.env` 中设置。示例：`firecrawl.internal`
`SSRF_DEFAULT_TIME_OUT`	`5`	代理请求的默认总超时（秒）。
`SSRF_DEFAULT_CONNECT_TIME_OUT`	`5`	默认连接超时（秒）。
`SSRF_DEFAULT_READ_TIME_OUT`	`5`	默认读取超时（秒）。
`SSRF_DEFAULT_WRITE_TIME_OUT`	`5`	默认写入超时（秒）。

Docker Compose

将 Compose 设置保存在 docker/.env 中：Compose 会在启动任何容器之前读取这些设置。修改 DB_TYPE 或 VECTOR_STORE 时，需相应更新 COMPOSE_PROFILES，具体步骤详见数据库配置和 VECTOR_STORE。

变量	默认值	说明
`COMPOSE_PROFILES`	`weaviate,postgresql,collaboration`	选择启动哪些自带服务容器。需包含所用自带数据库和向量数据库的 profile，如 `postgresql` 和 `weaviate`；缺少 profile 的自带服务不会启动。 `collaboration` profile 启动专用的 `api_websocket` 容器。只有将 `ENABLE_COLLABORATION_MODE` 设为 `false` 时，才可移除它。
`EXPOSE_NGINX_PORT`	`80`	映射到 Nginx HTTP 的宿主机端口。
`EXPOSE_NGINX_SSL_PORT`	`443`	映射到 Nginx HTTPS 的宿主机端口。

模型供应商与工具位置配置

自定义应用界面中可用的工具和模型供应商及其显示顺序。使用逗号分隔的值，项目之间不要有空格。

变量	默认值	说明
`POSITION_TOOL_PINS`	（空）	将特定工具固定在列表顶部。示例：`bing,google`。
`POSITION_TOOL_INCLUDES`	（空）	仅显示列出的工具。如未设置，所有工具可用。
`POSITION_TOOL_EXCLUDES`	（空）	隐藏特定工具（固定的工具不受影响）。
`POSITION_PROVIDER_PINS`	（空）	将特定模型供应商固定在顶部。示例：`openai,anthropic`。
`POSITION_PROVIDER_INCLUDES`	（空）	仅显示列出的模型供应商。如未设置，所有供应商可用。
`POSITION_PROVIDER_EXCLUDES`	（空）	隐藏特定模型供应商（固定的供应商不受影响）。

插件守护进程配置

插件守护进程是一个独立的服务，管理插件的生命周期（安装、执行、升级）。API 通过 HTTP 与其通信。

变量	默认值	说明
`PLUGIN_DAEMON_URL`	`http://plugin_daemon:5002`	插件守护进程服务 URL。
`PLUGIN_DAEMON_KEY`	（自带默认值中的开发密钥，生产环境必须替换）	API、Worker 和 Agent 后端向插件守护进程认证时使用的密钥。在 `docker/.env` 中设置，确保守护进程及其客户端使用相同的值。两边的值不一致时，对插件守护进程的调用会认证失败。使用高强度密钥，且与 `PLUGIN_DIFY_INNER_API_KEY` 不同。升级时保留现有可用的值。
`PLUGIN_DAEMON_PORT`	`5002`	插件守护进程监听端口。
`DB_SSL_MODE`	`disable`	插件守护进程连接 PostgreSQL 时使用的 `sslmode`。数据库强制 TLS 时设为 `require`。完整的 Compose 栈在 `docker/envs/core-services/plugin-daemon.env` 中设置。独立的中间件栈在 `middleware.env` 中设置。
`DB_PLUGIN_DATABASE`	`dify_plugin`	插件守护进程使用的数据库名称，与 Dify 主数据库分开。
`PLUGIN_DAEMON_TIMEOUT`	`600.0`	所有插件守护进程请求（安装、执行、列表）的超时时间（秒）。
`PLUGIN_MAX_PACKAGE_SIZE`	`52428800`	最大插件包大小（字节，50 MB）。在 Marketplace 下载时验证。
`PLUGIN_MAX_FILE_SIZE`	`52428800`	插件返回给 Dify 的单个文件的最大大小（字节，50 MB），例如工具插件输出的生成图片或文档。超过限制的文件会使本次调用失败，并报「file is too large」错误。
`PLUGIN_MODEL_SCHEMA_CACHE_TTL`	`3600`	缓存插件模型 Schema 的时间（秒）。减少重复查找。
`PLUGIN_MODEL_PROVIDERS_CACHE_ENABLED`	`true`	是否在 Redis 中缓存各租户的插件模型供应商列表。当插件由外部系统安装、无法在租户插件变更时使本部署的缓存失效时，应关闭此项。
`PLUGIN_MODEL_PROVIDERS_CACHE_TTL`	`86400`	在 Redis 中缓存各租户插件模型供应商列表的时长（秒），默认 24 小时。租户安装、卸载或升级插件时，Dify 会使该缓存失效。
`PLUGIN_DIFY_INNER_API_KEY`	（自带默认值中的开发密钥，生产环境必须替换）	回调 Dify API 时使用的共享凭据。在 `docker/.env` 中设置，确保 API、Worker、插件守护进程和 Agent 后端使用相同的值。各服务间的值不一致时，插件回调会认证失败。使用高强度密钥，且与 `PLUGIN_DAEMON_KEY` 不同。升级时保留现有可用的值。
`INNER_API_KEY_FOR_PLUGIN`	（自带默认值中的开发密钥，生产环境必须替换）	API 和 Worker 读取的插件回调密钥。使用 Docker Compose 时，改为在 `docker/.env` 中设置 `PLUGIN_DIFY_INNER_API_KEY`。 API 在处理插件回调（模型调用、工具调用、文件传输等）时校验此密钥。值不匹配时，这些调用会失败，但插件安装可能仍可正常进行。
`PLUGIN_DIFY_INNER_API_URL`	`http://api:5001`	插件守护进程回调的内部 API URL。
`PLUGIN_DEBUGGING_HOST`	`0.0.0.0`	插件远程调试连接的主机。
`PLUGIN_DEBUGGING_PORT`	`5003`	插件远程调试连接的端口。
`PLUGIN_REMOTE_INSTALL_HOST`	`localhost`	控制台向插件开发者展示的远程调试地址。仅用于展示，不影响插件守护进程实际监听的地址。需设置为开发者可访问的主机名（Compose 部署中通过 `EXPOSE_PLUGIN_DEBUGGING_HOST` 设置）；默认的 `localhost` 只适用于在 Docker 宿主机上开发的场景。
`PLUGIN_REMOTE_INSTALL_PORT`	`5003`	远程调试地址中的端口部分。必须与守护进程对外发布的调试端口（`EXPOSE_PLUGIN_DEBUGGING_PORT`）一致；Compose 部署中两者由同一变量保持同步。
`MARKETPLACE_ENABLED`	`true`	控制 Dify Marketplace 中的插件功能是否启用。禁用后，控制台会隐藏 Marketplace 插件的浏览和安装入口，API 拒绝从 Marketplace 安装和升级插件，周期性升级检查（`ENABLE_CHECK_UPGRADABLE_PLUGIN_TASK`）也会停止。插件版本也无法切换。控制台还会隐藏其余的 Marketplace 入口：帮助菜单中的创作者中心、主页模板区上方的查看更多，以及 Go to Anything 中的 `@plugin` 搜索范围。模板导入操作本身不受影响。但如果导入的模板依赖尚未安装的 Marketplace 插件，禁用 Marketplace 时将无法安装这些依赖。已安装的插件仍可正常使用；安装策略允许时，也仍可从 GitHub 或本地包安装插件。
`MARKETPLACE_API_URL`	`https://marketplace.dify.ai`	用于浏览和下载插件与模板，以及检查插件升级的 Marketplace API 端点。 Dify API 服务、后台任务进程、Web 服务端和用户浏览器都会使用该 URL，因此每个运行环境都需要能访问它。
`MARKETPLACE_URL`	（空；Compose 部署回退到 `https://marketplace.dify.ai`）	Marketplace 链接使用的基础 URL，包括插件详情页和「集成」页面的 Marketplace 入口。Dify 还会根据该值生成 Creator Center 指南链接。与 `MARKETPLACE_API_URL` 不同：后者是提供 Marketplace 数据和安装包的 API 端点。
`FORCE_VERIFYING_SIGNATURE`	`true`	安装插件前要求有效签名。防止安装被篡改或未签名的包。
`PLUGIN_MAX_EXECUTION_TIMEOUT`	`600`	插件执行超时（秒，插件守护进程侧）。应与 API 侧的 `PLUGIN_DAEMON_TIMEOUT` 匹配。
`PIP_MIRROR_URL`	（空）	插件守护进程安装插件依赖时使用的自定义 PyPI 镜像 URL。适用于加速安装或离线环境。
`UV_CACHE_DIR`	（空；回退到 `PLUGIN_WORKING_PATH` 下的 `.uv-cache`）	插件守护进程安装插件依赖时缓存 Python 包的目录。如果在 Docker 或 WSL 的绑定挂载上安装插件依赖时出现权限错误，将其设为容器内的路径，如 `/tmp/.uv-cache`。在 `docker/envs/core-services/plugin-daemon.env` 中设置。需要插件守护进程 0.6.11 或更高版本。

Creator Center 配置

Creator Center（creators.dify.ai）是用户将 Dify 应用以模板形式提交的入口。提交的模板经审核通过后会在 Dify Marketplace 上线。Dify 控制台会在新的浏览器标签页中打开 Creator Center 页面。工作室中的「发布到 Marketplace」操作会把应用导出为应用包（.ifpkg）并上传至 Creator Center，用户随后在那里完成提交。详见发布应用到 Marketplace。

变量	默认值	说明
`CREATORS_PLATFORM_FEATURES_ENABLED`	`true`	控制应用的「发布」面板中是否显示「发布到 Marketplace」操作。设为 `false` 时该操作被隐藏，对应的控制台 API 也会返回 403。适用于不希望用户拥有一键对外提交模板路径的部署。
`CREATORS_PLATFORM_API_URL`	`https://creators.dify.ai`	Creator Center 服务的基础 URL。API 服务和用户浏览器都会使用这个地址，因此两端都必须能访问它。
`CREATORS_PLATFORM_OAUTH_CLIENT_ID`	（空）	用于免登录 SSO 进入 Creator Center 的 OAuth 客户端 ID。自部署环境请保持为空。留空时仍可发布，但尚未登录的用户需要手动登录 Creator Center。填入未在本部署 OAuth 服务中注册的 ID 会导致「发布到 Marketplace」失败。

OTLP / OpenTelemetry 配置

OpenTelemetry 提供分布式追踪和指标收集。启用后，Dify 对 Flask 进行仪器化并将遥测数据导出到 OTLP 收集器。

变量	默认值	说明
`ENABLE_OTEL`	`false`	OpenTelemetry 仪器化的主开关。
`OTLP_TRACE_ENDPOINT`	（空）	专用追踪端点 URL。如未设置，回退到 `{OTLP_BASE_ENDPOINT}/v1/traces`。
`OTLP_METRIC_ENDPOINT`	（空）	专用指标端点 URL。如未设置，回退到 `{OTLP_BASE_ENDPOINT}/v1/metrics`。
`OTLP_BASE_ENDPOINT`	`http://localhost:4318`	OTLP 收集器基础 URL。当未设置特定追踪/指标端点时作为回退使用。
`OTLP_API_KEY`	（空）	OTLP 认证的 API key。以 `Authorization: Bearer` 头发送。
`OTEL_EXPORTER_TYPE`	`otlp`	导出器类型。`otlp` 导出到收集器；其他值使用控制台导出器（用于调试）。
`OTEL_EXPORTER_OTLP_PROTOCOL`	（空）	OTLP 导出协议。`grpc` 使用 gRPC 导出器；其他值使用 HTTP。
`OTEL_SAMPLING_RATE`	`0.1`	追踪的请求比例（0.1 = 10%）。在高流量生产环境中降低此值可减少开销。
`OTEL_BATCH_EXPORT_SCHEDULE_DELAY`	`5000`	批次导出之间的延迟（毫秒）。
`OTEL_MAX_QUEUE_SIZE`	`2048`	丢弃前可排队的最大 span 数。
`OTEL_MAX_EXPORT_BATCH_SIZE`	`512`	每次导出批次的最大 span 数。
`OTEL_METRIC_EXPORT_INTERVAL`	`60000`	指标导出间隔（毫秒）。
`OTEL_BATCH_EXPORT_TIMEOUT`	`10000`	批次 span 导出超时（毫秒）。
`OTEL_METRIC_EXPORT_TIMEOUT`	`30000`	指标导出超时（毫秒）。

杂项

变量	默认值	说明
`CSP_WHITELIST`	（空）	在 Content Security Policy 头中允许的额外域名。
`NEXT_TELEMETRY_DISABLED`	`0`	设为 `1` 可关闭 Next.js 的匿名遥测，Compose 栈默认保持开启。
`ALLOW_EMBED`	`false`	允许 Dify 页面在 iframe 中嵌入。为 `false` 时设置 `X-Frame-Options: DENY` 以防止点击劫持。
`SWAGGER_UI_ENABLED`	`false`	在 `SWAGGER_UI_PATH` 暴露 Swagger UI 以浏览 API 文档。Swagger 端点绕过认证。
`SWAGGER_UI_PATH`	`/swagger-ui.html`	Swagger UI 的 URL 路径。
`MAX_SUBMIT_COUNT`	`100`	线程池中用于并行工作流节点执行的最大并发任务提交数。
`TENANT_ISOLATED_TASK_CONCURRENCY`	`1`	每个租户同时处理的文档索引或 RAG 管道任务数。增大可加快索引速度但增加数据库负载。
`DIFY_ENV_NACOS_REQUEST_TIMEOUT`	`10.0`	向 Nacos 配置服务器发送 HTTP 请求的超时时间（秒）。
`DIFY_ENV_NACOS_CONNECT_TIMEOUT`	`3.0`	与 Nacos 配置服务器建立连接的超时时间（秒）。

定时任务配置

Dify 使用 Celery Beat 按可配置的计划运行后台维护任务。

变量	默认值	说明
`ENABLE_CLEAN_EMBEDDING_CACHE_TASK`	`false`	每天凌晨 2:00 从数据库中删除过期的嵌入缓存记录。管理数据库大小。
`ENABLE_CLEAN_UNUSED_DATASETS_TASK`	`false`	禁用在保留期内没有活动的知识库中的文档。每天凌晨 3:00 运行。
`ENABLE_CLEAN_MESSAGES`	`false`	每天凌晨 4:00 删除超过 `SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS` 保留期的对话消息。
`ENABLE_MAIL_CLEAN_DOCUMENT_NOTIFY_TASK`	`false`	向工作空间所有者发送邮件，列出被清理任务自动禁用文档的知识库。每周一上午 10:00 运行。
`ENABLE_DATASETS_QUEUE_MONITOR`	`false`	监控 Redis 中的数据集处理队列积压。当队列超过阈值时发送邮件警报。
`QUEUE_MONITOR_INTERVAL`	`30`	检查队列的频率（分钟）。
`QUEUE_MONITOR_THRESHOLD`	`200`	触发警报邮件的队列大小。
`QUEUE_MONITOR_ALERT_EMAILS`	（空）	接收队列警报的邮箱地址（逗号分隔）。
`ENABLE_CHECK_UPGRADABLE_PLUGIN_TASK`	`true`	每 15 分钟检查 Marketplace 中是否有更新的插件版本。根据每个租户的自动升级计划分发升级任务。
`ENABLE_WORKFLOW_SCHEDULE_POLLER_TASK`	`true`	启用工作流调度轮询器，检查并触发计划的工作流运行。
`WORKFLOW_SCHEDULE_POLLER_INTERVAL`	`1`	检查到期计划工作流的频率（分钟）。
`WORKFLOW_SCHEDULE_POLLER_BATCH_SIZE`	`100`	每次轮询周期获取的最大到期计划数。
`WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK`	`0`	熔断器：每个周期分发的最大计划数。`0` 表示不限制。
`ENABLE_WORKFLOW_RUN_CLEANUP_TASK`	`false`	启用工作流运行记录的自动清理。
`ENABLE_CREATE_TIDB_SERVERLESS_TASK`	`false`	预创建 TiDB Serverless 集群用于向量数据库池。
`ENABLE_UPDATE_TIDB_SERVERLESS_STATUS_TASK`	`false`	定期更新 TiDB Serverless 集群状态。
`ENABLE_HUMAN_INPUT_TIMEOUT_TASK`	`true`	检查过期的人工输入表单，恢复或停止超时的工作流。
`HUMAN_INPUT_TIMEOUT_TASK_INTERVAL`	`1`	检查过期人工输入表单的频率（分钟）。
`ENABLE_CONVERSATION_CLEANUP_TASK`	`true`	对话删除的兜底清理。对话删除后立即不可见，其消息以及对话中由工具生成的文件由后台任务清除，终端用户上传的文件会保留。该定时清理会为清理任务丢失的对话重新派发任务，避免数据残留。
`CONVERSATION_CLEANUP_TASK_INTERVAL`	`5`	清理任务的运行频率（分钟）。
`CONVERSATION_CLEANUP_BATCH_SIZE`	`100`	每次最多重新派发的对话数。

记录保留与清理

这些变量控制旧消息与工作流运行记录的定时清理，超过保留天数的记录会分批删除。

变量	默认值	说明
`SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS`	`30`	超过此天数的记录有资格被删除。
`SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_SIZE`	`1000`	每次清理批次处理的记录数。
`SANDBOX_EXPIRED_RECORDS_CLEAN_BATCH_MAX_INTERVAL`	`200`	清理批次间的最大随机延迟（毫秒），用于减少数据库负载。
`SANDBOX_EXPIRED_RECORDS_CLEAN_TASK_LOCK_TTL`	`90000`	Redis 锁 TTL（秒，约 25 小时），防止清理任务并发执行。

阿里云 SLS 日志存储配置

与阿里云简单日志服务（SLS）的可选集成，用于将工作流执行日志存储在外部而非数据库中。通过将仓库配置变量设置为使用 logstore 实现来启用。

变量	默认值	说明
`ALIYUN_SLS_ACCESS_KEY_ID`	（空）	阿里云 SLS 认证的 access key ID。
`ALIYUN_SLS_ACCESS_KEY_SECRET`	（空）	阿里云 SLS 认证的 access key secret。
`ALIYUN_SLS_ENDPOINT`	（空）	SLS 服务端点 URL（例如 `cn-hangzhou.log.aliyuncs.com`）。
`ALIYUN_SLS_REGION`	（空）	阿里云区域（例如 `cn-hangzhou`）。
`ALIYUN_SLS_PROJECT_NAME`	（空）	存储工作流日志的 SLS 项目名称。
`ALIYUN_SLS_LOGSTORE_TTL`	`365`	SLS logstore 的数据保留天数。使用 `3650` 表示永久存储。
`LOGSTORE_DUAL_WRITE_ENABLED`	`false`	同时将工作流数据写入 SLS 和 PostgreSQL。迁移到 SLS 时有用。
`LOGSTORE_DUAL_READ_ENABLED`	`true`	当 SLS 无结果时回退到 PostgreSQL。迁移期间历史数据仅存在于数据库中时有用。
`LOGSTORE_ENABLE_PUT_GRAPH_FIELD`	`true`	在 SLS 日志中包含完整的工作流图定义。设为 `false` 可通过省略大型图数据来减少存储。

事件总线配置

API 和 Celery 工作进程之间基于 Redis 的事件传输。

变量	默认值	说明
`EVENT_BUS_REDIS_URL`	（空）	事件流的 Redis 连接 URL。为空时使用主 Redis 连接设置。
`EVENT_BUS_REDIS_CHANNEL_TYPE`	`pubsub`	传输类型：`pubsub`（Pub/Sub，至多一次投递）、`sharded`（分片 Pub/Sub）或 `streams`（Redis Streams，至少一次投递）。
`EVENT_BUS_REDIS_USE_CLUSTERS`	`false`	为事件总线启用 Redis 集群模式。建议在大规模部署中使用。

向量数据库服务配置

这些变量配置向量数据库容器本身。

Weaviate 服务

如需强制身份认证，在 docker/envs/vectorstores/weaviate.env 中设置 WEAVIATE_AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=false。在同一文件中，将 WEAVIATE_API_KEY 设为强密钥，并将其加入 WEAVIATE_AUTHENTICATION_APIKEY_ALLOWED_KEYS。只替换密钥不会关闭匿名访问。

变量	默认值	说明
`WEAVIATE_PERSISTENCE_DATA_PATH`	`/var/lib/weaviate`	容器内的数据持久化目录。
`WEAVIATE_QUERY_DEFAULTS_LIMIT`	`25`	默认查询结果限制。
`WEAVIATE_AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED`	`true`	允许匿名访问。设为 `false` 可要求身份认证。
`WEAVIATE_DEFAULT_VECTORIZER_MODULE`	`none`	默认向量化模块。
`WEAVIATE_CLUSTER_HOSTNAME`	`node1`	集群节点主机名。
`WEAVIATE_AUTHENTICATION_APIKEY_ENABLED`	`true`	启用 API key 认证。
`WEAVIATE_AUTHENTICATION_APIKEY_ALLOWED_KEYS`	（自带默认值中的开发密钥，生产环境必须替换）	允许的 API 密钥。自带密钥与 `WEAVIATE_API_KEY` 的默认值一致。替换时，还需更新客户端密钥。
`WEAVIATE_AUTHENTICATION_APIKEY_USERS`	`hello@dify.ai`	与 API key 关联的用户。
`WEAVIATE_AUTHORIZATION_ADMINLIST_ENABLED`	`true`	启用管理员列表授权。
`WEAVIATE_AUTHORIZATION_ADMINLIST_USERS`	`hello@dify.ai`	管理员用户。
`WEAVIATE_DISABLE_TELEMETRY`	`false`	禁用 Weaviate 遥测。
`WEAVIATE_ENABLE_TOKENIZER_GSE`	`false`	启用 GSE 分词器（中文）。
`WEAVIATE_ENABLE_TOKENIZER_KAGOME_JA`	`false`	启用 Kagome 分词器（日文）。
`WEAVIATE_ENABLE_TOKENIZER_KAGOME_KR`	`false`	启用 Kagome 分词器（韩文）。
`WEAVIATE_HOST_VOLUME`	`./volumes/weaviate`	挂载为 Weaviate 数据卷的宿主机路径。中间件栈（源码部署），在其 `middleware.env` 中设置；完整的 Compose 栈直接挂载 `./volumes/weaviate`。
`EXPOSE_WEAVIATE_PORT`	`8080`	源码部署所用的中间件栈将 Weaviate REST API 发布到宿主机的端口，从源码运行的 Dify 通过 `http://localhost:8080` 访问。若宿主机上 8080 已被占用，改用其他端口，并将 `WEAVIATE_ENDPOINT` 指向新端口。仅适用于中间件栈；完整的 Compose 栈将 Weaviate 保留在内部网络中。
`EXPOSE_WEAVIATE_GRPC_PORT`	`50051`	中间件栈将 Weaviate gRPC 接口发布到宿主机的端口，访问地址为 `grpc://localhost:50051`。改动后需将 `WEAVIATE_GRPC_ENDPOINT` 指向新端口。

Milvus 服务（ETCD + MinIO）

变量	默认值	说明
`ETCD_AUTO_COMPACTION_MODE`	`revision`	ETCD 自动压缩模式。
`ETCD_AUTO_COMPACTION_RETENTION`	`1000`	自动压缩保留的修订数。
`ETCD_QUOTA_BACKEND_BYTES`	`4294967296`	后端配额（字节，4 GB）。
`ETCD_SNAPSHOT_COUNT`	`50000`	触发快照前的变更数。
`ETCD_ENDPOINTS`	`etcd:2379`	ETCD 服务端点。
`MINIO_ACCESS_KEY`	`minioadmin`	MinIO access key。
`MINIO_SECRET_KEY`	`minioadmin`	MinIO secret key。
`MINIO_ADDRESS`	`minio:9000`	MinIO 服务地址。
`MILVUS_AUTHORIZATION_ENABLED`	`true`	启用 Milvus 安全授权。

OpenSearch 服务

OPENSEARCH_MEMLOCK_* 和 OPENSEARCH_NOFILE_* 需要在 docker/.env 中设置：Compose 会在加载服务文件之前读取它们。

变量	默认值	说明
`OPENSEARCH_DISCOVERY_TYPE`	`single-node`	集群形成的发现类型。
`OPENSEARCH_BOOTSTRAP_MEMORY_LOCK`	`true`	启动时锁定内存以防止交换。
`OPENSEARCH_JAVA_OPTS_MIN`	`512m`	JVM 最小堆大小。
`OPENSEARCH_JAVA_OPTS_MAX`	`1024m`	JVM 最大堆大小。
`OPENSEARCH_INITIAL_ADMIN_PASSWORD`	`Qazwsxedc!@#123`	OpenSearch 服务的初始管理员密码，同时提供 `OPENSEARCH_PASSWORD` 的默认值；如果另行设置了客户端的值，必须与其一致。
`OPENSEARCH_MEMLOCK_SOFT`	`-1`	软内存锁限制（`-1` = 无限制）。
`OPENSEARCH_MEMLOCK_HARD`	`-1`	硬内存锁限制（`-1` = 无限制）。
`OPENSEARCH_NOFILE_SOFT`	`65536`	软文件描述符限制。
`OPENSEARCH_NOFILE_HARD`	`65536`	硬文件描述符限制。

Qdrant 服务

这些变量需要在 docker/.env 中设置：Compose 会在加载服务文件之前读取它们。

变量	默认值	说明
`QDRANT_NOFILE_SOFT`	`524288`	自带 Qdrant 容器可打开文件数的软限制。如果 Qdrant 报错提示打开的文件过多，调高此值。
`QDRANT_NOFILE_HARD`	`524288`	自带 Qdrant 容器可打开文件数的硬限制。软限制不能超过此值。

PGVector / PGVecto.RS 服务

变量	默认值	说明
`PGVECTOR_PGUSER`	`postgres`	PGVector 和 PGVecto.RS 容器的 PostgreSQL 用户，同时提供它们的默认客户端用户名。
`PGVECTOR_POSTGRES_PASSWORD`	`difyai123456`	PGVector 和 PGVecto.RS 容器的初始化密码，同时提供 `PGVECTOR_PASSWORD` 和 `PGVECTO_RS_PASSWORD` 的默认值；如果另行设置了客户端的值，必须与其一致。日后修改此值不会更改已有数据库中的密码：需先在 PostgreSQL 中修改密码，再将此值改为相同的密码。
`PGVECTOR_POSTGRES_DB`	`dify`	PGVector 和 PGVecto.RS 容器中的数据库名称，同时提供它们的默认客户端数据库名称。
`PGVECTOR_PGDATA`	`/var/lib/postgresql/data/pgdata`	容器内的数据目录。
`PGVECTOR_PG_BIGM_VERSION`	`1.2-20240606`	pg_bigm 扩展版本。

Oracle / Chroma / Elasticsearch 服务

变量	默认值	说明
`ORACLE_PWD`	`Dify123456`	Oracle 管理员密码，与 `ORACLE_PASSWORD` 中的 Dify 客户端密码分开设置。
`ORACLE_CHARACTERSET`	`AL32UTF8`	Oracle 字符集。
`CHROMA_SERVER_AUTHN_CREDENTIALS`	`difyai123456`	Chroma 服务器容器的认证凭据，同时提供 `CHROMA_AUTH_CREDENTIALS` 的默认值；如果另行设置了客户端的值，必须与其一致。
`CHROMA_SERVER_AUTHN_PROVIDER`	`chromadb.auth.token_authn.TokenAuthenticationServerProvider`	Chroma 服务器的认证提供者。
`CHROMA_IS_PERSISTENT`	`TRUE`	为 Chroma 启用持久化存储。
`KIBANA_PORT`	`5601`	Kibana 端口（Elasticsearch UI）。

IRIS / 其他服务

变量	默认值	说明
`IRIS_WEB_SERVER_PORT`	`52773`	IRIS Web 服务器管理端口。
`IRIS_TIMEZONE`	`UTC`	IRIS 容器的时区。

插件守护进程存储配置

插件守护进程可以在不同的存储后端中存储插件包。仅配置与 PLUGIN_STORAGE_TYPE 匹配的提供商。

变量	默认值	说明
`PLUGIN_STORAGE_TYPE`	`local`	插件存储后端：`local`、`aws_s3`、`tencent_cos`、`azure_blob`、`aliyun_oss`、`volcengine_tos`。
`PLUGIN_STORAGE_LOCAL_ROOT`	`/app/storage`	本地插件存储的根目录。
`PLUGIN_WORKING_PATH`	`/app/storage/cwd`	插件执行的工作目录。
`PLUGIN_INSTALLED_PATH`	`plugin`	已安装插件的子目录。
`PLUGIN_PACKAGE_CACHE_PATH`	`plugin_packages`	缓存插件包的子目录。
`PLUGIN_MEDIA_CACHE_PATH`	`assets`	缓存媒体资源的子目录。
`PLUGIN_STORAGE_OSS_BUCKET`	（空）	对象存储桶名称（跨 S3/COS/OSS/TOS 提供商共享）。
`PLUGIN_PPROF_ENABLED`	`false`	为插件守护进程启用 Go pprof 性能分析。
`PLUGIN_PYTHON_ENV_INIT_TIMEOUT`	`120`	初始化插件 Python 环境的超时时间（秒）。
`PLUGIN_STDIO_BUFFER_SIZE`	`1024`	插件标准 I/O 通信的缓冲区大小（字节）。
`PLUGIN_STDIO_MAX_BUFFER_SIZE`	`5242880`	插件标准 I/O 通信的最大缓冲区大小（字节，5 MB）。
`ENDPOINT_URL_TEMPLATE`	`http://localhost/e/{hook_id}`	插件端点的 URL 模板。`{hook_id}` 将被替换为实际的 hook ID。
`EXPOSE_PLUGIN_DAEMON_PORT`	`5002`	映射到插件守护进程的宿主机端口。
`EXPOSE_PLUGIN_DEBUGGING_HOST`	`localhost`	插件远程调试的主机。
`EXPOSE_PLUGIN_DEBUGGING_PORT`	`5003`	插件远程调试的宿主机端口。

插件 S3 存储

变量	默认值	说明
`PLUGIN_S3_USE_AWS`	`false`	使用 AWS S3（相对于 S3 兼容服务）。
`PLUGIN_S3_USE_AWS_MANAGED_IAM`	`false`	使用 IAM 角色代替显式凭证。
`PLUGIN_S3_ENDPOINT`	（空）	S3 端点 URL。
`PLUGIN_S3_USE_PATH_STYLE`	`false`	使用路径风格 URL 代替虚拟主机风格。
`PLUGIN_AWS_ACCESS_KEY`	（空）	AWS access key。
`PLUGIN_AWS_SECRET_KEY`	（空）	AWS secret key。
`PLUGIN_AWS_REGION`	（空）	AWS 区域。

插件 Azure Blob 存储

变量	默认值	说明
`PLUGIN_AZURE_BLOB_STORAGE_CONTAINER_NAME`	（空）	Azure Blob 容器名称。
`PLUGIN_AZURE_BLOB_STORAGE_CONNECTION_STRING`	（空）	Azure Blob 连接字符串。

插件腾讯 COS 存储

变量	默认值	说明
`PLUGIN_TENCENT_COS_SECRET_KEY`	（空）	腾讯 COS secret key。
`PLUGIN_TENCENT_COS_SECRET_ID`	（空）	腾讯 COS secret ID。
`PLUGIN_TENCENT_COS_REGION`	（空）	腾讯 COS 区域。

插件阿里云 OSS 存储

变量	默认值	说明
`PLUGIN_ALIYUN_OSS_REGION`	（空）	阿里云 OSS 区域。
`PLUGIN_ALIYUN_OSS_ENDPOINT`	（空）	阿里云 OSS 端点。
`PLUGIN_ALIYUN_OSS_ACCESS_KEY_ID`	（空）	阿里云 OSS access key ID。
`PLUGIN_ALIYUN_OSS_ACCESS_KEY_SECRET`	（空）	阿里云 OSS access key secret。
`PLUGIN_ALIYUN_OSS_AUTH_VERSION`	`v4`	阿里云 OSS 认证版本。
`PLUGIN_ALIYUN_OSS_PATH`	（空）	阿里云 OSS 路径前缀。

插件火山引擎 TOS 存储

变量	默认值	说明
`PLUGIN_VOLCENGINE_TOS_ENDPOINT`	（空）	火山引擎 TOS 端点。
`PLUGIN_VOLCENGINE_TOS_ACCESS_KEY`	（空）	火山引擎 TOS access key。
`PLUGIN_VOLCENGINE_TOS_SECRET_KEY`	（空）	火山引擎 TOS secret key。
`PLUGIN_VOLCENGINE_TOS_REGION`	（空）	火山引擎 TOS 区域。

最后修改于 2026年11月6日