Docker Compose结合Nginx实现PyTorch-CUDA服务前端访问

Docker Compose结合Nginx实现PyTorch-CUDA服务前端访问

在AI模型从实验室走向生产环境的过程中，一个常见的难题浮现出来：如何让团队成员方便、安全地访问运行在GPU服务器上的Jupyter Notebook或模型API？更进一步，能否在不牺牲性能的前提下，确保开发、测试与部署环境的一致性？

这个问题在中小团队和边缘计算场景中尤为突出。我们曾见过不少项目因“在我机器上能跑”而卡壳——依赖版本冲突、CUDA驱动不兼容、端口暴露带来的安全隐患……每一个都足以拖慢整个迭代节奏。

而今天这套基于Docker Compose + Nginx + PyTorch-CUDA的轻量级架构，正是为解决这些痛点而生。它不是追求极致高可用的Kubernetes方案，而是专注于“快速验证+稳定访问”的实用主义路线。

设想这样一个场景：你有一台带NVIDIA显卡的服务器（比如RTX 4090或A100），想把它变成一个共享的AI实验平台。多位研究人员需要通过浏览器直接编写代码、训练模型，并实时查看结果。同时你还希望：

• 不用每次重装系统就重新配置环境；
• 多人协作时不会互相干扰；
• 能通过标准HTTP协议访问，避免开放高危端口；
• 充分利用GPU算力，支持分布式训练。

这正是我们要构建的系统。它的核心思路非常清晰：用容器封装环境，用编排管理服务，用代理统一入口。

首先来看最底层的执行单元——PyTorch-CUDA镜像。如果你还在手动安装torch==2.8并折腾cuDNN版本匹配，那真的可以停下来了。官方提供的pytorch/pytorch:2.8-cuda11.8-devel镜像已经为你打包好一切：Python环境、PyTorch主库、torchvision、Jupyter、甚至包括NCCL多卡通信支持。更重要的是，它经过了官方验证，不存在“理论上应该能跑”的尴尬。

这个镜像之所以能在容器内调用宿主机GPU，关键在于NVIDIA Container Toolkit。当Docker启动容器时，如果指定了GPU资源，runtime会自动将主机的CUDA驱动库（如libcuda.so）挂载进容器。这意味着容器内的PyTorch可以直接通过CUDA Runtime API操作GPU，完全无需在容器里安装显卡驱动——既节省空间，又避免了版本错乱。

举个实际例子，当你运行：

docker run --gpus all pytorch/pytorch:2.8-cuda11.8-devel nvidia-smi

你会看到熟悉的nvidia-smi输出，显示当前可用的GPU设备。这就是透明化GPU访问的魅力所在。

但单个容器只是起点。真正的工程价值体现在服务编排上。Docker Compose的作用，就是把多个松散的服务组织成一个协同工作的整体。在这个方案中，我们需要两个核心服务：一个是承载计算任务的PyTorch容器，另一个是负责流量调度的Nginx网关。

来看docker-compose.yml的关键设计：

version: '3.8' services: pytorch-service: image: pytorch/pytorch:2.8-cuda11.8-devel container_name: pytorch_cuda_container runtime: nvidia environment: - NVIDIA_VISIBLE_DEVICES=all ports: - "8888:8888" volumes: - ./notebooks:/workspace/notebooks command: > bash -c " jupyter notebook --ip=0.0.0.0 --port=8888 --no-browser --allow-root --NotebookApp.token='' " nginx: image: nginx:alpine container_name: nginx_gateway ports: - "80:80" depends_on: - pytorch-service volumes: - ./nginx.conf:/etc/nginx/nginx.conf networks: - app-network networks: app-network: driver: bridge

这里有几个值得注意的细节：

• runtime: nvidia是启用GPU支持的传统方式。虽然新版本推荐使用deploy.resources，但在多数现有环境中仍广泛兼容。
• Jupyter启用了无token模式（--NotebookApp.token=''），仅建议用于内网可信环境。生产部署务必配合密码或OAuth认证。
• 两个服务通过自定义桥接网络app-network连接，使得Nginx可以通过服务名pytorch-service直接解析到后端容器IP，这是实现内部通信的基础。

