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