环境变量 - Dify Docs

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

Dify 使用默认配置即可开箱即用。如需自定义部署，编辑相关文件中的环境变量：

必要的启动值 位于 docker/.env 文件中（部署时从 docker/.env.example 复制创建）。直接编辑即可。
可选或特定提供商的设置 在 docker/envs/ 下有对应模板。要覆盖默认值，复制相应模板（去掉 .example 后缀），然后编辑副本。例如：
cd dify/docker cp envs/vectorstores/milvus.env.example envs/vectorstores/milvus.env

docker/.env 中的值优先于任何 docker/envs/*.env 文件中的值。

升级 Dify 后，对照各 .env.example 文件检查对应的 .env，确认是否有新增或变更的变量。

通用变量

这些 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`、`ENTERPRISE_ENABLED` 和 `BILLING_ENABLED`，这些旧变量自 1.17.0 起会被忽略。
`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

默认值：（在 .env.example 中预填充；生产环境必须替换）用于会话 Cookie 签名、JWT 认证令牌、文件 URL 签名（HMAC-SHA256）以及加密第三方 OAuth 凭证（AES-256）。首次启动前请生成一个强密钥：

openssl rand -base64 42

部署后更改此密钥将立即使所有用户登出、使所有文件 URL 失效，并破坏使用 OAuth 的插件集成，其加密凭证将无法恢复。

PASSWORD_PEPPER

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

openssl rand -base64 32

使用 Docker Compose 部署时，在 docker/envs/core-services/api.env 中设置（如尚未创建该文件，可从 api.env.example 复制）。不要写在 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。
`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

默认值：worker（worker 服务 env 文件的预置值；完全未设置该变量时，容器运行 API 服务）决定 dify-api 镜像在容器启动时运行的进程。三个 env 示例文件分别为各自服务固定取值：worker.env.example 为 worker，api.env.example 为 api，worker-beat.env.example 为 beat。可选值：

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

自带的 Compose 文件已为每个服务固定正确的值，只有 Kubernetes 等自定义部署才需要设置。配置错误会让容器运行错误的进程：没有 worker 时，索引和邮件任务会一直排队。

API 工具配置

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

数据库配置

数据库默认使用 PostgreSQL。同时支持 OceanBase、MySQL 和 seekdb。

变量	默认值	说明
`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 端点。仅填写协议 + 主机 + 端口（路径 `/socket.io/` 由客户端固定），把 `http(s)://` 替换为 `ws(s)://`。示例：`wss://dify.example.com`。默认值对应 Dify 自带 nginx 的 80 端口。运行时生效，容器重启即可应用。
`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 选择向量数据库后端。如果数据集已有索引，数据集存储的类型优先于此设置。在 Docker Compose 中切换提供商时，COMPOSE_PROFILES 会根据此值自动启动匹配的容器。支持的值：weaviate、oceanbase、seekdb、qdrant、milvus、myscale、relyt、pgvector、pgvecto-rs、chroma、opensearch、oracle、tencent、elasticsearch、elasticsearch-ja、analyticdb、couchbase、vikingdb、opengauss、tablestore、vastbase、tidb、tidb_on_qdrant、baidu、lindorm、huawei_cloud、upstash、matrixone、clickzetta、alibabacloud_mysql、iris、hologres。

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

Weaviate

变量	默认值	说明
`WEAVIATE_ENDPOINT`	`http://weaviate:8080`	Weaviate REST API 端点。
`WEAVIATE_API_KEY`	（空）	Weaviate 认证的 API key。
`WEAVIATE_GRPC_ENDPOINT`	`grpc://weaviate:50051`	独立的 gRPC 端点，用于高性能二进制协议。批量操作显著更快。如未设置，将从 HTTP 端点推断。
`WEAVIATE_TOKENIZATION`	`word`	文本字段的分词方法。选项：`word`（按空格和标点分割）、`whitespace`（仅按空格分割）、`character`（字符级别，更适合中日韩语言）。

OceanBase / seekdb

seekdb 是 OceanBase 的轻量版本，共享相同的连接配置。

变量	默认值	说明
`OCEANBASE_VECTOR_HOST`	`oceanbase`	主机名或 IP 地址。
`OCEANBASE_VECTOR_PORT`	`2881`	端口号。
`OCEANBASE_VECTOR_USER`	`root@test`	数据库用户名。
`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 key。
`QDRANT_CLIENT_TIMEOUT`	`20`	客户端超时（秒）。
`QDRANT_GRPC_ENABLED`	`false`	启用 gRPC 通信。
`QDRANT_GRPC_PORT`	`6334`	gRPC 端口。
`QDRANT_REPLICATION_FACTOR`	`1`	每个分片的副本数。

Milvus

变量	默认值	说明
`MILVUS_URI`	`http://host.docker.internal:19530`	Milvus URI。对于 Zilliz Cloud，使用 Public Endpoint。
`MILVUS_DATABASE`	（空）	数据库名称。
`MILVUS_TOKEN`	（空）	认证令牌。对于 Zilliz Cloud，使用 API Key。
`MILVUS_USER`	（空）	用户名。
`MILVUS_PASSWORD`	（空）	密码。
`MILVUS_ENABLE_HYBRID_SEARCH`	`false`	启用 BM25 稀疏索引用于全文搜索，配合向量相似性搜索使用。需要 Milvus >= 2.5.0。如果集合在未启用时创建，则需重新创建。
`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_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_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_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_HOST127.0.0.1Chroma 服务器主机。
CHROMA_PORT8000Chroma 服务器端口。
CHROMA_TENANTdefault_tenant租户名称。
CHROMA_DATABASEdefault_database数据库名称。
CHROMA_AUTH_PROVIDERchromadb.auth.token_authn.TokenAuthClientProvider认证提供者类。
CHROMA_AUTH_CREDENTIALS（空）认证凭证。

变量	默认值	说明
`CHROMA_HOST`	`127.0.0.1`	Chroma 服务器主机。
`CHROMA_PORT`	`8000`	Chroma 服务器端口。
`CHROMA_TENANT`	`default_tenant`	租户名称。
`CHROMA_DATABASE`	`default_database`	数据库名称。
`CHROMA_AUTH_PROVIDER`	`chromadb.auth.token_authn.TokenAuthClientProvider`	认证提供者类。
`CHROMA_AUTH_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_HOST`	`opensearch`	主机名。
`OPENSEARCH_PORT`	`9200`	端口号。
`OPENSEARCH_SECURE`	`true`	使用 HTTPS。
`OPENSEARCH_VERIFY_CERTS`	`true`	验证 SSL 证书。
`OPENSEARCH_AUTH_METHOD`	`basic`	`basic` 使用用户名/密码。`aws_managed_iam` 通过 Boto3 凭证使用 AWS SigV4 请求签名（适用于 AWS 托管的 OpenSearch 或 Serverless）。
`OPENSEARCH_USER`	`admin`	用户名。仅在 `basic` 认证下使用。
`OPENSEARCH_PASSWORD`	`admin`	密码。仅在 `basic` 认证下使用。
`OPENSEARCH_AWS_REGION`	`ap-southeast-1`	AWS 区域。仅在 `aws_managed_iam` 认证下使用。
`OPENSEARCH_AWS_SERVICE`	`aoss`	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

变量	默认值	说明
`ELASTICSEARCH_HOST`	`0.0.0.0`	主机名。
`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 以分离错误报告。

变量	默认值	说明
`SENTRY_DSN`	（空）	跨服务共享的 Sentry DSN。
`API_SENTRY_DSN`	（空）	API 服务的 Sentry DSN。如果设置，覆盖 `SENTRY_DSN`。为空则禁用后端的 Sentry。
`API_SENTRY_TRACES_SAMPLE_RATE`	`1.0`	包含在性能追踪中的请求比例（0.01 = 1%，1.0 = 100%）。追踪跨服务跟踪请求流。
`API_SENTRY_PROFILES_SAMPLE_RATE`	`1.0`	包含在 CPU/内存性能分析中的请求比例（0.01 = 1%）。分析显示代码中时间花费在哪里。
`SENTRY_TRACES_SAMPLE_RATE`	`1.0`	`API_SENTRY_TRACES_SAMPLE_RATE` 的直接变量名，供 `docker/envs/core-services/` 下的配置文件使用。 Compose 部署中以 `API_SENTRY_*` 的值为准。Sentry DSN 为空时不生效。
`SENTRY_PROFILES_SAMPLE_RATE`	`1.0`	`API_SENTRY_PROFILES_SAMPLE_RATE` 的直接变量名，用途同上。性能分析只在已被追踪采样的请求中采样，实际采样量约为两个比例的乘积。
`WEB_SENTRY_DSN`	（空）	Web 前端（Next.js）的 Sentry DSN。仅前端使用。
`PLUGIN_SENTRY_ENABLED`	`false`	为插件守护进程服务启用 Sentry。
`PLUGIN_SENTRY_DSN`	（空）	插件守护进程的 Sentry DSN。

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。

认证与账户

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

变量	默认值	说明
`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/shared.env 中设置这些变量。

变量	默认值	说明
`OPS_TRACE_UNIFIED_ENABLED`	`false`	设为 `true` 后，LangSmith 和 Arize/Phoenix 的追踪数据采用统一结构，记录工作流运行、节点及其父子关系。默认值 `false` 保留各供应商原有的追踪实现。其他供应商不受影响。各应用仍需单独开启 LLMOps 并配置供应商。
`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` 中设置，不要写在 `shared.env`：Agent 后端不读取这个文件。
`ENABLE_APPLICATION_TRACE_RECONCILE_TASK`	`true`	仅在 `OPS_AGENT_TRACE_ENABLED` 为 `true` 时生效。每 30 秒运行一次后台任务，重新发送仍在等待投递的 Agent 追踪数据，并在保留期（默认 7 天）结束后删除 Dify 自己存储的 Agent 追踪数据。已经发送到追踪供应商的数据不受影响。
`OPS_TRACE_RETRYABLE_DISPATCH_MAX_RETRIES`	`780`	追踪投递遇到瞬时失败后的最大重试次数，超出后该条追踪数据被丢弃。默认重试窗口（次数 × `OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS`）按覆盖一小时工作流上限加导出宽限期设定。目前只有 Arize/Phoenix 追踪嵌套工作流时会触发（子追踪先于父级上下文到达）。不能设为 `0`。
`OPS_TRACE_RETRYABLE_DISPATCH_DELAY_SECONDS`	`5`	两次重试的间隔秒数；总容忍窗口约为间隔 × 最大次数（默认约 65 分钟）。调低可让嵌套追踪更快送达，但重试次数消耗更快。不能设为 `0`。
`OPS_TRACE_PARENT_CONTEXT_TTL_SECONDS`	`3900`	父工作流追踪上下文的保留时长（秒），供后到的嵌套子追踪挂接。当 `OPS_TRACE_UNIFIED_ENABLED` 为 `true` 时，取值必须不低于重试窗口（次数 × 间隔）。低于此值会导致 Dify 无法加载配置。

索引

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

新用户默认配置

变量	默认值	说明
`NEW_USER_DEFAULT_PLUGIN_IDS`	（空）	创建新工作空间时自动安装的市场插件 ID，逗号分隔。
`NEW_USER_DEFAULT_MODELS`	（空）	为新工作空间预设的默认模型，逗号分隔，格式为 `model_type:provider:model`。

工作流生成

变量	默认值	说明
`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 如何连接沙箱。沙箱是一个独立服务，在隔离环境中运行代码节点（Python、JavaScript）和模板转换节点（Jinja2）。

变量	默认值	说明
`CODE_EXECUTION_ENDPOINT`	`http://sandbox:8194`	沙箱服务端点。
`CODE_EXECUTION_API_KEY`	`dify-sandbox`	沙箱认证的 API key。必须与沙箱服务中的 `SANDBOX_API_KEY` 匹配。
`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 会对代码节点和模板转换节点的输出强制执行这些限制，沙箱服务不会读取这些变量。修改后需重启 API 和 Worker（而非沙箱）才会生效。

变量	默认值	说明
`CODE_MAX_NUMBER`	`9223372036854775807`	代码节点输出允许的最大数值（64 位有符号整数最大值）。
`CODE_MIN_NUMBER`	`-9223372036854775808`	代码节点输出允许的最小数值（64 位有符号整数最小值）。
`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

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

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

DIFY_AGENT_API_TOKEN

默认值：（.env.example 中预填了开发令牌，生产环境必须替换） Dify API 调用 Agent 后端运行接口时出示的 Bearer 令牌。Compose 会把同一个值传给两侧服务，设置一次即可保持一致。默认值是一个公开的开发令牌，部署可开箱即用；但任何能访问 Agent 后端且知道该令牌的人都能发起运行，生产环境使用前务必替换为你自己的随机值。

DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN

默认值：（空；运行时后端为默认的 local 时必填） Agent 后端向内置沙箱证明身份时使用的共享密钥。留空时，这两个服务一启动就会退出并反复重启，所以要在启动 Dify 之前设置好。在 docker/.env 中设置一次即可，Compose 会把它传给两个服务。只写在 docker/envs/ 下某个文件里的值不会生效。可用以下命令生成：

openssl rand -base64 32

取代原 DIFY_AGENT_SHELLCTL_AUTH_TOKEN，旧名仍可作为兼容别名使用。

NEXT_PUBLIC_ENABLE_AGENT_V2

默认值：true 在 Web 界面中显示新 Agent：主导航中的 Agents 项，以及工作流节点选择器中的新 Agent 节点。设为 false 可隐藏它并回退到经典 Agent 节点。此变量替代了 ENABLE_AGENT_V2，后者仍可作为回退。

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 导出、导入失败时，可调高此值。

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`。取代原 `AGENT_BACKEND_RUN_TIMEOUT_SECONDS`。 API 侧的 `APP_MAX_EXECUTION_TIME` 与 `WORKFLOW_MAX_EXECUTION_TIME`（默认 `3600`）若设得低于此值，会更早终止运行。在 `e2b` 后端下，沙箱自身的 `DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS`（上限 3600）仍然生效，因此 E2B 上的运行最长仍为 1 小时。在 `local` 后端下，高于 1 小时的值会生效：如需更长的运行时间，同时调高此值和 API 侧的两项限制。
`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` 推导）	插件守护进程的凭证。
`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` 推导）	必须与 API 服务的 `INNER_API_KEY_FOR_PLUGIN` 一致，而非 `INNER_API_KEY`。
`DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT`	`http://local_sandbox:5004`	内置沙箱服务的地址。取代原 `DIFY_AGENT_SHELLCTL_ENTRYPOINT`，旧名仍可作为兼容别名使用。
`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 服务名。需在 `docker/.env` 中将其设为沙箱可访问、且能路由到 Agent 后端 `/agent-stub` 路径的地址，并发布或代理 Agent 后端的 5050 端口。
`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）都需在 docker/.env 中设置。Compose 从这里把这三个值传给 Agent 后端，因此写在 envs/core-services/dify-agent.env 中不会生效。每种远程后端各有一组专用变量：

E2B

docker/docker-compose.e2b.yaml 叠加文件会为此后端调整 Compose 配置。

变量	默认值	说明
`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 删除。
沙箱回连 Dify 的网络路径：
- 沙箱可访问的回调地址。
- 通往 Agent 后端 /agent-stub 路径的路由。基础 Compose 文件没有发布 Agent 后端的 5050 端口。这个端口同时承载启动 Agent 运行的 API，所以不要整个暴露，只暴露 /agent-stub 路径，比如通过反向代理。

按以下步骤切换到 OpenShell：

参照 OpenShell 配置指南搭建网关并完成上述准备，包括构建运行时镜像、初始化共享卷、挂载证书、Kubernetes 配置和冒烟测试。
在 docker/.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 也会导出。轨迹导出独立于 LLMOps 追踪投递（由应用构建者为每个应用单独配置 Langfuse 等供应商），也独立于 API 和 Worker 的 OpenTelemetry 插桩，两者的设置都不影响轨迹导出。按以下步骤开启轨迹导出：

在 docker/.env 中，将 DIFY_AGENT_TRAJECTORY_ENABLED 设为 true，将 DIFY_AGENT_TRAJECTORY_OTLP_TRACES_ENDPOINT 设为收集器的 traces URL。凭证（如有）写在 DIFY_AGENT_TRAJECTORY_OTLP_HEADERS 中。 Agent 后端不读取 shared.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 发布到宿主机的端口。

沙箱服务

沙箱是用于执行代码节点（Python、JavaScript、Jinja2）的隔离服务。可以禁用网络访问以增强安全性。

变量	默认值	说明
`SANDBOX_API_KEY`	`dify-sandbox`	沙箱认证的 API key。必须与 API 服务中的 `CODE_EXECUTION_API_KEY` 匹配。
`SANDBOX_GIN_MODE`	`release`	沙箱服务模式：`release` 或 `debug`。
`SANDBOX_WORKER_TIMEOUT`	`15`	单次代码运行的最大执行时间（秒）。
`SANDBOX_ENABLE_NETWORK`	`true`	允许代码发起出站 HTTP 请求。禁用可防止代码节点访问外部服务。
`SANDBOX_HTTP_PROXY`	`http://ssrf_proxy:3128`	网络启用时用于 SSRF 防护的 HTTP 代理。
`SANDBOX_HTTPS_PROXY`	`http://ssrf_proxy:3128`	SSRF 防护的 HTTPS 代理。
`SANDBOX_PORT`	`8194`	沙箱服务端口。

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 必须访问的主机，不要放行整个私有网络。在 `docker/.env` 中设置。写在 `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` 一样尽量缩小范围，设置方式也相同。`docker/.env.example` 中没有这一行，需自行添加。示例：`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_PROFILES`	`${VECTOR_STORE:-weaviate},${DB_TYPE:-postgresql},collaboration`	选择启动哪些服务容器。默认包含匹配的向量存储和数据库（如设置 `DB_TYPE=mysql` 将启动 MySQL 而非 PostgreSQL），以及启动专用 `api_websocket` 容器的 `collaboration` profile。移除 `collaboration` 即可跳过独立的 WebSocket 服务。
`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`	（自动生成）	插件守护进程的认证密钥。
`PLUGIN_DAEMON_PORT`	`5002`	插件守护进程监听端口。
`DB_SSL_MODE`	`disable`	插件守护进程连接 PostgreSQL 时使用的 `sslmode`。数据库强制 TLS 时设为 `require`。`.env.example` 中没有这一项：完整的 Compose 栈在 `docker/.env` 中设置，中间件栈在 `middleware.env` 中设置。
`PLUGIN_DAEMON_TIMEOUT`	`600.0`	所有插件守护进程请求（安装、执行、列表）的超时时间（秒）。
`PLUGIN_MAX_PACKAGE_SIZE`	`52428800`	最大插件包大小（字节，50 MB）。在市场下载时验证。
`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 使用的 API key。必须与插件守护进程服务配置中的 `DIFY_INNER_API_KEY` 匹配。
`INNER_API_KEY_FOR_PLUGIN`	（env 示例中已预填；生产环境必须更换）	同一密钥在 API 服务侧的直接变量名，来自 `docker/envs/core-services/`；Compose 部署中由 `PLUGIN_DIFY_INNER_API_KEY` 同时写入两侧。 API 在每次插件回调（模型调用、工具调用、文件传输）时校验该密钥，两侧不一致时这些调用会失败，但插件安装不受影响。务必更换预填的默认值：它公开在 Dify 仓库中，而且是插件回调 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 插件，禁用 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。适用于加速安装或离线环境。

Creator Center 配置

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

变量	默认值	说明
`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 分钟检查市场中是否有更新的插件版本。根据每个租户的自动升级计划分发升级任务。
`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 集群模式。建议在大规模部署中使用。

向量数据库服务配置

这些变量配置向量数据库容器本身（而非 Dify 客户端连接）。仅与你选择的 VECTOR_STORE 相关的变量有效。

Weaviate 服务

变量	默认值	说明
`WEAVIATE_PERSISTENCE_DATA_PATH`	`/var/lib/weaviate`	容器内的数据持久化目录。
`WEAVIATE_QUERY_DEFAULTS_LIMIT`	`25`	默认查询结果限制。
`WEAVIATE_AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED`	`true`	允许匿名访问。
`WEAVIATE_DEFAULT_VECTORIZER_MODULE`	`none`	默认向量化模块。
`WEAVIATE_CLUSTER_HOSTNAME`	`node1`	集群节点主机名。
`WEAVIATE_AUTHENTICATION_APIKEY_ENABLED`	`true`	启用 API key 认证。
`WEAVIATE_AUTHENTICATION_APIKEY_ALLOWED_KEYS`	（自动生成）	允许的 API key。必须与客户端配置中的 `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_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_MEMLOCK_SOFT`	`-1`	软内存锁限制（`-1` = 无限制）。
`OPENSEARCH_MEMLOCK_HARD`	`-1`	硬内存锁限制（`-1` = 无限制）。
`OPENSEARCH_NOFILE_SOFT`	`65536`	软文件描述符限制。
`OPENSEARCH_NOFILE_HARD`	`65536`	硬文件描述符限制。

PGVector / PGVecto.RS 服务

变量	默认值	说明
`PGVECTOR_PGUSER`	`postgres`	PGVector 容器的 PostgreSQL 用户。
`PGVECTOR_POSTGRES_PASSWORD`	（自动生成）	PGVector 容器的 PostgreSQL 密码。
`PGVECTOR_POSTGRES_DB`	`dify`	PGVector 容器中的数据库名称。
`PGVECTOR_PGDATA`	`/var/lib/postgresql/data/pgdata`	容器内的数据目录。
`PGVECTOR_PG_BIGM_VERSION`	`1.2-20240606`	pg_bigm 扩展版本。

Oracle / Chroma / Elasticsearch 服务

变量	默认值	说明
`ORACLE_PWD`	`Dify123456`	容器的 Oracle 数据库密码。
`ORACLE_CHARACTERSET`	`AL32UTF8`	Oracle 字符集。
`CHROMA_SERVER_AUTHN_CREDENTIALS`	（自动生成）	Chroma 服务器容器的认证凭证。
`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 容器的时区。
`DB_PLUGIN_DATABASE`	`dify_plugin`	插件数据的独立数据库名称。

插件守护进程存储配置

插件守护进程可以在不同的存储后端中存储插件包。仅配置与 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年10月23日

​通用变量

​CONSOLE_API_URL

​SERVER_CONSOLE_API_URL

​CONSOLE_WEB_URL

​SERVICE_API_URL

​APP_API_URL

​APP_WEB_URL

​TRIGGER_URL

​FILES_URL

​INTERNAL_FILES_URL

​FILES_ACCESS_TIMEOUT

​ENABLE_COLLABORATION_MODE

​系统编码

​服务器配置

​日志

​常规

​SECRET_KEY

​PASSWORD_PEPPER

​KEY_PROVIDER_TYPE

​INIT_PASSWORD

​令牌与请求限制

​容器启动配置

​MODE

​API 工具配置

​数据库配置

​连接池

​PostgreSQL 性能调优

​MySQL 性能调优

​Redis 配置

​Redis SSL 配置

​Redis 哨兵模式

​Redis 集群模式

​Redis 连接健壮性配置

​Celery 配置

​CELERY_BROKER_URL

​CORS 配置

​Dify CLI 与编程 API

​文件存储配置

​STORAGE_TYPE

​归档存储

​向量数据库配置

​VECTOR_STORE

​知识库配置

​标注导入

​模型配置

​多模态配置

​Sentry 配置

​Notion 集成配置

​邮件配置

​其他配置

​控制台功能

​认证与账户

​LLMOps 追踪投递

​索引

​新用户默认配置

​工作流生成

​令牌与邀请

​代码执行沙箱

​代码与模板输出限制

​工作流运行时

​工作流存储仓库

​工作流日志清理

​HTTP 请求节点

​Webhook

​SSRF 防护

​Agent 配置

​Web 前端服务

​NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW

​新版 Agent

​DIFY_AGENT_SERVER_SECRET_KEY

​DIFY_AGENT_API_TOKEN

​DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN

​NEXT_PUBLIC_ENABLE_AGENT_V2

​UPLOAD_SKILL_FILE_SIZE_LIMIT

​Agent 包与应用包限制

​AGENT_BACKEND_BASE_URL

​DIFY_AGENT_RUNTIME_BACKEND

​Agent 轨迹导出

​数据库服务

​沙箱服务

通用变量

CONSOLE_API_URL

SERVER_CONSOLE_API_URL

CONSOLE_WEB_URL

SERVICE_API_URL

APP_API_URL

APP_WEB_URL

TRIGGER_URL

FILES_URL

INTERNAL_FILES_URL

FILES_ACCESS_TIMEOUT

ENABLE_COLLABORATION_MODE

系统编码

服务器配置

日志

常规

SECRET_KEY

PASSWORD_PEPPER

KEY_PROVIDER_TYPE

INIT_PASSWORD

令牌与请求限制

容器启动配置

MODE

API 工具配置

数据库配置

连接池

PostgreSQL 性能调优

MySQL 性能调优

Redis 配置

Redis SSL 配置

Redis 哨兵模式

Redis 集群模式

Redis 连接健壮性配置

Celery 配置

CELERY_BROKER_URL

CORS 配置

Dify CLI 与编程 API

文件存储配置

STORAGE_TYPE

归档存储

向量数据库配置

VECTOR_STORE

知识库配置

标注导入

模型配置

多模态配置

Sentry 配置

Notion 集成配置

邮件配置

其他配置

控制台功能

认证与账户

LLMOps 追踪投递

索引

新用户默认配置

工作流生成

令牌与邀请

代码执行沙箱

代码与模板输出限制

工作流运行时

工作流存储仓库

工作流日志清理

HTTP 请求节点

Webhook

SSRF 防护

Agent 配置

Web 前端服务

NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW

新版 Agent

DIFY_AGENT_SERVER_SECRET_KEY

DIFY_AGENT_API_TOKEN

DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN

NEXT_PUBLIC_ENABLE_AGENT_V2

UPLOAD_SKILL_FILE_SIZE_LIMIT

Agent 包与应用包限制

AGENT_BACKEND_BASE_URL

DIFY_AGENT_RUNTIME_BACKEND

Agent 轨迹导出

数据库服务

沙箱服务