Apollo：超详细部署与使用教程

Apollo（阿波罗）是百度开源的自动驾驶开放平台，提供高性能、灵活的软件架构，用于加速自动驾驶车辆的开发、测试与部署。它覆盖感知、预测、规划、控制、定位、高精地图、车端通信（CyberRT）到可视化（DreamView）的全栈模块化能力，是全球最有影响力的开源自动驾驶平台之一。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

Apollo 是百度于 2017 年开源的自动驾驶开放平台，目标是构建一个「开放、完整、安全」的软件栈，帮助汽车产业合作伙伴快速搭建自己的自动驾驶系统。它并非单一软件，而是一整套模块化开发框架：开发者在官方提供的开发容器（dev container）中完成代码编译、模块调试与仿真，再通过标定（calibration）流程将软件部署到线控车辆（by-wire vehicle，如林肯 MKZ）上。平台历经 1.0（园区 GPS 循迹）→ 2.0（简单城市道路）→ 3.5（复杂城区）→ 5.0/5.5（城市道路）→ 6.0/7.0（深度学习模型 + Apollo Studio）→ 8.0（Package 化软件框架）→ 9.0（包管理 2.0 + DreamView Plus）→ 10.0/11.0（大规模部署与功能无人车）共十余个大版本演进，最新 Release 标签为 v9.0.0。

1.2 核心功能

• 模块化软件栈：定位（Localization）、感知（Perception）、预测（Prediction）、规划（Planning）、决策（Decider）、控制（Control）、Guardian（安全守护）、HMI/Monitor（人机交互与监控）、CANBus（车总线）等解耦模块。
• CyberRT 通信框架：自研中间件，负责模块间的发布/订阅消息通信与调度。
• DreamView / DreamView Plus 可视化：开发者工具，提供多场景模式切换、可定制可视化面板、资源中心（9.0 新增）。
• 包管理（Package）：8.0 引入「Package」复用软件模块；9.0 升级到包管理 2.0，支持组件级扩展与更轻量的插件扩展方式。
• 感知模型体系：LiDAR 与 Camera 检测模型持续升级（9.0 已升级并开放增量训练），新增 4D 毫米波雷达支持。
• 仿真能力：DreamView 内置本地仿真器，为 PnC（Planning and Control）开发者提供调试工具链。
• 多硬件适配：支持 x86_64 与 ARM（9.0 适配 ARM 架构，支持在 Orin 上编译运行）；GPU 支持 NVIDIA 与 AMD（ROCm）。
• 高精地图与标定：完整的硬件集成与标定文档（相机/激光雷达/毫米波雷达/IMU/GPS）。

Apollo 版本演进（官方 README Roadmap）

1.3 技术架构

Apollo 官方 Logo：

Apollo 官方软件架构图（数据流：HD Map → Localization；感知链 Perception → Prediction → Planning → Control → CANBus；Guardian 安全监控；Monitor/HMI 可视化）：

Apollo 官方硬件拓扑图（以林肯 MKZ 为例：车顶 128 线激光雷达、前/侧相机、GPS 天线、车身 16 线激光雷达与毫米波雷达、后备箱工控机与 IMU）：

二、环境要求

Apollo 是面向自动驾驶的重软件栈，对硬件要求显著高于普通服务：

说明：上述最低配置可完成开发容器启动与基础编译；感知模型相关模块编译/运行建议 32GB 内存 + 24GB 显存 GPU，具体以官方文档为准。

2024-11 官方重要变更（README 标注）

• CUDA 升级到 11.8，以支持 NVIDIA Ada Lovelace（40 系）显卡，要求驱动 >= 520.61.05；
• arm64 平台的 LibTorch 升级到 1.11.0（x86_64 仍为 1.7.0）；
• 升级后需清理旧 Bazel 缓存（见 3.2 节）。

三、部署方式

Apollo 官方推荐的部署方式是 Docker 开发容器（dev container）：所有编译工具链（Bazel、CUDA、依赖库）都预装在官方镜像 apolloauto/apollo 内，宿主机只需装好 Docker 与 NVIDIA 驱动，避免环境污染。下面给出完整步骤。

