temporal-cloud

Temporal Cloud 技能

使用 tcld 和 temporal CLI 帮助用户诊断并解决 Temporal Cloud 连接、身份验证和配置问题。

核心理念

云服务问题令人头疼，因为它们涉及配置、网络、身份验证和 Temporal 专属代码。大多数问题都有可预测的模式。本技能提供系统化的诊断方法，帮助快速找出根本原因并给出修复方案。

参考资料：

• 完整的 CLI 命令参考和错误代码，请参阅 references/cloud-troubleshooting-reference.md
• 分步设置指南，请参阅 references/common-scenarios.md
• 环境配置文档 - 连接到 Cloud 的 SDK 设置
• HA 命名空间连接 - 多区域端点和 DNS 设置
• Dev Success 故障排除指南 - 配套的连接故障排除指南

不在范围内： Worker 性能调优、扩缩容、指标解读、SDK 专属配置、部署模式。这些主题由单独的 Worker 专项技能介绍。

问题分类

类别	主要症状	首要检查项
tcld 登录	登录失败、令牌刷新失败、账号错误	tcld account get
连接/身份验证	无法连接、访问被拒绝、握手失败	端点格式 + DNS + 端口连通性
含糊不清的运行时错误	context deadline exceeded、workflow is busy	先确定操作和所在层级
mTLS/证书	x509 错误、未知颁发机构、证书过期	openssl x509 -enddate
命名空间	找不到命名空间、SNI 不匹配	命名空间名称格式
HA / 故障转移	故障转移不起作用、区域错误、DNS 记录过时	DNS CNAME 解析
Worker	未获取任务、连接过时	temporal task-queue describe
私有连接	PrivateLink/PSC 错误	VPC 端点状态
速率限制	RESOURCE_EXHAUSTED	APS 限制

处理流程

步骤 1：确定类别

询问用户：

• 具体错误消息是什么？（尽可能复制粘贴）
• 你要做什么？（tcld 命令、启动 Worker、运行工作流）
• 最近有什么变更？（新证书、新命名空间、新区域）

步骤 2：收集上下文

审查 SDK/客户端代码片段时：

• 使用哪种身份验证方法：API 密钥还是 mTLS？
• 使用哪个 SDK 和版本？
• 使用的 HostPort / 地址具体是什么？
• 使用的 Namespace 具体是什么？
• 这是 SDK 代码、temporal CLI 还是 tcld？

遇到 tcld 问题时：

• 能否运行 tcld account get？
• 是否有多个 Temporal 账号？

遇到连接问题时：

• 地址 / HostPort 具体是什么？
• 使用 mTLS 还是 API 密钥？
• 使用哪个 SDK 和版本？
• 你与 Cloud 之间是否有防火墙/代理？

遇到含糊不清的运行时错误时：

• 具体在哪个环节看到错误：启动工作流、发送信号/更新、轮询、查询还是日志？
• 错误是在工作开始前、轮询期间，还是工作流代码已经运行时发生的？
• 相关任务队列上是否有轮询器？
• 问题是否在流量激增、部署或配置变更后开始？

遇到证书问题时：

• 证书是什么时候生成的？
• 使用了什么 CA？
• CA 是否已上传到命名空间？

遇到 Worker 问题时：

• Worker 是否正在运行？有多少个？
• temporal task-queue describe 显示了什么？
• Worker 日志中是否有错误？

步骤 3：应用决策树

根据类别使用相应的决策树（见下文）。

步骤 4：提供修复方案

给出解决问题的具体命令，并附上验证步骤。

务必为建议的诊断或修复方案提供置信度评分：

• Confidence: 9-10/10：症状、操作和确认信号完全吻合
• Confidence: 6-8/10：证据充分，但仍存在一种合理的替代解释
• Confidence: 1-5/10：问题仍不明确，“修复方案”实际上只是下一步鉴别检查

如果问题不明确，请明确说明，并将建议限定为下一步检查，而不要把推测性的根本原因说成定论。

