---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: completed
tags:
  - langchain
  - langsmith
  - api-reference
  - self-hosted
  - kubernetes
topic: LangSmith Listeners v2 与自托管计算注册
sources:
  - https://docs.langchain.com/api-reference/listeners-v2
  - https://docs.langchain.com/api-reference/listeners-v2/create-listener
  - https://docs.langchain.com/api-reference/listeners-v2/delete-listener
  - https://docs.langchain.com/api-reference/listeners-v2/get-listener
  - https://docs.langchain.com/api-reference/listeners-v2/list-listeners
  - https://docs.langchain.com/api-reference/listeners-v2/patch-listener
last_verified: 2026-08-11
---

# Listeners v2 与 Self-hosted Compute

Listener 把一个 LangSmith workspace 与客户自托管的计算基础设施关联起来。创建 Listener 只对 LangSmith self-hosted enterprise 组织开放；它不是通用的 webhook/listener API。

## CRUD

| 方法与路径 | 成功 | 失败边界 |
|---|---:|---|
| `GET /v2/listeners?limit=20&offset=0` | 200 | 查询格式错误 422；根文档与 `list-listeners` 是同一操作的两个入口 |
| `POST /v2/listeners` | 201 | 非 self-hosted enterprise 为 403；同 workspace + compute ID 重复为 409；结构错误 422 |
| `GET /v2/listeners/{listener_id}` | 200 | 套餐/权限 403，不存在 404，ID 格式错误 422 |
| `PATCH /v2/listeners/{listener_id}` | 200 | 同样区分 403、404、422 |
| `DELETE /v2/listeners/{listener_id}` | 204 | 同样区分 403、404、422 |

调用方应区分“套餐不允许”与“资源不存在”，不能把 403 自动重试成 404，也不能因 409 再创建一条重复记录。

## 创建与返回模型

`ListenerCreateRequest` 必填：

- `compute_type`：当前是常量 `k8s`；
- `compute_id`：用户分配的基础设施唯一 ID，可使用集群名；
- `compute_config`：与计算类型对应的配置；
- 可选 `version`。

同一 workspace 中 `compute_id` 必须唯一，而且 `compute_type`、`compute_id` 创建后不可变。`PATCH` 只接受 `version` 和 `compute_config`，说明更换集群身份应走新建/迁移流程，而不是在原 Listener 上偷换。

返回 `Listener` 除上述字段外还有系统生成的 UUID `id`、`created_at`、`updated_at`。列表返回 `resources` 与 `offset`。

## Kubernetes 配置

`ListenerComputeConfig` 当前只有可空的 `k8s_namespaces` 列表。字段在 Schema 层可空，但服务端会按 `compute_type` 做组合校验，因此“OpenAPI 显示 nullable”不等于任意组合都有效。

namespace 列表本质上是可管理范围，应视为权限边界：

- 明确 allowlist，避免默认覆盖整个集群；
- 变更前验证目标 namespace、RBAC、NetworkPolicy 和 ServiceAccount；
- Patch 后观察 Listener 心跳/同步、目标 Deployment reconcile 与审计日志；
- 删除 Listener 前确认没有 Deployment 依赖该 compute ID。

## 生产运行建议

1. 创建前先列表查询 `(workspace_id, compute_id)`，409 后读取并核对现有资源，保证重试幂等。
2. 将 Listener ID、compute ID、集群/namespace 映射、版本与变更人写入 CMDB 或部署审计。
3. 控制面 API key 使用最小权限并定期轮换；不要把集群凭据或 kubeconfig 放进 Listener payload。
4. 对 403 做权限/订阅告警，对 404 做资源漂移告警，对 422 记录脱敏后的字段错误；仅对瞬态网络错误退避重试。
5. compute ID 与 namespace 变更属于基础设施权限变化，应经过审批、预检和可回滚迁移。