136 lines
10 KiB
Markdown
136 lines
10 KiB
Markdown
# Orbit 功能说明：Pulse 与公共能力
|
||
|
||
> 版本 0.2 · 2026-09-17。Pulse 与 Weave 首版功能范围已确认；标注“建议”的细节待评审。Weave 具体范围另见流程设计。基础、任务执行、调度、资源控制和可靠订阅已实现；批量受理、独立任务核查/人工重试、业务键/创建时间查询及直接来源追踪已实现，事务Outbox接入等继续开发，实现状态见持续开发计划。
|
||
|
||
## 1. 目标与责任边界
|
||
|
||
Orbit 统一提供任务调度与流程编排。Pulse 接收一个明确的工作单元，按照时间、容量、权限和重试策略交给业务 Worker 执行，管理可查询、可恢复的执行过程。Weave 将多个工作单元按流程规则连接起来，具体方案见 [流程设计](06-workflow-spec.md)。
|
||
|
||
| 参与方 | 职责 |
|
||
| --- | --- |
|
||
| Pulse | 任务受理、调度、派发、执行权、重试控制、运行记录、结果交付 |
|
||
| 业务系统 / Worker | 业务校验、业务授权、外部调用、业务幂等、业务结果与证据 |
|
||
| Weave（内部模块） | 研发定义发布、多步骤依赖、分支、汇合、持久化等待、有界重复查询、暂停/继续、人工恢复与流程版本 |
|
||
| MySQL 运维 | 数据持久化与复制配置、备份、故障切换、恢复演练 |
|
||
|
||
任务可以是一次文件转换、一次数据准备或一次外部作业结果查询。Pulse 管理任务执行过程，具体业务结果和完成条件由处理器契约定义。
|
||
|
||
任务类型、参数和标识采用通用模型，不要求平台理解接入方的专用业务概念。
|
||
|
||
## 2. 基本概念
|
||
|
||
| 概念 | 含义 |
|
||
| --- | --- |
|
||
| 应用 / 环境 / 命名空间 | 接入身份与资源边界；建议一个应用环境对应一个命名空间 |
|
||
| 队列 | 任务路由、资源配置与 Worker 消费范围 |
|
||
| 任务类型与版本 | 处理器身份及其兼容版本 |
|
||
| 任务 | 一项已受理工作，具有稳定的任务 ID |
|
||
| 执行尝试 | 一次派发与执行过程，具有独立尝试 ID 和执行凭据 |
|
||
| 调度计划 | 产生任务的时间规则，每次实际触发产生独立任务 |
|
||
| 业务关联键 | 由业务方提供的查找、追踪标识 |
|
||
| 并发控制键 | 在规定作用域内限制同时有效执行许可的通用标识 |
|
||
|
||
自动重试沿用任务 ID，产生新的执行尝试。HTTP 请求重试、任务重试和定时计划的下一次触发是三件不同的事情。
|
||
|
||
Weave 有界查询的一轮对应一个 Pulse 任务；查询得到“处理中”后，Weave 等待并创建下一轮任务。当前轮请求失败由 Pulse 在原任务下重试，不能通过开启新轮次绕过重试上限。
|
||
|
||
## 3. 任务提交与管理
|
||
|
||
### 3.1 提交方式
|
||
|
||
- **立即执行**：受理后尽快进入可派发范围，实际开始时间受资源和排队影响。
|
||
- **延迟执行**：在指定等待时长之后才允许开始。
|
||
- **指定时间执行**：在指定时间之后才允许开始，不承诺硬实时触发。
|
||
- **批量提交**：多项普通任务的提交方式；已实现最多32项逐项返回结果，每项独立幂等，失败项独立补交，整批请求不超过512 KiB。
|
||
|
||
任务至少说明：归属、队列、处理器与版本、参数版本、执行时间、时限、重试规则和提交幂等标识。已受理参数与生效策略保存快照；修改配置不静默改写历史任务。
|
||
|
||
最晚允许开始时间、单次执行超时、任务总时限分别定义。到期后停止授权新的执行；已经发出的业务请求是否产生效果，需要按处理器的结果确认规则判断。
|
||
|
||
### 3.2 操作行为
|
||
|
||
| 操作 | 目标行为 |
|
||
| --- | --- |
|
||
| 幂等提交 | 同作用域、同标识、同语义请求返回原任务；同标识不同请求明确冲突 |
|
||
| 查询 | 返回当前任务状态、关联计划、执行尝试、错误与结果引用 |
|
||
| 取消待执行任务 | 在与开始执行的竞争中原子决定取消是否生效 |
|
||
| 取消执行中任务 | 持久化取消意图并通知 Worker，等待停止或最终结果，已有业务效果不自动撤销 |
|
||
| 人工重试 | 校验权限、错误类别及业务确认条件，保留原历史，记录操作人和原因 |
|
||
| 修改业务参数 | 新建关联任务，原任务参数不变 |
|
||
|
||
**当前契约：人工重试创建带 `retry_of` 的新任务。** 原任务保留终态及结果，避免外部订阅方已经消费终态后任务又悄悄恢复。业务幂等键应按原操作语义保留；平台新任务 ID 不代表允许重复产生业务副作用。每个原任务最多一个直接后继，继续重试沿后继任务推进；需要明确安全声明、版本、证据和审计，详见[人工恢复接口](api/task-recovery.md)。
|
||
|
||
流程关联任务的人工恢复统一经过 Weave，校验流程版本、步骤归属和当前恢复条件；不能直接从普通任务重试入口生成无人接续的流程任务。
|
||
|
||
流程暂停的门控建议由 Pulse 通用执行控制承载，阻止关联任务的新领取、开始和执行重试，同时继续收集已授权执行的结果。它与定时计划暂停、队列暂停分别建模；具体规则见 [Weave 暂停与继续](06-workflow-spec.md#71-暂停与继续)。
|
||
|
||
任务成功表示处理器完成约定的这一步。例如“渠道提交已受理”可以是一个处理器的成功结果，最终业务成功应由查询或回执处理任务另行确认。
|
||
|
||
## 4. 定时计划
|
||
|
||
- 支持 Cron、固定间隔、时区、生效与结束边界、启用、暂停、恢复和修改计划。
|
||
- **设计建议**：首版采用五段 Cron；固定间隔首先定义为按基准时间推进的 fixed-rate。是否增加“完成后再等待”的 fixed-delay 待确认。
|
||
- 每个实际触发点具有唯一身份，记录采用的计划版本与原计划时间。
|
||
- 计划变更明确生效边界；已生成任务保留原参数与策略快照。
|
||
- 暂停计划阻止新的触发，不隐式取消已经生成或正在执行的任务。
|
||
|
||
创建计划时必须明确以下策略，不能在故障后临时猜测：
|
||
|
||
| 情况 | 可选策略及限制 |
|
||
| --- | --- |
|
||
| 漏跑 | 跳过、合并为一次、按次补跑；补跑必须有数量/时间窗口与速率上限 |
|
||
| 上一轮未完成 | 允许并行、串行等待、跳过本次；串行等待也必须有积压上限 |
|
||
| 时区夏令时变化 | 明确不存在时刻、重复时刻的处理，首版选定并测试后发布 |
|
||
| 停机期间修改计划 | 保存版本与生效边界，按明确的历史版本计算漏跑 |
|
||
|
||
跳过和合并需留下原因、原计划时间或覆盖范围。业务日历由业务系统决定，Pulse 执行其提交的时间计划。
|
||
|
||
## 5. Worker 与执行恢复
|
||
|
||
- Worker 通过 WSS 主动连接，经过鉴权后声明处理器版本、消费队列及执行容量。
|
||
- SDK 封装消息收发、任务去重、租约续期、结果重报、带抖动的重连和优雅退出。
|
||
- 同一 Worker 可执行多个任务，网络读写不能被业务处理器阻塞。
|
||
- 任务只分配给版本兼容且有容量的 Worker；无兼容 Worker 时可观测地等待，并受时限约束。
|
||
- 连接心跳检测通信；任务续租确认具体执行权，两者独立。
|
||
- 断线后先核对任务，不直接认定业务失败；无有效租约时 Worker 应停止推进并尝试取消可取消的操作。
|
||
- 优雅退出时停止接新任务，给已有任务留出受控完成时间，退出超时按恢复规则处理。
|
||
|
||
错误至少区分：可安全重试、明确不可重试、需要外部核查、需要人工处理。策略包含退避、抖动、尝试上限或总时限，禁止无限快速重试。
|
||
|
||
副作用是否发生不明确时，不允许因为“网络错误”自动重复提交业务操作。任务类型必须声明恢复安全等级；声明缺失时采用保守处理。
|
||
|
||
## 6. 队列与资源控制
|
||
|
||
- 支持队列并发、应用配额、速率限制、优先级和项目间公平性。
|
||
- 支持按业务提供的并发控制键限制有效执行许可。例如可用资源标识限制同一资源的一类操作。
|
||
- 跨节点限制必须由共享状态协调，单节点内存计数只能约束该节点。
|
||
- 并发控制不自动提供跨任务严格顺序；需要顺序的业务必须明确顺序协议或交由流程编排。
|
||
- 任务数量、参数大小、发送缓冲、事件积压和重试均有有限上限，并提供拒绝/背压行为。
|
||
|
||
过期 Worker 仍可能在物理上运行。业务资源端还需幂等或执行代次校验，避免旧执行产生额外效果。
|
||
|
||
## 7. 多项目、安全与管理
|
||
|
||
支持应用与环境隔离、可轮换凭据、队列级提交和消费授权、查询权限与管理权限。命名空间和 Worker 标识不能替代身份认证。
|
||
|
||
管理操作包括暂停队列派发、调整配额、取消、人工重试和计划变更。都应记录操作人、时间、原因和前后状态。暂停派发不等于强制停止运行中的处理器。
|
||
|
||
参数、结果与日志设置访问控制和脱敏规则。大文件使用业务侧引用；凭据不作为普通任务参数或日志传递。
|
||
|
||
## 8. 查询、审计、告警与结果交付
|
||
|
||
- 通过任务 ID、业务关联键、状态、队列、时间范围查找任务。
|
||
- 保存执行尝试和关键状态转换，关联 Worker、版本、错误分类与结果引用。
|
||
- 监控任务积压、到期派发延迟、重试、失联、数据库异常、结果通知积压和资源用量。
|
||
- 提供可靠结果订阅：事件持久化，接收方处理后确认，未确认可再次交付。
|
||
- 运行统计可最终一致；影响派发与终态判断的状态必须按权威状态读取。
|
||
- Orbit 运行审计与业务审计通过关联标识衔接，保存策略分别制定。
|
||
|
||
## 9. 首版范围与后续扩展
|
||
|
||
上述生产相关行为属于首版设计范围。首版首先交付 Go SDK、管理 API 与必要运行指标。完整图形化控制台、其他语言 SDK、高级全文检索及跨地域主动写入作为后续扩展评估。
|
||
|
||
流程依赖、等待及有界查询由平台内的 Weave 承担，已确认范围见 [流程功能与设计](06-workflow-spec.md)。审批人员与业务权限规则、专用规则计算由业务系统承担。通用 SQL 查询平台、文件处理平台不纳入 Orbit。
|
||
|
||
功能是否达标以 [生产验收](05-production-acceptance.md) 的结果为依据，不以接口存在或演示运行成功代替。
|