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 克隆与初始化

git clone <repo-url> hivecore_robot_system
cd hivecore_robot_system

3.2 安装通用依赖

sudo apt-get update && sudo apt-get install -y \
    build-essential cmake \
    python3-pip

各组件的额外依赖请参阅对应子目录的 README 或 USER_GUIDE.md。

3.3 编译工作空间

编译整个工作空间中的所有组件：

colcon build --symlink-install
source install/setup.bash

如仅需编译指定组件：

colcon build --packages-select <package_name> [<package_name> ...]
source install/setup.bash

各包需要选择哪些包名，请参阅对应包章节的说明。

3.4 验证安装

# 列出工作空间内所有已注册的 ROS 2 接口
ros2 interface list | grep hivecore

# 查看已安装的可执行命令
ros2 pkg executables | grep hivecore

4. 工程目录结构

本仓库以功能模块为单位组织子目录，每个模块是独立的 ROS 2 包（或包组），可单独编译和部署。

hivecore_robot_system/
├── hivecore_logger/        # 【日志系统】详见第 5 章
├── <future_module>/        # 【预留】后续新增功能模块
├── build/                  # colcon 构建输出（不纳入版本管理）
├── install/                # colcon 安装输出（不纳入版本管理）
└── log/                    # colcon 构建日志（不纳入版本管理）

新增模块约定：每个新模块在仓库根目录下创建独立子目录，建议包含：

<module_name>/
├── README.md         # 模块说明
├── USER_GUIDE.md     # 安装与使用手册
├── ros2/             # ROS 2 接口包及示例（如有）
├── examples/         # 接入示例
└── scripts/          # 验证脚本

5. hivecore_logger — 日志系统

面向 C++/Python 业务节点的企业级异步非阻塞日志基础设施。

5.1 目录结构

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 hivecore_logger/scripts/build_install_and_start_manager.sh

该脚本依次执行：编译 SDK（C++ + Python + ROS 2 接口）→ 安装 → 启动日志管理服务。

如需仅编译和安装 SDK，不启动服务：

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/USER_GUIDE.md
测试报告	hivecore_logger/TEST_REPORT.md

---

6. 许可证

© HiveCore. All rights reserved.