dify-deploy

# Dify Console Admin API ## 适用场景 当用户想通过 `ADMIN_API_KEY` 自动化调用 Dify Console API 时使用，包括： - 创建工作流应用。 - 导出应用或工作流 DSL。 - 从 YAML 内容或 URL 导入 DSL。 - 验证 admin key 鉴权是否生效。 ## 参数管理 ### 配置文件位置 配置保存在项目根目录下：`.dify_key/config.json` ### 首次使用：运行一键获取脚本 如果配置文件不存在，直接运行脚本自动获取三个 key： ```bash node .claude/skills/dify-deploy/scripts/fetch_keys.js ``` - 脚本会自动通过正在运行的 Docker 容器定位 Dify 部署目录，无需手动输入路径 - 脚本会自动创建 `.dify_key/config.json` 并写入初始值，同时将 `.dify_key/` 加入 `.gitignore` - 如果部分 key 获取失败，脚本会提示具体原因并引导阅读 `README.md` 进行手动配置 ### 后续使用：加载已保存参数 每次执行前先检查并加载配置： ```javascript const fs = require('fs'); const path = require('path'); const configPath = path.join('.dify_key', 'config.json'); if (fs.existsSync(configPath)) { const config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); process.env.DIFY_BASE_URL = config.DIFY_BASE_URL; process.env.ADMIN_API_KEY = config.ADMIN_API_KEY; process.env.WORKSPACE_ID = config.WORKSPACE_ID; console.log(`已加载配置：DIFY_BASE_URL=${config.DIFY_BASE_URL}`); } else { console.log('配置文件不存在，请先运行 fetch_keys.js'); } ``` ### 更新配置 用户要求更新参数时，读取现有配置、合并更新、重新保存： ```javascript const fs = require('fs'); const path = require('path'); const configPath = path.join('.dify_key', 'config.json'); const config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); config.WORKSPACE_ID = '新的-workspace-id'; // 按需修改对应字段 fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8'); ``` ### 安全要求 - 不要把 `ADMIN_API_KEY` 写入仓库文件、PR 描述、日志或长期保存的脚本 - 展示命令时，优先使用变量而非明文值 - 创建配置文件时脚本会自动将 `.dify_key/` 加入 `.gitignore` ### 操作类型 加载配置后，确认操作类型和附加参数： - 创建应用：`APP_NAME`，可选 `APP_DESCRIPTION` - 导出 DSL：`APP_ID`，可选 `INCLUDE_SECRET`、`WORKFLOW_ID` - 导入 DSL：`YAML_CONTENT` 或 `YAML_URL` - 覆盖导入：额外需要 `APP_ID`，且只能覆盖 workflow 或 advanced-chat 应用 - 确认导入：`IMPORT_ID` ## 前置条件 运行中的 API 进程必须启用： ```env ADMIN_API_KEY_ENABLE=true ADMIN_API_KEY=<admin-key> ``` 修改后必须重启 API 进程。如果请求返回 `401 Invalid token`，通常表示运行中的进程没有加载 admin key，或者 key 不正确。 ## 推荐变量模板 让用户先设置环境变量，再执行后续命令： ```javascript process.env.DIFY_BASE_URL = 'https://dify.example.com'; process.env.ADMIN_API_KEY = 'your-admin-key'; process.env.WORKSPACE_ID = 'your-workspace-id'; ``` 如果用户明确是在本地开发环境测试，`DIFY_BASE_URL` 常见值是： ```javascript process.env.DIFY_BASE_URL = 'http://127.0.0.1:5001'; ``` ## 请求头规则 所有通过 admin key 鉴权的 Console API 请求都要带： ```text Authorization: Bearer ${ADMIN_API_KEY} X-WORKSPACE-ID: ${WORKSPACE_ID} ``` admin key 生效时不需要 `X-CSRF-Token`，也不需要登录 cookie。API 会在指定 workspace 中找到一个 owner 账号，并以该账号身份执行。 ## 可选：查询 workspace id 如果用户不知道 `WORKSPACE_ID`，最简单的方式是在 Dify 网页上按 F12 打开开发者工具，找到 `/console/api/workspaces` 接口的响应，其中 `id` 字段即为 `WORKSPACE_ID`： ```json { "workspaces": [ { "id": "d4e26a01-162f-4366-9a25-1c2c1bdd15dz", "name": "admin's Workspace", "current": true } ] } ``` ## 创建工作流应用 先确认： ```javascript process.env.APP_NAME = 'admin-key-test-workflow'; process.env.APP_DESCRIPTION = 'created by admin api key test'; ``` ```bash curl -i -X POST "${DIFY_BASE_URL}/console/api/apps" -H "Authorization: Bearer ${ADMIN_API_KEY}" -H "X-WORKSPACE-ID: ${WORKSPACE_ID}" -H "Content-Type: application/json" -d "{\"name\": \"${APP_NAME}\", \"mode\": \"workflow\", \"description\": \"${APP_DESCRIPTION}\"}" ``` 成功时应返回： ```text HTTP/1.1 201 CREATED ``` ## 导出应用或工作流 DSL 先确认： ```javascript process.env.APP_ID = 'your-app-id'; process.env.INCLUDE_SECRET = 'false'; ``` ```bash curl -sS -X GET "${DIFY_BASE_URL}/console/api/apps/${APP_ID}/export?include_secret=${INCLUDE_SECRET}" -H "Authorization: Bearer ${ADMIN_API_KEY}" -H "X-WORKSPACE-ID: ${WORKSPACE_ID}" ``` 如果要导出指定草稿 workflow，追加 `workflow_id`： ```javascript process.env.WORKFLOW_ID = 'your-workflow-id'; ``` ```bash curl -sS -X GET "${DIFY_BASE_URL}/console/api/apps/${APP_ID}/export?include_secret=${INCLUDE_SECRET}&workflow_id=${WORKFLOW_ID}" -H "Authorization: Bearer ${ADMIN_API_KEY}" -H "X-WORKSPACE-ID: ${WORKSPACE_ID}" ``` 响应结构： ```json { "data": "version: 0.6.0\nkind: app\n..." } ``` ## 导入 DSL 从 YAML 内容导入： ```bash curl -i -X POST "${DIFY_BASE_URL}/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 内容>\"}" ``` 从 URL 导入： ```bash curl -i -X POST "${DIFY_BASE_URL}/console/api/apps/imports" -H "Authorization: Bearer ${ADMIN_API_KEY}" -H "X-WORKSPACE-ID: ${WORKSPACE_ID}" -H "Content-Type: application/json" -d "{\"mode\": \"yaml-url\", \"yaml_url\": \"https://example.com/workflow.yml\"}" ``` 如果要覆盖已有 workflow 或 advanced-chat 应用，传入 `app_id`： ```bash curl -i -X POST "${DIFY_BASE_URL}/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 内容>\", \"app_id\": \"${APP_ID}\"}" ``` 如果导入返回 `202` 且 `status: pending`，需要确认导入： ```bash curl -i -X POST "${DIFY_BASE_URL}/console/api/apps/imports/${IMPORT_ID}/confirm" -H "Authorization: Bearer ${ADMIN_API_KEY}" -H "X-WORKSPACE-ID: ${WORKSPACE_ID}" -H "Content-Type: application/json" -d "{}" ``` ## 排查 - `201 CREATED`：创建应用成功。 - `200 OK`：导出或导入完成，或已返回数据。 - `202 ACCEPTED`：导入进入 pending，需要调用 confirm 接口。 - `401 Invalid token`：admin key 缺失、未启用、值不正确，或配置变更后 API 进程未重启。 - Connection refused：`DIFY_BASE_URL` 不可达，或 API 服务未运行。 - `ModuleNotFoundError: werkzeug.utils`：`.venv` 里的 Werkzeug 安装损坏；重装 `Werkzeug==3.1.6` 或重建 `api/.venv`。