hivecore_robot_system/hivecore_logger

hivecore_logger

面向机器人系统的企业级统一日志基础设施。

1. 本项目提供能力

• 面向 C++/Python 业务节点的异步、非阻塞日志 SDK (极低开销)。
• Python SDK 支持原生 throttle (限流) 与 expression (条件) 宏级扩展，支持 inotify 零 CPU 占用热更新。
• 节点级日志文件轮转与统一日志格式。
• 强大且安全的集中式管理模块：磁盘配额、后台异步压缩（避免阻塞清理）、防止路径穿越攻击、运行时动态调级。
• 支持 HTTP 与 ROS 2 Service 两种动态调级入口。

2. 模块说明

• cpp/：基于 spdlog 的 C++ SDK（异步、非阻塞、轮转）。
• python/：基于 QueueHandler/QueueListener 的 Python SDK。
• manager/：集中式日志管理模块（配额、压缩、动态调级）。
• ros2/hivecore_logger_interfaces/：ROS 2 接口定义（SetLogLevel.srv）。

3. 工程目录结构

hivecore_logger/
├── cpp/                              # C++ 日志 SDK (含 tests)
├── python/                           # Python 日志 SDK (含 tests)
├── manager/                          # 管理模块（可独立部署）(含 tests)
├── ros2/
│   ├── hivecore_logger_interfaces/   # ROS2 接口包
│   └── examples/                     # ROS2 最小调用示例
├── examples/               # 外部业务节点接入示例（C++/Python）
└── scripts/                          # 一键验证与演示脚本

目录职责建议：

• cpp/、python/：供业务节点复用的 SDK 层。
• manager/：作为独立后台进程部署。
• ros2/：提供 ROS2 接口与示例调用。
• examples/：第三方节点接入模板。
• scripts/：CI 或手工回归的快捷入口。

4. 日志管理模块与命令行工具 (Manager & CLI)

本项目将日志管理服务端 (Manager) 与 客户端命令行工具 (CLI) 合并在 manager 工程中。 它既能作为独立 Python 进程后台运行，也能通过带有 ament_python 标记的方式无缝融入 ROS 2 体系。

4.1. 编译与环境准备

无论是服务端部署还是离线节点的日志检视，都可以通过以下两种方式之一完成准备：

方式 A（ROS 2 全局编译 - 推荐） 在整个 ROS 2 工作空间下将 manager 作为标准组件包编译：

colcon build --packages-select hivecore_logger_interfaces hivecore_log_manager
source install/setup.bash

方式 B（纯 Python 环境独立安装） 若目标机器无需 ROS 2（例如离线日志分析客户端或不支持 ROS 2 的纯服务网关环境）：

cd hivecore_logger/manager
pip install -e .

完成上述操作后，系统会自动注册以下三个全局命令：

• hivecore-log-manager：Log Manager 服务端主进程。
• hivecore-log-cli：功能丰富的操作客户端及查询入口。
• hivecore-log-merge：单独暴露的跨节点日志离线归并分析工具。

4.2. 启动 Log Manager（服务端）

日志管理模块负责全局的日志收集、磁盘配额管理、文件清理及提供配置服务接口。

方法一：命令行快速启动（测试/开发）

hivecore-log-manager \
    --log-dir /tmp/robot_logs \
    --quota-mb 2048 \
    --interval 60 \
    --http-host 127.0.0.1 \
    --http-port 18080

说明：若在已 source ROS 2 环境的终端运行该命令，系统会自动激活 /log_manager/set_node_level 的 ROS 2 服务和 ROS 2 话题发布。若需屏蔽，可追加 --disable-ros2-service 参数。

方法二：作为 systemd 服务开机自启（生产 Linux 推荐）

创建 /etc/systemd/system/hivecore-log-manager.service 文件：

[Unit]
Description=Hivecore Log Manager
After=network.target

[Service]
Type=simple
User=root
# 请修改为实际安装的 Python 虚拟环境或全局包路径下的可执行命令
ExecStart=/usr/local/bin/hivecore-log-manager --log-dir /var/log/robot --quota-mb 2048 --interval 60 --http-host 0.0.0.0 --http-port 18080
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

生效：

sudo systemctl daemon-reload
sudo systemctl enable --now hivecore-log-manager
sudo systemctl status hivecore-log-manager