3.1 方式一：Docker 开发容器（官方主推，开发/调试）

步骤 0：宿主机前置准备

# 1) 确认 NVIDIA 驱动版本 >= 520.61.05
nvidia-smi

# 2) 确认 Docker-CE >= 19.03
docker --version

# 3) 确认 NVIDIA Container Toolkit 已安装并可在容器内访问 GPU
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu18.04 nvidia-smi

步骤 1：拉取代码

cd ~
git clone https://github.com/ApolloAuto/apollo.git
cd apollo

建议初次使用按官方推荐顺序：先 1.0 版本验证各硬件/模块正常，再升级到更高版本。

步骤 2：启动开发容器（官方命令）

# 从仓库根目录执行
./docker/scripts/dev_start.sh

该脚本会自动拉取官方开发镜像（x86_64 版本如 apolloauto/apollo:dev-x86_64-18.04-20240620_1444，aarch64 自动选对应镜像），创建名为 apollo_dev_<用户名> 的容器并启动。

步骤 3：进入开发容器

./docker/scripts/dev_into.sh

进入后命令行提示符变为 in-dev-docker，即已进入 Apollo 开发环境（工作目录映射为宿主机的 Apollo 仓库根目录 /apollo）。

步骤 4：在容器内编译（可选，验证环境可用）

# 容器内：使用官方封装脚本构建（具体子命令以官方文档为准）
bash apollo.sh build        # 全量构建示例
# 或直接用 Bazel
bazel build //modules/...

首次构建会下载大量依赖并编译 C++，耗时较长（数十分钟级），请保持耐心并确保磁盘充足。

步骤 5：启动 DreamView 可视化

# 容器内启动 DreamView（Web 可视化，默认端口与启动命令以官方文档为准）
bash scripts/bootstrap.sh start_fe
# 随后在宿主机浏览器访问 DreamView 页面

3.2 方式二：升级迁移（已有旧版本 Apollo）

README 官方给出的 2024-11 升级步骤（CUDA 升级到 11.8 适配 40 系显卡）：

# 1) 宿主机 NVIDIA 驱动升级到 >= 510.61.05
# 2) 拉取最新代码后，进入开发容器清理旧 Bazel 缓存
rm -rf /apollo/.cache/{bazel,build,repos}

# 3) 重启开发容器
./docker/scripts/dev_start.sh

3.3 方式三：硬件上车部署（线控车辆）

无硬件时可先完成上面的容器开发；如有线控车辆（如林肯 MKZ），按官方文档完成硬件安装与标定后部署：

• 硬件安装指南：仓库内 docs/11_Hardware Integration and Calibration/ 目录
• 各版本 QuickStart（1.0 ~ 10.0）：README 有逐版本入口链接
• 9.0 软件安装指南：apollo.baidu.com/docs/apollo/9.0

3.4 官方脚本目录说明（docker/scripts/）

仓库 docker/scripts/ 目录提供完整的容器管理脚本：

容器命名规则：apollo_dev_<用户名>；GPU 与 ROCm（AMD）分别走不同镜像（apolloauto/apollo 与 rocmapollo/apollo）。

3.5 验证部署成功（通用）

1. ./docker/scripts/dev_start.sh 执行成功，无报错退出；
2. ./docker/scripts/dev_into.sh 进入容器，提示符含 in-dev-docker；
3. 容器内 ls /apollo 能看到 modules/、cyber/、scripts/ 等目录；
4. 启动 DreamView 后浏览器能打开可视化页面（以官方文档给出的地址为准）；
5. 编译产物目录生成 Bazel 输出（bazel-bin/ 存在）。

四、使用方法

4.1 基础工作流（开发循环）

# 宿主机：启动容器
./docker/scripts/dev_start.sh
# 进入容器
./docker/scripts/dev_into.sh

# 容器内：编译（apollo.sh 是官方封装脚本）
bash apollo.sh build

# 容器内：启动可视化（DreamView）
bash scripts/bootstrap.sh start_fe

