企业官网建设流程全解析

把推理服务封装进 Docker，这件事听起来很简单，但真正跑起来会发现每一步都有讲究。我最初是在一台装好 CUDA 和 PyTorch 的服务器上直接部署，后来要换机器、换卡、给同事复现环境，才发现裸机方案根本撑不住，于是老老实实走了一遍“Docker 封装 GPU 推理环境”的完整流程。这篇文章不讲虚的，直接从镜像构建到服务运行，把基础镜像选型、Dockerfile 细节、启动参数和排障经验一次说清，适合正在用 Docker 跑 GPU 推理服务的算法工程师、运维和想入门的后端同学。

1. 为什么用 Docker 封装 GPU 推理环境？先想清楚再动手

我一直觉得，Docker 化的第一步不是写 Dockerfile，而是搞清楚它到底解决了什么问题、引入了哪些新限制。很多教程上来就抄命令，结果遇到几个版本不匹配就懵了。这里先聊聊我在裸机环境踩过的坑，以及为什么最终选择了 Docker 这条链路。

1.1 裸机装推理环境的日常崩溃现场

之前团队拿到一台新服务器，显卡是 A100，驱动装好之后，我花了一天时间部署 PyTorch 推理服务。听起来不算难，但真实情况是：系统自带的 Python 版本不对，conda 环境里 CUDA 版本和 PyTorch 的编译版不匹配，cudnn 装的时候没注意目录、链接库找不到，等终于跑起来，发现 nvidia-smi 显示的驱动版本和 CUDA 版本要求又差了一点。这些事单挑出来都不算致命，但组合在一起就非常耽误时间。

更麻烦的是环境复现。配置好的 conda 环境要导出 yaml，可同事在自己的机器上装的时候，依然会遇到各种莫名其妙的库冲突。换一张卡、换一个 Ubuntu 版本，之前能跑的程序可能就起不来了。后来我意识到，推理服务本质上是一个“运行包”，它依赖的 CUDA 库、Python 库、模型结构、预处理逻辑都应当打包在一起，而不是散落在宿主机里。

Docker 最大的价值，就是把这些依赖全部固化成镜像。镜像在 A 机器上验证过，推到仓库后再拉到 B 机器，理论上行为是一致的，这比“你重装一下试试”要靠谱得多。

1.2 Docker 在 GPU 场景下的具体收益

除了环境一致，Docker 在 GPU 推理场景里还有几个实际好处：

• 资源控制更清晰。通过 --gpus 参数或 NVIDIA_VISIBLE_DEVICES 环境变量，可以精确指定容器用哪张卡，避免多个服务互相抢占显存。这在配了多卡、多服务的服务器上非常关键。
• 服务生命周期被纳管。容器挂了可以自动重启，日志可以被 docker logs 统一收集，比裸机下用 systemd 管理 Python 进程要直观得多。
• 模型权重和代码解耦。镜像里只放代码和依赖库，模型权重通过卷挂载进去。这样镜像体积小、推送快，权重更新也不用重新构建整个镜像，直接换挂载目录就行。

1.3 从镜像构建到服务运行的完整链路

我把整套方案拆成四个环节：基础镜像选型、依赖安装与 Dockerfile 编写、GPU 运行时接入、服务启动与验证。思路是先把镜像做小、做稳，再用正确的 runtime 参数把 GPU 能力暴露给容器，最后通过健康检查确认服务真的在用 GPU 而不是 CPU 跑。这个链路每一环都有对应的坑，下面逐步展开。

2. 镜像构建：从底层镜像到可用的推理镜像

镜像构建是整个流程里最需要耐心的一步。很多人图省事直接拿一个装了 PyTorch 的大镜像当底，结果镜像体积动辄几个 GB，构建和拉取都很痛苦。更合理的思路是：选一个小而全的官方基础镜像，再按需安装依赖。

2.1 基础镜像怎么选：base、runtime、devel 的区别

NVIDIA 官方在 Docker Hub 上提供了 nvidia/cuda 系列镜像，标签里的 flavor 部分通常有三种：base、runtime、devel。我第一次用的时候选了 devel，觉得“开发版肯定功能全”，结果镜像体积直接给我干到 5GB 多，推送到内部仓库等了半天。后来才明白，base 只包含 CUDA 运行所需的最底层库，runtime 增加了运行 CUDA 应用的用户态库（比如 libcudart、libcublas），devel 则额外包含编译器、头文件和调试工具，体积大很多。