4.3. 客户端命令行工具使用 (CLI)

hivecore-log-cli 用于快捷查看系统状态、修改业务节点级别和追踪合并日志。

CLI 命令兼容两种写法（等价）：

• hivecore-log-cli（中划线）
• hivecore_log_cli（下划线）

status / set 命令支持 HTTP 回退：

• 当 ROS 2 Python 依赖不可用（例如 rclpy、hivecore_logger_interfaces 未在当前 Python 环境）时，会自动改用 HTTP 接口。
• 当 ROS2 service 临时不可达时，set 会自动尝试 HTTP 回退。
• 默认回退地址：http://127.0.0.1:18080，可通过 --manager-url 或环境变量 HIVECORE_LOG_MANAGER_URL 覆盖。

查看全局日志系统监控状态:

hivecore-log-cli status

动态修改业务节点日志输出级别:

hivecore-log-cli set <node_name> <level>
# 示例：将视觉检测节点的日志等级降至 DEBUG
hivecore-log-cli set vision_node DEBUG

实时追踪对应节点的末端流 (Tail): 会自动定位到该节点最新生成的日志分卷上进行 tail -f 监视。

hivecore-log-cli tail vision_node

跨节点日志按时间戳顺序合并预览 (Merge): 纯离线分析排查必备，将目录下杂乱的多节点日志按照微秒级时间戳排序融合！

hivecore-log-cli merge /var/log/robot
# 也可使用更短的替代命令：
hivecore-log-merge /tmp/robot_logs

4.4. 外部探测与诊断拓扑 (Diagnostic Topic)

启动后，Manager 将以 1Hz 频率向外推发全局磁盘及存储配置情况：

• 话题名: /log_manager/status
• 消息类型: hivecore_logger_interfaces/msg/LoggerStatus

内部包含了核心系统信息，诸如 total_size_bytes（总体量）、file_count（分卷数）、last_cleanup_time 等，可以直接作为仪表盘或硬件诊断模块的数据源。也可以使用 ROS 2 命令直接健康检测：

ros2 topic echo /log_manager/status

5. 部署参数推荐表

可先按以下模板配置，再结合节点数量、日志量和磁盘容量做微调。

场景	--log-dir	--quota-mb	--interval	HTTP	ROS2 Service	适用说明
开发	/tmp/robot_logs	512	10	127.0.0.1:18080	可选	本地快速迭代，日志生命周期短
测试/CI	/tmp/robot_logs	1024	15	127.0.0.1:18080	通常关闭	压测/集成测试，保留量中等
生产	/var/log/robot	2048（或更高）	60	0.0.0.0:18080（或内网 IP）	按需开启	长周期运行，扫描频率更稳健

示例命令模板：

# 开发
/root/workspace/think/.venv/bin/python -m hivecore_log_manager.manager \
  --log-dir /tmp/robot_logs --quota-mb 512 --interval 10 --http-host 127.0.0.1 --http-port 18080 --disable-ros2-service

# 测试/CI
/root/workspace/think/.venv/bin/python -m hivecore_log_manager.manager \
  --log-dir /tmp/robot_logs --quota-mb 1024 --interval 15 --http-host 127.0.0.1 --http-port 18080 --disable-ros2-service

# 生产
/root/workspace/think/.venv/bin/python -m hivecore_log_manager.manager \
  --log-dir /var/log/robot --quota-mb 2048 --interval 60 --http-host 0.0.0.0 --http-port 18080

6. 统一日志格式

所有 SDK 输出兼容的文本格式：

[YYYY-MM-DD HH:MM:SS.mmm] [LEVEL] [NodeName] [Thread] [File:Line] Message

示例：

[2026-02-26 17:03:08.778] [INFO] [vision_node] [MainThread] [sdk.py:120] Vision node started successfully

6.1 日志文件存储路径

日志文件按日期自动分目录存储，文件名带有启动时间戳前缀，路径结构如下：

log_dir/
├── 20260304/                                    ← 当日日志目录（YYYYMMDD）
│   ├── 20260304_120000_control_node.log         ← 活跃日志文件（YYYYMMDD_HHMMSS_<node>.log）
│   ├── 20260304_120000_control_node.1.log       ← 轮转历史分卷（C++/spdlog 命名：<stem>.<N>.log）
│   ├── 20260304_093000_vision_node.log          ← 活跃日志文件
│   └── 20260304_093000_vision_node.log.1        ← 轮转历史分卷（Python 命名：<stem>.log.<N>）
├── 20260303/                                    ← 前日日志目录
│   └── ...
└── .levels/                                     ← 动态调级配置目录（固定于根目录，不随日期轮转）
    ├── control_node.level
    └── vision_node.level

