Apollo自动驾驶平台Docker部署实操：从环境准备到常见问题排查

小学期实践课程做到第四课，基本已经过了“看什么都有意思”的新鲜劲儿，剩下的全是硬骨头。这一课的任务是 Apollo 软件部署实操——让学生在本地环境里，把这个体积庞大的自动驾驶开源平台拉下来、编译起来、把界面跑起来。每年带这门课我都会遇到一批被 Docker 权限、镜像体积、编译超时折磨到怀疑人生的同学，所以这一篇我就把整个部署流程从头到尾拆开讲一遍，该提前做的准备工作、该避开的坑、该给学生的兜底方案，全部写清楚。适合今年或明年要带 Apollo 部署实操的助教和课程讲师参考，也适合那些想在课下自己动手把环境搭起来、但被各种报错反复劝退的同学照着操作。

这篇内容不会只停留在“执行哪几条命令”的层面，而是会把每一步背后的逻辑讲透——为什么要用 Docker 而不是直接在物理机里编译，为什么有些学生的机器明明配置不低却跑不起来，镜像下载到一半断掉了到底该怎么续。按照我实际带课的经验，把这些前置认知搞明白，后面踩坑的概率至少能降一半。

1. 课程定位与部署思路

1.1 为什么选 Apollo 作为小学期实践课的部署对象

小学期课程和常规学期内的理论课有本质区别。常规课讲究知识体系的完整性，小学期讲究的是“在有限时间内见到真实成果”。Apollo 这个项目刚好踩在这个需求点上——它是目前高校自动驾驶教学里能接触到的最接近工业级的开源平台，从硬件抽象层到感知、预测、规划、控制模块都有完整的工程实现。学生拿到的不再是教材上干巴巴的算法伪代码，而是一套真正能跑起来、能看到可视化界面、能操作仿真场景的完整系统。

另一个现实原因是生态成熟度。Apollo 的社区和文档经过多年积累已经相对完善，课程团队能找到的教学参考足够多。再加上很多高校的智能车实验室、自动驾驶课题组都在用它做原型验证，学生在课上学会这套部署流程，后面进实验室或者做毕业设计都能直接用得上。还有一点容易被忽略：Apollo 这套系统本身就是按“车辆级”标准设计的，部署过程中的 Docker 隔离、模块化编译、配置管理，本身就是很好的工程实践教材，哪怕学生以后不做自动驾驶方向，这套部署流程里面涉及的 Linux 基础、容器化思想、软件工程习惯，也足够让他们收获不小。

从课程安排的角度看，部署实操放在第四课也有讲究。前面几课一般会讲平台架构、操作系统基础和开发环境准备，学生已经对 Linux 命令、容器概念有了基本认知。到第四课直接让他们把一个大型系统部署起来，是对前面所学知识的综合检验。如果一上来第一课就做部署，学生对很多概念没有概念，出了问题连排查方向都没有，上课效果就是灾难现场。

1.2 部署方案选型：为什么是 Docker 而不是物理机直装

很多第一次接触 Apollo 的同学会问：为什么不能直接在 Ubuntu 系统里把代码拉下来编译运行，非要套一层 Docker？这个问题问得很好，答案也恰恰是这个平台设计的核心思路之一。

先算一笔实际成本。Apollo 涉及上百个依赖库和工具链，不同模块对依赖版本的要求各有差异。如果直接在物理机上编译，光是解决依赖冲突就能耗掉大半天时间。有一年我带课时遇到一个学生手动装依赖，最后把系统的 Python 环境搞坏了，连桌面环境都起不来，无奈只能重装系统。而 Docker 容器把整个编译运行环境完整封装在镜像里，宿主机只需要装好 Docker 和显卡驱动，剩下的所有依赖问题都在容器内解决，对学生机器是最大程度的保护。