# 容器内：运行/调试某模块（以官方文档模块命令为准）
# 例如规划模块相关调试入口见 docs/08_Planning/

数据流说明（对应 1.3 节架构图）：车辆传感器数据经 CANBus / 感知模块进入系统 → Perception 输出障碍物 → Prediction 预测障碍物轨迹 → Planning 结合 HD Map 与 Localization 生成局部轨迹 → Control 输出线控指令执行；Guardian 全程监控并在异常时接管；HMI/Monitor 通过 DreamView 展示给开发者。

4.2 仓库目录结构（官方文档划分）

4.3 进阶功能

• 包管理二次开发：9.0 提供 Package 2.0 与插件扩展方式，基于 Apollo 快速搭建自己的自动驾驶应用（见 docs/03_Package Management/）。
• 感知模型增量训练：9.0 开放 LiDAR/Camera 检测模型的增量训练方法，便于自定义场景。
• 本地仿真：DreamView 内置本地仿真器，PnC 开发者可在无车环境下调试规划控制。
• ARM/Orin 适配：9.0 适配 ARM 架构，支持在 Orin 平台编译运行。
• 4D 毫米波雷达：9.0 新增 4D 毫米波雷达支持。
• Apollo Studio / Data Pipeline：7.0 起引入的数据管线一站式在线开发平台（以官方文档为准）。

4.4 适用场景

• 自动驾驶科研机构的算法研究与平台验证；
• 汽车厂商/Tier1 的原型开发与二次开发；
• 园区/港口/矿区低速无人车方案；
• 自动驾驶教学与仿真教学；
• 车端中间件（CyberRT）与模块化架构参考。

4.5 最小上手验证清单

第一次使用 Apollo 时，建议按下面顺序逐项确认，避免一上来就被复杂环境劝退：

1. 宿主机 nvidia-smi 正常、docker --version 正常；
2. ./docker/scripts/dev_start.sh 成功，容器 apollo_dev_$USER 存在；
3. ./docker/scripts/dev_into.sh 进入容器，提示符出现 in-dev-docker；
4. ls /apollo/modules 能看到感知/规划/控制等模块目录；
5. bash scripts/bootstrap.sh start_fe 后 DreamView 页面可访问；
6. （可选）bash apollo.sh build 首次编译通过。

以上 6 步全部通过，即说明开发环境已就绪，可以进入具体模块的二次开发。若某一步失败，回到第五节 FAQ 对照排查；仍无法解决时，到仓库 GitHub Issues 搜索相同报错（官方维护者活跃）。

提示：本教程的硬件清单与脚本命令均来自官方 README；上车级部署（线控标定、传感器安装）请务必逐字阅读对应版本的 QuickStart 文档，不要凭经验跳过。

再次强调安全：README 建议从 1.0 版本顺序验证，确认各硬件模块正常后再逐步升级；任何道路测试都应在封闭场地且有 Apollo 工程团队支持下进行。

五、常见问题排查（FAQ）

Q1：dev_start.sh 失败，报错无法拉取镜像 / 超时 - 原因：Docker Hub 拉取 apolloauto/apollo 网络不通。 - 解决：配置 Docker 镜像加速器；确认磁盘剩余空间 > 20GB；重试或手动 docker pull 指定镜像 tag。

Q2：容器内 nvidia-smi 报错或看不到 GPU - 原因：宿主机未装 NVIDIA Container Toolkit，或驱动版本过低。 - 解决：安装/升级 NVIDIA Container Toolkit；nvidia-smi 确认宿主机驱动 >= 520.61.05；重启 Docker 后再 dev_start.sh。

Q3：编译报错「CUBLAS/CUDA version mismatch」或旧缓存冲突 - 原因：CUDA 升级（11.8）后旧 Bazel 缓存未清理。 - 解决：按 README 官方步骤执行 rm -rf /apollo/.cache/{bazel,build,repos} 后重启容器重编译。

Q4：内存不足（OOM killed）或编译极慢 - 原因：低于 16GB 内存或 CPU 核数不足。 - 解决：升级到 32GB 内存；关闭其他占用进程；Bazel 并行数视核数调整。