说明：

• 文件名前缀 YYYYMMDD_HHMMSS_ 为节点进程启动时刻的本地时间，同一节点每次重启都会生成新的文件，便于区分不同运行实例的日志。
• .levels/ 目录固定在 log_dir/ 根目录，便于 Manager 统一读写；日志文件本身按写入当天日期落入对应的 YYYYMMDD/ 子目录。
• hivecore-log-cli tail <node> 会自动定位到该节点最新修改的日志文件。

7. 外部节点接入示例

完整示例位置：

• examples/cpp
• examples/python
• examples/find_package_smoke
• examples/README.md

这些示例用于展示第三方业务节点如何接入 logger，而不依赖仓库内部测试代码。

8. 外部工程接入（C++）

8.1. 编译并链接 SDK

cd /root/workspace/think/hivecore_logger/cpp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

若需要给外部工程长期复用，建议安装 SDK：

cd /root/workspace/think/hivecore_logger/cpp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
cmake --install build --prefix /opt/hivecore_logger_cpp

安装后，外部工程可通过 CMAKE_PREFIX_PATH 查找：

cmake -S . -B build -DCMAKE_PREFIX_PATH=/opt/hivecore_logger_cpp

外部 CMake 工程可通过安装后 find_package，或 add_subdirectory 接入。

示例 A：安装后通过 find_package 接入（推荐用于已安装 SDK 的工程）

