Ratus

Ratus 是一个 RESTful 异步任务队列服务器。它将分布式任务队列的概念转化为符合 REST 原则的一组资源，并为各种后端提供了一致的 HTTP API。

Ratus 的主要特性包括：

具有快速内存存储的独立二进制文件。
支持多种嵌入式或外部存储引擎。
保证任务至少执行一次。
统一的优先级和基于时间的调度模型。
任务级别的超时控制和自动恢复。
语言无关的 RESTful API，内置 Swagger UI。
在动态数量的消费者之间进行负载均衡。
通过复制和分区实现水平扩展。
原生支持 Prometheus 和 Kubernetes。

终端截图

快速开始

安装

Ratus 提供多种安装选项：

Docker 镜像可在 Docker Hub 和 GitHub Packages 上获取。
Kubernetes 和 Docker Compose 示例可在 deployments 目录中找到。
所有主要平台的预编译二进制文件可在 GitHub releases 页面获取。
通过 go install github.com/hyperonym/ratus/cmd/ratus@latest 从源代码构建。

从命令行运行 Ratus 非常简单，只需输入：

$ ratus

上述命令将使用默认的内存存储引擎 memdb 启动一个临时 Ratus 实例，并在默认的 HTTP 端口 80 上监听。

要使用其他端口并启用磁盘快照以实现持久化，请使用以下命令启动 Ratus：

$ ratus --port 8000 --engine memdb --memdb-snapshot-path ratus.db

根据您选择的存储引擎，您可能还需要部署相应的数据库或代理。以 mongodb 引擎为例，假设数据库已在本地运行，则使用以下命令启动 Ratus：

$ ratus --port 8000 --engine mongodb --mongodb-uri mongodb://127.0.0.1:27017

基本用法

Ratus 引入的概念将在下文中以粗体显示，请参阅概念（即速查表）了解更多信息。

cURL

生产者创建一个新的任务并将其推送到 example 主题：

$ curl -X POST -d '{"payload": "hello world"}' "http://127.0.0.1:8000/v1/topics/example/tasks/1"

示例响应

{
	"created": 1,
	"updated": 0
}

然后，消费者可以发出一个承诺来认领并执行 example 主题中的下一个任务：

$ curl -X POST "http://127.0.0.1:8000/v1/topics/example/promises?timeout=30s"

示例响应

{
	"_id": "1",
	"topic": "example",
	"state": 1,
	"nonce": "e4SN6Si1nOnE53ou",
	"produced": "2022-07-29T20:00:00.0Z",
	"scheduled": "2022-07-29T20:00:00.0Z",
	"consumed": "2022-07-29T20:00:10.0Z",
	"deadline": "2022-07-29T20:00:40.0Z",
	"payload": "hello world"
}

执行任务后，请记得通过提交来告知 Ratus 任务已 completed：

$ curl -X PATCH "http://127.0.0.1:8000/v1/topics/example/tasks/1"

示例响应

{
	"_id": "1",
	"topic": "example",
	"state": 2,
	"nonce": "",
	"produced": "2022-07-29T20:00:00.0Z",
	"scheduled": "2022-07-29T20:00:00.0Z",
	"consumed": "2022-07-29T20:00:10.0Z",
	"deadline": "2022-07-29T20:00:40.0Z",
	"payload": "hello world"
}

如果在承诺的截止时间之前未收到提交，任务的状态将被重置为 pending，从而允许消费者再次尝试执行该任务。

Go 客户端

Ratus 附带了一个 Go 客户端库，它不仅封装了所有 API 调用，还提供了符合习惯的轮询-执行-提交工作流，如 Client.Poll 和 Client.Subscribe。examples 目录包含了使用该库的可直接运行的示例：

hello world示例演示了客户端库的基本用法。
爬虫前沿示例实现了分布式网络爬虫的简单URL前沿。它利用了并发订阅者和基于时间的任务调度等高级功能。

概念

数据模型

**任务**指代应异步执行的幂等工作单元。
**主题**指具有相同主题名称属性的有序任务子集。
**承诺**表示对活动任务所有权的声明。
**提交**包含要应用于任务的一组更新。

工作流程

生产者客户端将任务及其期望执行日期（计划时间）推送到主题。
消费者客户端承诺执行从主题轮询的任务，并在完成时通过提交确认。

拓扑结构

生产者和消费者客户端都可以同时运行多个实例。
可以动态添加消费者实例以提高吞吐量，任务将在消费者之间自然地进行负载均衡。
消费者实例可以随时移除（或崩溃），而不会冒丢失正在执行的任务的风险：在承诺的期限后未收到提交的任务将被其他消费者重新拾取并执行。

任务状态

待处理 (0)：任务已准备好执行或正在等待将来执行。
活动 (1)：任务正在被消费者处理。超时的活动任务将自动重置为"待处理"状态。消费者代码应处理失败并在必要时将状态设置为"待处理"以便稍后重试。
已完成 (2)：任务已完成执行。如果存储引擎实现支持TTL，已完成的任务将在保留期过期后自动删除。
已归档 (3)：任务作为存档存储。已归档的任务永远不会因过期而被删除。

行为

所有主题的任务ID共享相同的命名空间（ADR）。主题只是基于任务的topic属性生成的子集，因此不需要显式创建主题。
当消费者能够跟上任务生成速度时，Ratus是一个任务调度器；当消费者无法跟上任务生成速度时，Ratus是一个优先队列。
任务在计划时间到达之前不会执行。在计划时间之后，多余的任务将按计划时间的顺序执行。

