Dify 从部署安装到接口创建应用、发布和第三方集成调用操作指南

本文以 Dify 1.11.x 自部署版本为例，整理从 Docker 部署、初始化、获取工作空间 ID，到通过接口创建应用、发布、生成 API Key，并在第三方程序中调用 Dify 应用的完整流程。

1. 基础概念

Dify 里常见的几个 ID 和 Token：

名称	含义	是否敏感	说明
Workspace ID	工作空间 ID，后端通常叫 tenant_id	建议脱敏	多租户隔离用，接口和数据库中经常出现
App ID	应用 ID	建议脱敏	创建应用后返回的 id
App API Key	应用调用密钥	高敏感	第三方系统调用 /v1/chat-messages、/v1/workflows/run 等接口时使用
Console Cookie	控制台登录 Cookie	高敏感	用于调用 /console/api/* 管理接口
CSRF Token	控制台防跨站请求 Token	高敏感	调用 Console 写接口时需要带上

本文统一使用占位符：

<DIFY_BASE_URL>       Dify 访问地址，例如 https://dify.example.com
<EMAIL>               Dify 登录邮箱
<PASSWORD>            Dify 登录密码
<WORKSPACE_ID>        工作空间 ID，也就是 tenant_id
<APP_ID>              应用 ID
<APP_API_KEY>         应用 API Key，通常以 app- 开头
<USER_ID>             第三方调用时自定义的用户标识

2. Docker Compose 部署 Dify

2.1 环境准备

服务器建议准备：

• Linux 服务器，建议 Ubuntu 20.04+ / Debian 11+ / CentOS 7+
• Docker
• Docker Compose v2
• 至少 2C4G，生产环境建议更高
• 开放 HTTP/HTTPS 端口，默认 Docker Compose 使用 Nginx 暴露 80

检查 Docker：

docker version
docker compose version

2.2 获取 Dify 源码

git clone https://github.com/langgenius/dify.git
cd dify/docker

如果你使用的是指定版本，可以切换 tag：

git checkout <DIFY_VERSION_TAG>
cd docker

2.3 初始化环境变量

cp .env.example .env

重点检查 .env 中这些配置：

# 公开访问地址，按你的域名或 IP 修改
CONSOLE_API_URL=
SERVICE_API_URL=
APP_WEB_URL=
FILES_URL=

# 生产环境必须改成随机长字符串
SECRET_KEY=<CHANGE_ME_TO_A_RANDOM_SECRET>

# 默认向量库
VECTOR_STORE=weaviate

# 默认 Nginx 端口
EXPOSE_NGINX_PORT=80

如果服务器 80 端口被占用，可以改成：

EXPOSE_NGINX_PORT=8080

然后访问地址就是：

http://<SERVER_IP>:8080

2.4 配置 Console 管理接口密钥

如果希望不依赖浏览器 Cookie，而是通过脚本直接调用 /console/api/* 管理接口，例如创建应用、导入 DSL、发布 Workflow、生成应用 API Key，可以开启 Dify 的管理接口密钥。

先在 docker/.env 中增加或修改：

# 是否允许使用 ADMIN_API_KEY 调用 Console API
ADMIN_API_KEY_ENABLE=true

# 管理接口密钥。生产环境必须使用强随机字符串，不能使用示例值。
ADMIN_API_KEY=<CHANGE_ME_TO_A_STRONG_RANDOM_KEY>

生成随机密钥示例：

openssl rand -base64 48

注意：.env 文件中的变量默认只用于 Docker Compose 变量替换。要让 Dify API 容器真正读取到 ADMIN_API_KEY_ENABLE 和 ADMIN_API_KEY，还需要确认 docker-compose.yaml 中的 x-shared-env: &shared-api-worker-env 已经透传这两个变量。

打开 docker-compose.yaml，在顶部的共享环境变量块中加入：

x-shared-env: &shared-api-worker-env
  ADMIN_API_KEY_ENABLE: ${ADMIN_API_KEY_ENABLE:-false}
  ADMIN_API_KEY: ${ADMIN_API_KEY:-}
  CONSOLE_API_URL: ${CONSOLE_API_URL:-}
  CONSOLE_WEB_URL: ${CONSOLE_WEB_URL:-}

如果你的版本中已经存在这两行，则不需要重复添加。

修改后重建 API 相关容器：

docker compose up -d --force-recreate api worker worker_beat

验证容器内是否已经读取到配置：

docker compose exec api env | grep -E "ADMIN_API_KEY|ADMIN_API_KEY_ENABLE"

正常应能看到：

ADMIN_API_KEY_ENABLE=true
ADMIN_API_KEY=<CHANGE_ME_TO_A_STRONG_RANDOM_KEY>

使用管理接口密钥调用 Console API 时，需要同时带上工作空间 ID：

curl -sS "$DIFY_BASE_URL/console/api/apps" \
  -H "Authorization: Bearer <ADMIN_API_KEY>" \
  -H "X-WORKSPACE-ID: <WORKSPACE_ID>"

说明：docker-compose.yaml 文件通常由模板生成。长期维护时建议同步修改 docker-compose-template.yaml 或团队内部部署模板，避免后续重新生成 Compose 文件时丢失该配置。

2.5 启动 Dify

docker compose up -d

查看容器状态：

docker compose ps

查看日志：

docker compose logs -f api
docker compose logs -f worker
docker compose logs -f web

停止服务：

docker compose down

升级时建议先备份 .env 和 Docker volume，再拉取新版本后执行：

docker compose pull
docker compose up -d

3. 初始化管理员账号

部署完成后，在浏览器打开：

<DIFY_BASE_URL>

首次访问会进入初始化页面，按页面提示创建管理员账号。

配置大模型供应商：

1. 进入 Dify 控制台
2. 打开右上角账号菜单
3. 进入设置 / 模型供应商
4. 添加 OpenAI、通义千问、DeepSeek、Ollama 或其他模型供应商

说明：模型供应商配置涉及密钥，建议通过页面配置，避免把模型供应商 API Key 写入脚本或文章。

4. 获取 Workspace ID

Workspace ID 在 Dify 后端通常叫 tenant_id。

4.1 页面直接获取

登录 Dify 后：

1. 按 F12 打开浏览器开发者工具
2. 进入 Network
3. 刷新页面
4. 搜索接口：

workspaces

找到：

GET /console/api/workspaces

返回示例：

{
  "workspaces": [
    {
      "id": "<WORKSPACE_ID>",
      "name": "admin's Workspace",
      "plan": "sandbox",
      "status": "normal",
      "created_at": 1700000000,
      "current": true
    }
  ]
}

其中 id 就是 Workspace ID。

4.2 通过接口获取

先登录控制台，拿到 Cookie 和 CSRF Token。

Linux / macOS 示例：

BASE="<DIFY_BASE_URL>"
EMAIL="<EMAIL>"
PASSWORD="<PASSWORD>"
COOKIE_FILE="./dify-cookie.txt"

ENC_PASSWORD=$(printf "%s" "$PASSWORD" | base64)

curl -sS -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
  -H "Content-Type: application/json" \
  -X POST "$BASE/console/api/login" \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$ENC_PASSWORD\",\"remember_me\":true}"

CSRF_TOKEN=$(awk '/csrf_token/ {print $NF}' "$COOKIE_FILE" | tail -n 1)

curl -sS -b "$COOKIE_FILE" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  "$BASE/console/api/workspaces"

PowerShell 示例：

$BASE = "<DIFY_BASE_URL>"
$EMAIL = "<EMAIL>"
$PASSWORD = "<PASSWORD>"
$COOKIE = "$env:TEMP\dify-cookie.txt"

$ENC_PASSWORD = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($PASSWORD))

curl.exe -sS -c $COOKIE -b $COOKIE `
  -H "Content-Type: application/json" `
  -X POST "$BASE/console/api/login" `
  -d "{`"email`":`"$EMAIL`",`"password`":`"$ENC_PASSWORD`",`"remember_me`":true}"

$CSRF = ((Get-Content $COOKIE | Where-Object { $_ -match "csrf_token" } | Select-Object -Last 1) -split "`t")[-1]

curl.exe -sS -b $COOKIE `
  -H "Content-Type: application/json" `
  -H "X-CSRF-Token: $CSRF" `
  "$BASE/console/api/workspaces"

5. Console API 和 Service API 的区别

Dify 有两类常用接口：

类型	前缀	用途	鉴权方式
Console API	/console/api	创建应用、发布、生成 API Key、管理配置	登录 Cookie + X-CSRF-Token，或开启后使用 ADMIN_API_KEY + X-WORKSPACE-ID
Service API	/v1	第三方系统调用已发布应用	Authorization: Bearer <APP_API_KEY>

简单理解：

• 管理 Dify 用 Console API
• 调用 Dify 应用用 Service API
• 自动化创建、导入、发布应用时，可以使用 Console API

5.1 Console API 的两种鉴权方式

调用 /console/api/* 管理接口时，可以保留两种方式。

方式一：控制台登录态 Cookie + CSRF Token。

这种方式不需要额外开启 ADMIN_API_KEY，和浏览器控制台的鉴权方式一致。适合临时调试、抓包复现、少量人工操作脚本。

curl -sS -b "$COOKIE_FILE" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  "$BASE/console/api/apps"

方式二：ADMIN_API_KEY + X-WORKSPACE-ID。

这种方式不依赖浏览器 Cookie 和 CSRF Token，适合后端脚本、自动化部署、批量创建应用、导入 DSL、发布 Workflow、生成应用 API Key。

使用前需要先完成第 2.4 节中的配置：

ADMIN_API_KEY_ENABLE=true
ADMIN_API_KEY=<CHANGE_ME_TO_A_STRONG_RANDOM_KEY>

并确认 docker-compose.yaml 已经把这两个变量透传给 api 容器。

调用示例：

curl -sS \
  -H "Authorization: Bearer <ADMIN_API_KEY>" \
  -H "X-WORKSPACE-ID: <WORKSPACE_ID>" \
  -H "Content-Type: application/json" \
  "$BASE/console/api/apps"

后续章节中的 Console API 示例默认使用方式一。若使用方式二，只需要把：

-b "$COOKIE_FILE" \
-H "X-CSRF-Token: $CSRF_TOKEN"

替换为：

-H "Authorization: Bearer $ADMIN_API_KEY" \
-H "X-WORKSPACE-ID: $WORKSPACE_ID"

6. 通过接口创建应用

本节先给出 Cookie + CSRF 的写法。如果已经启用了 ADMIN_API_KEY，可以按第 5.1 节把鉴权参数替换成 Authorization: Bearer $ADMIN_API_KEY 和 X-WORKSPACE-ID: $WORKSPACE_ID。

6.1 创建 Chat 应用

BASE="<DIFY_BASE_URL>"
COOKIE_FILE="./dify-cookie.txt"
CSRF_TOKEN="<CSRF_TOKEN>"

curl -sS -b "$COOKIE_FILE" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -X POST "$BASE/console/api/apps" \
  -d '{
    "name": "接口创建的聊天助手",
    "description": "通过 Console API 创建的 Chat 应用",
    "mode": "chat",
    "icon_type": "emoji",
    "icon": "🤖",
    "icon_background": "#FFEAD5"
  }'

返回示例：

{
  "id": "<APP_ID>",
  "name": "接口创建的聊天助手",
  "mode": "chat"
}

保存返回的 id，后续接口都需要使用它。

使用 ADMIN_API_KEY 创建应用的写法如下：

BASE="<DIFY_BASE_URL>"
ADMIN_API_KEY="<ADMIN_API_KEY>"
WORKSPACE_ID="<WORKSPACE_ID>"

curl -sS -X POST "$BASE/console/api/apps" \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "X-WORKSPACE-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "接口创建的聊天助手",
    "description": "通过 Console API 创建的 Chat 应用",
    "mode": "chat",
    "icon_type": "emoji",
    "icon": "robot",
    "icon_background": "#FFEAD5"
  }'

6.2 创建 Workflow 应用

curl -sS -b "$COOKIE_FILE" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -X POST "$BASE/console/api/apps" \
  -d '{
    "name": "接口创建的工作流应用",
    "description": "通过接口创建 Workflow 应用",
    "mode": "workflow",
    "icon_type": "emoji",
    "icon": "⚙️",
    "icon_background": "#E0F2FE"
  }'

注意：空白 Workflow 应用创建后还需要配置工作流节点。实际项目中更推荐先在页面配置好模板应用，再导出 DSL，通过接口导入创建。

7. 推荐方式：通过 DSL 导入完整应用

如果应用包含复杂提示词、变量、工作流节点、知识库配置，直接用接口拼接所有配置会比较繁琐。更推荐：

1. 在 Dify 页面创建一个模板应用
2. 配置模型、提示词、工作流节点
3. 导出 DSL
4. 在其他环境通过接口导入 DSL

导入 DSL 接口：

curl -sS -b "$COOKIE_FILE" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -X POST "$BASE/console/api/apps/imports" \
  -d '{
    "mode": "yaml-content",
    "yaml_content": "<YAML_CONTENT>",
    "name": "从 DSL 导入的应用",
    "description": "通过接口导入 DSL 创建",
    "icon_type": "emoji",
    "icon": "🚀",
    "icon_background": "#DCFCE7"
  }'

如果使用 ADMIN_API_KEY，导入 DSL 的请求头改为：

curl -sS -X POST "$BASE/console/api/apps/imports" \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "X-WORKSPACE-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "yaml-content",
    "yaml_content": "<YAML_CONTENT>",
    "name": "从 DSL 导入的应用",
    "description": "通过接口导入 DSL 创建"
  }'

如果 DSL 很长，建议不要直接写在命令行里，可以把 YAML 放入文件，然后由脚本读取后提交。

8. 配置模型、提示词和工作流

通过 /console/api/apps 创建出来的是一个应用壳。要正常调用，还需要至少完成模型配置。

推荐做法：

• 简单 Chat / Completion 应用：在 Dify 页面配置模型、提示词、变量，然后保存
• 复杂 Workflow / Advanced Chat 应用：在页面编排好工作流，再发布
• 多环境迁移：用 DSL 导出和导入，避免手写复杂 graph JSON

如果一定要通过接口更新模型配置，可以使用：

curl -sS -b "$COOKIE_FILE" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -X POST "$BASE/console/api/apps/$APP_ID/model-config" \
  -d '{
    "model": {
      "provider": "<MODEL_PROVIDER>",
      "name": "<MODEL_NAME>",
      "mode": "chat",
      "completion_params": {
        "temperature": 0.7
      }
    },
    "pre_prompt": "你是一个专业的智能助手。",
    "prompt_type": "simple",
    "chat_prompt_config": {},
    "completion_prompt_config": {},
    "user_input_form": [],
    "dataset_query_variable": "",
    "opening_statement": "",
    "suggested_questions": [],
    "suggested_questions_after_answer": {
      "enabled": false
    },
    "more_like_this": {
      "enabled": false
    },
    "speech_to_text": {
      "enabled": false
    },
    "text_to_speech": {
      "enabled": false
    },
    "retriever_resource": {
      "enabled": false
    },
    "annotation_reply": {
      "enabled": false
    },
    "sensitive_word_avoidance": {
      "enabled": false
    },
    "external_data_tools": [],
    "dataset_configs": {
      "retrieval_model": "single"
    },
    "agent_mode": {
      "enabled": false,
      "max_iteration": 5,
      "tools": []
    }
  }'

注意：model-config 的实际 payload 会随应用类型、模型供应商、知识库、工具、Agent 配置变化。生产环境更推荐先在页面保存一次配置，然后在浏览器 Network 中复制该接口的 payload，或直接使用 DSL 导入完整应用。

Workflow 应用还需要草稿图配置。手写 graph JSON 容易出错，建议通过页面编排或 DSL 导入。

9. 启用应用 API

应用创建完成后，需要启用 API 调用能力。

APP_ID="<APP_ID>"

curl -sS -b "$COOKIE_FILE" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -X POST "$BASE/console/api/apps/$APP_ID/api-enable" \
  -d '{"enable_api": true}'

如果还需要启用 WebApp 公开页面：

curl -sS -b "$COOKIE_FILE" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -X POST "$BASE/console/api/apps/$APP_ID/site-enable" \
  -d '{"enable_site": true}'

10. 发布 Workflow / Advanced Chat 应用

普通 Chat / Completion 应用主要配置模型和提示词。Workflow / Advanced Chat 应用存在草稿和发布版本，需要发布后第三方接口才能稳定调用。

发布接口：

curl -sS -b "$COOKIE_FILE" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -X POST "$BASE/console/api/apps/$APP_ID/workflows/publish" \
  -d '{
    "marked_name": "v1",
    "marked_comment": "首次发布"
  }'

使用 ADMIN_API_KEY 发布时：

curl -sS -X POST "$BASE/console/api/apps/$APP_ID/workflows/publish" \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "X-WORKSPACE-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "marked_name": "v1",
    "marked_comment": "首次发布"
  }'

返回示例：

{
  "result": "success",
  "created_at": 1700000000
}

查看已发布工作流：

curl -sS -b "$COOKIE_FILE" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  "$BASE/console/api/apps/$APP_ID/workflows/publish"

11. 创建应用 API Key

创建 API Key：

curl -sS -b "$COOKIE_FILE" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -X POST "$BASE/console/api/apps/$APP_ID/api-keys" \
  -d '{}'

使用 ADMIN_API_KEY 创建应用 API Key 时：

curl -sS -X POST "$BASE/console/api/apps/$APP_ID/api-keys" \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "X-WORKSPACE-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

返回示例：

{
  "id": "<API_KEY_ID>",
  "type": "app",
  "token": "<APP_API_KEY>",
  "created_at": 1700000000
}

其中 token 就是第三方系统调用 Dify 应用时使用的 API Key。

查看已有 API Key：

curl -sS -b "$COOKIE_FILE" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  "$BASE/console/api/apps/$APP_ID/api-keys"

删除 API Key：

API_KEY_ID="<API_KEY_ID>"

curl -sS -b "$COOKIE_FILE" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -X DELETE "$BASE/console/api/apps/$APP_ID/api-keys/$API_KEY_ID"

12. 第三方程序调用 Dify 应用

第三方调用只需要 App API Key，不需要 Console Cookie。

12.1 调用 Chat 应用

BASE="<DIFY_BASE_URL>"
APP_API_KEY="<APP_API_KEY>"

curl -sS -X POST "$BASE/v1/chat-messages" \
  -H "Authorization: Bearer $APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "你好，请介绍一下你自己",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "third-party-user-001"
  }'

常用字段说明：

字段	说明
inputs	应用变量，没配置变量时传 {}
query	用户问题
response_mode	blocking 或 streaming
conversation_id	多轮对话 ID，首次可传空字符串
user	第三方系统里的用户唯一标识

12.2 调用 Completion 应用

curl -sS -X POST "$BASE/v1/completion-messages" \
  -H "Authorization: Bearer $APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "topic": "Dify 接口调用"
    },
    "response_mode": "blocking",
    "user": "third-party-user-001"
  }'

12.3 调用 Workflow 应用

curl -sS -X POST "$BASE/v1/workflows/run" \
  -H "Authorization: Bearer $APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "content": "这是一段需要处理的文本"
    },
    "response_mode": "blocking",
    "user": "third-party-user-001"
  }'

Workflow 的 inputs 必须和工作流开始节点定义的变量名称一致。

13. Python 集成示例

import requests

DIFY_BASE_URL = "<DIFY_BASE_URL>"
APP_API_KEY = "<APP_API_KEY>"

payload = {
    "inputs": {},
    "query": "帮我生成一段接口调用说明",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "python-client-001",
}

response = requests.post(
    f"{DIFY_BASE_URL}/v1/chat-messages",
    headers={
        "Authorization": f"Bearer {APP_API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
print(response.json())

14. Node.js 集成示例

const DIFY_BASE_URL = '<DIFY_BASE_URL>'
const APP_API_KEY = '<APP_API_KEY>'

async function callDify() {
  const res = await fetch(`${DIFY_BASE_URL}/v1/chat-messages`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${APP_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      inputs: {},
      query: '请用三句话介绍 Dify',
      response_mode: 'blocking',
      conversation_id: '',
      user: 'node-client-001',
    }),
  })

  if (!res.ok)
    throw new Error(`Dify request failed: ${res.status} ${await res.text()}`)

  const data = await res.json()
  console.log(data)
}

callDify().catch(console.error)

15. Java 集成示例

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class DifyClientDemo {
    public static void main(String[] args) throws Exception {
        String baseUrl = "<DIFY_BASE_URL>";
        String apiKey = "<APP_API_KEY>";

        String body = """
        {
          "inputs": {},
          "query": "请介绍一下 Dify 的接口调用方式",
          "response_mode": "blocking",
          "conversation_id": "",
          "user": "java-client-001"
        }
        """;

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(baseUrl + "/v1/chat-messages"))
                .header("Authorization", "Bearer " + apiKey)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

16. 常见问题

16.1 登录接口返回失败

Dify 1.11.x 的 Console 登录接口中，密码字段会做 Base64 解码。因此 curl 调用 /console/api/login 时，password 需要传 Base64 后的字符串。

16.2 Console API 返回 401

常见原因：

• Cookie 文件没有保存成功
• 登录已过期
• 没有带 X-CSRF-Token
• CSRF Token 取错了
• 访问域名和登录域名不一致
• 使用 ADMIN_API_KEY 调用时，ADMIN_API_KEY_ENABLE 没有开启
• .env 中配置了 ADMIN_API_KEY，但 docker-compose.yaml 没有把变量透传进 api 容器
• X-WORKSPACE-ID 传错，或者该工作空间下没有 owner 账号

建议重新登录并重新读取 Cookie 中的 csrf_token。

如果使用的是 ADMIN_API_KEY 调用 Console API，建议按下面顺序排查：

# 1. 确认容器是否读取到了管理接口密钥配置
docker compose exec api env | grep -E "ADMIN_API_KEY|ADMIN_API_KEY_ENABLE"

# 2. 如果没有输出，检查 .env 是否存在配置
grep -nE "^(ADMIN_API_KEY|ADMIN_API_KEY_ENABLE)=" .env

# 3. 检查 docker-compose.yaml 的 x-shared-env 是否透传了这两个变量
grep -nE "ADMIN_API_KEY|ADMIN_API_KEY_ENABLE|x-shared-env" docker-compose.yaml

docker-compose.yaml 中应包含：

x-shared-env: &shared-api-worker-env
  ADMIN_API_KEY_ENABLE: ${ADMIN_API_KEY_ENABLE:-false}
  ADMIN_API_KEY: ${ADMIN_API_KEY:-}

修改后重建容器：

docker compose up -d --force-recreate api worker worker_beat

然后重新验证：

docker compose exec api env | grep -E "ADMIN_API_KEY|ADMIN_API_KEY_ENABLE"

16.3 Service API 返回 Access token is invalid

常见原因：

• Authorization 格式错误，必须是 Bearer <APP_API_KEY>
• 使用了 Console 登录 token，而不是应用 API Key
• API Key 被删除或复制不完整
• 调用错了 Dify 环境

16.4 Workflow 调用失败

重点检查：

• Workflow 是否已经发布
• inputs 变量名是否和开始节点一致
• 应用 API 是否已启用
• 模型供应商是否已配置
• Worker 容器是否正常运行

16.5 第三方系统中如何保存 conversation_id

Chat 应用首次调用可以传空字符串：

"conversation_id": ""

Dify 返回里会带新的 conversation_id。第三方系统需要把它和自己的用户 ID 绑定保存，后续同一轮对话继续传这个 conversation_id。

17. 总结

完整流程可以概括为：

部署 Dify
  -> 初始化管理员账号
  -> 配置模型供应商
  -> 获取 Workspace ID
  -> 登录 Console API
  -> 创建应用或导入 DSL
  -> 配置模型 / 工作流
  -> 发布工作流
  -> 启用 API
  -> 创建 App API Key
  -> 第三方系统通过 /v1 接口调用

实际生产中推荐的方式是：

• 应用编排和模型供应商密钥配置尽量在 Dify 控制台完成
• 标准化应用用 DSL 导入导出迁移
• 第三方系统只持有 App API Key
• 不在前端页面暴露 App API Key
• 所有调用都走后端服务转发