---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: completed
tags:
  - langchain
  - langsmith
  - api-reference
  - deployment
  - operations
topic: LangSmith Deployments v2 与 Revision 生命周期
sources:
  - https://docs.langchain.com/api-reference/deployments-v2
  - https://docs.langchain.com/api-reference/deployments-v2/create-deployment
  - https://docs.langchain.com/api-reference/deployments-v2/create-deployment-revision
  - https://docs.langchain.com/api-reference/deployments-v2/delete-deployment
  - https://docs.langchain.com/api-reference/deployments-v2/delete-deployments
  - https://docs.langchain.com/api-reference/deployments-v2/get-deployment
  - https://docs.langchain.com/api-reference/deployments-v2/get-free-deployment-count
  - https://docs.langchain.com/api-reference/deployments-v2/get-revision
  - https://docs.langchain.com/api-reference/deployments-v2/interrupt-deployment-revision
  - https://docs.langchain.com/api-reference/deployments-v2/list-deployment-logs
  - https://docs.langchain.com/api-reference/deployments-v2/list-deployments
  - https://docs.langchain.com/api-reference/deployments-v2/list-revision-logs
  - https://docs.langchain.com/api-reference/deployments-v2/list-revisions
  - https://docs.langchain.com/api-reference/deployments-v2/patch-deployment
  - https://docs.langchain.com/api-reference/deployments-v2/patch-deployment-resource-tiers
  - https://docs.langchain.com/api-reference/deployments-v2/patch-deployment-tier
  - https://docs.langchain.com/api-reference/deployments-v2/redeploy-revision
last_verified: 2026-08-11
---

# Deployments v2 与 Revision 生命周期

## 资源模型

Deployment 是稳定的部署身份与资源配置，Revision 是一次可构建、可部署、可中断或重部署的版本。创建 Deployment 会自动创建首个 Revision；修改源码、镜像、环境变量等 revision-relevant 字段会产生新 Revision，而仅修改显示名不产生新 Revision。

Control Plane 快速流程是：

1. `POST /v2/deployments`，取得 Deployment ID 与 `latest_revision_id`；
2. `GET /v2/deployments/{deployment_id}` 读取部署；
3. 轮询 `GET .../revisions/{revision_id}`，直到 Revision 为 `DEPLOYED` 或终止态；
4. 后续使用 `PATCH /v2/deployments/{deployment_id}` 或显式创建 Revision 更新。

HTTP 201 只表示资源已接受创建，不表示 Agent Server 已就绪。

## 端点矩阵

| 资源 | 方法与路径 | 重要参数/响应 |
|---|---|---|
| Deployment 列表 | `GET /v2/deployments` | `limit=20`、`offset=0`；可按名称、状态、reconcile、tag、镜像版本、类型和 ID 过滤。根文档与 `list-deployments` 是同一操作的两个入口 |
| 创建 | `POST /v2/deployments` | 201；名称冲突 409，业务参数冲突 400 |
| 读取 | `GET /v2/deployments/{deployment_id}` | 404 表示不存在 |
| Patch | `PATCH /v2/deployments/{deployment_id}` | 200；可更新显示名、revision 源、配置、tier、secrets |
| 更新统一 tier | `PATCH .../{deployment_id}/deployment-tier` | 请求必须有 `deployment_tier` |
| 独立资源 tier | `PATCH .../{deployment_id}/resource-tiers` | 分别更新 `compute_tier`、`database_tier` |
| 删除一个 | `DELETE /v2/deployments/{deployment_id}` | `delete_tracing_project=false`、`force=false`；成功 204 |
| 批量删除 | `DELETE /v2/deployments?deployment_ids=...` | 返回逐项结果；调用方不能只看整体 200 |
| 免费部署数 | `GET /v2/deployments/free-count` | 返回 `count` |
| Revision 列表 | `GET .../{deployment_id}/revisions` | 分页并可按状态、reconcile 过滤 |
| 创建 Revision | `POST .../{deployment_id}/revisions` | 201；请求只接受 revision-relevant 字段 |
| 读取 Revision | `GET .../revisions/{revision_id}` | 200/404 |
| 中断 | `POST .../revisions/{revision_id}/interrupt` | 204；用于停止正在创建/构建/部署的 Revision |
| 重部署 | `POST .../revisions/{revision_id}/redeploy` | 200；对已有 Revision 再部署 |
| Deployment 日志 | `GET .../{deployment_id}/logs` | 时间范围、升降序、`limit=50`、offset、全文、level、run ID |
| Revision 日志 | `GET .../revisions/{revision_id}/logs` | 同类过滤；额外的 `type` 查询参数必填 |

