企业官网建设流程全解析

1. 先把问题想明白：深度学习环境为什么要用容器装起来

如果你跑过两年以上的训练任务，大概率经历过这种场面：半年前某个模型跑出的结果，今天想复现，代码仓库还在，数据还在，但环境装不回去了。pip install出来的依赖树已经和当年不一样，编译型扩展跟着系统库版本一起漂移，报错信息还停留在某个 C++ 头文件找不到上。我最初接触容器化，动机非常朴素——不是为了什么工程化，就是为了让“昨天能跑的东西今天还能跑”。

Docker 在深度学习场景里的价值，说到底就三件事：环境隔离、环境固化、环境搬运。隔离解决的是同一台机器上不同项目依赖互相打架的问题；固化解决的是“我这里是好的”这种玄学；搬运解决的是从开发机到训练机、从训练机到另一台不同系统的机器上，环境能不能原样过去。它不加速训练，也不提升显存利用率，它只是把“环境”这个东西从一堆手工操作变成一个可以版本管理的产物。

适合读这篇的人，大致分三类。第一类是自己买了显卡、在自己机器上折腾环境、被 CUDA 版本折磨过的新手，你想知道从零到能跑通一个训练脚本，最少需要哪几步。第二类是团队里负责“把环境统一起来”的人，你要的是一个能长期维护、能被别人接手、能挂到 CI 里重复构建的方案。第三类是已经把环境跑起来了，但日常使用中总有些小毛病——共享内存崩、权限不对、镜像越滚越大——你想知道别人是怎么绕过去的。这三类人的关注点不一样，但底层的东西是同一套，我按从选型到实操再到排错的顺序往下写。

注意：这篇里所有的路径、账号、版本号都是示例，你抄思维不要抄字面，尤其是版本号，一定要按你自己机器上驱动支持的版本去对齐。

2. 方案选型：三条路线，各自适合什么人

2.1 三条路线横向对比

一提到“在 Docker 里搭深度学习环境”，新手最容易犯的错是直接冲去写 Dockerfile，从ubuntu:22.04开始装驱动、装 CUDA、装 cuDNN，装到一半发现驱动根本不应该装在容器里。所以要先把路线选清楚。

我个人的选择长期停在路线一。理由很实际：框架官方镜像虽然开箱即用，但你迟早会遇到“这个镜像的 Python 是 3.9，而我要用的某个库只支持 3.11”这种问题，这时候你要么换镜像，要么在官方镜像上再叠一层，叠完发现体积比路线一还大。而路线三，除非你要把镜像分发到几百台机器上、对每一百兆都在意，否则投入产出比很差。

2.2 基础镜像怎么挑：devel 和 runtime 的区别决定了你能不能装东西

官方 CUDA 基础镜像一般有几种标签变体，关键在于devel和runtime这两种后缀。

runtime版本里只有运行所需的动态库，没有编译器、没有头文件、没有nvcc。它的体积小一些，但你在里面pip install一个需要编译 CUDA 扩展的包（比如某些自定义算子库），会直接报找不到nvcc或者找不到cuda_runtime.h。

devel版本包含了完整的工具链，nvcc、头文件、静态库都在。代价是体积大，通常比 runtime 版大出好几个 G。

我的建议是：除非你确定这个镜像只用来跑推理、绝对不会编译任何东西，否则一律选devel。省下来的那几个 G 的磁盘，远远比不上后期被迫重建镜像的时间成本。

另一个要盯的是 cuDNN 版本。镜像标签里通常带cudnn8、cudnn9这样的标识，这个必须和你要装的框架版本匹配。框架对 cuDNN 主版本是有硬要求的，装错了会在import阶段或者第一次卷积时炸掉，报错信息还不一定直观。查法很简单：去框架官方的安装说明页，看它给出的版本对应表，按表选镜像标签。

还有一个容易被忽略的点：基础镜像的系统版本要和你后续apt install的软件包对得上。比如你打算装 OpenCV 的运行时依赖，得先确认这个系统版本的包名和可用性，别等到构建到一半才发现某个包在这个发行版里已经改名了。

2.3 宿主机侧的前置条件：驱动不进容器，但运行时必须装

这是新手最容易绕晕的地方。NVIDIA 驱动永远装在宿主机上，不装进容器。容器里的 CUDA 是通过宿主机的驱动来跑的，容器镜像里的 CUDA 版本只决定它能用到的 API，实际执行能力由宿主机驱动决定。