我经常给学生打这样一个比方：Docker 镜像就像一个打包好的移动厨房，锅碗瓢盆、柴米油盐全在里面，走到哪儿一提就走。你不需要在每台新宿舍里重新买一套厨具，只要有个地方能放稳（Docker 引擎），就能马上开火。Apollo 官方把编译好的开发环境镜像发布出来，学生拉下来就是一个可以直接用的环境，省去了成百上千个依赖的安装过程，这在大规模教学场景里优势非常明显。

但事情都有两面性。用 Docker 部署也意味着学生必须理解容器和宿主机的边界问题——文件怎么共享、GPU 怎么透传进去、端口怎么映射出来、权限怎么处理。这几个点恰恰是部署实操中最容易出问题的环节，也是我这篇后面会重点展开讲的内容。所以课程设计上我一般会先花 20 分钟讲清楚“为什么要用 Docker”和“Docker 是怎么把自动驾驶环境隔离开的”这两个问题，再动手，学生后面遇到问题至少知道往哪个方向去想。

2. 环境准备与前置检查

2.1 硬件与系统版本要求

Apollo 这个项目对硬件的要求不算低，但也没有想象中那么吓人。我以近几个版本的部署要求为参考，一般来说 16GB 内存是舒适线，8GB 能跑但编译时候会比较痛苦——我遇到过学生用 8GB 内存的笔记本编译，内存吃满直接触发 OOM（内存溢出），编译进程被杀，报错信息又晦涩，学生根本看不懂。CPU 方面主流的多核处理器都能应付，磁盘空间建议至少预留 80GB，这里面镜像本身占掉三四十 GB，编译产物又占掉二三十 GB，剩下还得留点余量。

显卡和驱动是另一个关键点。运行 DreamView 界面和部分感知可视化需要 GPU 加速，虽然没有 NVIDIA 显卡也能把框架跑起来，但体验会差很多，部分演示模块可能直接跑不动。所以课程组在发课前面向学生做了一个硬件摸底问卷，只有个别老旧的核显笔记本需要特别处理。至于系统版本，Apollo 官方各版本对 Ubuntu 版本要求不完全一致，从 18.04 到 22.04 都有支持，我们课程统一用的是 20.04 版本，兼容性最稳妥，遇到的坑最少。

注意：不要让学生在 Windows 或 macOS 上直接尝试部署 Apollo。虽然可以通过虚拟机装 Ubuntu 再部署，但 GPU 透传、磁盘性能、USB 设备映射等大量问题会让课程难度失控。课程组明确要求所有学生物理机安装 Ubuntu 20.04 双系统，这是第一道硬性关卡。

另外还有一个特别容易踩的坑：学生拿到的电脑如果开启了 Secure Boot，安装驱动和 Docker 时大概率会遇到签名验证的问题。我给课程准备的预处理清单里，第一项就是进入主板 UEFI 设置关闭 Secure Boot。别小看这一步，往年有一个组因为这个问题在安装显卡驱动阶段卡了整整两个课时。

2.2 安装 Docker 与 NVIDIA 容器工具包的关键细节

基础环境安装这一节看似简单，但细节极多。Docker 安装本身没有太大难度，按官方文档加到软件源再安装即可。但有几个点必须提前叮嘱学生。

第一是用户组权限。安装完 Docker 后默认需要用 sudo 才能执行 docker 命令，学生如果每次操作都敲 sudo，一方面容易忘记，另一方面生成的容器内文件属主混乱，后面会带来一堆麻烦。正确做法是让学生把自己的账号加入 docker 用户组，这样当前用户可以直接操作 Docker。但这个操作有安全代价——加入 docker 组的用户相当于有了宿主机 root 权限，不过在教学场景里可控，我会明确告诉学生这个前提。

第二条是换源。国内网络环境下直接拉取 Docker Hub 镜像经常超时，这个是带课老师必须提前处理的。需要在 Docker 的配置文件里配置镜像加速器，用国内可用的镜像源。这一步不提前做，课堂上就会出现所有学生同时在那等镜像下载、进度条纹丝不动的壮观场面。我建议在课程正式开始前一天统一给学生下发配置好的 Docker 配置文件，第二天上课直接能用，省去一大段时间。

