aregtech/areg-sdk
GitHub: aregtech/areg-sdk
Areg SDK 是一个高性能的 C++ 中间件，用于自动化分布式服务中的线程管理、进程间通信和服务发现，简化从嵌入式到企业级的应用开发。
Stars: 351 | Forks: 136
**高性能、面向服务的C++中间件**
**从嵌入式系统到高性能分布式应用**
[](https://github.com/aregtech/areg-sdk/releases/tag/v1.5.0)
[](https://github.com/aregtech/areg-sdk/compare/v1.5.0...master)
[](https://github.com/aregtech/areg-sdk/stargazers)
[](./docs/wiki/README.md)
## 项目状态[](#project-status)
## 目录
- [为什么选择Areg SDK](#why-areg-sdk)
- [工作原理](#how-it-works)
- [性能](#performance)
- [Areg SDK 与 其他方案对比](#areg-sdk-vs-alternatives)
- [快速入门](#getting-started)
- [架构](#architecture)
- [网络部署模型](#network-deployment-model)
- [用例](#use-cases)
- [路线图](#roadmap)
- [文档](#documentation)
- [许可](#license)
- [社区](#community)
## 为什么选择Areg SDK[](#why-areg-sdk)
### 问问自己这些问题：
- 线程和同步问题是否拖慢了你的开发进度？
- 你的IPC集成是否脆弱、难以测试或难以扩展？
- 将一个组件从进程内移到进程外，是否需要重写其接口？
- 当服务意外重启时，你是否花费数小时调试静默故障？
- 你的分布式系统在生产环境中是否难以监控和诊断？
- 你是否正在构建一个数据密集型管道，要求框架开销接近于零？
**如果你对三个或更多问题回答是——那么Areg SDK值得你投入时间。**
Areg SDK是一个C++服务框架，它自动化了线程管理、进程间通信、
服务发现、故障恢复和消息分发——跨越线程边界、进程边界和网络边界——使用单一且一致的编程模型。
**相同的服务代码可以运行在：**
- 多线程（同一进程中的组件）
- 多进程（同一台机器上的组件）
- 多设备（跨网络的组件）
**无需修改代码。只需配置。**
## 工作原理[](#how-it-works)
Areg SDK实现了**对象RPC (ORPC)**——一种服务模型，其中组件暴露
类型化接口，并通过生成的代理进行通信，无论它们运行在哪里。
与gRPC或ZeroMQ不同，相同的代理代码可以调用线程、进程或网络设备——框架在运行时解析位置，无需更改API。
```
┌─────────────────────────────────────────────────────────┐
│ Same code. Same interface. Different deployment. │
│ │
│ Thread A ──────────────── Thread B (in-process) │
│ Process A ─── mtrouter ── Process B (same machine) │
│ Device A ─── mtrouter ── Device B (network) │
└─────────────────────────────────────────────────────────┘
```
消费者通过**名称**引用服务，而不是通过网络地址或端点。
框架将消费者连接到该命名服务，无论它运行在何处——
无论是在同一进程中、同一台机器上，还是在远程节点上。
**框架自动处理的事项：**
- 线程生命周期和同步
- 服务发现与注册
- 请求与响应的路由和分发
- 故障检测和看门狗重启
- 连接管理和重连
**你需要编写的：**
- 一个服务接口定义文件（`.siml`文件）——使用 [`Lusan`](https://github.com/aregtech/areg-sdk-tools/) 可视化设计或作为XML编辑
- 用业务逻辑扩展生成的提供者和消费者类
代码生成器生成所有RPC基础设施——序列化、代理、事件以及服务提供者和消费者基类。你只需填充逻辑。
### 服务接口与代码生成
一个**服务接口**定义了API契约：数据类型、属性（发布/订阅）、请求、响应、广播和常量。**服务**是一个命名的组件实例，它实现一个或多个接口。消费者声明它们依赖于哪个命名服务——当该服务在网络上任何地方可用时，框架会自动连接它们。
从接口定义到运行代码的工作流程：
```
MyService.siml ──► codegen.jar ──► MyServiceProviderBase.hpp
(design in Lusan) │ MyServiceConsumerBase.hpp
│ MyServiceProxy.hpp
│ Serialization code
| Event objects
```
**CMake集成**——一行命令即可生成并链接所有基础设施：
```
addServiceInterface(MyServiceLib ./services/MyService.siml)
```
完整详情，请参阅[服务接口指南](./docs/wiki/06e-lusan-service-interface.md)。
## 性能[](#performance)
Areg SDK的传输层专为生产级数据管道设计。
下面的数字是在**移动级消费硬件**上测量的，包括数据序列化、事件分发和多线程——而非原始套接字吞吐量。
## Areg SDK 与 其他方案对比[](#areg-sdk-vs-alternatives)
| 特性 | Areg SDK | gRPC / DDS / ZeroMQ |
|---------------------------|--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **设置复杂度** | ✅ 自动化，零样板 | ⚠️ 手动配置，[冗长的设置](https://www.innoq.com/en/blog/2024/06/grpc/#whataresomechallengesofworkingwithgrpc) |
| **线程管理** | ✅ 自动化线程 | ⚠️ 手动线程和同步 |
| **代码生成** | ✅ 全自动ORPC | ⚠️ [仅桩代码](https://grpc.io/docs/what-is-grpc/introduction/#overview)，手动分发 |
| **服务发现** | ✅ 基于名称，自动 | ✅ DDS: [原生](https://opendds.readthedocs.io/en/latest-release/devguide/introduction_to_dds.html#discovery-matching-and-association)， ⚠️ gRPC/ZeroMQ: [外部](https://stackoverflow.com/questions/59398556/grpc-equivalent-of-wcf-service-discovery) |
| **故障恢复** | ✅ 看门狗自动重启 | ✅ DDS: [QoS策略](https://opendds.readthedocs.io/en/latest-release/devguide/quality_of_service.html)， ⚠️ gRPC/ZeroMQ: [手动](https://grpc.io/docs/guides/retry/) |
| **请求-响应** | ✅ 原生对象RPC | ✅ gRPC: [RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#overview)， ⚠️ DDS/ZeroMQ: [主题/模式](https://zguide.zeromq.org/docs/chapter3/) |
| **发布/订阅** | ✅ 原生属性 | ✅ DDS: [主题](https://opendds.readthedocs.io/en/latest-release/devguide/built_in_topics.html)， ⚠️ gRPC/ZeroMQ: 附加组件 |
| **位置透明性** | ✅ 线程和IPC统一API | ⚠️ 本地和远程使用不同API |
| **日志系统** | ✅ 分布式日志 + 查看器 | ⚠️ [供应商特定](https://community.rti.com/static/documentation/connext-dds/current/doc/manuals/addon_products/observability/telemetry_data/logs.html)或外部工具 |
| **开发速度** | ✅ 通过全自动化加快 | ⚠️ 较慢，更多样板代码 |
🔹 **关键差异点：**
- **完全自动化** —— 不仅是传输，还包括线程、分发和生命周期管理
- **真正的位置透明性** —— 无论是线程、进程还是网络，使用相同接口
- **服务发现** —— 自动按名称连接服务消费者和提供者，并路由消息
- **集成栈** —— 框架 + 路由器 + 工具 + 日志记录整合在一个SDK中
- **高吞吐量传输** —— 完整的服务栈，而非精简的基准测试条件
## 快速入门[](#getting-started)
### 依赖要求
| 依赖项 | 最低版本 | 备注 |
|--------------|----------------------------|---------------------------|
| C++ 编译器 | C++17 | GCC, Clang, MSVC |
| CMake | 3.20+ | 包含MSVS解决方案 |
| Java 运行时 | 17+ | 仅代码生成器需要 |
| 操作系统 | Windows 10+, Linux, macOS | 包括Cygwin, MinGW |
### 快速构建
```
git clone https://github.com/aregtech/areg-sdk.git
cd areg-sdk
cmake -B build
cmake --build build -j20
```
### 运行第一个示例
**构建后示例位置：**
```
# Linux
./product/build/gnu-g++/linux-64-x86_64-release-shared/bin/01_minimalrpc.elf
# macOS
./product/build/llvm-clang++/macos-64-arm64-release-shared/bin/01_minimalrpc.mac
# Windows
.\product\build\msvc-cl\windows-64-amd64-release-shared\bin\01_minimalrpc.exe
```
**运行过程：** 开发者定义一个**模型**——一个结构化声明，包含线程、组件及其提供的或消费的服务。一次对
`Application::load_model()`的调用即可实例化所有线程、加载组件并自动启动服务。无需手动创建线程或管理对象。
在运行时，服务消费者检测到提供者，发送一个`hello`请求，
提供者打印`'Hello Service!'`并触发一个应用退出事件。
然后`Application::unload_model()`停止所有服务、退出线程，并通知每个消费者服务不再可用——这一切都由框架处理。
模型可以在编译时静态定义，也可以在运行时动态构建。加载和卸载始终是动态且安全的。
**预期输出：**
```
'Hello Service!'
```
配套示例`02_minimalipc`通过`mtrouter`在**单独的进程**中运行**相同的**`ServiceComponent`和
`ClientComponent`代码。只需将`areg.init`更改为指向远程机器的`mtrouter`，它就变成了设备间通信。
这两个示例是“相同代码——线程、进程、网络”的具体证明。
### 开始你自己的项目
```
git clone https://github.com/aregtech/areg-sdk.git
cd areg-sdk
cmake -B build -DAREG_BUILD_EXAMPLES=OFF
cmake --build build -j20
```
然后使用项目设置工具：
```
# Linux / macOS
./areg-sdk/tools/setup-project.sh
```
```
# Windows
.\areg-sdk\tools\setup-project.bat
```
生成后，构建：
```
cd
cmake -B build
cmake --build build -j20
```
### 学习路径
1. **[01_minimalrpc](examples/01_minimalrpc/)** — 多线程：服务提供者和消费者在单独的线程中，一个进程，无`mtrouter`
2. **[02_minimalipc](examples/02_minimalipc/)** — IPC：来自`01_minimalrpc`的相同组件通过`mtrouter`在单独的进程中运行
3. **[03_helloservice](examples/03_helloservice/)** — 扩展进阶：三个项目展示相同的服务和消费者在一个线程中 -> 单独线程 -> 单独进程
4. **[16_pubmesh](examples/16_pubmesh/)** — 服务网格：多个本地和公共服务自动发现彼此
5. **[23_pubdatarate](examples/23_pubdatarate/)** — 平台依赖的高吞吐量基准测试：在`localhost`上达到2.2–7 GB/s和1M+消息/秒
6. **[更多示例](examples/README.md)** — 高级模式和特性
## 架构[](#architecture)
### 组件模型
Areg SDK使用**对象RPC (ORPC)** 模型。服务暴露类型化接口；消费者
通过生成的代理进行通信。框架路由所有通信——无论目标是线程、进程还是远程设备。
```
┌──────────────────────────────────────────────────────────────────┐
│ Service Interface (.siml) │
│ │ │
│ ├─ Code Generator ──► Provider Base (implement logic) │
│ │ Consumer Proxy (call methods) │
│ │ │
│ └─ Framework ────────► Service Registry │
│ Thread Manager │
│ Message Dispatcher │
│ Watchdog │
└──────────────────────────────────────────────────────────────────┘
```
### 服务标识模型
一个**服务接口**是API契约——在`.siml`文件中定义的数据类型、请求、响应、广播和常量。一个**服务**是一个命名的组件实例，它
实现一个或多个接口。相同的接口可以被多个扮演不同角色的服务实现。
| 概念 | 描述 | 示例 |
|-----------------------|----------------------------------------------------------------------------------|----------------------------------------------------------------------|
| **服务接口** | API契约——类型化的通信定义 | `PrinterDevice` 接口 |
| **服务** | 实现一个或多个接口的命名组件实例 | `HP-Lab1`（实现`ScannerDevice`和`PrinterDevice`），`Canon-Floor3`（实现`PrinterDevice`） |
| **消费者** | 声明依赖于哪个命名服务；当它出现时接收`connected`信号 | `HP-Lab1`的消费者 |
消费者通过名称声明一个特定服务——“我需要`HP-Lab1`。”当该命名服务在网络上任何地方可用时，框架会
连接它们，并立即通知消费者。无需轮询。无需手动连接管理。
### 模块概述
| 模块 | 描述 |
|----------------|---------------------------------------------------------------------------------------------------------------------------|
| `areg` | 核心框架：线程、IPC、ORPC、服务模型、通信 |
| `aregextend` | 扩展服务：通信、SQLite封装、其他小型实用工具 |
| `areglogger` | 日志观察者API和库 |
| `mtrouter` | 多目标消息路由器：路由IPC和网络流量 |
| `logcollector` | 分布式日志聚合服务 |
| `logobserver` | 日志捕获、存储（文件 + SQLite）、作用域控制 |
| `Lusan` | 用于服务接口设计、实时日志收集和日志分析的GUI工具（[`Lusan`应用](https://github.com/aregtech/areg-sdk-tools） |
### 位置透明性
相同的服务在三个部署级别上表现完全相同：
| 部署 | 传输 | 代码更改需求 |
|-------------------------------|-----------------------|----------------------|
| 多线程（同一进程） | 直接调用 | 无 |
| 多进程（同一机器）| 通过`mtrouter`的TCP | 无 |
| 多设备（网络） | 通过`mtrouter`的TCP | 无 |
组件可以在单个进程中开发和测试，然后仅通过配置和构建脚本更改部署到多台机器。
## 网络部署模型[](#network-deployment-model)
Areg SDK专为**受控私有网络**设计——在这些部署中，节点是已知的，
网络是可信的，通信模式在设计时就已定义。
**雾层** — 设备集群：传感器、执行器和控制器形成一个本地
服务网格，无需中央代理即可通过名称自动相互解析。
**边缘层** — 网关节点：聚合来自雾集群的数据，运行本地
推理或控制逻辑，并将服务暴露给私有基础设施。
**私有基础设施** — 服务器和工作站：处理边缘数据，
协调分布式工作负载，并托管操作工具。
相同的服务接口、生成的代码和操作模型在每一层都有效——从设备集群到数据中心的**垂直一致架构**。
## 用例[](#use-cases)
对于**“为什么用Areg SDK而不是其他”**这个问题，每个领域的答案都不同，
但根本原因始终相同：Areg SDK将**高吞吐量传输**、**自动化线程**、**位置透明服务**和**内置故障恢复**
结合在一个有凝聚力的栈中——在线程、进程和网络部署之间切换时只需要配置更改。
### 科学与工业成像管道
**为什么用Areg SDK：** 成像管道——激光显微镜、X射线、电子显微镜、
机器视觉——在采集、处理和存储进程之间移动连续的多兆字节帧。在标准笔记本电脑CPU上达到2.0–6.0 GB/s全栈IPC，Areg SDK
几乎涵盖了所有此类管道的软件传输层，无需自定义网络代码或精简基准测试。很少有面向服务的C++框架能在
保持完整服务语义的同时达到这种吞吐量。
**实际意义：** 用类型化、命名的服务接口替换自定义的共享内存hack和平台特定的
IPC。管道阶段可以从线程重新排列到单独的进程，再到单独的机器，只需配置和构建脚本更改。
### 边缘AI与推理管道
**为什么用Areg SDK：** 边缘AI管道——传感器采集 → 预处理 → 模型
推理 → 输出/遥测——需要在各阶段之间进行快速IPC，这些阶段可能作为
线程、进程或分布式节点运行，具体取决于硬件限制。Areg SDK的
位置透明性意味着管道拓扑可以在不触及推理或采集代码的情况下更改。很少有框架能将这种灵活性与IPC
吞吐率相结合，使其与标准CPU上的硬件DMA和PCIe数据速率相匹配。
**实际意义：** 在单个进程中开发和测试整个管道。
在专用核心进程上部署采集，在GPU连接的进程上部署推理。
扩展到分布式节点。每次转换时只需配置和构建脚本更改。
### 设备即服务（无驱动硬件）
**为什么用Areg SDK：** 内核模式驱动程序开发需要数月的专业工作，需要
操作系统特定的专业知识，并且产生的代码调试危险且维护成本高。Areg SDK实现了无驱动架构：设备应用程序将其
功能作为命名服务暴露。任何主机应用程序都可以通过
生成的代理调用设备API——无需驱动程序安装，无内核模式代码，无特殊权限。
**实际意义：** 外部硬件（测量仪器、工业传感器、嵌入式控制器）
通过`mtrouter`注册为命名服务。主机应用程序通过名称连接到特定设备——就像它们连接到任何本地服务一样。开发时间从数月缩短到数天。设备像任何用户模式应用程序一样可调试、可测试和可升级。
### 工业自动化与机器人（工业4.0）
**为什么用Areg SDK：** 工业控制系统以难以预测且手动恢复成本高昂的方式发生故障。Areg SDK内置的看门狗重启、自动服务重新注册和容错重连处理了那些破坏手写IPC代码的故障情况。组件重新启动其线程并重新连接，无需操作员干预——并且不更改任何应用逻辑。
**实际意义：** 传感器融合节点、PLC替换控制器和机器人臂协调器通过类型化服务接口进行通信。当一个节点的线程在故障后重启时，它会重新注册，消费者也会自动重新连接。无需监控重启脚本，无需手动重连逻辑。
### 数字孪生与实时监控
**为什么用Areg SDK：** 数字孪生需要物理设备与其软件表示之间的双向实时同步。Areg SDK的事件驱动架构将状态变化从硬件传递到软件，将命令从软件传递到硬件，无需额外的中间件层。相同的服务接口定义物理设备及其数字孪生——无论是连接到真实硬件还是其虚拟对应物，都提供相同的API。
**实际意义：** 用发布/订阅属性广播和请求/响应RPC替换轮询循环和自定义TCP协议。数字孪生可以镜像、模拟或代理真实设备——所有都共享相同的服务接口。消费者在真实硬件和其孪生体之间切换时无需更改代码。
### 仿真与硬件在环测试
**为什么用Areg SDK：** 针对真实硬件进行测试速度慢、成本高，且在早期开发阶段不可用。由于Areg SDK服务是通过名称发现的，以相同名称注册的模拟服务与真实硬件服务无法区分。将真实硬件服务替换为在相同服务名称下注册的模拟服务——应用程序的其余部分不会注意到差异。无需特定于测试的代码路径，无需模拟框架，无需条件编译。
**实际意义：** 在硬件存在之前开发和验证完整的应用业务逻辑。在CI中针对模拟服务运行自动化回归测试。部署到真实硬件时，应用代码零更改。
### 分布式C++后端服务
**为什么用Areg SDK：** C++后端系统——游戏服务器、仿真引擎、金融数据处理器、实时分析——通常从头构建自定义线程和IPC。Areg SDK用生成的、类型化的服务层取代了该基础设施，自动处理线程安全、消息分发和进程间路由。在单台机器上稳定消费者分发达到300–600K消息/秒（平台依赖），该框架不会限制任何现实后端工作负载的吞吐量。
**实际意义：** 定义服务接口，生成基础设施，实现逻辑。服务可以从进程内组件扩展到分布式节点，无需架构更改。在嵌入式部署中工作的相同看门狗和日志基础设施在后端部署中同样有效。
## 路线图[](#roadmap)
**进行中（2026年）：**
- RTOS平台支持（FreeRTOS, Zephyr）
- 增强序列化吞吐量（目标：消费者分发稳定达到500K+消息/秒）
- 基于Python的代码生成器（替代Java依赖）
- 共享内存传输（同机IPC零拷贝）
- 安全通信（`mtrouter`连接可选TLS）
- 扩展网络协议
**考虑征求社区意见：**
- 语言绑定（Python, Rust）
- 云原生部署模式
- WebSocket传输
## 文档[](#documentation)
Wiki深入涵盖了所有部署、集成和开发场景：
- **[安装与构建](./docs/wiki/README.md#1-installation-and-build)** - 跨平台构建、工具链、CMake集成
- **[构建选项与集成](./docs/wiki/README.md#2-build-options-and-integrations)** - FetchContent、打包、嵌入
- **[网络与通信](./docs/wiki/README.md#3-networking-and-communication)** - 路由器设置、IPC、低延迟消息传递
- **[日志记录与监控](./docs/wiki/README.md#4-logging-and-monitoring)** - 用于调试的分布式日志记录
- **[持久化](./docs/wiki/README.md#5-persistence)** - 本地数据存储
- **[开发与测试工具](./docs/wiki/README.md#6-development-and-testing-tools)** - 代码生成器、Lusan、测试实用工具
- **[故障排除](./docs/wiki/README.md#7-troubleshooting)** - 常见问题与解决方案
- **[示例与测试](./docs/wiki/README.md#8-examples-and-tests)** - 示例项目目录
- **[操作指南](docs/HOWTO.md)** - 实用开发任务
## 许可[](#license)
Areg SDK在**[Apache License 2.0](LICENSE.txt)**下发布——这是一个适用于开源和商业使用的宽松许可。
**商业支持：** 提供企业许可、培训和专用支持。访问 **[areg.tech](https://www.areg.tech/)** 或发送邮件至 **info[at]areg[dot]tech**。
## 社区[](#community)
[](https://github.com/aregtech/areg-sdk)
如果你使用Areg SDK，请将此徽章添加到你的项目中。
**贡献：**
- [问题](https://github.com/aregtech/areg-sdk/issues)
- [讨论](https://github.com/aregtech/areg-sdk/discussions)
- [贡献指南](./CONTRIBUTING.md)
- [Wiki](https://github.com/aregtech/areg-sdk/wiki)
**展示你的项目：**
如果你用Areg SDK构建了什么，开启一个讨论并告诉我们。
*Areg (Արեգ) — 古亚美尼亚语：太阳。*标签：Bash脚本, C++, C++17, CMake, HTTP头分析, IPC, MSBuild, RPC, RustScan, 中间件, 代码安全, 企业应用, 分布式系统, 响应大小分析, 实时系统, 嵌入式系统, 数据擦除, 服务导向, 漏洞枚举, 网络通信, 高吞吐量
