很多人说“配一下 Dify 的 API Key”，指的其实是完全不同的东西：有时是让 Dify 调用模型的供应商密钥，有时是让业务系统调用 Dify 应用的访问密钥，还有一种是知识库的 Service API Key。三者创建位置、权限范围、泄露后的影响都不一样。混用最常见的后果是：把供应商 Key 写进前端、给调用方发了权限过大的应用 Key，或者轮换时改错对象，导致线上一起报 401。

下面按“是什么—在哪配—怎么存—怎么轮换—怎么排错”讲一遍。界面名称与权限细节可能随版本调整，以你所在实例的当前界面和官方文档为准。

说明：Dify 为其权利人 LangGenius, Inc. 的商标；本文为独立技术说明，与 Dify 团队无隶属或代理关系。

一、先分清三种 Key

先用一张表把边界划清。

Key 类型 作用 创建位置 权限范围 谁可以管理
模型供应商 Key Dify 调用上游模型 设置 → 模型供应商 → 对应供应商 整个工作区共享 Owner、Admin
应用 API Key 外部系统调用某个 Dify 应用 应用 → API 访问 单应用，覆盖该应用全部终端用户 通常为 Editor 及以上，以版本为准
知识库 Service Key 外部系统调用知识库 API 知识库 → Service API 可限定到指定知识库 通常为 Editor 及以上，以版本为准

三者不能互换。供应商 Key 不能拿来调用应用接口；应用 Key 也不能让 Dify 去调用模型。排错时第一件事，就是确认手里拿的是哪一种。

二、模型供应商 Key：工作区级，管理员配置

模型供应商 Key 是工作区级配置。它在模型供应商设置里添加，由 Dify 用来向上游发起模型请求。添加时平台会先校验一次，通过后该供应商才对整个工作区可用。只有 Owner 和 Admin 能管理模型供应商，Editor 与 Normal 看不到这些设置。

几个容易被忽略的细节：

  • 一个供应商可以保存多把 Key。常见做法是按开发、生产、不同账号分开，便于定位账单和单独停用。
  • 自定义模型的 Key 单独管理。删除最后一个 Key 会连同自定义模型一起删除；只删除模型时，Key 会保留，之后重新添加不用再填。
  • Professional 与 Team 计划支持同模型多 Key 负载均衡。某把 Key 触达上限后，平台会在一分钟内不再向它重试；是否可用取决于你的计划。
  • Cloud 自带 AI credits 时，可以不给供应商配 Key；也可以两者并存，用 Usage Priority 决定优先走哪一个。用自己的 Key，费用记在你自己的供应商账户上。

建议给每把 Key 起可读的名字，例如“用途-环境-负责人”，不要用 test、key1 这类命名。供应商后台通常能看到每把 Key 的用量，命名清楚才能在异常时快速定位。

三、应用 API Key：只放在后端

应用 API Key 解决的是另一个问题：外部系统如何调用已经发布的应用。它不参与模型选择，也不能拿去调模型接口。典型流程如下。

  1. 打开目标应用，进入 API 访问页面。
  2. 创建密钥，按“调用方-环境-日期”命名。
  3. 复制到服务端的环境变量或密钥管理服务，不要写进前端、代码仓库或聊天记录。
  4. 先调 GET /info 验证 Key 与应用是否匹配。
  5. 再按应用类型调用对应接口，Chatflow、Workflow、Agent、文本生成应用的接口并不相同。
  6. 上线后记录 Key 所属应用、负责人和创建时间。
# Dify Cloud 的基础地址；自托管替换成你的实例地址
export DIFY_BASE_URL="https://api.dify.ai/v1"
export DIFY_APP_KEY="你的应用 Key"

curl "$DIFY_BASE_URL/info" \
  -H "Authorization: Bearer $DIFY_APP_KEY"

返回应用名称、模式和描述，说明 Key 有效。注意两点：一把应用 Key 对该应用的所有终端用户生效，调用时用请求体里的 user 字段区分用户，但 user 只是标识，不是身份认证，不能拿它当权限边界；另外，应用接口应从后端调用，文档明确不建议把 Key 放到前端或客户端代码里。

四、知识库 Service Key：能限范围就限范围

知识库有独立的 Service API Key，入口在知识库的 Service API 页面，不与应用 Key 共用。创建时可以限定这把 Key 能访问哪些知识库；能访问全部知识库的 Key 还可以调用列出知识库的接口。

最小权限的做法是：每个外部消费方单独建 Key，只勾选它需要的知识库。不要图省事用一把全量 Key 给所有服务。知识库 Key 泄露的影响是数据被读取或写入，而不只是模型额度被消耗，风险等级更高。

五、密钥存在哪里：.env、SECRET_KEY 与工作区加密

自托管部署的密钥分两层，很多人只改了第一层。