第三是 NVIDIA Container Toolkit 的安装。这块是让容器里能用 GPU 的关键，也是报错重灾区。初代课程我们只装了 Docker 没装 Toolkit，结果容器里运行带 GPU 优化的模块直接报找不到设备，排查了很久才发现是这个原因。Toolkit 的安装逻辑是让 Docker 运行时能够把宿主机显卡设备映射到容器内部，需要和 Docker 版本匹配，装完以后跑一下测试命令验证 GPU 是否在容器内可见，这一步值得专门花时间确认。

2.3 网络环境与镜像下载的准备工作

网络问题在教学场景中被严重低估，直到上课那天才爆发。Apollo 的镜像体积非常大，通常有好几 GB，上百个学生同时拉取，再好的带宽也扛不住。而且部分镜像文件托管在国外的源上，不做好前置准备，现场就可能变成大型比惨现场。

我的做法是提前把镜像拉取到本地，然后在局域网内部署一个镜像分发方案。具体操作分三步：第一，课程准备阶段在一台有良好外网访问的机器上预先拉取好全部所需镜像；第二，把镜像导出为离线包，上传到课程内部的存储服务；第三，上课当天学生统一从内部服务导入镜像，而不是各自去外网拉取。这个流程成熟以后，学生从零开始到进入开发容器，全程控制在二十分钟以内，比让学生各自拉镜像快了很多，也稳了很多。

针对个人自学的情况，没有课程组提供的镜像源，那就只能靠耐心和好网络。我给学生的建议是拉取镜像时用后台续传方式，不要在一个终端窗口死等；如果中途断了，重新拉取一般会复用已有层，不用从头再来。还有一招是避峰下载，早上网络通畅的概率远大于晚上。

镜像拉完之后还有一个细节：验证镜像完整性和标签正确性。不同版本的 Apollo 镜像对应不同容器启动脚本，标签写错了后面启动容器的时候会有一堆莫名其妙的错误。每年都有学生在 docker images 列表里看着一堆镜像不知道用哪个，这个我会在下一节里具体讲怎么和项目版本对应起来。

3. Apollo 部署实操全流程

3.1 代码拉取与分支选择

环境准备好之后，进入正式的部署流程。第一步是获取 Apollo 源码。课程统一从远程仓库拉取，分支选择是关键。Apollo 各版本分支差别很大，不同分支对应不同的镜像标签和编译方式，用错了就是开局一步错、步步错。

我的建议是课程开课前老师就确定好一个版本，不要让学生自己选。虽然这个平台上很多分支可供探索，但在教学场景下，统一版本意味着所有学生的报错信息是同一批、解决办法可以共享，一个班四五十个人的助教压力会小得多。有一年我们尝试让学生自由选择版本，结果课上出现了五种不同版本的部署问题，助教根本答不过来，最后只能临时调整为统一版本。

拉取代码时有几个细节值得留意。首先要确认磁盘剩余空间，我见过学生拉代码拉到最后报磁盘满，整个目录处于半损坏状态，只能删掉重新拉。其次是网络协议的选择，如果环境允许就选 SSH 方式，否则选 HTTPS 方式也别换，中途切换协议会让 git 仓库的远程关联变得混乱。最后是 submodule 的问题，Apollo 的部分依赖是以子模块方式管理的，拉完主仓库后一定要执行子模块初始化命令，否则后续构建工具会报找不到组件的错。这是很多学生第一次拉代码时会忽略的隐形步骤。

3.2 进入开发容器的完整过程

代码拉好后，关键的一步就来了——启动容器并进入开发环境。Apollo 提供了封装好的脚本来处理这个过程，但我强烈建议不要只让学生 “无脑跑脚本”，而是让他们理解脚本里的每一步干了什么，这样后面出问题才知道怎么排查。

