服务注册与分布式协调 / 系统课时

配置 Activity 超时

配置 Activity 超时

本课解决 Activity「到底允许等多久、跑多久、多久没进展就算失活」的问题。你会用四类 Timeout 分别约束排队、单次执行、整段尝试链和心跳进度,并按外部依赖特征组合配置。

学习目标

  • 区分四类 Activity Timeout 的计时起点、覆盖范围与主要用途
  • 为短请求、慢查询和长轮询任务选择合理的超时组合
  • 避免把 Schedule-To-Start 当作执行超时,或用 Heartbeat Timeout 代替总时限

先看四个时间边界

Temporal 的四类 Activity Timeout 解决的是不同问题:Schedule-To-Start 限制任务从进入队列到被 Worker 取走的等待;Start-To-Close 限制一次 Activity Task Execution 从开始到结束的时间;Schedule-To-Close 从调度开始一直覆盖到最终完成,因而可以形成包含重试等待在内的总边界;Heartbeat Timeout 则要求长时间运行的 Activity 持续上报进度,否则会被判定为超时。:contentReference[oaicite:0]{index=0}

可以把它们理解成四个互不替代的保险栓。队列慢,主要看 Schedule-To-Start;单次执行卡住,主要看 Start-To-Close;允许重试但又不想无限延长,增加 Schedule-To-Close;任务本身很长,则用 Heartbeat Timeout 检测 Worker 是否仍在活跃推进。

Activity 四类 Timeout 的计时窗口与组合关系

用一组配置建立基本边界

TypeScript SDK 可以通过 proxyActivities 给 Activity 设置默认 Timeout。下面这个片段同时配置四类边界,假设远端 HTTP 请求通常在几十秒内结束,偶尔需要更长时间,但必须持续发送心跳证明自己还在处理。

ts
import { proxyActivities } from '@temporalio/workflow';
import type * as activities from '../activities';

const { fetchRemoteData } = proxyActivities<typeof activities>({
  scheduleToStartTimeout: '30 seconds',
  startToCloseTimeout: '2 minutes',
  scheduleToCloseTimeout: '10 minutes',
  heartbeatTimeout: '20 seconds',
  retry: {
    maximumAttempts: 3,
  },
});

export async function syncRemoteData(id: string): Promise<string> {
  return fetchRemoteData(id);
}

预期结果

text
Workflow 可以正常调度 Activity;如果 Worker 长时间未取到任务、单次尝试运行过久、总调度窗口耗尽,或心跳长期缺失,Temporal 会分别依据对应 Timeout 判定失败边界。

这组值不是固定模板。尤其要注意 scheduleToCloseTimeout 不是简单地把 startToCloseTimeout 放大几倍;它应该代表一次 Activity 从被调度到最终完成所允许消耗的总窗口,而重试策略也必须放在这个总预算里设计。

按外部依赖选择组合

对于普通 HTTP API,最关键的通常是 Start-To-Close,因为单次调用应该有明确上限;Schedule-To-Start 可以较短,用来发现 Worker 饱和。若该 Activity 允许自动重试,再用 Schedule-To-Close 限制整个 Activity 生命周期。

对于批量导出、文件处理、长时间轮询等任务,Heartbeat Timeout 更重要。Activity 每完成一个可观测阶段就发送一次 heartbeat,既能告诉 Temporal Worker 仍然存活,也能让系统在长时间没有进展时及时失败。:contentReference[oaicite:1]{index=1}

不要把所有 Timeout 都设置成同一个数字。排队等待、单次执行和业务总时限表达的是不同约束;统一设置往往会掩盖 Worker 容量问题,或者把本应快速失败的外部故障拖得很久。

最容易配错的边界

只配 Start-To-Close。 这能限制单次执行,却不能表达整体调度窗口。Activity 存在重试时,总耗时仍可能远超一次尝试的时长,因此有总窗口要求时应同时考虑 Schedule-To-Close。

把 Schedule-To-Start 设置得特别长。 这样做会让 Worker 饱和更难暴露。它更适合表达「多久还没有任何 Worker 接手就应该视为异常」,而不是给业务操作本身预留时间。

配置 Heartbeat Timeout 却不发送 heartbeat。 Heartbeat Timeout 只有在 Activity 实际持续发送心跳时才有意义;没有心跳的 Activity 无法及时把取消等运行中信号传递给自身。:contentReference[oaicite:2]{index=2}

实际设计时,先从业务依赖倒推:外部系统最快失败时间、正常 P95、允许重试次数、最长业务窗口和可观测进度点。把这些约束分别映射到四类 Timeout,最终得到的是一套可解释的时间边界,而不是一组拍脑袋的秒数。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 Activity 超时

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通