部署

创建文档部署（发布文档），生成可通过 API 调用的版本快照。

源码: apps/backend/src/routes/deployments.ts

POST /deployments

创建新的 deployment（发布文档）。

认证方式

JWT Token / API Key / Agent Token（combinedAuth），或 OAuth access token（须有 releases:publish Scope）。OAuth 请求仍按授权用户在文档所属 Project 上的写权限校验。

版本规则

每次发布会根据 API Schema 的变化自动计算版本号：

场景	版本变化	示例
首次发布	`1.0`	-
API Schema 无变化	小版本 +0.1	`1.0` -> `1.1`
API Schema 有变化	主版本 +1，小版本重置	`1.1` -> `2.0`

请求参数

Body 参数

json

{
  "document_id": "uuid",
  "visibility": "public"
}

参数	类型	必填	说明
`document_id`	string	是	要发布的文档 UUID
`visibility`	`"public"` \| `"private"`	是	可见性。`public`：任何持有 API Key 的用户可调用；`private`：仅同团队成员可调用
`revision_id`	string（UUID）	条件必填	`DOCUMENT_VERSIONING_WRITE_ENABLED=true` 时必须传已创建的 revision ID；未启用时可不传，走现有草稿快照发布路径

版本化写功能未启用时，POST /documents/:documentId/revisions 会返回 404 document_versioning_write_disabled，不影响本接口按旧路径创建 deployment。版本化写功能启用后，请先创建 revision，再带其 revision_id 发布。详情见文档修订 API。

响应格式

状态码: 201

json

{
  "id": "uuid",
  "owner_user_id": "uuid",
  "project_id": "uuid",
  "document_id": "uuid",
  "team_id": "uuid",
  "version_major": 1,
  "version_minor": 0,
  "snapshot": { "type": "doc", "content": [...] },
  "api_schema": {
    "inputs": [
      { "name": "text", "type": "text", "required": true }
    ],
    "outputs": [
      { "variableName": "result", "variableType": "string" }
    ]
  },
  "visibility": "public",
  "doc_type": "workflow",
  "sub_deployments": [],
  "created_at": "2026-03-07T12:00:00.000Z",
  "updated_at": "2026-03-07T12:00:00.000Z",
  "deleted_at": null
}

字段	类型	说明
`id`	string	部署 UUID
`version_major`	number	主版本号
`version_minor`	number	次版本号
`snapshot`	object	文档内容快照（ProseMirror 格式）
`api_schema`	ApiSchema	API 输入输出定义
`visibility`	string	可见性
`doc_type`	string	文档类型
`sub_deployments`	SubDeploymentRef[]	子文档部署引用（级联发布）

请求示例

bash

curl -X POST \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"document_id": "DOC_UUID", "visibility": "public"}' \
  https://block2-api.wainao.chat/deployments

错误码

级联部署在创建任何快照前校验根文档与全部依赖文档的活动引用。引用不合法时返回 400 { error: "人类可读错误", code: "workflow_reference_invalid", details: { failedDocId, referenceIssues } }；referenceIssues 包含引用的 code/reference/path，适用时带 blockId/nearBlockId。修正 failedDocId 对应文档后再部署，不会先留下部分部署快照。

状态码	错误	说明
400	`无效的请求体`	请求体不是有效 JSON
400	`document_id 是必填字段`	缺少 document_id
400	`visibility 必须是 public 或 private`	visibility 值无效
400	`REVISION_REQUIRED`	版本化写功能已启用，但请求缺少 `revision_id`（响应的稳定码位于 `code` 字段）
400	`workflow_reference_invalid`	根文档或依赖文档的引用无效；稳定码在 `code`，`details.failedDocId/referenceIssues` 定位目标
403	`insufficient_scope` / 项目权限错误	OAuth token 缺少 `releases:publish`，或授权用户无项目写权限
404	`文档不存在或无权访问`	文档不存在或无权限
500	`<error message>`	创建部署过程中发生的其他错误

部署 ​

POST /deployments ​

认证方式 ​

版本规则 ​

请求参数 ​

Body 参数 ​

响应格式 ​

请求示例 ​

错误码 ​

部署