宿主机驱动支持的最高 CUDA 版本，直接看nvidia-smi输出右上角那个CUDA Version。这个数字是个上限，容器镜像里的 CUDA 版本不能超过它。举个例子，如果右上角显示的是 12.2，那你能用 12.1、12.0、11.8 的镜像，但用 12.4 的镜像就可能出问题。

除了驱动，宿主机上还需要容器 GPU 运行时组件。没有它，docker run --gpus all会直接报could not select device driver "" with capabilities: [[gpu]]。这个组件装完之后必须重启 Docker 服务才会生效，很多人装完没重启，然后对着同样的报错怀疑人生。

装好之后，用一条最简单的命令验证：

docker run --rm --gpus all <你选的基础镜像> nvidia-smi

能打印出显卡列表，说明宿主机侧通了。这一步不通，后面的所有工作都是白费，所以别急着写 Dockerfile，先花五分钟把这一步走通。

3. 从零写一个能长期用的 Dockerfile

3.1 分层与缓存：把变动频率低的东西放前面

Docker 的构建是按层缓存的，某一层失效，它后面的所有层都要重建。所以写 Dockerfile 的第一原则是：变动频率低的放前面，变动频率高的放后面。

系统包、时区、locale、基础工具这些，一个项目里基本不会变，放最前面。Python 依赖会随项目演进变化，放中间。你自己的项目代码变动最频繁，理论上放最后——但我不建议把代码COPY进镜像，代码应该通过挂载目录进去，镜像只负责环境。这一点后面会展开。

3.2 系统层：时区、locale、源，这些琐碎的东西最影响体验

下面是我常用的系统层写法，你可以直接照着改：