决策树

tcld 登录问题

Symptom: tcld login not working
│
├─ Can `tcld account get` run?
│  ├─ Yes → Login is valid; continue with account verification
│  └─ No → Run `tcld login`
│
├─ Token refresh failed?
│  └─ tcld logout && tcld login
│
├─ Wrong organization/account?
│  ├─ tcld account get
│  └─ Verify the expected namespace appears in `tcld namespace list`
│
└─ "unauthorized" or auth errors?
   └─ tcld logout && tcld login

连接失败

文档：环境配置——SDK 连接选项

网络排查前先检查端点：

用例	推荐端点	备注
Worker 和客户端（所有身份验证方式）	<namespace>.<account>.tmprl.cloud:7233	命名空间端点——同时适用于 mTLS 和 API 密钥身份验证。推荐用于所有命名空间。
多区域高可用（高级）	<region>.<cloud_provider>.api.temporal.io:7233	区域端点——仅在需要高级高可用路由时使用。请参阅命名空间访问文档。
tcld / Cloud Ops API	saas-api.tmprl.cloud	控制平面

**例外：**使用 Flexible Auth（预发布版）的命名空间暂时无法使用命名空间端点。

Symptom: Can't connect to Temporal Cloud
│
├─ Check: Using Namespace Endpoint?
│  ├─ Using regional endpoint (`*.api.temporal.io`) without HA need?
│  │  └─ Switch to Namespace Endpoint (`<ns>.<acct>.tmprl.cloud:7233`)
│  ├─ Using old/stale endpoint format?
│  │  └─ Switch to Namespace Endpoint
│  └─ Endpoint looks correct → Continue
│
├─ Check: DNS resolution
│  └─ nslookup <host-from-address>
│     ├─ Fails → DNS issue (check network, VPN)
│     └─ Succeeds → Continue
│
├─ Check: Port connectivity
│  └─ nc -zv <host-from-address> 7233
│     ├─ Fails → Firewall blocking port 7233
│     └─ Succeeds → Continue
│
├─ Check: TLS handshake
│  └─ openssl s_client -connect <address>
│     ├─ Fails → Certificate issue (see mTLS tree)
│     └─ Succeeds → Continue
│
└─ Check: Temporal CLI test
   └─ temporal workflow list --limit 1 --address ...
      ├─ PERMISSION_DENIED → Check namespace name format
      ├─ UNAUTHENTICATED → Certificate not accepted
      └─ Works → Connection OK, issue elsewhere

模糊的运行时错误

不要默认认为这些是纯粹的连接故障。请先根据操作类型进行分类。

错误文本	常见解释	首要鉴别问题
context deadline exceeded	端点错误、网络超时、负载过大、执行路径被阻止、客户端超时	错误发生在流程的哪个环节？
workflow is busy / RESOURCE_EXHAUSTED: Workflow is busy	操作级争用、工作负载压力、面向用户的错误语义容易引起误解	哪项操作返回了该错误？
no pollers	没有已连接的 Worker、Worker 存在但配置不正确、指标过时或具有误导性	temporal task-queue describe 是否显示 poller？

按以下决策顺序进行：

Symptom: ambiguous runtime error
│
├─ Check: Which operation returned the error?
│  ├─ start / signal / update / query request
│  ├─ poll loop / worker logs
│  └─ UI / metrics only
│
├─ Check: Is work reaching a task queue?
│  ├─ No pollers listed
│  │  └─ Treat as worker connectivity / config until proven otherwise
│  ├─ Pollers listed, backlog growing
│  │  └─ Worker capacity / tuning issue (out of scope for this skill)
│  └─ Pollers listed, no backlog issue
│     └─ Continue
│
├─ For `context deadline exceeded`
│  ├─ Happens before any work starts
│  │  └─ Check endpoint format, auth, proxy, DNS, firewall
│  ├─ Happens on workflow start with large payloads
│  │  └─ Consider payload size / client timeout path
│  └─ Happens during local execution / queries
│     └─ Consider blocked execution path, local activity, or client-side timeout
│
└─ For `workflow is busy`
   ├─ Identify exact API / operation
   ├─ Check whether user is conflating this with a generic workflow failure
   └─ Explain that the error class is operation-specific before prescribing fixes