接下来是Nginx的角色。很多人以为反向代理只是为了“换个端口”，其实不然。它的真正价值在于解耦与抽象。外部用户只需要知道你的服务器IP，所有请求都打到80端口，然后由Nginx根据路径规则分发到不同后端服务。

比如未来你可以扩展出/api/v1/inference转发给FastAPI模型服务，/jupyter指向Notebook，全部统一在一个域名下。这种灵活性是直接暴露端口无法比拟的。

以下是nginx.conf的核心配置：

events { worker_connections 1024; } http { upstream pytorch_backend { server pytorch-service:8888; } server { listen 80; location / { proxy_pass http://pytorch_backend/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } } }

特别注意最后三行——它们是为了支持WebSocket。Jupyter Lab的终端、内核交互等功能依赖WebSocket长连接，如果不开启，你会遇到“连接已中断”的报错。这一点很容易被忽略，却是保障完整功能体验的关键。

整个系统的数据流向也很清晰：

[用户浏览器] ↓ (HTTP GET http://your-server/) [Nginx 容器] ↓ (反向代理 → http://pytorch-service:8888) [PyTorch 容器中的 Jupyter] ↓ (GPU加速执行代码) [返回HTML/JSON响应] ↑ 经Nginx回传至浏览器

部署完成后，只需一条命令即可启动全部服务：

docker-compose up -d

但这并不意味着万事大吉。在真实使用中，有几个最佳实践必须纳入考虑。

首先是安全性。开发阶段为了便利可以关闭认证，但一旦接入公网，就必须加固。建议至少做到以下几点：

• 修改Jupyter启动命令，加入--NotebookApp.password='sha:...'，使用哈希密码保护；
• 配置Let’s Encrypt证书，启用HTTPS，防止中间人攻击；
• 使用防火墙限制仅允许特定IP段访问80/443端口。

其次是资源控制。一台服务器可能要承载多个项目，不能任由某个容器耗尽所有GPU显存。可以在docker-compose.yml中添加资源限制：

deploy: resources: limits: cpus: '4' memory: 16G devices: - driver: nvidia count: 1 capabilities: [gpu]

这样即使多人共用，也能保证基本的资源隔离。

再者是持久化问题。容器一旦删除，里面的数据就会丢失。因此必须将重要目录挂载为主机卷：

volumes: - ./notebooks:/workspace/notebooks - ./models:/workspace/models - ./logs:/workspace/logs

这样即便更新镜像或重建容器，代码、模型权重和日志都能保留下来。

最后是可观测性。别等到GPU风扇狂转才发现有人在跑大模型。简单的做法是定期查看日志：

docker-compose logs pytorch-service

更进一步，可以集成Prometheus + cAdvisor监控容器资源使用情况，用Grafana展示GPU利用率、显存占用趋势图。这些信息对于优化调度策略至关重要。

当然，这套架构也有明确的边界。它适合5人以下团队的快速原型开发，或是边缘节点的轻量部署。如果你需要处理百万级QPS、自动扩缩容、灰度发布等复杂需求，那就该考虑Kubernetes + Istio这样的重型武器了。

但从另一个角度看，正是这种“够用就好”的设计理念，让它具备极强的落地能力。很多AI项目的失败并非技术不够先进，而是过度设计导致迟迟无法上线。而这套方案，往往能在半天之内跑通端到端流程，让团队迅速获得反馈，进入正向循环。

展望未来，这个基础架构很容易演进为更完整的MLOps流水线：

• 加入Redis作为缓存层，加速频繁调用的推理接口；
• 集成MLflow进行实验跟踪和模型版本管理；
• 使用GitHub Actions实现CI/CD，代码提交后自动构建镜像并部署；
• 引入Traefik替代Nginx，原生支持动态路由和服务发现。

每一步扩展都不需要推倒重来，因为最初的结构足够简洁且可组合。

回到最初的问题：我们为什么需要这样的部署方案？答案或许可以用一句话概括：让工程师专注于AI本身，而不是环境和运维的琐事。

当你不再为“为什么CUDA找不到设备”而焦头烂额，当你能一键复现同事的运行环境，当新成员第一天就能跑通全流程——这才是技术基础设施应有的样子。