✨零基础手把手｜Docker+vLLM极速部署OpenAI风格API：5分钟4卡GPU推理+避坑指南+完整镜像配置

一、Docker 基础命令

1. 查看容器状态

Bash docker ps        # 查看运行中的容器 docker ps -a     # 查看所有容器（包括已停止的）

1. 查看镜像列表

Bash docker images    # 列出本地所有镜像

二、镜像与容器操作

1. 镜像打包为 .tar 文件

Bash docker save -o   # 将镜像导出为 .tar 文件 # 示例： docker save -o my_image.tar vllm/vllm-openai:v0.8.4

打包多个镜像到一个文件

Bash docker save -o multiple_images.tar image1:tag image2:tag

1. 从容器创建镜像

Bash docker commit   # 将容器保存为镜像

1. 加载 .tar 镜像文件

Bash docker load -i    # 从 .tar 文件加载镜像

1. 修改镜像名和版本

Bash docker tag <原镜像名>:<原标签> <新镜像名>:<新标签>

1. 删除旧镜像

Bash docker rmi <原镜像名>:<原标签>

三、docker run 命令详解

示例命令拆解：

Bash docker run -d \   --runtime nvidia \   --gpus '"device=4,5,6,7"' \   -v /data02/YangXian/models/Qwen/Qwen3-30B-A3B:/workspace/models \   -v /data02/log:/var/log/vllm \   -p 8002:8000 \   --ipc=host \   --name vllm2 \   vllm/vllm-openai:v0.8.4 \   --model /workspace/models \   --max-num-batched-tokens 131072 \   --tensor-parallel-size 4 \   --enable-auto-tool-choice \   --tool-call-parser hermes \   --api-key vllm \   --served-model-name Qwen3-30B-A3B

参数解释：

• -d: 后台运行容器（detached 模式）

• --runtime nvidia: 使用 NVIDIA 容器运行时（依赖 GPU）

• --gpus: 指定 GPU 设备（"device=4,5,6,7" 使用 4,5,6,7 号 GPU）

• -v :: 挂载主机目录到容器（数据持久化）

• -p :: 端口映射（主机 8002 → 容器 8000）

• --ipc=host: 共享主机 IPC 命名空间（提升多进程性能）

• --name : 指定容器名称

• 镜像名后参数为容器内服务启动参数（如模型路径、并行配置等）

四、Dockerfile 制作

1. 基础模板示例：

Dockerfile FROM ubuntu:22.04        # 基础镜像 WORKDIR /app             # 容器工作目录 COPY . .                 # 复制本地文件到容器 RUN apt update && \      # 安装依赖     apt install -y python3 CMD ["python3", "app.py"] # 启动命令

1. 构建镜像：

Bash docker build -t .  # 根据 Dockerfile 构建镜像

五、清理缓存与资源

1. 清理未使用的资源

Bash docker system prune          # 删除停止的容器、未使用的镜像和网络 docker system prune -a       # 删除所有未使用的镜像（包括悬空镜像） docker volume prune          # 清理未使用的卷

1. 清理指定镜像/容器

Bash docker rmi         # 删除镜像 docker rm      # 删除容器

六、切换 Docker 存储路径

1. 修改 Docker 数据目录

Bash # 1. 停止 Docker 服务 systemctl stop docker # 2. 修改配置文件（如 /etc/docker/daemon.json） {   "data-root": "/new/path/docker" } # 3. 迁移数据（可选） rsync -aP /var/lib/docker/ /new/path/docker # 4. 重启 Docker systemctl start docker

七、dockercompose

以下是基于 docker run 命令编写的 docker-compose.yml文件，并附带详细注释和操作说明：

docker-compose.yml

