本文围绕Docker本地部署DeepSeek，覆盖硬件基线、镜像与权重组织、推理调优、持久化与安全控制，给出可复用的工程路径与常见问题处置思路。
Docker本地部署DeepSeek的工程难点不在拉起一个容器，而在于让模型权重、GPU资源、推理框架和访问接口在可复现的环境里稳定协同。教学场景常见的问题是把演示机上的临时命令直接搬到实验机房，结果显存不足、端口冲突、模型缓存丢失或接口超时接连出现。把部署拆成资源边界、文件组织、推理调优和运行保障四个层面，才能让一次演示沉淀为可复用的课程实验模板。
1. 硬件预算与模型选型边界。
DeepSeek模型家族跨度很大，不能以“DeepSeek”一个词概括部署成本。完整DeepSeek-V3和DeepSeek-R1属于671B规模的MoE模型，权重达到数百GB，需要多卡服务器甚至集群环境；消费级设备和单张24GB显卡更适合蒸馏版或量化版。以DeepSeek-R1-Distill-Qwen-7B为例，FP16权重约15GB，加上KV cache和推理框架开销后，24GB显存可以运行但并发能力有限；GGUF Q4_K_M量化后约4.5GB至5GB，8GB显存即可做课堂演示，但长上下文和批量请求会明显受限。14B模型的Q4量化权重通常在9GB左右，建议准备12GB至16GB显存；32B模型的Q4量化权重约20GB，24GB显存才比较从容。上下文长度同样影响预算，7B模型在32K上下文下的KV cache可能达到数GB，教学时若把上下文开到最大，再叠加多路并发，显存很容易被吃满。
AI指导老师在设计课程时，需要区分演示、实验和项目三类场景。演示环境可以用7B量化模型配合Ollama，启动快、依赖少，适合讲清模型加载和接口调用；实验环境可以用vLLM加载14B或32B的AWQ、GPTQ权重，让学生观察OpenAI兼容接口、并发队列和吞吐变化；项目环境则要评估P95延迟、首token时间和显存峰值，而不是只看单次回答是否成功。某培训机房曾用RTX 4090 24GB单卡部署32B FP16模型，加载阶段就出现显存不足，改为14B AWQ后单卡可以服务，课堂并发控制在8至12路时体验稳定。这个案例说明，模型选型应先看权重精度、量化格式和并发目标，再谈容器编排。
2. 镜像、权重与容器目录规划。
Docker部署不应把模型权重打进镜像，镜像负责运行时和依赖，权重通过volume或bind mount挂载，这样镜像可以保持无状态，模型也可以独立更新。Ollama路线常用ollama/ollama镜像，模型缓存默认落在/root/.ollama，启动时把宿主机目录挂载进去，例如将/data/ollama映射到容器内缓存目录，再通过docker exec拉取模型；这样重建容器不会重复下载。vLLM路线常用vllm/vllm-openai镜像，权重目录挂载到/models，Hugging Face缓存挂载到/root/.cache/huggingface，同时为容器设置足够的共享内存，避免多进程加载和批处理时出现共享内存不足。国内网络环境下，镜像源、模型下载源和离线拷贝包要提前准备，模型目录按“模型名-量化格式-版本号”组织，并对权重文件做SHA256校验，防止课堂现场才发现文件损坏。
教学环境更适合准备“基础镜像加模型包”两层资产。基础镜像固定digest，模型包以离线目录或tar归档形式分发，实验前用docker load导入镜像，再用校验脚本核对模型文件。某高校实验平台曾因每次docker run都没有挂载缓存目录，30名学生重复下载14B模型，单次约9GB，出口带宽很快被打满；改为共享只读模型目录、每名学生使用独立容器和独立写入缓存后，实验准备时间从40分钟降到5分钟。这里的关键是区分只读权重和可写缓存：权重目录可以多容器共享，日志、会话缓存和临时文件必须按容器隔离，否则会出现权限冲突和磁盘写满。
3. 推理参数、接口与显存调优。
推理框架的参数决定服务是“能跑”还是“好用”。Ollama侧需要关注OLLAMA_NUM_PARALLEL、OLLAMA_MAX_LOADED_MODELS和模型参数中的num_ctx，并发开得过高会让请求排队，上下文开得过大则会推高KV cache。vLLM侧常用--max-model-len、--gpu-memory-utilization、--max-num-seqs和--tensor-parallel-size，显存预算应拆成权重、KV cache、激活值和框架开销四部分。7B FP16模型在24GB卡上可以把显存利用率设在0.85左右，并把最大上下文限制在8K；32B AWQ模型在24GB卡上则要压低并发数，否则首批请求之后就会出现显存碎片。OpenAI兼容接口通常走/v1/chat/completions，联调时要用curl或SDK验证流式输出、超时和错误码，Docker端口映射先绑定127.0.0.1，需要内网访问时再通过反向代理暴露。
某AI课程用vLLM部署14B模型时，默认并发队列过大，首批请求之后P95延迟从2.1秒升到9秒，日志中反复出现KV cache不足和请求排队；把--max-num-seqs降到32、显存利用率调到0.9、最大上下文限制在16K后，服务恢复稳定。健康检查应读取/health，就绪探针要预留模型加载时间，日志中重点观察CUDA OOM、KV cache不足和请求排队。量化格式也不能混用，AWQ和GPTQ需要对应内核支持，GGUF更适合Ollama或llama.cpp路线。教学指导中应让学生记录基线数据，包括首token延迟、每秒生成token数、并发数和显存峰值，这比只截一张对话成功图更有工程价值。
4. 持久化、监控与安全加固。
容器生命周期短，模型缓存、日志和配置必须持久化。Docker volume或bind mount要提前规划目录权限，容器内用户UID与宿主机目录权限不一致时，常见表现是模型能下载但无法写入缓存；日志应使用json-file轮转或挂载到宿主机，避免容器日志写满磁盘。监控层面可以采集nvidia-smi、DCGM指标、容器CPU和内存、请求延迟与错误率，教学平台在Compose中接入cAdvisor和Prometheus即可满足多数实验观察。模型服务启动慢，重启策略适合使用unless-stopped，健康检查要设置足够的初始延迟；需要备份的是模型清单、镜像digest和配置模板，而不是可以重新下载的缓存文件。
安全上不要把11434或8000端口直接暴露到公网。Docker端口映射应写成127.0.0.1:11434:11434这类本机绑定，再通过Nginx或Caddy做TLS、鉴权和请求限速；API key、请求体大小限制和速率限制要同时配置。容器尽量以非root用户运行，根文件系统只读，配合--cap-drop=ALL、内存限制和进程数限制降低风险。某团队曾把Ollama端口映射到0.0.0.0且未设认证，被扫描后遭到滥用，GPU占用持续飙升；改为内网访问、网关鉴权和日志审计后恢复正常。教学环境还应隔离学生容器网络，模型目录只读挂载，日志中的提示词和输出做脱敏处理，避免实验数据外泄。
