apache/iggy

# Apache Iggy (孵化中) **Iggy** 是一个用 Rust 编写的持久化消息流平台，支持 QUIC、WebSocket、TCP（自定义二进制规范）和 HTTP（常规 REST API）传输协议，**能够以超低延迟每秒处理数百万条消息**。 Iggy 提供了**极高的吞吐量和性能**，同时仅占用极少的计算资源。 这**不是**运行在 Kafka 或 SQL 数据库等现有基础设施之上的**又一个扩展**。 Iggy 是一个使用低级 I/O **从头构建**的持久化消息流日志，采用**每核一线程（thread-per-core）的无共享（shared nothing）架构**，并利用 `io_uring` 和 `compio` 实现最大的速度和效率。 这个名字是意大利灵缇犬（Italian Greyhound）的缩写——体型虽小但速度极快的狗，是同类中最好的。看看可爱的 [Fabio & Cookie](https://www.instagram.com/fabio.and.cookie/) ❤️ ## 功能特性 - **高性能**、持久的仅追加日志（append-only log），用于消息流 - 写入和读取均具有**极高的吞吐量** - 得益于 Rust 编译型语言（无 GC）和 `io_uring`，具有**低延迟和可预测的资源使用** - 具有细粒度权限和个人访问令牌（PAT）的**用户认证和授权** - 支持多个流、主题和分区 - 支持**多种传输协议**（QUIC、WebSocket、TCP、HTTP） - 功能齐全的 RESTful API，可选择启用 - 提供多种语言的客户端 SDK - **每核一线程的无共享设计**与 `io_uring` 共同保证了在现代 `Linux` 系统上可能达到的最佳性能。 - **直接处理二进制数据**，避免强制模式（schema）和序列化/反序列化的开销 - 自定义**零拷贝序列化/反序列化**，极大地提高了性能并减少了内存使用。 - 可配置的服务器功能（例如缓存、段大小、数据刷新间隔、传输协议等） - 服务器端存储**消费者偏移量** - 多种消息拉取方式： - 按偏移量（使用索引） - 按时间戳（使用时间索引） - 前/后 N 条消息 - 特定消费者的下 N 条消息 - **自动提交偏移量**的可能性（例如实现 *at-most-once* 交付） - **消费者组**提供消息排序和跨连接客户端的水平扩展 - 基于可配置**保留策略**的**消息过期**与自动删除 - 附加功能，如**服务器端消息去重** - 通过对**主题**进行分组的**流**的抽象，提供**多租户**支持 - 所有传输协议（TCP、WebSocket、QUIC、HTTPS）均支持 **TLS** - **[连接器](https://github.com/apache/iggy/tree/master/core/connectors)** - 基于自定义 **Rust 插件**的接收器、源头和数据转换 - **[模型上下文协议](https://github.com/apache/iggy/tree/master/core/ai/mcp)** - 通过 **MCP 服务器**为 LLM 提供上下文 - 可选的服务器端以及客户端**数据加密**，使用 AES-256-GCM - 可选的**消息头**形式的元数据支持 - 可选的**数据备份和归档**到磁盘或 **S3** 兼容的云存储（例如 AWS S3） - 支持 **OpenTelemetry** 日志和追踪 + Prometheus 指标 - 内置 **CLI** 用于管理流服务器，可通过 `cargo install iggy-cli` 安装 - 内置**基准测试应用**以测试性能 - **单一二进制文件部署**（无外部依赖） - 以单节点运行（基于 Viewstamped Replication 的集群将在不久的将来实现）   ## 架构 这是 Iggy 消息流服务器的高级架构，其首要目标是极高的性能和超低且稳定的尾部延迟。该服务器旨在处理高吞吐量和极低的延迟（亚毫秒级尾部延迟），使其适用于实时应用。有关更多详细信息，请参阅[文档](https://iggy.apache.org/docs/introduction/architecture)。  ## 版本 正式发布版本遵循常规的 semver（`0.5.0`）或带有 `latest` 标签（`apache/iggy:latest`）。 我们也会发布 edge/dev/nightly 版本（例如 `0.6.0-edge.1` 或 `apache/iggy:edge`），包括 SDK 和 Docker 镜像，这些版本通常与最新的更改兼容，但不保证稳定，正如其名，不建议在生产环境中使用。 ## 路线图 - 基于 **[VSR](http://pmg.csail.mit.edu/papers/vr-revisited.pdf)** 的**集群**和数据复制（在沙盒项目中使用 Raft，将在无共享设计完成后实现） ## 支持的语言 SDK - [Rust](https://crates.io/crates/iggy) - [C#](https://www.nuget.org/packages/Apache.Iggy/) - [Java](https://mvnrepository.com/artifact/org.apache.iggy/iggy) - [Python](https://pypi.org/project/apache-iggy/) - [Node.js (TypeScript)](https://www.npmjs.com/package/apache-iggy) - [Go](https://pkg.go.dev/github.com/apache/iggy/foreign/go) C++ 和 Elixir 正在开发中。 ## CLI 交互式 CLI 在 `cli` 项目下实现，旨在提供最佳的开发者体验。这是 Web UI 的一个很好的补充，特别适合所有喜欢使用控制台工具的开发者。 可以通过 `cargo install iggy-cli` 安装 Iggy CLI，然后在终端中输入 `iggy` 即可访问。  ## Web UI 服务器有一个专用的 Web UI，允许管理流、主题、分区、浏览消息等。目前正在努力为 Iggy 服务器的管理目的构建一个全面的仪表板。在 `/web` 目录中查看 Web UI。[Web UI 的 Docker 镜像](https://hub.docker.com/r/apache/iggy-web-ui) 已可用，可以通过 `docker pull apache/iggy-web-ui` 获取。  ## 连接器 高性能且模块化的**[运行时](https://github.com/apache/iggy/tree/master/core/connectors)**，用于静态类型但动态加载的连接器。从外部源头接收数据并将其推送到 Iggy 流，或者从 Iggy 流获取数据并将其推送到外部源头。通过简单地实现 `Source` 或 `Sink` trait 来**创建您自己的 Rust 插件**，并**构建自定义的数据处理管道**。 ``` ## 在独立的配置文件中配置 sink 或 source connector，根据您的需求。 type = "sink" key = "quickwit" enabled = true version = 0 name = "Quickwit sink" path = "target/release/libiggy_connector_quickwit_sink" plugin_config_format = "yaml" [[streams]] stream = "qw" topics = ["records"] schema = "json" batch_length = 1000 poll_interval = "5ms" consumer_group = "qw_sink_connector" [transforms.add_fields] enabled = true [[transforms.add_fields.fields]] key = "service_name" value.static = "qw_connector" [[transforms.add_fields.fields]] key = "timestamp" value.computed = "timestamp_millis" [transforms.delete_fields] enabled = true fields = ["email", "created_at"] ``` ## 模型上下文协议 [模型上下文协议](https://modelcontextprotocol.io) (MCP) 是一个开放协议，用于标准化应用程序向 LLM 提供上下文的方式。**[Iggy MCP Server](https://github.com/apache/iggy/tree/master/core/ai/mcp)** 是针对消息流基础设施的 MCP 协议实现。它可用于实时向 LLM 提供上下文，从而允许更准确和相关的响应。  ## Docker 官方 Apache Iggy 镜像可以在 [Docker Hub](https://hub.docker.com/r/apache/iggy) 中找到，只需输入 `docker pull apache/iggy` 即可拉取镜像。 您也可以在 [Docker Hub](https://hub.docker.com/u/apache?page=1&search=iggy) 找到所有不同工具（如连接器、MCP 服务器等）的镜像。 请注意，标记为 `latest` 的镜像基于官方稳定版本，而 `edge` 版本则直接从 `master` 分支的最新版本更新。 您可以在存储库的根目录中找到 `Dockerfile` 和 `docker-compose`。要构建并启动服务器，请运行：`docker compose up`。 此外，您可以通过执行以下命令来运行容器中可用的 `CLI`：`docker exec -it iggy-server /iggy`。 请记住，在 Linux 以外的操作系统上运行容器时，由于 Docker 在 VM 中运行，可能会导致性能下降。 另外，在运行容器时，**请确保包含额外的能力**，如您在 [docker-compose](https://github.com/apache/iggy/blob/master/docker-compose.yml) 文件中所见： ``` cap_add: - SYS_NICE security_opt: - seccomp:unconfined ulimits: memlock: soft: -1 hard: -1 ``` ## 配置 默认配置可以在 `core/server` 目录下的 `config.toml` 文件中找到。 配置文件从当前工作目录加载，但您可以通过设置 `IGGY_CONFIG_PATH` 环境变量来指定配置文件的路径，例如 `export IGGY_CONFIG_PATH=core/server/config.toml`（或其他取决于操作系统的命令）。 当找不到配置文件时，将使用嵌入式 `config.toml` 文件中的默认值。 有关配置文件的详细文档，请参阅[配置](https://iggy.apache.org/docs/server/configuration)部分。 ## 快速入门 构建项目（较长的编译时间是由于发布 [profile](https://github.com/apache/iggy/blob/master/Cargo.toml#L2) 中启用了 [LTO](https://doc.rust-lang.org/rustc/linker-plugin-lto.html))： `cargo build` 运行测试： `cargo test` 设置 root 用户凭据（可选）： Iggy 需要凭据来验证对服务器的请求。 您可以在启动服务器**之前**设置 root 用户。 (macOS/Linux) ``` export IGGY_ROOT_USERNAME=iggy export IGGY_ROOT_PASSWORD=iggy ``` (Windows(Powershell)) ``` $env:IGGY_ROOT_USERNAME = "iggy" $env:IGGY_ROOT_PASSWORD = "iggy" ``` 默认情况下，当尚未创建用户时，`iggy-server` 会生成一个随机的 root 用户密码并将其打印到 `stdout`。 启动服务器： `cargo run --bin iggy-server` 服务器使用的所有数据默认将持久化在 `local_data` 目录下，除非在配置中另有指定（参见 `config.toml` 中的 `system.path`）。 可以使用默认的 root 凭据及可选的 `--with-default-root-credentials`。 此标志等同于设置 `IGGY_ROOT_USERNAME=iggy` 和 `IGGY_ROOT_PASSWORD=iggy`，另外 它仅应用于开发和测试。 `cargo run --bin iggy-server -- --with-default-root-credentials` Root 凭据仅在首次启动服务器且数据目录尚不存在时设置。一旦服务器已启动并存在持久化数据，将重用现有的 root 凭据，此时 `--with-default-root-credentials` 标志或环境变量将无效。要重置凭据，请删除数据目录。 查看配置选项和详细帮助： `cargo run --bin iggy-server -- --help` 您也可以使用环境变量覆盖任何配置设置： - 覆盖 TCP 地址 `IGGY_TCP_ADDRESS=0.0.0.0:8090 cargo run --bin iggy-server` - 设置自定义数据路径 `IGGY_SYSTEM_PATH=/data/iggy cargo run --bin iggy-server` - 启用 HTTP 传输 `IGGY_HTTP_ENABLED=true cargo run --bin iggy-server` - 设置自定义 root 用户凭据 `IGGY_ROOT_USERNAME=iggy IGGY_ROOT_PASSWORD=iggy cargo run --bin iggy-server` 快速生成样本数据： `cargo run --bin data-seeder-tool` *请注意，以下所有命令均使用 `iggy` 二进制文件，它是发布版本的一部分（`cli` 子 crate）。* 使用默认凭据和 `tcp` 传输（可用传输：`quic`、`websocket`、`tcp`、`http`，默认为 `tcp`）创建一个名为 `dev` 的流（数字 ID 将由服务器自动分配）： `cargo run --bin iggy -- --transport tcp --username --password stream create dev` 列出可用的流： `cargo run --bin iggy -- --username --password stream list` 获取 `dev` 流详情： `cargo run --bin iggy -- -u -p stream get dev` 为流 `dev` 创建一个名为 `sample` 的主题（数字 ID 将由服务器自动分配），包含 2 个分区（ID 1 和 2），禁用压缩（`none`）并禁用消息过期（跳过可选参数）： `cargo run --bin iggy -- -u -p topic create dev sample 2 none` 列出流 `dev` 的可用主题： `cargo run --bin iggy -- -u -p topic list dev` 获取流 `dev` 中主题 `sample` 的主题详情： `cargo run --bin iggy -- -u -p topic get dev sample` 向流 `dev` 的主题 `` 和分区 1 发送消息 'hello world'（消息 ID 1）： `cargo run --bin iggy -- -u -p message send --partition-id 1 dev sample "hello world"` 向相同的流、主题和分区发送另一条消息 'lorem ipsum'（消息 ID 2）： `cargo run --bin iggy -- -u -p message send --partition-id 1 dev sample "lorem ipsum"` 以 ID 为 1 的普通消费者身份从流 `dev` 的主题 `sample` 和 ID 为 1 的分区拉取消息，起始偏移量为 0，消息数为 2，不自动提交（在服务器上存储消费者偏移量）： `cargo run --bin iggy -- -u -p message poll --consumer 1 --offset 0 --message-count 2 --auto-commit dev sample 1` 最后，重启服务器以查看它能够加载持久化的数据。 HTTP API 端点可以在 [server.http](https://github.com/apache/iggy/blob/master/core/server/server.http) 文件中找到，该文件可与 VS Code 的 [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) 扩展一起使用。 要查看 CLI/服务器的详细日志，请使用 `RUST_LOG=trace` 环境变量运行。参见下图： ## 示例 您可以在 `examples/rust` 目录下找到全面的示例应用程序。这些示例展示了 Iggy 客户端 SDK 的各种使用模式，从基本操作到高级的多租户场景。 有关可用示例以及如何运行它们的详细信息，请参阅 [Examples README](examples/rust/README.md)。 ## SDK Iggy 附带 Rust SDK，可在 [crates.io](https://crates.io/crates/iggy) 上找到。 该 SDK 既提供了针对特定传输的低级客户端，包括消息发送和拉取以及所有管理操作（如管理流、主题、用户等），也提供了高级客户端，它抽象了低级细节，为消息生产者和消费者提供了易于使用的 API。 您可以在 `examples` 目录下找到更多示例，包括多租户示例。 ``` // Create the Iggy client let client = IggyClient::from_connection_string("iggy://user:secret@localhost:8090")?; // Create a producer for the given stream and one of its topics let mut producer = client .producer("dev01", "events")? .direct( // Use either direct (instant) or background message sending DirectConfig::builder() .batch_length(1000) .linger_time(IggyDuration::from_str("1ms")?) .build(), ) .partitioning(Partitioning::balanced()) .build(); producer.init().await?; // Send some messages to the topic let messages = vec![IggyMessage::from_str("Hello Apache Iggy")?]; producer.send(messages).await?; // Create a consumer for the given stream and one of its topics let mut consumer = client .consumer_group("my_app", "dev01", "events")? .auto_commit(AutoCommit::IntervalOrWhen( IggyDuration::from_str("1s")?, AutoCommitWhen::ConsumingAllMessages, )) .create_consumer_group_if_not_exists() .auto_join_consumer_group() .polling_strategy(PollingStrategy::next()) .poll_interval(IggyDuration::from_str("1ms")?) .batch_length(1000) .build(); consumer.init().await?; // Start consuming the messages while let Some(message) = consumer.next().await { // Handle the message } ``` ## 基准测试 **基准测试应被视为一等公民**。我们相信性能对任何系统都至关重要，并努力为用户提供最佳的性能。请查看为什么我们认为 **[透明基准测试](https://iggy.apache.org/blogs/2025/02/17/transparent-benchmarks)** 如此重要。 我们还构建了 **[基准测试平台](https://benchmarks.iggy.apache.org)**，任何人都可以上传基准测试结果并与他人进行比较。该平台的源代码位于 `core/bench/dashboard` 目录中。  出于基准测试的目的，我们开发了专门的 **iggy-bench** 工具，它是 **iggy** 项目的一部分。这是一个命令行工具，允许您运行各种完全可自定义的基准测试。  要对项目进行基准测试，首先以发布模式构建项目： ``` cargo build --release ``` 然后，使用所需的选项运行基准测试应用程序： 1. 发送（写入）基准测试 cargo run --bin iggy-bench -r -- -v pinned-producer tcp 2. 拉取（读取）基准测试 cargo run --bin iggy-bench -r -- -v pinned-consumer tcp 3. 并行发送和拉取基准测试 cargo run --bin iggy-bench -r -- -v pinned-producer-and-consumer tcp 4. 向多个分区的平衡发送基准测试 cargo run --bin iggy-bench -r -- -v balanced-producer tcp 5. 消费者组拉取基准测试： cargo run --bin iggy-bench -r -- -v balanced-consumer-group tcp 6. 并行平衡发送和从消费者组拉取基准测试： cargo run --bin iggy-bench -r -- -v balanced-producer-and-consumer-group tcp 7. 端到端生产和消费基准测试（单个任务按顺序生产和消费消息）： cargo run --bin iggy-bench -r -- -v end-to-end-producing-consumer tcp 这些基准测试将使用默认配置启动服务器，创建流、主题和分区，然后发送或拉取消息。默认配置针对最佳性能进行了优化，因此您可能需要根据自己的需求进行调整。如果您需要更多选项，请参考 `iggy-bench` 子命令的 `help` 和 `examples`。 例如，要对已启动的服务器运行基准测试，请提供额外的参数 `--server-address 0.0.0.0:8090`。 **Iggy 已经能够在微秒级的 p99+ 延迟范围内每秒处理数百万条消息**。根据硬件、传输协议（`quic`、`websocket`、`tcp` 或 `http`）和有效负载大小（`messages-per-batch * message-size`）的不同，您可以预期**写入和读取的吞吐量超过 5000 MB/s（例如 500 万条 1 KB 消息/秒）**。 请参阅提到的[基准测试平台](https://benchmarks.iggy.apache.org)，您可以在其中浏览在不同硬件配置上使用不同 Iggy 服务器版本所取得的结果。 ## 贡献 请参阅 [Contributing](CONTRIBUTING.md)

标签：Apache Iggy, Apache 孵化器, DNS解析, io_uring, QUIC, REST API, Rust, TCP, Thread-per-Core, WebSocket, 中间件, 二进制协议, 低延迟, 依赖分析, 共享无架构, 可视化界面, 大数据, 实时数据处理, 并发架构, 底层编程, 开源项目, 微服务通信, 持久化存储, 服务器, 流处理, 消息流, 消息队列, 用户代理, 目录扫描, 网络流量审计, 请求拦截