> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 部署环境

> 调用运行在部署环境中的应用，了解它们专有的基础 URL、认证方式和错误码

在 [部署环境](/zh/3.13.x/use/deploy/overview) 中，应用的 API 使用 `v2` 基础 URL，调用时使用的密钥只对一个应用、一个环境有效。

## 基础 URL

所有部署环境共用一个 `v2` 基础 URL，即把标准服务 API 地址中的 `/v1` 换成 `/v2`。打开应用的 **访问点** 标签页，任一部署环境的 **后端服务 API** 卡片上都能看到它。

## 认证

打开应用的 **访问点** 标签页，在该环境的卡片上生成 API 密钥，并作为 Bearer token 发送：

```bash theme={null}
curl https://api.example.com/v2/workflows/run \
  -H "Authorization: Bearer $DIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {}, "response_mode": "blocking", "user": "user-123"}'
```

每个环境的基础 URL 都一样，因此请求由哪个应用、哪个环境处理，完全取决于密钥：要调用 `staging`，就用为 `staging` 生成的密钥。

已生成的 API 密钥在应用从环境下线后依然有效：下线期间调用会失败，重新部署到该环境后，原有密钥仍然可用。

## 支持的接口

部署环境只提供以下操作。在该基础 URL 上调用其他路径会返回 `404 not_found`。

* Workflow 应用：
  * [执行工作流](/zh/3.13.x/develop/api/deployed-environments/run-workflow)
  * [停止工作流任务](/zh/3.13.x/develop/api/deployed-environments/stop-workflow-task)

* Chatflow 应用：
  * [发送对话消息](/zh/3.13.x/develop/api/deployed-environments/send-chat-message)
  * [停止响应](/zh/3.13.x/develop/api/deployed-environments/stop-chat-message-generation)
  * [获取会话列表](/zh/3.13.x/develop/api/deployed-environments/list-conversations)
  * [删除会话](/zh/3.13.x/develop/api/deployed-environments/delete-conversation)
  * [重命名会话](/zh/3.13.x/develop/api/deployed-environments/rename-conversation)
  * [获取会话历史消息](/zh/3.13.x/develop/api/deployed-environments/list-conversation-messages)
  * [获取会话变量](/zh/3.13.x/develop/api/deployed-environments/list-conversation-variables)
  * [更新会话变量](/zh/3.13.x/develop/api/deployed-environments/update-conversation-variable)

* 两类应用通用：
  * [上传文件](/zh/3.13.x/develop/api/deployed-environments/upload-file)
  * [下载文件](/zh/3.13.x/develop/api/deployed-environments/download-file)

## 错误

HTTP 错误响应示例：

```json theme={null}
{
  "code": "deployment_not_ready",
  "message": "deployment is in progress",
  "status": 503
}
```

流式响应开始后，错误改为以流中的 `error` 事件返回，具体格式见对应接口的说明。

每个操作具体会返回哪些错误码，见对应的参考页面。这组操作中有三种情况反复出现：

* 运行类和上传类操作（工作流的执行与停止、对话的发送与停止、文件上传）在密钥无效或部署不可用时，返回以下错误码：

  | 错误码 | 状态码 | 含义 |
  | :- | :- | :- |
  | `token_invalid` | 401 | API 密钥缺失、格式错误或无法识别。 |
  | `unauthorized` | 401 | API 密钥已撤销。 |
  | `forbidden` | 403 | 该环境的 API 访问已在 **访问点** 中关闭。 |
  | `deployment_undeployed` | 503 | 应用已从此环境下线。部署一个版本即可恢复服务。 |
  | `deployment_not_ready` | 503 | 部署正在进行中，稍后重试。 |
  | `apprunner_not_deployed` | 503 | 环境不可用，例如正在删除、未运行或无法连接。请平台管理员检查该环境。 |
  | `service_not_ready` | 503 | 已部署的版本尚未在该环境中就绪，例如正在加载或正在被替换。稍后重试。 |
  | `enterprise_unavailable` | 503 | 平台侧的路由服务暂时不可用，稍后重试。 |

* 会话管理和文件下载返回：

  * 密钥无效时返回 `401 unauthorized`。
  * 应用关闭了 API 访问，或在此环境中没有可用的部署时，返回 `400 app_unavailable`。

* 工作流运行或对话请求超过该环境的最长执行时间（默认 20 分钟）时会停止，并返回 `request_timeout`：阻塞式返回时响应 HTTP 504，流式返回时则在事件流中收到一个 `status: 504` 的 `error` 事件。

  该时限对应的配置项见 [部署环境（App Runner）](/zh/3.13.x/deploy/advanced-configuration/environment-variables#app-runner) 中的 `enterprise.workflowMaxExecutionTimeSeconds`。