ghcr.io/getsentry/taskbroker:fe8b45244abb14071e313fb3a62c15f1b0532bb0

Taskbroker

Taskbroker 提供 Kafka 消费者、RPC 接口以及运行中任务存储，三者共同构成 Sentry 异步任务执行的核心引擎。本仓库还包含 Python 客户端库。

概述

flowchart LR

Sentry -- 生成任务激活消息 --> k[(Kafka)]
k -- 消费消息 --> Taskbroker
Taskbroker -- 存储 --> sql[(SQLite)]
Worker -- 通过 gRPC 调用 GetTask --> Taskbroker
Worker -- 通过 gRPC 调用 SetTaskStatus --> Taskbroker

Sentry（及后续其他应用）会生成任务激活消息。Taskbroker 消费这些消息并将其存储到 SQLite 数据库中，以此避免队头阻塞、支持乱序执行和单任务级确认。

Worker 通过 gRPC 与 Taskbroker 通信，核心 gRPC 方法有两个：

• GetTask：Worker 可向 Taskbroker 请求待执行任务。
• SetTaskStatus：Worker 完成任务后，通过该方法上报任务执行结果。

构建

Taskbroker 基于 Rust 开发，需安装最新稳定版 Rust 编译器。执行以下命令完成编译：

cargo build --release

编译生成的二进制文件与调试信息文件一同存放在 target/release/ 目录下。

开发环境配置

构建 taskbroker 需安装最新稳定版 Rust 和 protoc。仓库根目录下的 Makefile 包含常用开发命令：

• devenv sync：执行环境初始化任务，创建并配置开发环境。
• make unit-test：运行 Rust 单元测试。
• make integration-test：运行端到端集成测试。
• make format：通过 cargo fmt 和 cargo clippy 格式化 Rust 代码。

构建与运行

运行 taskbroker 最简单的方式是通过 cargo，同时需要提前启动 kafka 服务，Kafka 通常通过 devservices 管理：

# 使用默认配置启动
cargo run

# 指定配置文件启动
cargo run -- -c ./config/config-sentry-dev.yaml

配置

Taskbroker 使用 YAML 文件作为配置载体，所有可用配置项均可在 Config 结构体定义中查看。

所有配置项也可通过带 TASKBROKER_ 前缀的环境变量定义，嵌套配置使用 __ 作为分隔符，示例：TASKBROKER_KAFKA_CLUSTERS__DEFAULT__ADDRESS=127.0.0.1:9092。

Kafka 主题与集群配置

Kafka 配置包含两个映射表：

• kafka_clusters：定义每个集群的 broker 地址（及可选认证配置）
• kafka_topics：声明每个主题所属的目标集群

配置要求：必须恰好指定一个可消费主题，其余主题（重试、死信队列）需标记为 produce_only（仅生产）。死信队列主题和重试主题必须与后台任务生产者属于同一集群。

Kafka 生产者使用 Arroyo 处理重试、死信队列和降级任务转发逻辑：

kafka_deadletter_topic: taskworker-dlq

kafka_clusters:
  default:
    address: 127.0.0.1:9092
    # 可选认证配置，将应用到该集群下所有主题：
    # security_protocol: sasl_ssl
    # sasl_mechanism: scram-sha-256
    # sasl_username: ...
    # sasl_password: ...

kafka_topics:
  taskworker:
    cluster: default
    consumer_group: taskworker
  taskworker-retry:
    cluster: default
    consumer_group: taskworker
    produce_only: true
  taskworker-dlq:
    cluster: default
    consumer_group: taskworker
    produce_only: true

[!NOTE] 旧版扁平结构配置字段 kafka_cluster / kafka_topic / kafka_consumer_group 以及 kafka_deadletter_* 认证字段已标记为废弃，但仍兼容使用。如需从旧配置格式迁移至新版格式，请参考 docs/kafka-config-migration.md。

测试

测试套件由 Rust 单元测试、Rust 集成测试和 Python 脚本实现的端到端测试组成：

# 运行单元测试与集成测试
make unit-test

# 运行端到端测试
make integration-test

代码检查

我们使用最新稳定 Rust 工具链的 rustfmt 和 clippy 完成代码格式化与静态检查：

# 检查格式问题
make style

# 自动修复格式与检查发现的问题
make format

Python 客户端

更多详情请参考 Python 客户端 README 文档。

客户端发布说明

[!IMPORTANT] 客户端与 Taskbroker 本体采用独立发布策略：Taskbroker 采用自托管风格的 calver 版本号格式（例如 26.4.0），客户端采用标准 semver 版本号格式（例如 0.1.8）。二者共享标签与发布分支，因此 GitHub 上展示的最新发布版本不一定是你制定版本号的参考基准。

1. 调用 https://github.com/getsentry/taskbroker/actions/workflows/release-client.yml 工作流
2. 选择「Run workflow」并输入目标版本号
3. 工作流将通过 craft + getsentry/publish 工具将软件包同步发布到内部与公共 PyPI 源。