所有带标识符或复杂查询的操作都可能返回 422；部署/Revision 不存在返回 404；非法状态转换或配置通常返回 400。

## 创建与来源约束

`DeploymentCreateRequest` 必填：

- 不可变的 `name`；系统会创建同名 LangSmith tracing project；
- `source`；
- `source_config` 与 `source_revision_config`；
- `secrets` 数组，即便为空也属于必填结构。

可选 `secret_references` 只适用于 `external_docker`。支持的 `source`：

| source | 用途 | 环境限制 |
|---|---|---|
| `github` | GitHub 仓库构建 | Cloud SaaS |
| `internal_docker` | CLI 推送的镜像 | Cloud SaaS |
| `internal_source` | 上传源码 | Cloud SaaS |
| `internal_template` | 预构建模板 | Cloud SaaS |
| `external_docker` | 外部镜像 | Self-hosted |

Deployment 创建后不能改变默认 `source`、name、GitHub integration/repo 等身份字段。Revision 可以用 `revision_source` 覆盖本次来源，但只允许 `github`、`internal_docker`、`internal_source`。

`SourceConfigRequest` 按来源组合使用 integration ID、repo URL、deployment type、build-on-push、custom URL、资源规格和 listener 等字段。GitHub integration ID 来自 Integrations v1；tag 必须写完整 `refs/tags/...`，且 tag 不可变，不能开启 build-on-push。

`SourceRevisionConfigRequest` 的关键字段：

- `repo_ref`：分支名或完整 tag ref；
- `langgraph_config_path`：`github`/`internal_source` 构建型来源创建时需要，其他来源必须为空；
- `image_uri`：外部镜像；
- `source_tarball_path`：只能使用服务端 upload-url 流程返回的对象路径，不能传任意存储路径。

返回模型还会给只读 `repo_commit_sha`，可用于审计与回滚，不应只记录易漂移的分支名。

## 状态机

Deployment 状态：`AWAITING_DATABASE`、`READY`、`UNUSED`、`AWAITING_DELETE`、`AWAITING_FINAL_DELETE`、`UNKNOWN`。

Revision 状态覆盖完整异步流水线：

`CREATING → QUEUED → AWAITING_BUILD → BUILDING → AWAITING_DEPLOY → DEPLOYING → DEPLOYED`

终止或异常还包括 `CREATE_FAILED`、`BUILD_FAILED`、`DEPLOY_FAILED`、`SKIPPED`、`INTERRUPTED`、`UNKNOWN`。轮询器应：

- 对终止态立即停止；
- 指数退避并设置总超时；
- 用 `revision_id` 而非只看 Deployment 的 `latest_revision_id`，防止并发发布串线；
- `UNKNOWN` 触发告警和人工检查，而不是自动当成功或无限重试。

## Tier、秘密与自托管扩展

固定 tier 枚举为 `SERVERLESS_S/M/L` 与 `DEDICATED_S/M/L`。旧部署的 `compute_tier`/`database_tier` 可能回退到 `deployment_tier`；若两者不同，Deployment 的统一 tier 反映 compute tier。自托管资源模型还可配置 CPU、内存、扩缩容、Redis/Core/数据库资源、Kubernetes labels/annotations、service account、卷、init container、sidecar 等，因此属于高风险运维面，必须经过策略校验。

`secrets` 是环境变量秘密；`secret_references` 用 `name + secret_name + secret_key` 引用部署同 namespace 的既有 Kubernetes Secret。不要把 secret 值写入 Git、构建日志或 Revision 日志；Patch secrets 会触发新 Revision，应纳入发布审批。

## 上线与回滚原则

- 客户端生成自己的发布请求 ID，并保存 Deployment ID、Revision ID、commit SHA、发起人和配置摘要，以便幂等审计。
- 创建接口遇到超时先按名称/ID查询，不能盲目重试制造冲突。
- 发布成功条件应是 Revision `DEPLOYED` 加健康检查、Smoke Test 与观测验证，而非单一 HTTP 状态。
- `force` 删除、批量删除和 `delete_tracing_project=true` 都属于破坏性操作，应双重确认、逐项记录结果并设置保留期。
- 回滚优先重部署已知良好的 Revision；不要依赖当前分支内容重建“同名版本”。