8. 故障排查

8.1 依赖安装

现象	可能原因	处理
`apt-get install` 失败	包冲突 / 源不可用	`sudo apt-get -y --fix-broken install` 后重试
`install_opencv.sh` 中断	网络 / 内存不足	`--resume-from install_opencv.sh`
`libceres.so not found`	第三方未装全	`python3 -m install_deps --thirdparty-only`
`behaviortree_cpp` 找不到	BT 库未安装	确认 `install_behaviortree_cpp.sh` 成功
非 Ubuntu 警告	脚本面向 Ubuntu	手动对照 `APT_PACKAGES` 安装等效包

8.2 CMake 配置

现象	可能原因	处理
`Could NOT find Protobuf`	缺少 dev 包	`sudo apt install libprotobuf-dev protobuf-compiler`
`Could NOT find Ceres`	`/usr/local` 无 Ceres	运行 `install_ceres_solver.sh`
`Could NOT find Lua`	缺少 lua5.3	`sudo apt install liblua5.3-dev`
gRPC 相关错误	`BUILD_GRPC=ON` 但缺 gRPC	安装 gRPC 或 `-DBUILD_GRPC=OFF`

清理后重配：

cd build && rm -rf * && cmake -G Ninja .. && ninja

8.3 编译错误

现象	可能原因	处理
C++17 相关错误	编译器过旧	升级 GCC 至 11+
OOM / 编译器被 kill	内存不足	`ninja -j2` 限制并行
链接错误 undefined reference	依赖顺序 / 缺库	检查 `/usr/local/lib` 是否在 `LD_LIBRARY_PATH`
submodule 缺失	未初始化 submodule	`git submodule update --init --recursive`

8.4 Docker

现象	可能原因	处理
无法启动容器	Docker 未运行	`sudo systemctl start docker`
GPU 不可用	未装 NVIDIA Toolkit	`install_nvidia_container_toolkit.sh`
挂载目录为空	`AUTONOMY_ENV` 未设置	`export AUTONOMY_ENV=/正确/路径`
权限 denied	root 创建的文件	`run_autonomy.py --as-host-user`
Isaac 镜像自动启动 Kit	ENTRYPOINT 行为	默认已覆盖为 bash；勿加 `--keep-isaac-entrypoint` 除非需要

8.5 运行时

现象	可能原因	处理
`libautonomy.so: cannot open`	未设置 rpath	从 `build/bin` 运行或 `export LD_LIBRARY_PATH=build/lib`
`Autonomy not ready`	BT 插件路径错误	设置 `AUTONOMY_BT_PLUGIN_PATH`
配置加载失败	`config_directory` 错误	确认 `config/autonomy.lua` 存在
TF / 帧名错误	`common.lua` 不一致	统一 `global_frame` / `robot_base_frame`

8.6 Habitat-Sim（可选）

仅在使用仿真相关功能时需要：

git clone --branch stable https://github.com/facebookresearch/habitat-sim.git
cd habitat-sim
pip3 install -r requirements.txt
git config --global --add safe.directory '*'
python3 setup.py install --headless --no-update-submodules

验证：

python3 -c "import habitat_sim; print('OK')"

内存不足时限制并行：python3 setup.py build_ext --parallel 1 install --headless --no-update-submodules

8.7 获取帮助

渠道	说明
GitHub Issues	https://github.com/quandy2020/autonomy/issues
文档	01 Instructions
FAQ	19 FAQs

8.8 相关文档