david
7a4d3607f6
- Use DEPLOY_MODE=prod for build_install_and_start_manager.sh and build_install_sdk.sh - Switch health check to check_manager_health_prod.sh - Note production install path /opt/hivecore/
201 lines
6.4 KiB
Markdown
201 lines
6.4 KiB
Markdown
# 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
|
||
DEPLOY_MODE=prod bash hivecore_logger/scripts/build_install_and_start_manager.sh
|
||
```
|
||
|
||
该脚本依次执行：编译 SDK（C++ + Python + ROS 2 接口）→ 安装至 `/opt/hivecore/` → 启动日志管理服务。
|
||
|
||
如需仅编译和安装 SDK，不启动服务：
|
||
|
||
```bash
|
||
DEPLOY_MODE=prod bash hivecore_logger/scripts/build_install_sdk.sh
|
||
```
|
||
|
||
验证服务健康状态：
|
||
|
||
```bash
|
||
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/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.
|