如果操作及其周边信号仍不足以解释错误，请将其标记为模糊情况，并在建议修复方案前收集更多上下文。

回复时，请为建议的诊断或下一步提供 1-10 的置信度评分。模糊情况应给出较低的置信度评分，并建议范围明确的下一步检查，而不是声称存在广泛适用的修复方案。

SDK 代码片段审查

当用户粘贴 SDK 配置时，请先验证配置本身，再建议进行更底层的网络检查。

按以下顺序审查：

1. 身份验证方式：API 密钥还是 mTLS
2. 地址 / HostPort：大多数情况下应使用命名空间端点（<ns>.<acct>.tmprl.cloud:7233）
3. 命名空间：完整的 Cloud 命名空间格式（<namespace>.<account-id>）
4. TLS 配置：对于 API 密钥身份验证，空的 tls.Config{} 属于正常情况；mTLS 则需要客户端证书和密钥
5. 环境配置：优先使用 TEMPORAL_ADDRESS、TEMPORAL_NAMESPACE、TEMPORAL_API_KEY、TEMPORAL_TLS_CLIENT_CERT_PATH、TEMPORAL_TLS_CLIENT_KEY_PATH

常见代码片段诊断：

• 使用区域端点（*.api.temporal.io），而命名空间端点即可满足需求 → 简化为 <ns>.<acct>.tmprl.cloud:7233
• HostPort 为空，且使用 Cloud 命名空间 / 身份验证 → 缺少明确的 Cloud 端点
• API 密钥未启用 SDK / 运行时的 TLS → 查看对应 SDK 的 Cloud 指南
• 使用旧端点格式（过时的文档 / 示例）→ 更新为当前的命名空间端点

如果代码片段有误，请先修正。端点和命名空间尚未确认合理之前，不要先排查 DNS / TLS。

证书错误

Symptom: x509 certificate errors
│
├─ "certificate signed by unknown authority"
│  ├─ Is CA uploaded to namespace?
│  │  └─ tcld namespace accepted-client-ca list --namespace <ns>
│  │     ├─ CA not listed → Add it:
│  │     │  tcld namespace accepted-client-ca add \
│  │     │    --namespace <ns> --ca-certificate-file ca.pem
│  │     └─ CA listed → Cert not signed by that CA
│  │        └─ Verify: openssl verify -CAfile ca.pem client.pem
│  │
│  └─ Self-signed cert without CA?
│     └─ Must use CA-signed certs for Cloud
│
├─ "certificate has expired"
│  ├─ Check expiry: openssl x509 -enddate -noout -in cert.pem
│  └─ Generate new cert:
│     tcld generate-certificates end-entity-certificate \
│       --organization <org> --validity-period 365d \
│       --ca-certificate-file ca.pem --ca-key-file ca.key \
│       --certificate-file client.pem --key-file client.key
│
├─ "private key does not match"
│  └─ Wrong key file - verify match:
│     openssl x509 -modulus -noout -in cert.pem | md5
│     openssl rsa -modulus -noout -in key.pem | md5
│
└─ "bad certificate" from server
   └─ Server rejected cert - CA not in accepted list
      └─ tcld namespace accepted-client-ca list --namespace <ns>

命名空间问题