容器的启动逻辑大致是：先检查本地是否存在对应标签的镜像，不存在就尝试拉取；然后创建并启动一个容器实例，把宿主机上的 Apollo 源码目录挂载进容器，把 DreamView 等服务的端口映射出来；如果配置了 GPU，还会把显卡设备传进容器。理解挂载和端口映射这两个概念尤为重要——挂载保证了在容器里改代码等于改宿主机文件，不会因为容器销毁而丢失；端口映射保证了容器内部的 Web 服务能被宿主机浏览器访问到。

实际操作中我见过最常见的启动失败原因有两个。一个是端口被占用——学生之前启动过容器没有正确关闭，再次启动时端口冲突。解决办法也简单，让学生先查看当前是否有残留容器，清理干净再启动。第二个是硬盘权限问题——挂载的源码目录属主和容器内用户不一致，导致容器内没有写权限。这不是学生拿着终端能立刻看出来的问题，需要带着他们一步步查属主、查挂载参数，理解了原理后根治。

容器启动并进入之后，第一件事不是立刻编译，而是先让学生在容器里跑一下基础自检命令，确认 GPU 可以被容器访问、确认挂载目录内的代码和宿主机一致、确认网络连通性。这三项确认完，再继续往下面走，能避免很多“做了半天发现基础环境就没对”的无效劳动。我上课时会明确要求学生在群里发自检命令的输出截图，过了这一关才算环境部署完成，这比看谁的进度快更可靠。

3.3 代码编译与 DreamView 启动

容器就绪以后，接下来是编译和启动可视化界面。编译这一步在普通电脑上耗时比较长，短则三四十分钟，长则一两个小时，跟机器性能和磁盘速度直接相关。有固态硬盘的学生会比机械硬盘快一大截，课程组会在分组时尽量把不同配置的机器打散，避免“第 3 组整体落后”的尴尬。

编译指令本身不复杂，但要注意选择正确的构建方式。不同版本的构建命令和参数略有差异，但大体上是先安装依赖，再执行构建脚本。构建过程中输出信息极其庞大，学生会看到大量日志快速滚动，很容易慌。这时候要反复强调一句话：只要最后不是以“失败”或“错误”结尾并且返回了命令行提示符，就说明是成功的。很多学生看到日志里出现“warning”就以为出错了，其实那些大多是编译器给出的提示信息，不影响构建结果。

构建完成后再启动 DreamView 就简单了。执行启动脚本后，打开浏览器访问本地端口，就能看到自动驾驶可视化界面。那一刻的成就感对学生的激励作用非常大——前面几十分钟的等待和折腾，在看到界面的瞬间都会被冲淡。这里再强调一个细节：DreamView 默认监听端口是固定的，启动服务后要注意防火墙是否拦截了本地访问，有些学生装了安全软件会把本地端口拦住，报错的时候先往这个方向查一下。

体验完界面之后，点开一个示例场景让车辆在模拟环境里跑一段，看到感知画面和规划轨迹在屏幕上实时显示，这节部署课的目标就达成了。跑完演示后别忘了引导学生顺手做一个操作——在容器内执行命令把编译产物保存到挂载目录，这样即使容器销毁重建，下次也不用全部重新编译。

4. 常见问题与排查技巧实录

4.1 部署高频问题速查表

每次带课下来，我都会把学生问到的高频问题整理进文档，到下一届上课时直接发给学生先行排查。下面的表格就是我从这几年课程答疑记录里汇总出来的高频情况，值得截图保存。

这张表只能解决“怎么办”的问题，下面我再挑三个最有代表性的问题，展开讲讲背后的排查思路和教学处理方式。

4.2 编译超时与内存不足的处理策略

编译卡住或者被杀进程是每届都会出现的情况，而且往往集中在内存偏小的机器上。Apollo 的编译对内存的需求峰值很高，并行编译时多个编译任务同时开火，内存瞬间就吃满了。系统为了自保会杀掉内存占用最大的进程，表现出来就是终端里刷出一大段报错，然后构建进程退出。

