---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags: [langchain, langsmith, cloud, deployment, cicd]
topic: Cloud、自托管控制面与多框架部署流水线
sources:
  - "https://docs.langchain.com/langsmith/cicd-pipeline-example"
  - "https://docs.langchain.com/langsmith/deploy-cloudflare-workers"
  - "https://docs.langchain.com/langsmith/deploy-deno"
  - "https://docs.langchain.com/langsmith/deploy-frameworks-and-platforms"
  - "https://docs.langchain.com/langsmith/deploy-google-adk"
  - "https://docs.langchain.com/langsmith/deploy-nextjs"
  - "https://docs.langchain.com/langsmith/deploy-nuxt"
  - "https://docs.langchain.com/langsmith/deploy-other-frameworks"
  - "https://docs.langchain.com/langsmith/deploy-standalone-server"
  - "https://docs.langchain.com/langsmith/deploy-sveltekit"
  - "https://docs.langchain.com/langsmith/deploy-to-cloud"
  - "https://docs.langchain.com/langsmith/deploy-vite-langsmith"
  - "https://docs.langchain.com/langsmith/deploy-with-control-plane"
  - "https://docs.langchain.com/langsmith/deployment-quickstart"
last_verified: 2026-08-11
---

# Cloud 与多框架部署流水线

## Cloud 的两条发布路径

| 路径 | 构建来源 | 优点 | 风险与控制 |
| --- | --- | --- | --- |
| LangSmith UI + GitHub | 已授权 Repository | 自动构建、push 可触发 Revision | GitHub App 权限、默认分支和自动发布范围需审计 |
| `langgraph deploy` | 本地项目；可本地或远程构建 | 不依赖 GitHub，适合 CI | 必须固定 CLI/架构；Apple Silicon 要验证 `linux/amd64` |

Cloud 创建前必须先通过 `langgraph dev`，但这只是必要条件。UI 路径首次需要 GitHub Organization owner/admin 授权 `hosted-langserve` App；后续开发者仍要有 Deployment 权限。新 Revision 与 Deployment 是不同对象，更新应创建 Revision、观察构建/服务日志和指标，再决定切流或中断。

## 推荐 CI/CD 门禁

```text
PR
 ├─ 静态检查 + 单元测试
 ├─ Graph/Tool 集成测试
 ├─ 离线 Dataset 评估（AgentEvals/OpenEvals/LangSmith）
 └─ Preview Revision + 端到端验证
       └─ 质量阈值通过 → Production Revision
             └─ 在线 Trace/规则/评估/告警
```

- CI 要明确区分 LangSmith 数据 API 与 Deployment Control Plane API；混用 endpoint 是官方列出的常见错误。
- 预览和生产用独立 Secrets、模型配额与数据范围；不要让 PR 环境读取生产长期记忆。
- 发布门禁使用相对基线和关键失败样本，不只比较平均分。
- Revision 失败应中断/回滚，不删除整个 Deployment；保留构建日志、评估结果和版本关联供审计。

## 自托管控制平面发布

启用完整 Self-hosted Deployment 后，集群新增 Control Plane、Listener 与 Operator。典型流程是：本地验证 → `langgraph build` → 推到集群可访问的私有 Registry → 在自托管 Control Plane UI 填镜像 URL → Listener/Operator 部署。

这条路径不会替你管理 Registry、镜像签名、漏洞扫描或回滚。私有 Registry 凭据应由 Kubernetes Secret/工作负载身份提供；禁止把凭据写进镜像 URL 或 `langgraph.json`。

## Standalone Agent Server

Standalone 不需要 Control Plane，可用 Kubernetes、Docker 或 Compose 直接运行 API/Queue + PostgreSQL + Redis，并可选把 Trace 发到 Cloud 或自托管 LangSmith。它是生产可用拓扑，但所有发布、扩缩容、健康检查和数据库生命周期由客户负责。

官方明确不建议把 Standalone Server 跑在会 scale-to-zero 的 Serverless 环境：后台任务可能丢失，冷启动扩容也不可靠。需要 Serverless Web 前端时，将持久 Agent Server 放在 Deployment/常驻容器，前端只做协议代理。

## 任意 Agent 框架接入

LangSmith Deployment 的服务契约是 Agent Server/Graph，而不是限定业务框架：

- Google ADK：`deployments-wrap-sdk` 把 ADK Runner、Session 与 token event 桥接成 Graph；包名是 `deployments-wrap-sdk`，import path 是 `saf_sdk`。
- Claude Agent SDK、Strands、CrewAI、AutoGen 等：用 LangGraph Functional API 的 `@task` + `@entrypoint` 包装入口，并用 `entrypoint.final(value, save)` 分离本轮输出与下轮持久状态。
- 未列出的框架也可按同样模式包装 callable，但 Tool/interrupt/streaming 能力取决于原框架和包装层，不能假设与原生 LangGraph 完全一致。

接入验收要覆盖：session/checkpoint 恢复、partial token、Tool error、cancel/interrupt、Trace 父子关系、并发与幂等。

## Full-stack Web 的共同协议

Next.js、Nuxt、SvelteKit、Cloudflare Workers、Deno 和 Vite 示例共享 Agent Streaming Protocol：

- `POST /api/threads/:threadId/commands` 接收 `run.start` 等命令；
- `POST /api/threads/:threadId/stream` 返回 SSE；
- `GET/POST /api/threads/:threadId/state` 读写/初始化状态；
- Sidebar 还需要 Thread 列表、历史与删除路由。

示例的内存 Map、单实例对象或本地文件只适合演示。生产必须选择适配宿主的持久层：Cloudflare 可用 Durable Objects，Vercel/Node 可用外部 Redis/DB，并验证多实例、冷启动和 SSE replay。

### 框架差异

- Next.js：Route Handler 必须使用 Node runtime，SSE route 需动态执行；Vercel 部署时注意函数超时。
- Nuxt：Nitro 可部署到 Vercel、Netlify 或常驻 Node；不同 preset 的 streaming 行为要实测。
- SvelteKit/Cloudflare：Durable Object class 必须由 Worker module 导出，构建脚本会补充该导出。
- Cloudflare Worker：需 `nodejs_compat`，Free plan 的 DO 使用 SQLite class migration；访问外部模型受 Worker 限额约束。
- Deno：本地 source upload 不会自动跑云端 build command，CLI 部署前必须先构建 SPA。
- Vite + LangSmith：Agent 在 LangSmith Deployment，静态前端只通过 SDK 访问部署 URL；跨域、终端用户 Auth 和环境变量要单独配置。

## 生产化检查

1. 明确 Agent 是“嵌入 Web Host”还是“独立 Agent Server”，避免两个后端都维护 Thread。
2. 对 SSE 建立 heartbeat、断线续传、代理 buffering 和最长连接测试。
3. Thread ID 由服务端授权并采用 UUID；客户端给定 ID 不代表拥有该 Thread。
4. 所有协议命令做 schema 校验、幂等和并发策略选择。
5. 演示持久化替换为外部持久层，并验证多实例与恢复。
6. 发布使用 Revision、质量门禁与可观察回滚，不以“构建成功”代替在线验证。