feat: initial commit
- Add workspace-level README with monorepo structure and per-package chapters - Add hivecore_logger: C++/Python async logging SDK with spdlog/QueueHandler - Add hivecore_log_manager: centralized log management (quota, compression, dynamic level) - Add hivecore_logger_interfaces: ROS 2 SetLogLevel service definition - Add build/install/start scripts for one-command setup
This commit is contained in:
194
README.md
Normal file
194
README.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# hivecore_robot_system
|
||||
|
||||
面向机器人系统的企业级 ROS 2 基础设施工作空间。
|
||||
|
||||
## 1. 简介
|
||||
|
||||
`hivecore_robot_system` 是 HiveCore 机器人系统的核心 ROS 2 工作空间，提供一套高质量、生产就绪的基础设施组件。
|
||||
|
||||
本仓库采用 **monorepo** 结构，每个功能领域以独立子目录的形式进行组织，所有组件统一由顶层 `colcon` 工作空间管理，可按需选包编译。各包的详细说明从第 5 章起依次展开，每个顶层包独占一章。
|
||||
|
||||
当前已包含的软件包：
|
||||
|
||||
| 软件包 | 所属模块 | 说明 |
|
||||
| :--- | :--- | :--- |
|
||||
| `hivecore_logger` | 日志系统 | 面向 C++/Python 业务节点的异步非阻塞日志 SDK |
|
||||
| `hivecore_log_manager` | 日志系统 | 集中式日志管理服务：磁盘配额、压缩、动态调级 |
|
||||
| `hivecore_logger_interfaces` | 日志系统 | ROS 2 服务接口定义（`SetLogLevel.srv`） |
|
||||
| *(更多组件持续添加中)* | — | — |
|
||||
|
||||
## 2. 系统要求
|
||||
|
||||
以下为整个工作空间的通用基础要求，各组件若有额外依赖，请参阅对应子目录的文档。
|
||||
|
||||
| 项目 | 要求 |
|
||||
| :--- | :--- |
|
||||
| 操作系统 | Ubuntu 20.04 / 22.04（或其他 POSIX Linux） |
|
||||
| ROS 2 | Foxy / Humble |
|
||||
| C++ 编译器 | GCC 9+，支持 C++17 |
|
||||
| CMake | 3.14+ |
|
||||
| Python | 3.8+ |
|
||||
|
||||
## 3. 快速开始
|
||||
|
||||
### 3.1 克隆与初始化
|
||||
|
||||
```bash
|
||||
git clone <repo-url> hivecore_robot_system
|
||||
cd hivecore_robot_system
|
||||
```
|
||||
|
||||
### 3.2 安装通用依赖
|
||||
|
||||
```bash
|
||||
sudo apt-get update && sudo apt-get install -y \
|
||||
build-essential cmake \
|
||||
python3-pip
|
||||
```
|
||||
|
||||
各组件的额外依赖请参阅对应子目录的 README 或 `USER_GUIDE.md`。
|
||||
|
||||
### 3.3 编译工作空间
|
||||
|
||||
编译整个工作空间中的所有组件：
|
||||
|
||||
```bash
|
||||
colcon build --symlink-install
|
||||
source install/setup.bash
|
||||
```
|
||||
|
||||
如仅需编译指定组件：
|
||||
|
||||
```bash
|
||||
colcon build --packages-select <package_name> [<package_name> ...]
|
||||
source install/setup.bash
|
||||
```
|
||||
|
||||
各包需要选择哪些包名，请参阅对应包章节的说明。
|
||||
|
||||
### 3.4 验证安装
|
||||
|
||||
```bash
|
||||
# 列出工作空间内所有已注册的 ROS 2 接口
|
||||
ros2 interface list | grep hivecore
|
||||
|
||||
# 查看已安装的可执行命令
|
||||
ros2 pkg executables | grep hivecore
|
||||
```
|
||||
|
||||
## 4. 工程目录结构
|
||||
|
||||
本仓库以功能模块为单位组织子目录，每个模块是独立的 ROS 2 包（或包组），可单独编译和部署。
|
||||
|
||||
```text
|
||||
hivecore_robot_system/
|
||||
├── hivecore_logger/ # 【日志系统】详见第 5 章
|
||||
├── <future_module>/ # 【预留】后续新增功能模块
|
||||
├── build/ # colcon 构建输出（不纳入版本管理）
|
||||
├── install/ # colcon 安装输出（不纳入版本管理）
|
||||
└── log/ # colcon 构建日志（不纳入版本管理）
|
||||
```
|
||||
|
||||
**新增模块约定**：每个新模块在仓库根目录下创建独立子目录，建议包含：
|
||||
|
||||
```text
|
||||
<module_name>/
|
||||
├── README.md # 模块说明
|
||||
├── USER_GUIDE.md # 安装与使用手册
|
||||
├── ros2/ # ROS 2 接口包及示例（如有）
|
||||
├── examples/ # 接入示例
|
||||
└── scripts/ # 验证脚本
|
||||
```
|
||||
|
||||
## 5. hivecore_logger — 日志系统
|
||||
|
||||
面向 C++/Python 业务节点的企业级异步非阻塞日志基础设施。
|
||||
|
||||
### 5.1 目录结构
|
||||
|
||||
```text
|
||||
hivecore_logger/
|
||||
├── cpp/ # C++ 日志 SDK（基于 spdlog，异步非阻塞）
|
||||
├── python/ # Python 日志 SDK（基于 QueueHandler）
|
||||
├── manager/ # 集中式日志管理模块（独立部署或 ROS 2 节点）
|
||||
├── ros2/
|
||||
│ ├── hivecore_logger_interfaces/ # ROS 2 接口包
|
||||
│ └── examples/ # ROS 2 最小调用示例
|
||||
├── examples/ # 外部业务节点接入示例（C++/Python）
|
||||
└── scripts/ # 一键验证与演示脚本
|
||||
```
|
||||
|
||||
### 5.2 核心特性
|
||||
|
||||
| 特性 | 说明 |
|
||||
| :--- | :--- |
|
||||
| 异步非阻塞日志 | C++/Python SDK 均采用异步队列，极低业务侧开销 |
|
||||
| 热更新日志级别 | Python SDK 支持 inotify 零 CPU 占用热更新，无需重启节点 |
|
||||
| 日志限流与条件宏 | Python SDK 原生支持 `throttle`（限流）与 `expression`（条件）扩展 |
|
||||
| 集中式管理 | 统一的磁盘配额控制、后台异步压缩、节点级文件轮转 |
|
||||
| 安全性 | 防路径穿越攻击，日志目录强制沙箱隔离 |
|
||||
| 双调级入口 | 支持 HTTP REST 与 ROS 2 Service 两种运行时动态调级方式 |
|
||||
|
||||
### 5.3 快速编译与验证
|
||||
|
||||
**一键编译、安装并启动 Manager：**
|
||||
|
||||
```bash
|
||||
bash hivecore_logger/scripts/build_install_and_start_manager.sh
|
||||
```
|
||||
|
||||
该脚本依次执行：编译 SDK（C++ + Python + ROS 2 接口）→ 安装 → 启动日志管理服务。
|
||||
|
||||
如需仅编译和安装 SDK，不启动服务：
|
||||
|
||||
```bash
|
||||
bash hivecore_logger/scripts/build_install_sdk.sh
|
||||
```
|
||||
|
||||
其他常用脚本：
|
||||
|
||||
| 脚本 | 用途 |
|
||||
| :--- | :--- |
|
||||
| `scripts/start_manager.sh` | 单独启动日志管理服务 |
|
||||
| `scripts/stop_manager.sh` | 停止日志管理服务 |
|
||||
| `scripts/check_manager_health.sh` | 检查服务健康状态 |
|
||||
| `scripts/run_all_checks.sh` | 运行全量验证（单元测试 + 集成检查） |
|
||||
| `scripts/run_manager_demo.sh` | 运行演示流程 |
|
||||
|
||||
### 5.4 文档
|
||||
|
||||
| 文档 | 链接 |
|
||||
| :--- | :--- |
|
||||
| 模块说明 | [hivecore_logger/README.md](hivecore_logger/README.md) |
|
||||
| 安装与使用手册 | [hivecore_logger/USER_GUIDE.md](hivecore_logger/USER_GUIDE.md) |
|
||||
| 测试报告 | [hivecore_logger/TEST_REPORT.md](hivecore_logger/TEST_REPORT.md) |
|
||||
|
||||
---
|
||||
|
||||
<!-- ============================================================
|
||||
【新增包模板】
|
||||
当有新的顶层包加入本仓库时，参照以下模板在此处追加一章，
|
||||
并同步更新第 1 章的软件包列表与第 4 章的目录结构。
|
||||
|
||||
## N. <package_name> — <功能领域>
|
||||
|
||||
<一句话描述该包的定位与用途。>
|
||||
|
||||
### N.1 核心特性
|
||||
|
||||
| 特性 | 说明 |
|
||||
| :--- | :--- |
|
||||
| ... | ... |
|
||||
|
||||
### N.2 文档
|
||||
|
||||
| 文档 | 链接 |
|
||||
| :--- | :--- |
|
||||
| 模块说明 | [<package_name>/README.md](<package_name>/README.md) |
|
||||
| 安装与使用手册 | [<package_name>/USER_GUIDE.md](<package_name>/USER_GUIDE.md) |
|
||||
|
||||
============================================================ -->
|
||||
|
||||
## 6. 许可证
|
||||
|
||||
© HiveCore. All rights reserved.
|
||||
Reference in New Issue
Block a user