Symptom: namespace not found or access denied
│
├─ Check: Namespace name format
│  ├─ Format: <namespace-name>.<account-id>
│  ├─ Example: my-namespace.a1b2c3
│  └─ Wrong format → Use full namespace name
│
├─ Check: Namespace exists
│  └─ tcld namespace list
│     └─ Not listed → Wrong account, or namespace not created
│
├─ Check: Address format
│  ├─ Namespace Endpoint (recommended): <namespace>.<account>.tmprl.cloud:7233
│  ├─ Regional Endpoint (HA only): <region>.<cloud_provider>.api.temporal.io:7233
│  └─ Using wrong or stale endpoint? → switch to Namespace Endpoint
│
└─ Check: User permissions
   └─ tcld user list
      └─ Verify user has access to namespace

Worker 问题

此技能用于诊断 Worker 的云连接问题。Worker 性能调优、扩缩容和部署模式不在范围内。

文档：环境配置 - SDK 连接设置

Symptom: Workers not picking up tasks
│
├─ Check: Are workers running?
│  └─ Verify worker process is up, check logs for errors
│
├─ Check: Task queue status
│  └─ temporal task-queue describe --task-queue <queue>
│     ├─ No pollers listed → Workers not connected (Cloud issue)
│     │  ├─ Check task queue name matches
│     │  ├─ Check namespace in worker config
│     │  ├─ Verify SDK connection options (see env config docs)
│     │  └─ Check for connection errors in logs
│     │
│     │  Note: if only metrics or dashboards say "no pollers", verify with CLI or another direct surface before concluding workers are absent.
│     │
│     ├─ Pollers listed but backlog growing
│     │  └─ NOT a Cloud issue (worker scaling/tuning problem)
│     │
│     └─ Pollers listed, no backlog
│        └─ Workers healthy, issue is elsewhere
│
├─ Check: DNS caching (common in K8s)
│  └─ Stale DNS can cause workers to connect to wrong endpoint
│     └─ Restart workers to refresh DNS
│
└─ Check: Rate limiting
   └─ RESOURCE_EXHAUSTED in logs?
      └─ See Rate Limiting section

范围说明：

问题类型	是否在范围内？
tcld 登录、证书、命名空间、私有连接	是
Worker 扩缩容、指标、调优、部署	否
“Worker 未获取任务”	是 - 进行诊断；如果不是 Cloud 问题，则转交处理

HA 命名空间连接

文档：HA 命名空间连接

HA（多区域）命名空间使用分层 DNS 结构：

• 命名空间端点：<ns>.<acct>.tmprl.cloud（CNAME 指向活动区域）
• 区域端点：<region>.region.tmprl.cloud
• 故障转移期间，CNAME 会切换区域（TTL 为 15s，约 30s 收敛）

Symptom: HA namespace connectivity or failover issues
│
├─ Check: DNS resolution
│  └─ nslookup <namespace>.tmprl.cloud
│     ├─ Should return CNAME → <region>.region.tmprl.cloud
│     └─ Then resolve to IP address
│
├─ Symptom: Clients not failing over
│  ├─ Check: DNS caching
│  │  ├─ TTL is 15s - clients should converge within 30s
│  │  ├─ Some DNS resolvers cache longer
│  │  └─ Fix: Restart workers to refresh DNS
│  │
│  └─ Check: SDK connection caching
│     └─ Some SDKs cache connections - may need restart
│
├─ Symptom: PrivateLink not working after failover
│  ├─ Check: Regional DNS override configured?
│  │  └─ Need Route 53 private hosted zone for region.tmprl.cloud
│  │     mapping regional endpoints to VPC endpoint IPs
│  │
│  └─ Check: Inter-region connectivity
│     └─ Workers need Transit Gateway or VPC Peering to reach
│        VPC endpoints in both regions
│
├─ Symptom: GCP Private Service Connect not working
│  └─ NOT SUPPORTED: Private connectivity not yet offered for
│     GCP Multi-region Namespaces
│
└─ Symptom: sa-east-1 region issues
   └─ NOT SUPPORTED: sa-east-1 not available for Multi-region namespaces (because there are no other regions on the continent)

HA 的 Worker 部署位置：