FROM cuda:12.1.1-cudnn8-devel-ubuntu22.04 ARG DEBIAN_FRONTEND=noninteractive ENV TZ=Etc/UTC \ LANG=C.UTF-8 \ LC_ALL=C.UTF-8 \ PYTHONDONTWRITEBYTECODE=1 \ PYTHONUNBUFFERED=1 \ PIP_NO_CACHE_DIR=1 RUN apt-get update && apt-get install -y --no-install-recommends \ build-essential \ git curl wget vim tmux htop unzip ca-certificates \ libgl1 libglib2.0-0 libsm6 libxext6 libxrender1 \ libjpeg-dev zlib1g-dev libpng-dev \ && rm -rf /var/lib/apt/lists/*

FROM那一行，前面要按你所用的镜像仓库补上完整前缀，我这里只保留了标签部分。DEBIAN_FRONTEND=noninteractive是为了让apt install不要弹交互式对话框，否则构建会卡在那里等输入，在 CI 里表现为超时。

PYTHONDONTWRITEBYTECODE=1关掉 pyc 文件生成，在容器这种一次性环境里没什么必要留缓存，还会在挂载目录里留下一堆__pycache__。PYTHONUNBUFFERED=1让 Python 的输出直接打到终端，不然docker logs看到的进度条和日志是断断续续的，训练卡住了你都看不出来。

rm -rf /var/lib/apt/lists/*这一句必须和apt-get install写在同一个RUN里，不能拆成两条。拆开的话，前一层已经把这些文件固化进镜像了，删除只是加了一个“删除标记”，体积一点没省。

关于镜像源：如果你所在网络环境访问默认源比较慢，可以在apt-get update之前改一下源地址。改源的方式依发行版不同，Ubuntu 系可以 sed 替换，Debian 系要处理新的.sources格式。这一步不做也能构建，只是慢，但慢到一定程度会超时失败，所以在大规模构建前建议先解决。

时区这里我填的是 UTC。如果你希望容器内的日志时间是本地时间，就把TZ换成你所在时区的标识，但要注意：训练日志统一用 UTC 是个好习惯，跨机器对比日志时会感谢当初的自己。

3.3 非 root 用户：不建这个，你挂载出来的文件全是 root 的

这是我踩过最烦的一个坑。默认情况下容器里是 root 用户，你把宿主机的目录挂载进去，容器里写出来的文件，在宿主机上看属主是 root。下次你在宿主机上想删它、改它，就得sudo。更麻烦的是，某些编辑器会因为文件属主不对而拒绝保存。

解决办法是在镜像里创建一个和宿主机同 UID/GID 的用户：

ARG UID=1000 ARG GID=1000 RUN groupadd -g ${GID} dev 2>/dev/null || true \ && useradd -m -u ${UID} -g ${GID} -s /bin/bash dev \ && mkdir -p /workspace && chown -R ${UID}:${GID} /workspace USER dev WORKDIR /workspace

ARG允许你在构建时通过--build-arg覆盖。构建时这样传：

docker build \ --build-arg UID=$(id -u) \ --build-arg GID=$(id -g) \ -t dl-base:1.0 .

这样镜像里的用户 UID 和你宿主机上的 UID 一致，挂载目录的权限问题就自然消解了。注意USER dev之后的所有RUN指令都以这个用户身份执行，所以任何需要写系统目录的操作（比如apt install）必须放在USER之前。

3.4 框架层：版本要钉死，别用浮动标签

Python 依赖这一层，核心原则只有一条：所有版本号都钉死，一个都不许浮动。

RUN python -m pip install --upgrade pip setuptools wheel \ && python -m pip install \ torch==2.1.2 torchvision==0.16.2 \ numpy==1.26.4 \ pandas==2.1.4 \ pillow==10.2.0 \ opencv-python-headless==4.9.0.80 \ tensorboard==2.15.1 \ tqdm==4.66.1 \ && python -m pip cache purge

为什么钉死？因为在不钉死的情况下，你今天构建出来的镜像和下周构建出来的镜像，可能装了不同小版本的 numpy，然后某个依赖它的库行为变了，你的实验数据就对不上了。这类问题极难排查，因为它没有任何报错，只是数值上有微小差异。

装框架的 wheel 时要注意 CPU 版和 GPU 版的区别。默认pip install torch装出来的可能是 CPU 版，torch.cuda.is_available()返回False，而你对着nvidia-smi看半天显卡明明在。正确做法是指定框架自己的索引源，或者按官方说明加上对应的版本后缀。装完之后务必验证一次：

python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

三个值分别是框架版本、它编译时用的 CUDA 版本、GPU 是否可用。第三个是True才算过。

opencv这里我特意选的是headless版本。普通的opencv-python会拖进一堆图形界面相关的系统库（libGL、libgtk之类），在服务器上根本用不到，白白让镜像变大、还容易和系统库版本冲突。除非你确实要在容器里弹窗口看图，否则一律用headless。

4. 构建与运行：一次跑通的实操记录

4.1 构建：开启 BuildKit，注意构建上下文

DOCKER_BUILDKIT=1 docker build \ --build-arg UID=$(id -u) \ --build-arg GID=$(id -g) \ -t dl-base:1.0 \ -f Dockerfile .

最后那个.是构建上下文，Docker 会把这个目录下的所有内容打包发给构建引擎。如果你的项目目录里有几十 G 的数据集或者一堆 checkpoint，构建会先花几分钟在这些文件上，非常浪费时间。解决办法是在同目录下放一个.dockerignore：

data/ checkpoints/ logs/ *.pyc __pycache__/ .git/ *.pt *.pth

按需增删。这个文件的意义不只是快，还能避免把敏感文件误打进镜像。

4.2 运行：每个参数都是为了让日常使用少踩坑

下面这条 run 命令，我用了两年多，参数基本没变过：

docker run -it --rm \ --gpus all \ --shm-size=16g \ --ulimit memlock=-1 \ --ulimit stack=67108864 \ -v /data/datasets:/workspace/datasets:ro \ -v /data/exp:/workspace/exp \ -v $HOME/.cache/huggingface:/home/dev/.cache/huggingface \ -p 8888:8888 \ --name dl-dev \ dl-base:1.0 \ bash

逐个拆一下，为什么这么配。

--gpus all把宿主机所有 GPU 都暴露给容器。如果你只想给容器用两张卡，可以写--gpus '"device=0,1"'。这个参数的原理是把宿主机的设备节点和驱动库挂进容器，所以容器内的 CUDA 版本必须和宿主机驱动兼容——这就是上一节反复强调版本对齐的原因。

--shm-size=16g是最容易被忽视、但几乎一定会踩到的参数。Docker 默认给容器的共享内存只有 64MB。当你用 DataLoader 开多个 worker 加载数据时，worker 之间通过共享内存传张量，64MB 瞬间爆掉，容器直接挂掉，报错通常是Bus error (core dumped)或者RuntimeError: DataLoader worker (pid xxx) is killed by signal: Bus error。这个报错极具迷惑性，因为它看起来像是数据有问题或者内存不够，实际只是共享内存太小。16g 对大多数场景够用，卡多、batch 大的可以再往上调。

--ulimit memlock=-1解除内存锁定限制。某些通信库在初始化时会锁定一大块内存做缓冲，锁不住就会报RuntimeError: unable to write to file </torch_xxx>或者直接初始化失败。--ulimit stack=67108864把栈大小提到 64MB，避免深层递归或者某些算子在编译期栈溢出。

-v挂载：数据集目录我只给了只读权限（:ro），这是个保险措施，防止训练脚本写错路径把原始数据覆盖掉。实验输出目录给读写。第三行是把宿主机上的模型缓存目录挂进去，这样每次重建容器时不需要重新下载预训练权重——这一条能省下大量时间和流量，强烈建议加上。

-p 8888:8888用于 Jupyter。--rm让容器退出后自动删除，避免攒一堆死容器。但要注意：--rm只删容器，不删镜像，也不删你挂载出去的目录。反过来，如果你把所有东西都放在容器内部不挂载，--rm一执行，数据就真没了。

4.3 GPU 到底进去了没有：三重校验

不要凭感觉，按顺序跑三条命令。

第一条，在容器内执行nvidia-smi。能看到显卡列表和显存占用，说明容器运行时和驱动对接正常。

第二条，echo $CUDA_VERSION或者nvcc --version。nvcc只有在devel镜像里才有，能用它说明工具链完整。容器内 CUDA 版本和宿主机nvidia-smi右上角那个版本之间的关系，就是上一节说的“不超过上限”。

第三条，进 Python 验框架：

python -c " import torch print('torch:', torch.__version__) print('built with cuda:', torch.version.cuda) print('available:', torch.cuda.is_available()) print('count:', torch.cuda.device_count()) print('name:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'N/A') "

available是False，八成是装了 CPU 版 wheel。count是 0，八成是--gpus没传对。name不对，说明设备映射有问题。这三种情况的处理方式完全不同，所以要把它们分开打印，别只打一个is_available()。

4.4 第一次跑训练：用最小脚本验证整条链路

环境验证通过不等于训练能跑。第一次进容器，我习惯跑一个极小的脚本，把数据加载、前向、反向、显存分配全走一遍：

import torch import torch.nn as nn from torch.utils.data import DataLoader, TensorDataset dev = "cuda" model = nn.Sequential( nn.Linear(512, 1024), nn.ReLU(), nn.Linear(1024, 10) ).to(dev) x = torch.randn(4096, 512) y = torch.randint(0, 10, (4096,)) loader = DataLoader(TensorDataset(x, y), batch_size=128, num_workers=8, pin_memory=True) opt = torch.optim.Adam(model.parameters(), lr=1e-3) lossf = nn.CrossEntropyLoss() for epoch in range(2): for bx, by in loader: bx, by = bx.to(dev), by.to(dev) loss = lossf(model(bx), by) opt.zero_grad(); loss.backward(); opt.step() print(f"epoch {epoch} loss {loss.item():.4f}") print("peak mem:", torch.cuda.max_memory_allocated() / 1024**2, "MB")

这个脚本的价值在于：num_workers=8会真实地触发多进程数据加载，正好检验共享内存够不够；pin_memory=True检验锁页内存是否正常；to(dev)检验设备拷贝链路；最后打印峰值显存，给你一个后续调 batch size 的基准。如果这个脚本能跑完，说明环境基本没有硬伤。

5. 日常使用里的效率配套

5.1 交互式开发：把 Jupyter 跑在容器里

命令行调试适合排查，但日常写代码还是交互式环境舒服。在容器里起一个 Jupyter：

jupyter lab --ip=0.0.0.0 --port=8888 --no-browser \ --NotebookApp.token='<自己设一个>' \ --notebook-dir=/workspace

--ip=0.0.0.0是必须的，默认只监听本地回环，容器外访问不到。--no-browser防止它在无图形界面的环境里尝试打开浏览器。token 一定要自己设，别用默认的空 token，尤其是这台机器在网络里能被别人访问的时候。

启动之后宿主机浏览器访问http://<宿主机IP>:8888，配合-p 8888:8888就能连上。如果你通过跳板机访问，用 SSH 端口转发比直接暴露端口更稳妥。

这里有一个细节：Jupyter 的内核进程和你在终端里python跑的是两个进程，环境变量可能不一致。如果你在终端里设了CUDA_VISIBLE_DEVICES，Jupyter 里不一定会继承。要么在启动 Jupyter 前设好，要么在 notebook 里用os.environ显式指定，别指望它自动同步。

5.2 数据挂载的路径约定与读写性能

挂载路径我建议在镜像里就固定下来，形成约定：/workspace/datasets放数据，/workspace/exp放实验输出，/workspace/code放代码。这样不管换成谁的机器、换多少个项目，进容器之后第一件事cd /workspace，路径永远是同样的，脚本里的相对路径也不用改。

关于读写性能，有个容易忽略的点：挂载目录的 IO 走的是宿主机的文件系统，容器本身没有额外开销，但如果宿主机那块盘是网络盘或者机械盘，读小文件会非常慢。深度学习的数据集往往是小文件海量（几万张图片一个目录），这种场景下，网络盘上的随机读性能可能比本地 SSD 差一个数量级。我的做法是把数据集放在本地 SSD 上，容器只挂载，不做拷贝。

如果数据集实在太大放不下本地盘，可以考虑先打包成几个大的归档文件再读，顺序读的吞吐比小文件随机读高得多。这个优化跟 Docker 没关系，但配合容器化部署时经常要一起考虑。

5.3 镜像瘦身与离线分发

本地构建好的镜像，要搬到另一台机器上。最直接的办法是推到镜像仓库再拉，但如果目标机器不通外网，就得用导出导入：

docker save dl-base:1.0 -o dl-base-1.0.tar # 传输到目标机器 docker load -i dl-base-1.0.tar

docker save会把所有层打包，包括基础镜像那几 G，最终 tar 包可能十几 G。传输前先压缩一下，能省不少时间：

docker save dl-base:1.0 | gzip > dl-base-1.0.tar.gz

瘦身的几个实操手段：一，所有apt操作和rm -rf /var/lib/apt/lists/*写在同一个RUN里；二，pip 加--no-cache-dir（我在ENV里全局设了PIP_NO_CACHE_DIR=1），并在装完后pip cache purge；三，不要在镜像里COPY数据、日志、checkpoint；四，能用headless版本的库就用headless；五，多阶段构建——如果你要编译某个 C++ 扩展，用一个大镜像编译，再把产物COPY到最终的小镜像里。

提醒一句：镜像瘦身不要在项目初期做。先把环境跑通、功能跑全，等稳定了再花时间优化体积。反过来做的话，你会陷入“这个包能不能删”的反复试错，非常低效。

6. 踩坑实录：报错速查与几条不写在文档里的经验

6.1 常见报错速查表

6.2 几个不写在文档里的经验

第一条：把环境拆成“基础镜像”和“项目镜像”两层。基础镜像只装系统依赖、CUDA、Python、常用库，一年半载才更新一次。项目镜像FROM基础镜像，只装这个项目特有的几个包。这样九成的构建都是秒级完成，因为你只重跑最后那一层。我见过太多人一个 Dockerfile 从头写到尾，改一行依赖就要等二十分钟。

第二条：不要在容器里装杀毒软件或者做任何需要内核权限的事。容器的隔离是操作系统层面的，内核是共享的。任何试图改动内核参数、加载内核模块的操作都会失败或者影响宿主机。这不是配置问题，是设计如此。

第三条：日志目录一定要挂出来。训练跑崩了之后，容器--rm自动删除，日志跟着没了，你连崩溃原因都看不到。哪怕只挂一个logs/目录，也比什么都没有强。

第四条：定期清理。镜像和悬空容器攒多了很占地方，docker image prune和docker container prune可以清，但清之前确认没有依赖它们的容器在跑。我自己是每次重建镜像后顺手docker image prune -f，时间长了能省出几十 G。

第五条：docker exec进去的 shell 和容器主进程的环境变量可能不同。排查问题时，如果你在主进程里看到的现象和 exec 进去看到的不一致，先env | grep CUDA对比一下，别急着怀疑代码。这个坑我遇到过两次，都是因为主进程启动时带了环境变量文件而 exec 进去是干净的登录 shell。

第六条：版本信息写进镜像标签，别偷懒用latest。镜像标签里带上驱动支持情况、框架版本、构建日期，比如dl-base:torch2.1.2-cu121-202406。三个月后你回头找“当时跑出那个结果的镜像”，一眼就能定位。用latest的话，你永远不知道自己当初用的是哪个。

第七条：第一次搭建别追求完美。先用最省事的方式跑通一个能训练的最小环境，把流程走顺，再回头优化体积、加工具、拆分层。我最初那版 Dockerfile 有四十多行，现在精简到十几行还更好用，但那是在用了半年、知道哪些东西真正常用之后才有的结论。上来就按“最佳实践”设计，大概率会设计出一堆自己用不上的东西。

这套东西跑顺之后，你换机器、换团队、换项目的时候会非常轻松：git clone代码，docker build或者直接拉现成镜像，一条run命令进去，五分钟内就能开始调试。省下来的那些重复劳动时间，攒起来足够多跑几组实验了。