Deployments v2 与 Revision 生命周期

资源模型

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

Control Plane 快速流程是：

POST /v2/deployments，取得 Deployment ID 与 latest_revision_id；
GET /v2/deployments/{deployment_id} 读取部署；
轮询 GET .../revisions/{revision_id}，直到 Revision 为 DEPLOYED 或终止态；
后续使用 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；不要依赖当前分支内容重建“同名版本”。