• 选项 A：持续在两个区域运行 Worker
• 选项 B：仅在单一区域运行，并通过 Transit Gateway/VPC Peering 访问故障转移区域

私有连接问题

Symptom: PrivateLink or Private Service Connect not working
│
├─ AWS PrivateLink
│  ├─ Check: VPC endpoint status
│  │  └─ AWS Console → VPC → Endpoints → Status = available
│  │
│  ├─ Check: Security groups
│  │  └─ Allow outbound to endpoint on port 7233
│  │
│  ├─ Check: DNS resolution
│  │  └─ Should resolve to private IP (10.x or 172.x)
│  │
│  └─ Check: Connectivity rules
│     ├─ tcld connectivity-rule list --namespace <ns>
│     └─ If needed, attach rules with:
│        tcld namespace set-connectivity-rules --namespace <ns> --connectivity-rule-ids <id>
│
├─ GCP Private Service Connect
│  ├─ Check: PSC endpoint status
│  │  └─ GCP Console → Network Services → Private Service Connect
│  │
│  ├─ Check: Firewall rules
│  │  └─ Allow egress to PSC endpoint
│  │
│  └─ Check: DNS configuration
│     └─ Cloud DNS zone for tmprl.cloud pointing to PSC
│
└─ General
   └─ Verify rule details:
      tcld connectivity-rule get --connectivity-rule-id <id>

速率限制

Symptom: RESOURCE_EXHAUSTED errors
│
├─ Check: Which operation is limited?
│  └─ Error message indicates operation type
│
├─ "namespace write ops" exceeded
│  ├─ Too many workflow starts
│  ├─ Too many signals/updates
│  └─ Fix: Add backoff, batch operations
│
├─ "namespace read ops" exceeded
│  ├─ Too many list/query operations
│  └─ Fix: Add caching, reduce polling frequency
│
└─ Poll operations rate limited
   ├─ Too many pollers across workers
   └─ Fix: Reduce MaxConcurrentPollers settings

常见场景

请参阅 references/common-scenarios.md，了解分步操作指南：

• API 密钥连接设置
• 新命名空间设置（mTLS）
• 证书轮换
• 从 mTLS 切换到 API 密钥

常见陷阱

陷阱	原因	解决方法
命名空间格式错误	使用了短名称，而不是 name.account-id	使用 tcld namespace list 中的完整命名空间
自签名证书	尝试在没有 CA 的情况下使用自签名证书	先生成 CA，再用其签署证书，并上传 CA
不必要地使用区域端点	使用 *.api.temporal.io，而命名空间端点可用	切换到 <namespace>.<account>.tmprl.cloud:7233
端点文档过时	使用了命名空间端点普及之前的过时示例	使用命名空间端点：<ns>.<acct>.tmprl.cloud:7233
证书过期	未监控证书有效期	设置提醒，并在证书过期前轮换
tcld 账户错误	登录了其他组织	使用 tcld account get，然后通过 tcld namespace list 验证命名空间
tcld 登录状态过时	缓存的身份验证状态已失效	tcld logout && tcld login
DNS 缓存	K8s Pod 缓存了旧 DNS 记录	更改端点后重启 Pod
缺少端口	防火墙阻止了 7233 端口	确保允许通过 7233 端口出站

提示

• 务必获取准确的错误消息 - 复制粘贴，不要转述
• 先检查简单问题 - DNS、端口连接、证书是否过期
• 默认使用命名空间端点 - <ns>.<acct>.tmprl.cloud:7233 同时适用于 mTLS 和 API 密钥身份验证
• 使用 openssl 排查证书问题 - 它给出的错误消息比 SDK 更清晰
• tcld account get 是你的好帮手 - 它会显示当前账户上下文
• 命名空间名称区分大小写 - 必须完全匹配
• API 密钥比 mTLS 更简单 - 对于更简单的设置，可考虑使用 API 密钥
• 引导用户查看环境配置文档 - 环境配置涵盖所有 SDK 连接选项