cmake_minimum_required(VERSION 3.14)
project(my_robot_node LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(spdlog REQUIRED)
find_package(fmt REQUIRED)
find_package(hivecore_logger_cpp REQUIRED)

add_executable(my_robot_node src/main.cpp)
target_link_libraries(my_robot_node
  PRIVATE
    hivecore_logger_cpp::hivecore_logger_cpp
)

示例 B：通过 add_subdirectory 直接引入源码（推荐用于单仓或联调阶段）

cmake_minimum_required(VERSION 3.14)
project(my_robot_node LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(HIVECORE_LOGGER_CPP_BUILD_DEMO OFF CACHE BOOL "" FORCE)
set(HIVECORE_LOGGER_CPP_BUILD_TESTS OFF CACHE BOOL "" FORCE)
add_subdirectory(../hivecore_logger/cpp ${CMAKE_BINARY_DIR}/hivecore_logger_cpp_build)

add_executable(my_robot_node src/main.cpp)
target_link_libraries(my_robot_node
  PRIVATE
    hivecore_logger_cpp
)

8.2. 进程级初始化

hivecore::log::LoggerOptions options;
options.log_dir = "/var/log/robot";
options.default_level = hivecore::log::Level::INFO;
hivecore::log::Logger::init("motion_control_node", options);

8.3. 业务代码中打日志

LOG_INFO("Controller started, mode={}", mode);
LOG_WARN("Joint near limit, joint={}, q={}", joint_name, position);
LOG_ERROR("Trajectory failed, code={}", error_code);

// 支持限流 (每 1000ms 最多输出一次)
LOG_INFO_THROTTLE(1000, "High frequency state: {}", state);

// 支持条件输出 (当 condition 满足时输出)
LOG_ERROR_EXPRESSION(err_code != 0, "Pipeline failed code={}", err_code);

8.4. 进程退出前关闭

hivecore::log::Logger::shutdown();

9. 外部工程接入（Python）

9.1. 安装 SDK

cd /root/workspace/think/hivecore_logger
/root/workspace/think/.venv/bin/python -m pip install -e python

9.2. 初始化并获取 logger

import logging
import hivecore_logger

hivecore_logger.init(
    node_name="vision_node",
    log_dir="/var/log/robot",
    level=logging.INFO,
)
logger = hivecore_logger.get_logger()

9.3. 在业务流程中记录日志

logger.info("Vision node started")
logger.warning("Low confidence target=%s conf=%.2f", target_id, confidence)
logger.error("Pipeline failed code=%s", err_code)

# 支持限流 (每秒最多输出一次)
logger.info_throttle(1.0, "High frequency state: %.2f", state)

# 支持条件输出
logger.error_expression(err_code != 0, "Pipeline failed code=%s", err_code)

9.4. 进程退出前停止

hivecore_logger.stop()

说明：Python SDK 默认启用 atexit 与 SIGINT/SIGTERM 自动收尾（可配置关闭），用于在忘记显式 stop() 时降低丢日志风险；但该机制是 best-effort，SIGKILL/掉电等场景仍可能丢失日志。

10. 关键配置项

10.1. 节点级配置 (C++ LoggerOptions / Python LoggerConfig)

node_name 安全校验: 仅允许 [A-Za-z0-9_-] 字符，长度 1–127。C++ Logger::init() 违规时返回 false 并输出警告；Python LoggerConfig 违规时抛出 ValueError。

配置项	类型	默认值	安全范围	说明
log_dir	string	/var/log/robot	—	主日志目录
fallback_log_dir	string	/tmp/robot_logs	—	权限失败时回退目录
max_file_size_mb	int	50	[1, 100]	单个日志文件轮转阈值 (MB)
max_files	int	10	[1, 100]	单个节点最多保留的日志文件数
queue_size	int	8192	[64, 65536]	异步队列大小（C++: spdlog thread pool 预分配；Python: queue.Queue 上限）
default_level / level	string/int	INFO	—	节点启动时的默认日志级别
enable_console	bool	true	—	是否输出到控制台
enable_level_sync	bool	true	—	是否监听 .levels/<node>.level 动态调级
level_sync_interval_sec	float	0.1	[0.01, 60.0] (Python); C++ level_sync_interval_ms [10, 60000] ms	动态调级等待兜底间隔 (Linux 环境优先使用 inotify 零开销监听)
flush_interval_ms	uint32	1000	—	定期刷盘间隔 (ms)；0 表示仅在 WARN+ 级别时触发刷盘（仅 C++）
worker_threads	size_t	1	[1, 16]	异步日志后台工作线程数（仅 C++；仅首次 init() 生效）
enable_auto_shutdown_hook	bool	true	—	是否启用 atexit 自动收尾 (仅 Python)
enable_signal_handlers	bool	true	—	是否接管 SIGINT/SIGTERM 触发收尾 (仅 Python)

安全校验：queue_size、worker_threads（C++ only）、max_file_size_mb、max_files、level_sync_interval_sec（Python）/ level_sync_interval_ms（C++）超出上表安全范围时，SDK 会自动将其夹到邻近边界值，并通过以下渠道发出 WARNING 告警：

• C++：spdlog::warn("[hivecore_logger] '<字段名>' value <原值> out of safe range [<lo>, <hi>], clamped.")
• Python：logging.getLogger("hivecore_logger.config").warning("hivecore_logger: '<字段名>' value <原值> out of safe range [<lo>, <hi>], clamped.")

超出范围不会导致初始化失败，但建议在上线前修正配置以避免资源耗尽风险。

10.2. 全局管理配置 (Manager 启动参数)

参数	类型	默认值	安全范围	说明
--log-dir	string	/var/log/robot	—	全局日志存储根目录
--quota-mb	int	2048	[1, 1,000,000]	全局日志最大占用空间 (MB)
--interval	int	60	[1, 86400]	配额检查周期 (秒)
--min-interval	int	5	[1, interval]	配额超限时的快速重试间隔 (秒)
--safe-watermark-ratio	float	0.9	[0.01, 0.99]	磁盘清理降至此水位比例后停止删除
--panic-watermark-ratio	float	0.98	[safe, 1.0]	超过此水位比例时发出 CRITICAL 告警
--compress-interval	int	3600	[1, 86400]	日志压缩扫描周期 (秒)
--compress-min-age-hours	float	2.0	[0.0, 48.0]	午夜后至少等待此时长才压缩昨日目录（跨午夜滚动宽限期）
--disable-compression	flag	-	—	禁用后台日志 gz 压缩
--http-host	string	127.0.0.1	—	HTTP API 监听地址
--http-port	int	18080	[1, 65535]	HTTP API 监听端口
--disable-http	flag	-	—	禁用 HTTP API 服务
--disable-ros2-service	flag	-	—	禁用 ROS 2 动态调级服务

11. 运行时动态调级

11.1. HTTP API（默认）

• 接口：POST /set_node_level
• 请求体：

{
  "node_name": "vision_node",
  "level": "DEBUG"
}

• 状态接口：GET /status

11.2. HTTP 快速调用

curl -X POST http://127.0.0.1:18080/set_node_level \
  -H 'Content-Type: application/json' \
  -d '{"node_name":"vision_node","level":"DEBUG"}'

11.3. ROS 2 Service（可选）

• 服务名：/log_manager/set_node_level
• 类型：hivecore_logger_interfaces/srv/SetLogLevel

若 ROS2 环境或接口不可用，Manager 会自动降级为仅 HTTP 模式。

11.4. ROS 2 快速调用

ros2 service call /log_manager/set_node_level hivecore_logger_interfaces/srv/SetLogLevel \
  "{node_name: vision_node, level: DEBUG}"

12. 快速开始

12.1. C++

cmake -S cpp -B cpp/build -DCMAKE_BUILD_TYPE=Release
cmake --build cpp/build -j
ctest --test-dir cpp/build --output-on-failure

运行 C++ 外部节点示例：

cd examples/cpp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
./build/external_cpp_node

12.2. Python 外部节点示例

python -m pip install -e python
python examples/python/external_python_node.py

12.3. Python SDK 测试

python3 -m pip install -e python
python3 -m pytest -q python/tests/

12.4. Manager 测试

python3 -m pip install -e manager
python3 -m pytest -q manager/tests/

12.5. 集成测试

python3 -m pytest -q manager/tests/integration_tests/

12.6. 全量测试（含覆盖率报告）

# Python SDK + Manager 全量测试（带行覆盖率）
python3 -m pytest python/tests/ manager/tests/ \
    --cov=hivecore_logger --cov=hivecore_log_manager \
    --cov-report=term-missing -q

# C++ 全量测试
cmake -S cpp -B cpp/build -DCMAKE_BUILD_TYPE=Release
cmake --build cpp/build -j
cd cpp/build && ./test_logger && ./test_logger_stress

当前测试状态（v1.0.1）：

测试套件	用例数	通过率	覆盖率
C++ SDK（功能 + 压力）	21	100%	~95%（功能路径）
Python SDK	27	100%	94%
Log Manager	114	100%	92%
总计	162	100%	93%

详细测试报告见 TEST_REPORT.md。

13. 一键脚本

13.1. 编译并安装 SDK（C++/Python）

权限说明（生产模式）：

• 默认会写入 /opt/hivecore/logger-sdk/<SDK_VERSION> 与 /opt/hivecore/venvs/robot-runtime
• /opt 通常需要 root 权限；若当前用户无写权限，请使用 sudo 执行安装命令，或改用用户可写目录（通过 INSTALL_PREFIX、PYTHON_VENV_DIR 覆盖）

首次在新机器执行前，请先安装系统依赖（Ubuntu/Debian）：

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

说明：

• python3-venv：用于创建 venv（AUTO_CREATE_VENV=1 时会用到）
• python3-pip：确保 python -m pip 可用，避免 No module named pip

若历史 venv 已创建但缺少 pip，可修复：

/opt/hivecore/venvs/robot-runtime/bin/python -m ensurepip --upgrade

若出现类似报错：Python package path is not writable: /opt/.../site-packages，表示当前用户对该 venv 无写权限。可使用 sudo 执行安装，或改用用户可写的 PYTHON_VENV_DIR/PYTHON_BIN。

./scripts/build_install_sdk.sh

支持双模式：

• DEPLOY_MODE=dev（默认）
• DEPLOY_MODE=prod

默认行为：

• 编译 C++ SDK（cpp/build）
• 安装 C++ SDK 到 output/sdk_install
• 安装 Python SDK（editable）
• 安装 Manager（editable）
• （prod 默认）构建 ROS2 接口相关包：hivecore_logger_interfaces、hivecore_log_manager

模式差异：

• dev：默认安装到工作区，Python 包使用 editable 安装（便于开发调试）
• prod：默认 C++ 安装到 /opt/hivecore/logger-sdk/<SDK_VERSION>，Python 默认使用 /opt/hivecore/venvs/robot-runtime/bin/python，Python 包默认非 editable 安装，并默认构建 ROS2 接口包（避免 start_manager.sh 再提示手工 colcon build）

可选环境变量：

• DEPLOY_MODE：dev 或 prod
• SDK_VERSION：生产模式下 C++ SDK 版本号（默认 1.0.1）
• INSTALL_PREFIX：覆盖 C++ SDK 安装目录
• PYTHON_VENV_DIR：指定 venv 目录（若未显式传 PYTHON_BIN）
• PYTHON_BIN：指定 Python 解释器
• PIP_EDITABLE：1/0，控制 Python 包是否 editable 安装
• AUTO_CREATE_VENV：1/0，解释器不存在时自动创建 venv
• BUILD_ROS2_IFACE：1/0，是否在安装脚本内执行 colcon build --packages-up-to hivecore_log_manager（prod 默认 1，dev 默认 0）
• ROS2_SETUP_FILE：ROS2 环境脚本（默认 /opt/ros/humble/setup.bash）
• WS_SETUP_FILE：工作区环境脚本（默认 <workspace>/install/setup.bash）

示例：

# 开发模式（默认）
./scripts/build_install_sdk.sh

# 生产模式
DEPLOY_MODE=prod SDK_VERSION=1.0.1 ./scripts/build_install_sdk.sh

# 生产模式（/opt 无写权限时）
sudo DEPLOY_MODE=prod SDK_VERSION=1.0.1 ./scripts/build_install_sdk.sh

# 生产模式（仅 HTTP，不构建 ROS2 接口）
DEPLOY_MODE=prod BUILD_ROS2_IFACE=0 SDK_VERSION=1.0.1 ./scripts/build_install_sdk.sh

13.2. 启动 Manager

./scripts/start_manager.sh

默认以 ROS2 节点模式 启动（会启用 /log_manager/set_node_level 服务和 /log_manager/status 话题发布）。

支持双模式：

• DEPLOY_MODE=dev（默认）：本地开发友好，默认日志目录为 output/manager_logs
• DEPLOY_MODE=prod：生产默认日志目录为 /var/log/robot，默认 HTTP 监听 0.0.0.0

可选环境变量：

• DEPLOY_MODE：dev 或 prod
• LOG_DIR（dev 默认 output/manager_logs；prod 默认 /var/log/robot）
• QUOTA_MB（dev 默认 2048；prod 默认 4096）
• INTERVAL_SEC（默认 60）
• HTTP_HOST（dev 默认 127.0.0.1；prod 默认 0.0.0.0）
• HTTP_PORT（默认 18080）
• DISABLE_ROS2_SERVICE（默认 0，即启用 ROS2）
• ROS2_SETUP_FILE（默认 /opt/ros/humble/setup.bash）
• WS_SETUP_FILE（默认 <workspace>/install/setup.bash）
• AUTO_BUILD_ROS2_IFACE（dev 默认 1；prod 默认 0）
• PYTHONPATH_SOURCE：1/0（dev 默认 1；prod 默认 0），是否将仓库 python/ 注入 PYTHONPATH
• PYTHON_BIN（dev 默认 <workspace>/.venv/bin/python；prod 默认 /opt/hivecore/venvs/robot-runtime/bin/python）

说明：prod 模式默认值不同（LOG_DIR=/var/log/robot、QUOTA_MB=4096、HTTP_HOST=0.0.0.0、AUTO_BUILD_ROS2_IFACE=0、PYTHONPATH_SOURCE=0）。

启动成功后会写入 manager.pid 到日志目录。

如需仅 HTTP 模式：

DISABLE_ROS2_SERVICE=1 ./scripts/start_manager.sh

生产模式示例：

DEPLOY_MODE=prod PYTHON_BIN=/opt/hivecore/venvs/robot-runtime/bin/python ./scripts/start_manager.sh

13.3. 停止 Manager（清理 PID）

./scripts/stop_manager.sh

默认读取 output/manager_logs/manager.pid，支持通过 LOG_DIR 覆盖路径。

生产模式若使用默认日志目录，可直接：

DEPLOY_MODE=prod ./scripts/stop_manager.sh

13.4. 兼容入口（串行执行）

./scripts/build_install_and_start_manager.sh

该脚本会依次调用：build_install_sdk.sh + start_manager.sh。

13.5. 如何检查安装是否成功

执行完 ./scripts/build_install_sdk.sh 后，可用以下命令快速确认：

# 1) C++ SDK 安装产物（静态库 + CMake config）
ls -l output/sdk_install/lib/libhivecore_logger_cpp.a
ls -l output/sdk_install/lib/cmake/hivecore_logger_cpp/hivecore_logger_cppConfig.cmake

# 生产模式下（示例）
ls -l /opt/hivecore/logger-sdk/1.0.1/lib/libhivecore_logger_cpp.a
ls -l /opt/hivecore/logger-sdk/1.0.1/lib/cmake/hivecore_logger_cpp/hivecore_logger_cppConfig.cmake

# 2) Python SDK / Manager 包是否可导入
/root/workspace/think/.venv/bin/python -c "import hivecore_logger, hivecore_log_manager; print('python packages ok')"

# 生产模式下（示例）
/opt/hivecore/venvs/robot-runtime/bin/python -c "import hivecore_logger, hivecore_log_manager; print('python packages ok')"

# 3) CLI 是否可执行
/root/workspace/think/.venv/bin/hivecore-log-cli --help

# 生产模式下（示例）
/opt/hivecore/venvs/robot-runtime/bin/hivecore-log-cli --help

# 4) ROS2 接口是否可见（需 source ROS2 与 workspace）
source /opt/ros/humble/setup.bash
source /root/workspace/think/install/setup.bash
ros2 interface show hivecore_logger_interfaces/srv/SetLogLevel

若 start_manager.sh 已启动成功，还可继续验证：

ros2 node list | grep '^/hivecore_log_manager$'
ros2 service list | grep '^/log_manager/set_node_level$'

13.6. 验收记录（2026-03-03）

本次已按 13.5 的 dev/prod 清单实际执行并记录结果。

前置处理：

colcon build --packages-select hivecore_logger hivecore_logger_interfaces hivecore_log_manager

dev 模式结果：

• PASS: C++ SDK 静态库存在
• PASS: C++ SDK CMake 配置存在
• PASS: Python import hivecore_logger, hivecore_log_manager
• PASS: hivecore-log-cli --help
• PASS: ros2 interface show hivecore_logger_interfaces/srv/SetLogLevel
• PASS: ros2 node list 可见 /hivecore_log_manager
• PASS: ros2 service list 可见 /log_manager/set_node_level

13.7. 启动后自检（单命令 PASS/FAIL）

用于在 start_manager.sh 启动后，一次性检查 CLI/HTTP/ROS2：

./scripts/check_manager_health.sh

生产模式示例：

DEPLOY_MODE=prod \
PYTHON_BIN=/opt/hivecore/venvs/robot-runtime/bin/python \
HTTP_HOST=127.0.0.1 HTTP_PORT=18080 \
./scripts/check_manager_health.sh

仅 HTTP 模式（跳过 ROS2 检查）：

DEPLOY_MODE=prod CHECK_ROS2=0 ./scripts/check_manager_health.sh

生产环境快捷包装（内置 prod 参数，免输环境变量）：

./scripts/check_manager_health_prod.sh

prod 模式结果：

• PASS: /opt/hivecore/logger-sdk/1.0.1 安装产物存在
• PASS: /opt/hivecore/venvs/robot-runtime Python 导入成功
• PASS: /opt/hivecore/venvs/robot-runtime/bin/hivecore-log-cli --help
• PASS: ros2 interface show hivecore_logger_interfaces/srv/SetLogLevel
• PASS: ros2 node list 可见 /hivecore_log_manager
• PASS: ros2 service list 可见 /log_manager/set_node_level

14. 一键验证

./scripts/run_all_checks.sh

15. Manager 演示

./scripts/run_manager_demo.sh

16. 多版本并存时的版本选择

本节内容已移至 USER_GUIDE.md §8 多版本并存时的版本选择。

17. 常见问题

• 若 /var/log/robot 无写权限，SDK 会自动回退到 /tmp/robot_logs。
• 日志文件存储于 log_dir/<YYYYMMDD>/ 日期子目录下（如 /var/log/robot/20260304/20260304_120000_vision_node.log），文件名带有启动时间戳前缀；动态调级文件位于 log_dir/.levels/<node>.level。
• 若未 source ROS2 环境，动态服务调用可能失败：
  • source /opt/ros/humble/setup.bash
  • source ros2/install/setup.bash
• 若 pytest 受无关插件干扰，使用：PYTEST_DISABLE_PLUGIN_AUTOLOAD=1。