YAML version: '3.8'  # 要求 Docker Compose 版本 ≥ 1.27.0 services:   vllm-service:   # 服务名称（自定义）     runtime: nvidia  # 使用 NVIDIA 容器运行时（需提前安装 NVIDIA Container Toolkit）     deploy:       resources:         reservations:           devices:             - driver: nvidia               device_ids: ['4', '5', '6', '7']  # 指定 GPU 设备号               capabilities: [gpu]     image: vllm/vllm-openai:v0.8.4  # 基础镜像     container_name: vllm2  # 容器名称     ipc: host  # 共享主机 IPC 命名空间     ports:       - "8002:8000"  # 端口映射（主机端口:容器端口）     volumes:       - /data02/YangXian/models/Qwen/Qwen3-30B-A3B:/workspace/models  # 挂载模型目录       - /data02/log:/var/log/vllm  # 挂载日志目录     command:  # 覆盖镜像默认的启动参数       - --model       - /workspace/models       - --max-num-batched-tokens       - "131072"       - --tensor-parallel-size       - "4"       - --enable-auto-tool-choice       - --tool-call-parser       - hermes       - --api-key       - vllm       - --served-model-name       - Qwen3-30B-A3B     restart: unless-stopped  # 容器异常退出时自动重启

操作步骤

1. 创建 docker-compose.yml 文件将上述内容保存为 docker-compose.yml。

1. 启动服务 

Bash docker-compose up -d  # 后台启动容器

1. 查看服务状态 

Bash docker-compose logs -f  # 实时查看日志 docker-compose ps       # 查看容器状态

1. 停止服务 

Bash docker-compose down     # 停止并删除容器

关键配置说明

1. GPU 支持 

• runtime: nvidia 和 deploy.resources 确保容器可以使用 GPU。 

• 需提前在主机安装 NVIDIA Container Toolkit。

1. 卷挂载 (volumes)

• 模型目录和日志目录通过卷映射到容器内，确保数据持久化。

1. 端口映射 (ports)

• 主机的 8002 端口映射到容器的 8000 端口，通过 http://主机IP:8002 访问服务。

1. 启动参数 (command)

• 覆盖镜像默认的 CMD 参数，直接传递模型配置和性能参数。

扩展优化（可选）

1. 环境变量管理

将敏感参数（如 API Key）通过环境变量注入： 

YAML environment:   - API_KEY=vllm  # 定义环境变量 command:   - --api-key   - $${API_KEY}   # 使用环境变量（注意 Compose 变量转义）

2. 多服务扩展

若需同时启动多个服务（如数据库+模型服务）： 

YAML services:   vllm-service:     # ... 原配置 ...   redis:  # 添加 Redis 服务     image: redis:alpine     ports:       - "6379:6379"

3. 一键启动脚本

创建 start.sh： 

Bash #!/bin/bash docker-compose up -d && docker-compose logs -f

赋予执行权限： 

Bash chmod +x start.sh ./start.sh

常见问题

1. GPU 无法识别 

• 检查 NVIDIA 驱动和容器工具包是否安装：nvidia-smi 和 nvidia-container-cli --version。 

• 确保 Docker Compose 版本 ≥ 1.27.0。

1. 端口冲突 

• 若主机 8002 端口被占用，修改 ports 中的左侧端口（如 "8003:8000"）。

1. 模型路径错误 

• 确认主机目录 /data02/YangXian/models/Qwen/Qwen3-30B-A3B 存在且有权访问。
   

~~注意啦！！~~ 
一键三连关注，解锁AI开发宝库！
✨ 我是谁？

23岁·双非逆袭｜大模型应用开发工程师
AI干货：大模型部署/调优/落地实战
职场升级：简历优化+面试技巧+成长思维

关注福利
1️⃣ 《LLM工程化落地指南》（周更中）
2️⃣ 《Docker+VLLM炼丹手册》源码合集
3️⃣ 大模型岗位内推群（24届25界可投）

本周更新

专栏：《vLLM生产级部署避坑大全》
限免：30B模型推理优化代码包（评论区扣“LLM”领取）

想看我拆解哪个技术难点？
留言区见！ 高频问题将纳入下周直播专题