引擎

Ratus为各种后端提供一致的API，允许用户根据需求选择特定引擎，而无需修改客户端代码。

要使用特定引擎，请将--engine标志或ENGINE环境变量设置为以下名称之一：

名称	持久化	复制	分区	过期
`memdb`	○/●	○	○	●
`mongodb`	●	●	●	●

MemDB

MemDB是Ratus的默认存储引擎。它基于go-memdb实现，后者建立在不可变的基数树之上。MemDB适用于开发和不需要持久性的生产环境。

持久化

MemDB存储引擎默认是临时性的，但它也提供基于快照的持久化选项。通过将--memdb-snapshot-path标志或MEMDB_SNAPSHOT_PATH环境变量设置为非空文件路径，Ratus将按MEMDB_SNAPSHOT_INTERVAL指定的间隔写入磁盘快照。

MemDB不写入仅追加文件（AOF），这意味着如果Ratus由于任何原因在没有优雅关闭的情况下停止工作，你应该准备好丢失最近几分钟的数据。如果持久性对你的工作流程至关重要，请切换到外部存储引擎，如mongodb。

实现细节

列表操作相对昂贵，因为它们需要扫描整个数据库或索引，直到收集到所需数量的结果。幸运的是，这些操作在大多数情况下不会被使用。
快照在适当时与定期后台作业一起执行。如果数据量较大，写入快照文件可能会延迟后台作业的执行。
由于MemDB中计划时间的分辨率为毫秒级，并受实例自身时钟的影响，消费者接收任务的顺序不能严格保证。
不能为completed任务禁用TTL，为了永久保存任务，请将其设置为archived状态。

MongoDB

Ratus最适合与MongoDB版本~4.4配合使用。MongoDB 5.0+也受支持，但需要额外考虑，请参阅实现细节了解更多信息。

💭 简而言之 使用MongoDB 5.0+时，请设置MONGODB_DISABLE_ATOMIC_POLL=true。

复制

使用MongoDB存储引擎时，Ratus实例本身是无状态的。为了实现高可用性，启动多个Ratus实例并将它们连接到同一个MongoDB复制集。

所有Ratus实例应运行在配置了健康检查的负载均衡器后面。生产者和消费者客户端应连接到负载均衡器，而不是直接连接到实例。

分区

通过对任务集合进行分片可以实现水平扩展。然而，在TTL机制的帮助下，大多数情况下不需要分区。只有在不分片的情况下才能获得最佳性能和最强的原子性。

如果数据量超过单个节点或复制集的容量，请从以下分片选项中选择：

如果有大量主题，使用topic字段的哈希索引作为分片键，这也将在分片集群上实现最佳的轮询性能。
如果在少数几个主题中有大量任务，使用_id字段的哈希索引作为分片键，这也将导致更均衡的数据分布。

实现细节

在使用MongoDB存储引擎时，所有主题的任务都存储在同一个集合中。
任务是MongoDB存储引擎中唯一的具体数据模型，而主题和承诺仅仅是为了强制执行RESTful设计原则的概念实体。
由于MongoDB中调度时间的分辨率为毫秒级，并且受实例自身时钟的影响，消费者接收任务的顺序并不能严格保证。
无法为completed状态的任务禁用TTL，若要永久保存任务，请将其设置为archived状态。
不建议在使用topic字段作为分片键的分片集合上执行任务的upsert操作。由于MongoDB自身的限制，这种情况下无法使用原子操作，只能使用等同于先删除后插入的回退方案，因此无法保证原子性和性能。可以通过使用简单的插入操作并配合精细调整的TTL设置来规避这个问题。
默认情况下，轮询是通过findAndModify实现的。发生冲突时，MongoDB的原生乐观并发控制 (OCC)会透明地重试操作。但在MongoDB 5.0及以上版本中，重试会在数据库服务器的日志中报告WriteConflict错误（尽管从客户端角度看操作仍然成功）。你可以选择忽略这个错误，或者**在使用MongoDB 5.0+时设置MONGODB_DISABLE_ATOMIC_POLL=true**来规避问题。这个选项会使Ratus不使用findAndModify进行轮询，而是依赖应用层的OCC来确保原子性。

索引模型

除非设置MONGODB_DISABLE_INDEX_CREATION为true，否则以下索引将在启动时创建：

键模式	部分过滤表达式	TTL
`{"topic": "hashed"}`	-	-
`{"topic": 1, "scheduled": 1}`	`{"state": 0}`	-
`{"deadline": 1}`	`{"state": 1}`	-
`{"topic": 1}`	`{"state": 1}`	-
`{"consumed": 1}`	`{"state": 2}`	`MONGODB_RETENTION_PERIOD`

可观察性

指标和标签

Ratus在/metrics端点上暴露以下Prometheus指标：

名称	类型	标签
ratus_request_duration_seconds	直方图	`topic`, `method`, `endpoint`, `status_code`
ratus_chore_duration_seconds	直方图	-
ratus_task_schedule_delay_seconds	仪表	`topic`, `producer`, `consumer`
ratus_task_execution_duration_seconds	仪表	`topic`, `producer`, `consumer`
ratus_task_produced_count_total	计数器	`topic`, `producer`
ratus_task_consumed_count_total	计数器	`topic`, `producer`, `consumer`
ratus_task_committed_count_total	计数器	`topic`, `producer`, `consumer`