# hermes **Repository Path**: asialjim/hermes ## Basic Information - **Project Name**: hermes - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-23 - **Last Updated**: 2026-01-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Hermes 分布式事件总线 ## 项目简介 Hermes 是一个高性能的分布式事件总线系统，采用 Rust 语言开发，旨在为微服务架构提供可靠、高效的事件通信能力。它支持事件的发布/订阅、推送/拉取模式，具备灵活的路由策略和完善的集群管理功能。 ## 核心特性 ### 事件传输模式 - **发布/订阅模式**：支持一对多的事件广播 - **推送模式**：服务端主动将事件推送给消费者 - **拉取模式**：消费者主动从服务端拉取事件 - **分片路由**：支持基于哈希键的事件分片分发 ### 集群能力 - **去中心化集群管理**：基于 Raft 协议的 Leader 选举 - **节点自动发现**：使用 etcd 实现服务发现 - **增量数据同步**：支持多节点间数据实时同步 - **故障恢复机制**：自动检测并恢复异常节点 ### 存储与归档 - **高性能存储引擎**：基于 RocksDB 的本地存储 - **事件归档服务**：支持按时间和容量策略自动归档 - **数据压缩**：支持多种压缩算法（LZ4、Zstd） - **查询服务**：支持按主题、时间、标签等条件查询 ### 安全机制 - **传输安全**：支持 TLS/SSL 加密 - **认证授权**：基于 JWT 的身份认证 - **细粒度权限控制**：支持按主题配置访问权限 ## 系统架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 客户端层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ gRPC │ │ REST │ │ SDK │ │ CLI │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ 接口层 │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ gRPC / REST 服务 │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ 核心服务层 │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │发布服务 │ │订阅服务 │ │拉取服务 │ │消费注册 │ │延迟服务 │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────────┐ │ │ │归档服务 │ │安全认证 │ │查询服务 │ │集群管理服务 │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────────────────┘ │ ├─────────────────────────────────────────────────────────────────┤ │ 存储层 │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ 存储引擎抽象层 │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │ │ │ │事件存储 │ │消费者元│ │归档存储 │ │索引存储 │ │ │ │ │ │ │数据存储 │ │ │ │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────────────┘ │ │ │ RocksDB 存储实现 │ │ ├─────────────────────────────────────────────────────────────────┤ │ 基础设施层 │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │日志系统 │ │监控系统 │ │健康检查 │ │配置管理 │ │追踪系统 │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ## 快速开始 ### 环境要求 - Rust 1.70+ - etcd（用于集群服务发现） - RocksDB（本地存储） ### 编译构建 ```bash # 克隆项目 git clone https://gitee.com/asialjim/hermes.git cd hermes # 编译服务端 cd server cargo build --release # 编译客户端 cd client cargo build --release ``` ### 配置说明 创建配置文件 `config.yaml`： ```yaml server: host: "0.0.0.0" port: 50051 http_port: 8080 storage: type: "rocksdb" path: "/data/hermes/data" cluster: enabled: true cluster_name: "hermes-cluster" etcd_endpoints: - "http://localhost:2379" security: enabled: true jwt_secret: "your-secret-key" tls_enabled: true archive: enabled: true check_interval: 3600 batch_size: 1000 compression: "lz4" ``` ### 启动服务 ```bash # 启动 Hermes 服务 ./target/release/hermes-server --config config.yaml ``` ## API 使用示例 ### gRPC 接口 #### 发布事件 ```protobuf message PublishRequest { string topic = 1; bytes payload = 2; int64 delay_ms = 3; bool shardable = 4; string trace_id = 5; string idempotency_key = 6; } service Hermes { rpc Publish(PublishRequest) returns (PublishResponse); } ``` #### 订阅事件 ```protobuf message SubscribeRequest { string consumer_id = 1; repeated string topics = 2; } service Hermes { rpc Subscribe(SubscribeRequest) returns (stream EventEnvelope); } ``` #### 拉取事件 ```protobuf message PullRequest { string consumer_id = 1; string topic = 2; int64 max_count = 3; int64 timeout_seconds = 4; } service Hermes { rpc Pull(PullRequest) returns (PullResponse); } ``` ### REST 接口 #### 发布事件 ```bash curl -X POST http://localhost:8080/events \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "topic": "user.created", "payload": "{\"user_id\": 123}", "delay_ms": 0, "shardable": false }' ``` #### 拉取事件 ```bash curl -X GET "http://localhost:8080/events/pull?consumer_id=consumer1&topic=user.created&max_count=10" \ -H "Authorization: Bearer " ``` ## 核心概念 ### 事件（Event） 事件是 Hermes 的核心数据单元，包含以下属性： - **topic**：事件主题，用于路由分发 - **payload**：事件载荷，二进制数据 - **event_id**：全局唯一的事件ID - **trace_id**：追踪ID，用于分布式追踪 - **effective_delay_ms**：延迟投递时间 - **shardable**：是否支持分片 ### 消费者（Consumer） 消费者是事件的接收者，分为两种类型： - **推送消费者（Push）**：接收服务端主动推送的事件 - **拉取消费者（Pull）**：主动从服务端拉取事件 ### 消费者组（Consumer Group） 消费者组用于实现负载均衡和故障转移，同一组内的消费者共享主题订阅。 ### 延迟事件 Hermes 支持延迟事件投递，使用时间轮算法实现高效的延迟队列。 ## 部署架构 ### 单机部署 适用于开发测试环境，所有组件运行在同一节点。 ### 主从部署 主节点处理读写请求，从节点提供高可用性和读取扩展。 ### 集群部署 多节点集群部署，支持水平扩展和高可用。 ``` ┌──────────────────────────────────────────────────────┐ │ 负载均衡器 │ └──────────────────────────────────────────────────────┘ │ │ │ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │ Node1 │ │ Node2 │ │ Node3 │ │(Leader) │ │(Follower)│ │(Follower)│ └─────────┘ └─────────┘ └─────────┘ │ │ ┌────┴──────────────┴────┐ │ etcd 集群 │ └────────────────────────┘ ``` ## 监控与运维 ### 监控指标 Hermes 提供以下监控指标： - **事件吞吐量**：发布/订阅速率 - **延迟统计**：事件投递延迟分布 - **消费者健康**：消费者连接状态和健康检查 - **集群状态**：节点数量、同步状态 - **存储统计**：存储容量、事件数量 ### 日志配置 日志使用 log4rs 配置，支持控制台和文件输出： ```yaml appenders: console: kind: console encoder: pattern: "{d(%Y-%m-%d %H:%M:%S)} - {l} - {m}{n}" file: kind: rolling_file path: "logs/hermes.log" policy: kind: compound trigger: kind: size limit: 10485760 roller: kind: delete root: level: info appenders: - console - file ``` ## 性能基准 | 指标 | 数值 | |------|------| | 事件发布吞吐量 | 100,000+ events/s | | 事件投递延迟 | < 1ms (P99) | | 集群节点支持 | 100+ 节点 | | 单节点事件存储 | 10M+ 事件 | ## 开发指南 ### 项目结构 ``` hermes/ ├── client/ # 客户端库 ├── server/ # 服务端 │ ├── src/ │ │ ├── cluster/ # 集群管理 │ │ ├── common/ # 公共组件 │ │ ├── config/ # 配置管理 │ │ ├── core/ # 核心数据模型 │ │ ├── protocol/ # 协议实现 │ │ ├── security/ # 安全模块 │ │ ├── service/ # 业务服务 │ │ └── storage/ # 存储引擎 │ └── proto/ # protobuf 定义 ├── docs/ # 文档 └── proto/ # 公共 proto 文件 ``` ### 测试 ```bash # 运行单元测试 cargo test --workspace # 运行集成测试 cargo test --test integration # 运行性能测试 cargo bench ``` ## 常见问题 ### Q: 如何处理消费者离线？ A: Hermes 会自动将未确认的事件重新入队，消费者上线后可继续拉取未处理事件。 ### Q: 如何保证事件不丢失？ A: 通过配置同步引擎实现多节点数据同步，结合消费者确认机制保证可靠性。 ### Q: 支持多语言客户端吗？ A: 目前提供 Rust 客户端，后续将支持 Java、Go、Python 等语言。 ## 许可证 本项目采用 MIT 许可证开源。 ## 贡献指南 欢迎贡献代码和文档，请参考 CONTRIBUTING.md 了解详细流程。 ## 联系方式 - 项目地址：https://gitee.com/asialjim/hermes - 问题反馈：https://gitee.com/asialjim/hermes/issues