Ubuntu 20.04 上 Apollo 6.0 自动驾驶平台安装与编译实战指南

1. 为什么Apollo 6.0值得在Ubuntu 20.04上折腾一番如果你正在做自动驾驶相关的开发或者学习大概率绕不开百度Apollo这个开源平台。Apollo 6.0是其中一个比较经典的长期支持版本它在感知、预测、规划、控制这几个核心模块上都做了不少工程化打磨社区文档和踩坑记录也相对丰富。而Ubuntu 20.04作为目前最主流的LTS发行版之一软件源新、内核版本合适、长期维护有保障把这两者搭在一起算是目前自动驾驶入门和二次开发的一个稳妥组合。但说实话Apollo的安装过程对新手并不算友好。它不像装个Python库那样一行pip就能搞定整个流程涉及Docker容器、GPU驱动、NVIDIA Container Toolkit、镜像拉取、编译构建、地图数据下载等多个环节任何一个环节出问题都可能导致卡住。我自己第一次装的时候光是Docker和GPU的兼容问题就折腾了大半天。所以这篇内容我会把整个安装链路拆开从系统准备到最终跑通Demo把每一步的意图、参数含义、容易踩的坑都讲清楚。这篇文章适合谁看如果你是自动驾驶方向的学生、刚转行做自动驾驶开发的工程师、或者想在自己机器上跑通Apollo做算法验证的研究人员那这篇内容基本可以当作一份实操手册来用。前提是你需要有一台装了Ubuntu 20.04的机器最好带一块NVIDIA显卡因为Apollo的感知模块很多依赖GPU加速纯CPU跑虽然也能编译但实际体验会差很多。整个安装流程我把它分成四大块系统环境准备、Docker与GPU环境配置、Apollo源码获取与镜像构建、以及最后的编译验证与Demo运行。下面逐块展开。2. 系统环境准备与基础依赖安装2.1 硬件与系统版本确认在动手之前先确认你的机器满足基本条件。Apollo 6.0官方推荐的配置是CPU 4核以上、内存16GB起步32GB更稳、硬盘至少100GB可用空间因为Docker镜像和编译产物很占地方、NVIDIA显卡显存4GB以上推荐8GB。系统方面必须是Ubuntu 20.04而且建议是全新安装的干净系统。如果你之前装过其他版本的CUDA或者Docker可能会有残留冲突。我试过在一台之前装过CUDA 11的机器上直接装Apollo结果Docker里的CUDA版本和宿主机的驱动版本对不上编译一直报错最后重装系统才解决。确认系统版本lsb_release -a输出应该是Ubuntu 20.04.x LTS。如果不是20.04后面的步骤不保证能跑通。确认显卡和驱动nvidia-smi这条命令会输出显卡型号、驱动版本、CUDA版本。如果提示命令找不到说明驱动没装需要先装NVIDIA驱动。Apollo 6.0对驱动版本的要求是 455CUDA版本 11.1。我实测用470系列的驱动比较稳。2.2 安装NVIDIA驱动与CUDA如果你的机器还没装驱动最省事的方式是通过Ubuntu的“附加驱动”工具安装或者用命令行sudo apt update sudo apt install nvidia-driver-470装完重启再跑nvidia-smi确认。CUDA不需要单独装因为Apollo的Docker镜像里已经包含了CUDA运行时。宿主机只需要保证驱动版本够新就行。这一点很多人会搞混以为要在宿主机装CUDA Toolkit其实没必要反而可能引起版本冲突。注意如果你之前手动装过CUDA Toolkit建议把/usr/local/cuda相关的环境变量从.bashrc里注释掉避免干扰Docker内的CUDA环境。2.3 安装Docker与NVIDIA Container ToolkitApollo 6.0的整个开发和运行环境都封装在Docker容器里所以Docker是必须的。安装Docker的步骤sudo apt update sudo apt install apt-transport-https ca-certificates curl gnupg lsb-release curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo deb [archamd64 signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io装完之后把当前用户加入docker组这样不用每次sudosudo usermod -aG docker $USER然后注销重新登录或者执行newgrp docker让组权限生效。接下来装NVIDIA Container Toolkit这是让Docker容器能访问GPU的关键distribution$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt update sudo apt install nvidia-docker2 sudo systemctl restart docker验证GPU是否能在Docker里用docker run --rm --gpus all nvidia/cuda:11.1-base nvidia-smi如果能看到显卡信息说明GPU透传配置成功。这一步非常关键如果这里不通后面Apollo的感知模块编译会直接失败。2.4 其他基础工具还需要装一些辅助工具比如git、curl、wget等一般系统自带缺的话补一下sudo apt install git curl wget unzip另外Apollo的构建脚本依赖Python 3.6Ubuntu 20.04自带Python 3.8满足要求。但建议装一下pip和virtualenv方便后续管理Python依赖sudo apt install python3-pip python3-venv3. Apollo源码获取与Docker镜像构建3.1 克隆Apollo仓库Apollo的源码托管在GitHub上直接clone就行。但要注意分支Apollo 6.0对应的分支是v6.0.0git clone -b v6.0.0 https://github.com/ApolloAuto/apollo.git cd apollo如果网络不稳定clone可能会断可以试试加--depth 1只拉最新一次提交减少数据量git clone -b v6.0.0 --depth 1 https://github.com/ApolloAuto/apollo.gitclone完成后目录结构大概是这样的modules放各个功能模块docker放Docker相关脚本scripts放构建和启动脚本tools放一些辅助工具。3.2 配置Docker镜像加速Apollo的Docker镜像有好几个GB从官方源拉取在国内网络环境下可能很慢甚至超时。建议配置一下Docker镜像加速器。编辑/etc/docker/daemon.json{ registry-mirrors: [https://your-mirror.example.com], runtimes: { nvidia: { path: nvidia-container-runtime, runtimeArgs: [] } } }把your-mirror.example.com替换成你实际可用的镜像加速地址。改完重启Dockersudo systemctl daemon-reload sudo systemctl restart docker提示runtimes那段是给NVIDIA Container Toolkit用的有些版本的nvidia-docker2会自动加如果没有就手动补上。3.3 启动Apollo开发容器Apollo提供了一个脚本docker/scripts/dev_start.sh来启动开发容器。这个脚本会自动拉取镜像、创建容器、挂载源码目录。执行bash docker/scripts/dev_start.sh第一次执行会拉取镜像时间取决于网速。拉完之后会启动一个名为apollo_dev_$USER的容器并进入容器的bash环境。如果一切正常你会看到命令行提示符变成类似[userin-dev-docker:/apollo]$的样子说明已经进到容器里了。这里有个细节dev_start.sh默认会拉取apolloauto/apollo:dev-x86_64-18.04-20210517_1530这样的镜像标签。如果你想指定版本可以用-t参数。但一般不用管脚本会根据分支自动选。注意如果你在启动容器时看到Cannot connect to the Docker daemon说明Docker服务没起来执行sudo systemctl start docker。如果看到GPU相关的报错回头检查NVIDIA Container Toolkit是否装好。3.4 容器内的环境初始化进入容器后先执行一下环境初始化脚本bash /apollo/scripts/apollo_base.sh这个脚本会设置一些环境变量比如APOLLO_ROOT、GLOG_logtostderr等。其实不执行也行因为.bashrc里已经配好了但手动跑一次可以确认没有报错。然后检查一下容器内的CUDA和GPU是否可用nvidia-smi nvcc --versionnvidia-smi应该能正常输出nvcc的版本应该是11.1左右。如果nvcc找不到可能需要手动加一下PATH但Apollo的镜像一般都已经配好了。4. 编译构建与常见报错处理4.1 全量编译ApolloApollo使用Bazel作为构建工具。在容器内执行./apollo.sh build这个命令会编译整个Apollo项目包括感知、规划、控制等所有模块。编译时间取决于机器性能我在一台16核32GB的机器上大概花了40分钟如果是4核机器可能要2小时以上。如果你想只编译某个模块比如只编译感知./apollo.sh build_perception或者只编译规划./apollo.sh build_planning这样可以节省时间。但第一次建议全量编译确保环境没问题。编译过程中最常见的报错有几类第一类是内存不足导致的OOM。Bazel默认会开很多并行任务如果内存不够编译到一半会被系统kill掉。解决办法是限制并行数./apollo.sh build --jobs4或者直接加swap分区。我一般会预留至少8GB swap防止编译中途崩掉。第二类是GPU相关的编译错误比如cuda_runtime.h not found。这通常是因为Docker容器里的CUDA路径没配好。检查/usr/local/cuda是否存在以及LD_LIBRARY_PATH是否包含/usr/local/cuda/lib64。第三类是网络问题导致的依赖下载失败。Bazel在编译时会下载一些第三方库如果网络不通会报Failed to fetch。解决办法是配置Bazel的代理或者提前把依赖下载好放到缓存目录。Apollo的WORKSPACE文件里定义了所有外部依赖可以手动下载后放到~/.cache/bazel对应的位置。4.2 编译产物的位置编译成功后产物在/apollo/bazel-bin目录下。各个模块的可执行文件分别在对应的子目录里比如感知模块的libperception.so在bazel-bin/modules/perception下。你可以用ls bazel-bin/modules/看看各个模块是否都编译出来了。如果某个模块目录是空的说明那个模块没编译成功需要单独排查。4.3 常见编译报错速查表报错信息可能原因解决办法Out of memory内存不足减少jobs数加swapcuda_runtime.h: No such fileCUDA路径未配置检查/usr/local/cuda和LD_LIBRARY_PATHFailed to fetch xxx网络问题配置代理或手动下载依赖bazel: command not foundBazel未安装执行./apollo.sh会自动安装Permission denied文件权限问题chmod x或检查用户组protobuf version mismatchprotobuf版本冲突清理bazel缓存重新编译实操心得如果编译失败后想重新编译建议先执行./apollo.sh clean清理缓存否则可能因为残留的中间文件导致奇怪的错误。但clean之后所有东西都要重编时间会比较长。5. 运行Demo与地图数据准备5.1 下载地图数据Apollo运行需要地图数据官方提供了一些示例地图。在容器内执行bash scripts/apollo_map.sh download这个脚本会下载一些示例地图到/apollo/modules/map/data目录下。如果下载失败也可以手动从Apollo的GitHub Release页面下载地图包解压到对应目录。常用的示例地图有sunnyvale美国加州某区域、san_mateo另一个美国区域等。每个地图目录下会有base_map.bin、sim_map.bin等文件。5.2 启动DreamviewDreamview是Apollo的可视化界面用来查看车辆状态、传感器数据、规划轨迹等。启动方式bash scripts/bootstrap.sh start这个脚本会启动Dreamview的后端和前端。启动完成后在浏览器里访问http://localhost:8888就能看到界面。如果是在远程服务器上跑的需要做端口转发或者用ssh -L 8888:localhost:8888把端口映射到本地。Dreamview启动后在界面上选择车型和地图。车型一般选Lincoln MKZ地图选你下载的那个比如sunnyvale。5.3 播放Demo数据Apollo提供了一些录制好的数据包record文件可以用来回放测试。数据包一般在/apollo/docs/demo_guide目录下或者需要单独下载。播放数据包的命令cyber_recorder play -f demo_3.5.record --loop这个命令会循环播放数据包Dreamview界面上就能看到车辆动起来感知模块会识别出障碍物规划模块会生成轨迹。如果Dreamview里看不到任何反应检查以下几点数据包路径是否正确、Dreamview是否选了正确的地图、各个模块是否已经启动。可以用cyber_monitor工具查看各个channel是否有数据。5.4 模块启动与调试Apollo的各个模块可以单独启动比如只启动感知bash scripts/perception.sh start或者只启动规划bash scripts/planning.sh start启动后可以用cyber_monitor查看模块的输出。cyber_monitor是Apollo自带的命令行工具能实时显示各个topic的数据。如果某个模块启动失败查看日志tail -f data/log/perception.log日志里一般会有详细的报错信息根据报错去排查。6. 实操避坑经验与性能调优6.1 磁盘空间管理Apollo的Docker镜像、编译产物、地图数据、日志文件加起来很容易超过100GB。建议定期清理# 清理bazel缓存 ./apollo.sh clean # 清理Docker无用镜像 docker system prune -a # 清理日志 rm -rf data/log/*但注意docker system prune -a会删掉所有未使用的镜像包括Apollo的镜像下次启动容器又要重新拉。所以执行前确认一下。6.2 GPU显存优化Apollo的感知模块比较吃显存如果显存不够可以把一些模型换成轻量版。在modules/perception/production/conf/perception_camera.conf里可以配置使用哪个模型。另外Dreamview界面上也可以关闭一些不必要的可视化选项减少GPU占用。6.3 编译加速技巧如果机器核心多可以适当增加jobs数./apollo.sh build --jobs8但要注意内存一般每个job需要2GB左右内存。16GB内存建议jobs不超过6。另外Bazel支持增量编译改一个文件后重新编译只会编改动的部分速度很快。所以不要动不动就clean。6.4 常见运行时问题问题现象排查方向解决方法Dreamview打不开端口占用或服务未启动检查8888端口重启bootstrap车辆不动数据包未播放或地图不对检查record播放和地图选择感知无输出GPU未透传或模型加载失败检查nvidia-smi和感知日志规划报错地图数据缺失确认地图文件完整编译卡住内存或磁盘不足检查系统资源我个人踩过最坑的一个问题是Docker容器里的时间跟宿主机不一致导致一些依赖时间戳的模块报错。解决办法是在启动容器时加-v /etc/localtime:/etc/localtime:ro把宿主机时区挂进去。Apollo的dev_start.sh脚本其实已经处理了这个问题但如果你手动用docker run启动容器就要自己加。6.5 关于Apollo 6.0的一些个人体会Apollo 6.0相比之前的版本在Docker化方面做得更彻底了基本上所有依赖都封装在镜像里宿主机只需要装好Docker和GPU驱动就行。这降低了环境配置的复杂度但也带来一个问题镜像体积很大拉取和构建都比较耗时。另外Apollo的文档虽然比较全但有些细节更新不及时比如某些脚本的参数变了但文档没改。遇到这种情况直接看脚本源码比看文档靠谱。docker/scripts/dev_start.sh和scripts/apollo.sh这两个脚本我建议通读一遍能省很多排查时间。最后再分享一个小技巧如果你只是想做算法验证不需要完整的感知规划控制链路可以只编译你关心的模块然后用cyber_recorder录制自己的数据包来测试。这样能大大缩短编译时间也减少资源占用。Apollo的模块化设计其实挺灵活的没必要每次都全量编译。