对于 pytorch 这类已经预编译好的推理框架，runtime 足够用了。因为 pip 安装的 torch、tensorflow 库里已经带了自己需要的 CUDA 运行库，镜像只需要提供一个干净的、与宿主驱动兼容的运行环境即可。如果你还要编译扩展或调试底层代码，才需要切换到 devel 或者其他带完整工具链的基础镜像。

标签里的 Ubuntu 版本和 CUDA 版本也要对齐。我习惯用 nvidia/cuda:12.1.1-runtime-ubuntu22.04 这种明确写法的镜像，而不是用 latest，因为 latest 可能随着官方更新变化，导致后面的依赖失效。当前推理框架对 CUDA 的适配情况可以通过官方安装文档确认，例如 PyTorch 2.1 这一代主要支持 CUDA 12.1，那么我选的镜像 CUDA 版本就以 12.1 或 12.4 为主，避免版本漂移。

2.2 Dockerfile 的核心写法与依赖安装

基础镜像定好之后，Dockerfile 的编写有几个实用技巧。依赖文件尽量单独复制到镜像里，利用 Docker 的层缓存机制，这样在代码频繁修改但依赖不变时，不会每次都重新安装依赖包。我把这套做法整理成一个精简示例：

FROM nvidia/cuda:12.1.1-runtime-ubuntu22.04 ENV DEBIAN_FRONTEND=noninteractive \ PYTHONUNBUFFERED=1 RUN apt-get update && apt-get install -y --no-install-recommends \ python3.10 python3-pip \ && ln -s /usr/bin/python3 /usr/bin/python \ && rm -rf /var/lib/apt/lists/* WORKDIR /app COPY requirements.txt . RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple && \ pip install --upgrade pip && \ pip install -r requirements.txt COPY app/ ./app/ EXPOSE 8080 CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

这里有几个细节值得展开说。

apt-get 安装时必须加上 --no-install-recommends，避免把一堆用不到的推荐包装进来，同时记得清理 /var/lib/apt/lists，这一步能有效压缩镜像体积。pip 的 index-url 我做了统一指向，避免在构建过程中因为默认源不稳定导致反复重试。如果你在纯内网环境，还可以把 index-url 指向公司私有镜像源。

requirements.txt 里要特别注意 torch 的安装。直接 pip install torch 很容易装成 CPU 版本，因为 PyPI 上的默认包多数是 CPU 版。更稳妥的做法是显式指定官方源：

pip install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu121

如果网络受限，也可以先把 wheel 下载到本地，再用 COPY 放进镜像安装。这样构建过程更可控，适合有严格离线要求的环境。

2.3 模型权重和配置不进镜像

很多新手会把模型权重直接 COPY 进镜像，我建议尽量别这么做。一个场景是权重文件特别大，动辄几个 GB，会导致镜像体积膨胀到很难推送；另一个场景是权重需要频繁更新，如果每次更新都重新构建镜像，流程会非常繁琐。

我的做法是：镜像只包含代码、依赖和默认配置，模型权重通过数据卷或宿主机目录挂载进去。运行命令里加一个 -v /data/models:/models:ro，容器内代码从 /models 目录下读取权重。这样做既能保持镜像轻量，又能在不重新构建镜像的情况下快速切换不同模型版本，对算法迭代和灰度验证都很友好。

如果你从安全的内部仓库拉取模型权重，也可以把下载逻辑放到容器启动阶段，作为 entrypoint 脚本的一部分。这样模型文件不需要跟随镜像分发，只要目标机器能访问模型仓库即可。

3. 服务运行：把 GPU 能力真的暴露给容器

镜像构建好只是第一步，真正跑起来的时候，最大的问题往往出现在 GPU 访问上。这个环节依赖宿主机驱动、容器运行时和启动参数三者的配合，少一个都会导致容器内看不到显卡。

3.1 容器访问 GPU 的底层依赖

容器的本质是隔离的进程，默认情况下它看不到宿主机的 PCIe 设备、GPU 驱动接口和显存信息。要让容器访问 GPU，需要宿主机安装 NVIDIA 驱动，并安装 NVIDIA Container Toolkit（旧版叫 nvidia-docker2）。它会在启动容器时自动把 GPU 设备节点、驱动库文件注入容器。

这个机制很关键：镜像里的 CUDA 只是运行库，不包含内核驱动；真正干活的是宿主机驱动。所以容器里的 PyTorch 是否能跑 GPU，本质上是看宿主机驱动是否支持镜像要求的 CUDA 版本。如果宿主驱动太老，容器内会报类似 “CUDA driver version is insufficient for CUDA runtime version” 的错误。

我检查这套依赖是否就绪，通常先用这几个命令快速确认：

# 宿主机能否看到 GPU nvidia-smi # container toolkit 是否安装 nvidia-container-toolkit --version # 查看 docker runtime 是否已注册 docker info | grep -i runtime

如果 runtime 里没有 nvidia，说明 toolkit 还没配置好。安装并重启 Docker 服务后，docker info 里就能看到 nvidia runtime，接下来才能正常用 --gpus 参数。

3.2 启动命令逐参数拆解

服务启动命令看起来只有一行，每个参数背后都对应一个可能踩坑的点。我常用的是这个形式：

docker run -d \ --name gpu-infer-01 \ --restart unless-stopped \ --gpus all \ --shm-size=16g \ -p 8080:8080 \ -e NVIDIA_VISIBLE_DEVICES=0 \ -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \ -v /data/models:/models:ro \ myteam/gpu-infer:0.1.0

各参数我在表格里梳理一下：

这里重点讲一下 --shm-size。很多人在 GPU 推理容器里会遇到莫名其妙的崩，比如 DataLoader 多进程加载数据时报 shared memory 不足，或者 PyTorch 在加载大模型时出现 “Bus error”。原因就是 Docker 默认给容器的 /dev/shm 只有 64MB，而 PyTorch 的 DataLoader 多进程、CUDA IPC 之类的操作依赖共享内存。把它调成 16g 或者更高，能避开很多诡异的崩溃。

另一个容易忽略的是容器内服务监听地址。即使你写了 -p 8080:8080，如果 uvicorn 启动时绑定的是 127.0.0.1，外部请求还是访问不到服务。我习惯在 Dockerfile 的 CMD 或启动脚本里显式写成 --host 0.0.0.0，让服务监听容器内所有网卡地址。

3.3 用 Compose 管理逻辑和环境变量

如果服务不止一个，或者启动参数太长，直接用 docker run 维护起来比较痛苦。我一般在多服务协作时会改用 docker compose，配置更清晰，也方便统一管理网络、挂载和环境变量。

services: inference: image: myteam/gpu-infer:0.1.0 container_name: gpu-infer-01 restart: unless-stopped ports: - "8080:8080" gpus: all shm_size: 16g environment: - NVIDIA_VISIBLE_DEVICES=0 - NVIDIA_DRIVER_CAPABILITIES=compute,utility volumes: - /data/models:/models:ro

新版 docker compose 的 gpus 字段可以直接使用，不用再依赖旧的 runtime: nvidia 写法。如果你是老版本，也可以写成 runtime: nvidia，但迁移到新版本后建议统一改用 gpus。这个文件提交到 Git 仓库里，团队其他人拉到项目后，只要机器上有正确的驱动和 toolkit，一条 docker compose up -d 就能复现同样环境。

3.4 从镜像到服务运行的验证流程

服务启动后不要急着压测，先做一轮基础验证。我会按顺序看三个东西。

先看容器状态和日志，确认没有启动即退：

docker ps -a | grep gpu-infer-01 docker logs --tail 50 gpu-infer-01

再看容器内 GPU 是否真的可见：

docker exec gpu-infer-01 nvidia-smi

最后用 curl 打健康检查接口，确认服务对外的响应是正常的：

curl http://127.0.0.1:8080/healthz

我给 FastAPI 服务写健康检查接口时，会刻意把 CUDA 是否可用作为一个字段返回，这样一眼就能看清服务是不是真的跑在 GPU 上。接口大概长这样：

import torch from fastapi import FastAPI app = FastAPI() @app.get("/healthz") def health(): return { "status": "ok", "cuda_available": torch.cuda.is_available(), "device_name": torch.cuda.get_device_name(0) if torch.cuda.is_available() else None, }

如果 cuda_available 返回 false，说明容器根本没拿到 GPU，这时候别再往上层应用查了，先回去检查宿主机驱动和 runtime 配置。

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

再顺的流程，也难免翻车。这一节我把部署过程中最容易遇到的问题整理成排查实录，每条都是我在实际环境中遇到过或者被同事问过的。照着这个思路排查，能少走不少弯路。

4.1 Docker Desktop 虚拟化相关报错

Windows 上使用 Docker Desktop 跑 GPU 容器时，最常见的一条报错是 “virtualisation support wasn‘t detected” 或类似提示。这通常意味着系统的 CPU 虚拟化没开启，或者 Windows 的虚拟化相关功能缺了一半。

排查动作一般是：先确认 BIOS 里 Intel VT-x 或 AMD-V 已开启，再检查 Windows 的“启用或关闭 Windows 功能”，确保“虚拟机平台”和“适用于 Linux 的 Windows 子系统”都被勾选。如果之前安装过 VMware、VirtualBox 等虚拟化软件，也可能相互冲突，需要停用或调整 Hypervisor 相关设置。

我的个人体验是，如果只是在 Windows 上做开发验证，可以直接使用 WSL2 里的 Linux 环境安装 Docker Engine，性能损耗和问题卡点都比 Docker Desktop 少。特别是 GPU 透传场景，WSL2 对 NVIDIA GPU 的支持相对成熟，不容易遇到 Desktop 和 WSL2 后端之间互相干扰的怪问题。

4.2 容器内看不到 GPU 或报驱动版本不足

宿主机能跑 nvidia-smi，但容器内一跑就提示找不到显卡，或执行 nvidia-smi 直接报错。这种问题九成出在 NVIDIA Container Toolkit 没装好，或者没有重启 Docker 服务。还有一个隐蔽的小点，就是启动容器时忘了加 --gpus 或不带 runtime 参数。

驱动版本不够的情况也很常见。镜像里 PyTorch 是 CUDA 12.1 编译的，宿主驱动只支持到 CUDA 11.4，那么容器内跑 GPU 就会报 “CUDA driver version is insufficient”。这个是版本兼容问题，跟镜像重装多少次无关，只能升级宿主机 NVIDIA 驱动，或者降低镜像内 CUDA 版本，让两者重新匹配。我后来开始使用固定的驱动版本配基础镜像，并把对应关系写进团队的 README，问题大幅减少。

4.3 驱动错误代码 43 与新卡不兼容类问题

Windows 下驱动报“Windows 已停止此设备，因为它报告了问题（代码 43）”，通常和驱动不匹配、供电不足、显卡过热或主板 BIOS 设置有关。遇到代码 43，我会先用 DDU 这类工具把旧驱动彻底清理干净，再重新安装合适版本的官方驱动。排除软件问题后，再考虑物理链路，比如重插显卡、更换供电线。这类问题是硬件层问题居多，容器配置改变不了。

另一个和硬件强相关的坑是新一代显卡的架构兼容问题。比如某些新卡的计算能力是 sm_120 这种较新的架构，旧版 PyTorch 或旧版 CUDA 镜像可能直接报不兼容，提示 “is not compatible” 之类的错误。解决办法是把基础镜像升级到支持该架构的 CUDA 版本，同时把 PyTorch 升级到对应支持新架构的版本，或者干脆换用官方已适配的新版推理镜像。不要试图硬改配置文件跳过检查，那会让运行时行为变得不可预测。

4.4 Docker 网络不通与外网访问问题

容器跑起来了，但宿主机 curl 不通端口，或者另一个服务访问它一直超时。这里先看端口映射有没有生效，docker ps 里能看到 0.0.0.0:8080->8080/tcp 这样的内容，说明端口映射已经建立；然后进容器验证服务本身是否在监听 0.0.0.0。如果容器里用 127.0.0.1 绑定服务，外部端口映射能通才怪。

跨容器通信时，我通常用 docker compose 里定义的 service 名，而不是写死容器 IP。容器 IP 会变，service 名在 compose 网络里是稳定的 DNS 名称。如果容器之间 ping 不通，先确认它们是不是在同一个 docker network 里；不同网络即使端口相同也互不可见。

4.5 问题排查速查表

顺手列一个速查表，遇到问题直接按表索骥。

最后分享一个我自己跑这套环境时的习惯：先不急着上服务，第一个镜像直接用基础镜像加一句 CMD ["nvidia-smi"]，跑通“容器内能看到 GPU”这一步，再往上加 Python 和推理代码。这样分层验证的好处是，出问题时能快速定位是运行时问题还是应用代码问题。等整套链路稳定了，后续换卡、换机器、加新模型，基本都是复制粘贴的活了。把这条路走通一次，后面就再也没有为环境问题熬过夜。