安装指南

本指南将帮助您安装和配置 Autonomy 项目所需的所有先决条件软件。

1 系统要求

1.1 支持的操作系统

  • Linux: Ubuntu 20.04/22.04 LTS (推荐)

  • 架构: x86-64 或 ARM64 (aarch64)

1.2 硬件要求

  • 内存: 至少 8GB RAM (推荐 16GB)

  • 存储: 至少 20GB 可用磁盘空间

  • CPU: 多核处理器 (推荐 4 核或以上)

2 Docker 安装与配置

Docker 是推荐的运行环境，提供了跨平台支持和一致的开发环境。

2.1. 安装 Docker

如果您的系统尚未安装 Docker，请运行以下命令：

cd autonomy/docker/scripts
sudo ./install_docker.sh

安装完成后，验证 Docker 是否正常工作：

docker --version

2.2 构建 Docker 镜像

run_autonomy.sh 脚本会根据您的计算机平台（x86-64 或 aarch64）自动选择并构建相应的 Docker 镜像。

重要提示: 在运行脚本之前，请设置环境变量 AUTONOMY_ENV 指向宿主机上的 autonomy 项目路径（如果需要在宿主机和容器之间共享代码）。

# 设置环境变量（可选，仅在需要时设置）
# export AUTONOMY_ENV=/path/to/autonomy

# 构建并运行 Docker 容器
cd autonomy/docker
./run_autonomy.sh

脚本会自动：

  • 检测系统架构（x86-64 或 aarch64）

  • 构建相应的 Docker 镜像

  • 启动名为 SpaceHero 的容器

  • 挂载工作目录到容器中

2.3 进入 Docker 容器

容器启动后，您可以通过以下命令进入容器：

docker exec -it SpaceHero /bin/bash

3 获取源码

3.1克隆仓库

从 Gitee 或 GitHub 克隆 Autonomy 项目的源码：

# 从 Gitee 克隆（国内推荐）
git clone https://gitee.com/openbotbeginner/autonomy.git
git clone https://gitee.com/openbotbeginner/autonomy_ros.git

# 或从 GitHub 克隆
git clone https://github.com/quandy2020/autonomy.git
git clone https://github.com/quandy2020/autonomy_ros.git

3.2 目录结构

克隆完成后，您的目录结构应该如下所示：

autonomy/
├── src/
│   ├── autonomy/          # 核心 Autonomy 框架
│———└── autonomy_ros/      # ROS/ROS2 兼容层

4 编译与安装

Autonomy 项目支持两种编译方式：使用 ROS2 (推荐) 或仅使用 C++ (无 ROS 依赖)。

4.1 使用 ROS2 编译（推荐）

此方式适合需要在 ROS2 环境中运行或与 ROS2 集成的场景。

  1. 进入 Docker 容器

docker exec -it SpaceHero /bin/bash

  1. 设置 ROS2 环境

source /opt/ros/humble/setup.bash

  1. 编译项目

cd /workspace/autonomy
colcon build --symlink-install

编译选项说明:

  • --symlink-install: 使用符号链接安装，便于开发时修改代码

  • 如需仅编译特定包，使用: colcon build --packages-select <package_name>

  1. 运行测试（可选）

colcon test
colcon test-result --verbose

4.2 C++ 编译（无 ROS 依赖）

此方式适合仅使用 Autonomy 核心功能，不依赖 ROS/ROS2 的场景。

  1. 进入 Docker 容器

docker exec -it SpaceHero /bin/bash

  1. 创建构建目录并编译

cd /workspace/autonomy/src/autonomy
mkdir -p build
cd build
cmake .. -G Ninja
ninja

  1. 运行测试（可选）

CTEST_OUTPUT_ON_FAILURE=1 ninja test

编译选项说明:

  • -G Ninja: 使用 Ninja 构建系统，编译速度更快

  • 如需使用 Makefile，可省略 -G Ninja 选项