处理这个问题的标准操作是限制并行编译的数量。构建工具一般支持指定并行任务数，默认可能是 CPU 核数的两倍，对学生笔记本来说太激进了。我建议参数直接减半甚至减到四分之一，编译时间会延长不少，但至少不会半路崩掉。对内存实在吃紧的机器，加交换分区也是有效手段，SATA 接口的机械硬盘配合大交换分区虽然慢一点，但能保证任务最终完成。

还有一类情况是学生同时开了太多程序：浏览器十几个标签页还挂着视频，微信后台在传文件，云端同步客户端实时扫描磁盘。这些都在抢内存资源。开课前我会要求全体学生把不需要的图形界面程序关掉。这不是强制约束，但我会在课上讲清楚“资源是有限游戏”的道理，让他们理解为什么编译时机器那么卡。

4.3 学生机器差异大，如何统一教学节奏

教学场景里最让助教头疼的不是技术本身，而是学生之间的进度差拉得越来越大。有的机器二十分钟编译完了，有的机器还在拉镜像；进度领先的同学开始玩手机刷别的，进度落后的同学急得满头大汗。这种情况下课程安排一定要有“弹性”。

我把部署课设计成三段式节奏：第一段是同步操作，所有人跟着走，不允许自由发挥；第二段是异步操作，编译等待时间长的同学继续等，领先的同学开始阅读官方文档里关于架构设计的章节，并回答几个思考题；第三段是分组结对，先把环境弄好的组员去帮助落后的组员，既锻炼了表达能力，也减轻了助教压力。这样安排下来，没有哪个时间段是完全浪费的。

针对机器特别老、怎么也跑不动的个别情况，我会启用备用方案——让这些学生通过远程方式连接到课程组准备的高配置服务器上操作。虽然少了点亲自部署的体验，但至少不会让个别同学因为硬件问题完全掉队。这个兜底方案在报名阶段就通过摸底问卷识别出来了，不需要到课堂上再临时救火。

5. 实操总结与给课程组的几点建议

5.1 带课过程中的执行要点回顾

通篇讲下来，Apollo 部署课的核心逻辑可以压缩成四句话：前置准备工作比课上操作更重要，环境统一比各自发挥更重要，让学生理解原理比单纯跑通命令更重要，合理的课堂结构比一味追赶进度更重要。

把这几句话落实成具体的行动项就是——课程开始前一周完成镜像离线化、确定统一版本、下发环境配置清单；课程开始当天先花二十分钟讲清 Docker 隔离和挂载映射背后的原理，再进入实操；实操阶段设置互帮互助机制，让进度领先的学生带动进度落后的学生；课后布置一个思考作业，让学生把容器启动脚本的关键参数逐个查清楚说明含义。以上几步都做到位，Apollo 部署这件事就可以从“让学生惧怕的大型翻车现场”变成“学生收获感最强的一节实践课”。

5.2 下届课程可继续优化的方向

每一届课程结束之后，课程组都会做一次复盘。目前已经在计划内的优化方向有两个。

第一个方向是把离线镜像和部署脚本进一步自动化打包，尝试做到学生下载一个安装包、执行一条命令，就能把整个开发环境初始化好。当然自动化程度越高，学生“动手”的部分就越少，所以要在“降低门槛”和“保留学习过程”之间找一个平衡点，不能因噎废食。

第二个方向是引入更多的运行时诊断工具，比如容器内资源占用实时监控面板、编译进度可视化工具。这些工具能让学生更直观地看到部署过程中发生了什么，而不是只在终端里面对一堆滚动的日志猜测现状。工具本身不复杂，但确实能显著改善课堂体验。

最后再多说一句带课时的个人体会：Apollo 部署这门课，最怕的不是学生技术底子差，而是他们卡住以后不知道该从哪里开始排查。所以带课的过程中，我会刻意训练学生的“问题拆解”习惯——看到报错先判断是环境问题、代码问题还是资源问题，然后再动手。这个思维方式练好了，这几天的部署课带给他们的收获，就远远不止“学会装一个自动驾驶平台”那么简单了。