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（发行版）：
DEPLOY_MODE=prod bash hivecore_logger/scripts/build_install_and_start_manager.sh
该脚本依次执行：编译 SDK（C++ + Python + ROS 2 接口）→ 安装至 /opt/hivecore/ → 启动日志管理服务。
如需仅编译和安装 SDK，不启动服务：
DEPLOY_MODE=prod bash hivecore_logger/scripts/build_install_sdk.sh
验证服务健康状态：
bash hivecore_logger/scripts/check_manager_health_prod.sh
其他常用脚本：
| 脚本 | 用途 |
|---|---|
scripts/start_manager.sh |
单独启动日志管理服务 |
scripts/stop_manager.sh |
停止日志管理服务 |
scripts/check_manager_health_prod.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.