5 Habitat-Sim 安装（可选）

Habitat-Sim 是 Facebook Research 开发的 3D 仿真平台，用于训练和评估具身智能体。如果项目需要使用 Habitat-Sim 功能，请按照以下步骤从源码编译安装。

5.1 前置要求

  • Python 版本: >= 3.9

  • 编译时间: 约 30-60 分钟（取决于系统性能）

  • 存储空间: 约 2-3 GB（编译后）

5.2 安装步骤

  1. 获取源码

git clone --branch stable https://github.com/facebookresearch/habitat-sim.git
cd habitat-sim

  1. 安装 Python 依赖

pip3 install -r requirements.txt

  1. 配置 Git 安全设置（Docker 环境）

git config --global --add safe.directory '*'

  1. 编译安装（Headless 模式，适用于 Docker/服务器环境）

python3 setup.py install --headless --no-update-submodules

编译参数说明：

  • --headless: 用于无显示器系统（Docker 容器、服务器等）

  • --no-update-submodules: 跳过 Git 子模块更新，避免权限问题

其他编译选项：

  • --with-cuda: 启用 CUDA 支持

  • --bullet: 启用 Bullet 物理引擎

  • --audio: 启用音频传感器（仅 Linux）

示例（组合使用）：

python3 setup.py install --headless --with-cuda --bullet --no-update-submodules

5.3 验证安装

# 检查 Python 模块
python3 -c "import habitat_sim; print('habitat-sim installed successfully')"

# 检查安装版本
pip3 list | grep habitat-sim

5.4 常见问题

问题 1: Git 子模块权限错误

如果遇到 fatal: detected dubious ownership in repository 错误，运行：

git config --global --add safe.directory '*'

问题 2: 编译时间较长

Habitat-Sim 编译需要较长时间，这是正常现象。如果内存不足，可以限制并行编译：

python3 setup.py build_ext --parallel 1 install --headless --no-update-submodules

5.5 参考资源

  • GitHub 仓库: https://github.com/facebookresearch/habitat-sim

  • 官方编译文档: habitat-sim/BUILD_FROM_SOURCE.md

  • 稳定版本列表: https://github.com/facebookresearch/habitat-sim/releases

6 环境配置

6.1 Docker 容器内环境变量配置

在 Docker 容器中，建议将以下环境变量添加到 ~/.bashrc 文件中：

# 编辑 .bashrc
vim ~/.bashrc

# 添加以下内容
### Autonomy Environment Variables ###
export GLOG_logtostderr=1           # 日志输出到标准错误
export GLOG_alsologtostderr=0       # 不同时写入日志文件
export GLOG_colorlogtostderr=1      # 启用彩色日志输出
export GLOG_minloglevel=0           # 最小日志级别（0=INFO, 1=WARNING, 2=ERROR, 3=FATAL）
export GLOG_log_dir=${HOME}/.autonomy/log  # 日志文件目录

# 加载 Autonomy 环境
source /usr/local/setup.bash

# 如果使用 ROS2 编译，还需要加载 ROS2 环境
source /opt/ros/humble/setup.bash

使配置生效：

source ~/.bashrc

5.2 环境变量说明

变量名

说明

推荐值

GLOG_logtostderr

是否将日志输出到标准错误

1

GLOG_alsologtostderr

是否同时写入日志文件

0

GLOG_colorlogtostderr

是否启用彩色日志

1

GLOG_minloglevel

最小日志级别

0 (INFO)

GLOG_log_dir

日志文件保存目录

${HOME}/.autonomy/log

7 验证安装

7.1 检查编译产物

编译完成后，检查是否成功生成了可执行文件和库文件：

# ROS2 编译方式
ls -la /workspace/autonomy/install/autonomy/bin/

# C++ 编译方式
ls -la /workspace/autonomy/src/autonomy/build/bin/

7.2 运行测试示例

参考项目中的测试示例验证安装是否正确：

运行示例