Q5：DreamView 页面打不开 - 原因：前端未启动或端口未映射。 - 解决：容器内确认 scripts/bootstrap.sh start_fe 执行成功；检查浏览器地址与端口（以官方文档为准）；确认宿主机防火墙未拦。

Q6：Ubuntu 版本不支持（如 24.04） - 原因：官方仅支持 Ubuntu 18.04/20.04/22.04。 - 解决：在支持版本上安装，或用官方支持版本的虚拟机/WSL2（GPU 直通需配置）。

Q7：进入容器后 ls /apollo 为空或目录结构不对 - 原因：在错误目录执行脚本，或挂载路径异常。 - 解决：从 Apollo 仓库根目录执行 docker/scripts/dev_into.sh；确认仓库完整 clone。

Q8：升级后部分模块行为异常 - 解决：按 README 升级步骤清理 .cache 全量重编译；跨大版本（如 8.0→9.0）务必阅读对应版本 Release Notes 与包管理迁移文档。

Q9：AMD 显卡用户如何使用？ - 原因：官方同时支持 AMD ROCm 路线。 - 解决：宿主机安装 ROCm v5.1+；dev_start.sh 会自动识别架构选择 ROCm 镜像（rocmapollo/apollo），具体版本见脚本头部。

Q10：只想跑仿真/可视化，不买硬件可以吗？ - 解决：可以。README 明确「无硬件也能成功构建 Apollo」：dev_start 进入容器 → 编译 → DreamView 启动，即可在本地仿真环境调试 PnC 模块；硬件标定与上车按后续 QuickStart 逐步进行。

六、部署注意事项与最佳实践

1. 严格遵守支持矩阵：Ubuntu 18.04/20.04/22.04 + 驱动 >= 520.61.05 + Docker-CE >= 19.03，不要在未支持系统上强行安装。
2. 先无硬件跑通容器：没有线控车辆时，先完成 dev_start → 进入容器 → DreamView → 编译这条最小链路，再碰硬件。
3. 上车安全第一：README 明确建议按 1.0 → 目标版本的顺序验证，确认每个硬件模块正常后再上高版本；2.5 及以上版本路测需 Apollo 工程团队协助。
4. 磁盘与缓存：Bazel 构建缓存增长快，定期清理 /apollo/.cache；保持 50GB+ 可用空间。
5. 版本与镜像绑定：开发镜像 tag 与代码版本对应，不要混用不同时期拉取的镜像。
6. GPU 驱动先行验证：宿主机先 nvidia-smi、再 docker run --gpus all nvidia-smi，确认 GPU 穿透正常再进容器。
7. 阅读对应版本文档：9.0 与 10.0/11.0 的包管理、DreamView 差异较大，使用时先确认当前代码版本对应的官方文档章节。
8. 商业部署合规：README Disclaimer 提示，商业产品化部署需结合网络安全防护策略，详见官方 Disclaimer。
9. 不要在容器内直接动宿主机文件：开发容器只挂载仓库目录，系统级变更应在 Dockerfile 层重建镜像，避免容器删除后配置丢失。
10. 保留官方脚本：版本升级时勿覆盖修改过的 docker/scripts/ 脚本，先 git status 确认本地改动再 pull。

七、参考资料

• GitHub 仓库：https://github.com/ApolloAuto/apollo
• 官方文档站：https://developer.apollo.auto
• 9.0 文档：https://apollo.baidu.com/docs/apollo/9.0/
• 10.0 最新文档：https://apollo.baidu.com/docs/apollo/latest/
• 硬件安装指南（仓库）：https://github.com/ApolloAuto/apollo/tree/master/docs/11_Hardware%20Integration%20and%20Calibration
• FAQ（仓库）：https://github.com/ApolloAuto/apollo/tree/master/docs/15_FAQS/README.md
• Release 下载：https://github.com/ApolloAuto/apollo/releases
• Docker 镜像：https://hub.docker.com/u/apolloauto
• 官方网站：http://apollo.auto