第一层是 docker/.env。它由 .env.example 复制而来，根目录的 .env 会覆盖 docker/envs/*.env 里的同名配置。其中 SECRET_KEY 最容易被忽略：它参与会话 Cookie 与 JWT 签名、文件 URL 的 HMAC-SHA256 签名，以及第三方 OAuth 凭据的 AES-256 加密。示例文件里的值必须替换，可以用 openssl rand -base64 42 生成。

更换 SECRET_KEY 会让所有用户退出登录、已签发的文件 URL 失效，已用旧值加密的 OAuth 凭据无法恢复。它不是常规轮换项，改动前要评估影响并备份。

第二层是工作区凭据加密。模型供应商 Key、工具凭据等由每个工作区的 RSA 密钥加密，私钥存放在 STORAGE_TYPE 指定的后端。KEY_PROVIDER_TYPE 默认是 local，也可以接 Azure Key Vault 并配置自动轮换；轮换间隔有下限，旧版本密钥在轮换后仍可使用。关键点：这个选项要在创建第一个工作区之前定好。两种方式的密文互不兼容，中途切换会让已有凭据无法解密，只能重新录入。

此外，较新版本的 Agent 相关配置里有 DIFY_AGENT_SERVER_SECRET_KEY 和 DIFY_AGENT_API_TOKEN，开发默认值是公开的，上线前必须替换。.env 不要提交到代码仓库，文件权限按文档收紧；备份时把密钥材料一起纳入，否则恢复环境后凭据可能全部失效。

Cloud 用户的供应商凭据由平台托管，不需要自己管理 SECRET_KEY，但这不意味着可以随意发 Key：仍应使用独立账号或项目 Key，并保留供应商侧的使用记录。

六、轮换、最小权限与团队角色

轮换不是只在大泄露时才做。建议在这些时点检查：人员离职、调用方变更、疑似泄露、供应商要求，以及固定的季度或半年周期。一次完整的轮换按下面顺序走。

  1. 在供应商或 Dify 中新建一把同权限的新 Key，先与旧 Key 并行。
  2. 把新 Key 写入密钥管理服务或环境变量，发布配置。
  3. 观察一段时间的错误率、调用量和供应商账单，确认流量已切换。
  4. 停用旧 Key，而不是只从配置里删掉。
  5. 记录轮换时间、执行人和影响范围，更新交接文档。

团队分工上，Dify 工作区角色大致是：Owner 拥有全部控制权且只有一个；Admin 管理成员与模型供应商；Editor 可以创建、编辑、删除应用和知识库；Normal 只能使用已发布的应用。由此可以推出一条简单规则：模型供应商 Key 只留在 Owner 和 Admin 手里；应用 Key 交给对应的后端服务负责人；知识库 Key 按消费方拆分并限定范围。Editor 能修改应用，通常也能接触该应用的 API Key，所以不要把“能编辑应用”等同于“可以管理全公司的模型密钥”。

七、常见报错与排查

排查时先确认 Key 类型，再看网络和权限。

  • 401 Unauthorized：Key 拼错、已撤销、带了多余空格或换行，或把供应商 Key 当成应用 Key。用 GET /info 复测。
  • 403 或权限不足：角色不够，或知识库 Key 没有包含目标知识库。
  • 404 Not Found：Base URL 不对。Cloud 用 https://api.dify.ai/v1；自托管用你自己的域名并以 /v1 结尾，不要带完整接口路径。
  • 应用能打开但接口报模型不可用：供应商 Key 过期、余额不足或被上游限流；到模型供应商设置里重新校验。
  • 知识库接口 404/403：应用 Key 与 Service Key 用混了，或知识库不在 Key 的访问范围内。
  • 429 Too Many Requests：触发限流。降低并发，按指数退避重试，不要无限重试。
  • 换 SECRET_KEY 后集体掉线：这是预期行为，见上一节；不要靠改回旧值“修复”，先评估影响再操作。

还有一个常见误区：把 Dify 部署在容器或云端，却填了 localhost 或内网地址。Dify 访问不到你的本地服务，Key 再对也没用。反过来，业务系统访问不到自托管 Dify 时，先查 DNS、防火墙、反向代理和 HTTPS 证书。

常见问题

模型供应商 Key 和应用 API Key 可以互换吗？

不能。前者是 Dify 调用上游模型的凭据，后者是外部系统调用 Dify 应用的凭据。接口、权限和计费对象都不同。

一个应用可以创建多把 API Key 吗？

通常可以。常见做法是按环境或调用方拆分，便于单独停用和追踪。具体入口和数量限制以当前版本界面为准。

应用 API Key 能限制到某个知识库或某个用户吗？

应用 Key 的粒度是应用，不能按知识库拆分；请求里的 user 字段只用于区分终端用户，不是认证机制。需要按知识库限权时，使用知识库的 Service API Key 并勾选范围。

更换 SECRET_KEY 会影响模型供应商 Key 吗？

供应商与工具凭据由工作区 RSA 密钥加密，不由 SECRET_KEY 直接加密；但更换 SECRET_KEY 会导致用户退出、文件 URL 失效，并让 OAuth 凭据不可恢复。生产环境改动前先读部署文档并做备份。

自托管升级后 Key 突然失效，先查什么？

先比对 .env.example 与现有 .env 是否有新增变量，再确认 KEY_PROVIDER_TYPE 和存储后端没有变化；如果换过加密方式，旧凭据无法解密，只能重新录入。最后看应用日志里的具体错误码。

下一步

Dify 的 Key 管理可以归纳为三句话：先分清类型，再按最小权限发放，最后把轮换当成固定流程。需要统一的 OpenAI 兼容入口、把模型调用集中到一处管理，可以先注册中商起航 AI 网关，模型范围与价格以模型价格为准。

相关阅读：