做GPUStack离线部署最折磨人的环节往往不是GPU驱动不是Kubernetes网络而是“镜像”这两个字。我在内网环境里部署GPUStack时曾天真地以为把Docker镜像导出再导入就万事大吉结果接连踩了架构不匹配、tag混乱、ghcr.io镜像完全拉不动、模型文件半路中断等一堆坑前前后后折腾了一个多星期。事后复盘发现只要把“镜像准备与国内加速源”这一环想清楚整个离线部署过程可以做得非常流程化。这篇文章就以GPUStack离线部署的镜像准备为主线把我实际操作中的思路、命令、踩坑记录和排查方法完整列出来。适合正在做GPU资源池化、私有化大模型推理平台、以及需要在隔离网络里交付GPUStack的工程师参考。内容不绕弯子所有操作都是我在真实环境里验证过的。1. GPUStack解决什么问题离线部署难在哪里1.1 用一句话理解GPUStackGPUStack是一个开源的GPU资源管理与大模型推理服务平台。你可以把多台服务器上型号不一、显存不一的GPU卡统一纳管起来把物理显卡切成虚拟GPU分给不同团队或应用使用同时直接在平台上部署和调用大模型推理服务暴露统一API接口。底层它借助Kubernetes通常是一套轻量的k3s完成容器调度把GPU资源池化这件事做得比较顺滑。它的部署逻辑并不复杂一台控制节点跑gpustack-server提供管理界面和API每台GPU节点上跑gpustack-worker负责接收任务并调度给推理运行时Ollama或vLLM等。问题在于这些组件大量以容器镜像的形式分发而且镜像不只来自一个仓库。1.2 离线部署实际要过的三道坎第一道坎是容器镜像获取。GPUStack自身镜像、Ollama运行时镜像、底层依赖镜像分散在Docker Hub、ghcr.io等不同仓库完全离线的情况下一条pull命令都执行不了。第二道坎是模型文件获取。部署GPUStack的最终目的往往是跑大模型模型动辄几个GB甚至几十GB通常托管在HuggingFace等境外平台下载本身就是个问题。第三道坎是工具链依赖。安装脚本、Python依赖包、前端静态资源等也都有自己的来源渠道网络不通时同样会阻断部署。这三道坎不解决后面所有步骤都白搭。所以我把离线部署的制高点放在“镜像与模型供应链准备”上只要这一步做得足够细后面的安装配置反而花不了多少时间。1.3 适合谁看这份经验这段内容特别适合三类场景一是企业内网或生产环境有严格安全策略服务器不能访问公网需要整体离线交付二是跨地域项目现场网络质量极差从境外仓库拉一个几百MB的镜像要重试十几次三是对软件供应链有版本固化要求想把所有组件固定在一个经过验证的版本组合里避免在线安装时悄悄漂移。2. 动手之前先盘点镜像依赖别凭感觉开干2.1 GPUStack镜像到底从哪些仓库来GPUStack的镜像来源并不是单一的。从我实际部署和阅读安装脚本的经验来看镜像主要分散在这么几类仓库Docker Hub上主要是Ollama运行时、一些基础工具镜像ghcr.io上主要是GPUStack官方镜像以及部分配套组件此外K3s底层组件、监控组件还可能涉及quay.io等容器仓库。不同版本、不同安装方式依赖清单会有差异。这里提醒一句GPUStack版本更新很快网上各种教程里写的镜像名和版本号未必一致。我在一条旧教程里看到一个镜像tag照着拉取后发现推送到ghcr.io的镜像已经被删除白白浪费了时间。所以最可靠的办法是直接用官方安装脚本或Helm Chart里的引用关系来梳理而不是靠网上文章拼凑。2.2 怎么快速梳理出真实镜像清单我习惯在一个能联网的跳板机上先跑一遍官方在线安装流程但故意在半途让安装失败然后通过容器运行时查看“它究竟要拉哪些镜像”。这个方法有点野但非常高效。具体做法是先在跳板机上执行安装脚本观察日志里出现的镜像地址并记录下来再用docker images或crictl images查看已经拉下来的镜像列表如果脚本自动装了K3s还可以在/var/lib/rancher/k3s/agent/containerd/的日志里搜pulling image关键字把所有待拉取的镜像整理到一份清单里。最后把这份清单与官方仓库里的默认镜像列表比对人工确认版本和用途就可以作为后续离线准备的依据。2.3 版本、架构、tag是三个最容易忽略的细节镜像清单整理出来后必须确认三件事。第一是架构GPUStack节点如果是ARM架构的机器拉取x86镜像会直接启动失败所以联网拉取时就要选对linux/arm64或linux/amd64的版本。第二是tag的一致性GPUStack server和worker版本如果相差太远可能因为API兼容性问题无法注册节点最好所有组件锁定在同一发布版本。第三是镜像签名或摘要把docker pull后的Digest值记下来离线导入后可以通过比对验证镜像是否完整。这里的经验是不要只抄镜像名和tag要把完整的repositorysha256:xxx摘要一起记录。这样做的好处是后续无论从哪个仓库重新拉取都能确认是同一份内容避免“名字一样但内容不一致”的诡异问题。3. 联网环境配好国内加速源把镜像个个拿下3.1 Docker daemon配置registry mirror联网环境下拉取Docker Hub镜像首选方案是配置registry mirror。修改/etc/docker/daemon.json加入国内可用的镜像加速器地址然后重启Docker使配置生效。{ registry-mirrors: [ https://docker.m.daocloud.io, https://docker.mirrors.ustc.edu.cn, https://hub-mirror.c.163.com, https://mirror.baidubce.com ], insecure-registries: [ 192.168.1.0/24 ] }配置完成后执行systemctl restart docker再跑一下docker info在输出的Registry Mirrors字段中能看到生效的加速器列表。这里有一个细节registry mirror只对Docker Hub官方镜像生效对ghcr.io、quay.io这类第三方仓库基本无效别指望一个加速配置解决所有镜像源的问题。3.2 ghcr.io镜像拉不动的现实解法ghcr.io的镜像在国内网络环境下经常拉取超时这点在实际操作中非常普遍。GPUStack官方镜像恰好放在这个仓库所以这是个绕不开的问题。我的处理顺序是这样的先在普通网络下重试两三次确认是否真的拉不下来然后用支持多仓库的聚合镜像加速服务把ghcr.io的镜像转成中间地址再拉取如果仍然不行就找一台能稳定访问境外仓库的云服务器在那边把镜像拉好、导出、压缩再传回内网。这里我不推荐把一个固定加速站写死在生产脚本里因为这类公共服务变动太频繁今天能用明天可能就失效。比较稳妥的做法是把整个镜像离线包作为交付物的一部分而不是寄希望于现场网络临时加速。3.3 镜像导出docker save/load还是skopeo导出镜像我试过两种方式。一种是最常见的docker savedocker load操作简单但存在格式限制另一种是skopeo copy可以直接把镜像从一个registry复制到另一个registry或本地目录对镜像格式的保留更原生。# docker save 方式保留镜像结构和tag docker save -o gpustack-images.tar \ ghcr.io/gpustack/gpustack:v0.4.0 \ ollama/ollama:latest # 传输前用zstd压缩 zstd -T0 gpustack-images.tar -o gpustack-images.tar.zst如果你的离线环境里有自建私有仓库我推荐用skopeo直接把镜像推到Harbor或Registry中命令大概是skopeo copy docker://ghcr.io/gpustack/gpustack:v0.4.0 docker://harbor.local/gpustack/gpustack:v0.4.0这样连tar包中转都省了。二者适用场景不同下面的对比可以帮你判断该用哪条路线方式优点缺点适用场景docker save/load操作简单不依赖额外组件镜像格式受限大镜像导出耗时较长单机或小规模集群快速交付skopeo copy保留原始镜像格式支持多registry互传需要额外安装skopeo命令参数稍复杂有私有仓库的中大规模集群导出镜像后建议把多个tar文件合并管理并生成对应的清单文件记录仓库地址、tag、架构、大小、sha256摘要。这一步能为后续离线导入节省大量核对时间。4. 离线环境导入镜像从单机load到Harbor分发4.1 小规模集群直接用docker load如果离线环境只有两三台GPU节点最省事的方案是把前面导出的tar包拷贝到每台机器上执行docker load导入本地镜像。我用zstd压缩后体积能减少一半以上传输耗时明显降低。tar -I zstd -xvf gpustack-images.tar.zst docker load -i gpustack-images.tar docker images | grep gpustack导入完成后别急着部署先确认镜像的repo和tag是否与离线安装脚本期望的名称完全一致。很多安装脚本硬编码了镜像地址如果你的镜像名带了私有仓库前缀或tag不同就会导致后续创建Pod时提示拉取镜像失败。解决办法是导入后立即执行docker tag把镜像重命名为脚本期望的完整名称。4.2 多节点生产环境推到Harbor统一分发节点多的情况下逐台docker load一方面效率低另一方面镜像版本容易在各节点间漂移今天你改了一版镜像少同步了一台机器后面排查起来极其痛苦。所以在生产环境或正式交付场景我更倾向于在内网部署一个Harbor私有仓库把所有镜像统一推送到Harbor各节点通过Kubernetes拉取。Harbor本身也是容器化部署这意味着离线准备镜像时要把Harbor的几个核心镜像也一并拉好、导出、带到内网。部署Harbor时需要特别注意registry地址被各节点访问所以要么给Harbor配好TLS证书要么在每台节点的Docker和containerd配置中将Harbor地址加入insecure-registries。# 修改每台节点的 /etc/docker/daemon.json追加harbor地址 { insecure-registries: [harbor.internal:443] }K3s或Kubernetes节点一般用containerd作为运行时光是改Docker配置还不够还要改/etc/rancher/k3s/registries.yaml让K3s在拉取私有仓库镜像时跳过TLS校验mirrors: harbor.internal: endpoint: - https://harbor.internal configs: harbor.internal: tls: insecure_skip_verify: true这个配置不提前写好等到GPUStack创建Pod时再发现拉取失败中间排查的过程会非常耗时。我的经验是Harbor地址在所有节点上要先通过crictl pull harbor.internal/gpustack/gpustack:v0.4.0做一次连通性验证确认能拉取后再跑GPUStack安装流程。4.3 离线上手脚本示例为了不让繁琐的load和tag操作重复执行我写了一个简单的bootstrap脚本放在tar包旁边。脚本做的事情是解压镜像、load镜像、检查关键镜像是否存在、按需设置tag、最后把配置写入daemon.json和registries.yaml。#!/bin/bash set -e IMAGES_DIR$(dirname $0)/images HARBOR # 1. 导入所有镜像压缩包 for f in $IMAGES_DIR/*.tar.zst; do echo 导入镜像包: $f tar -I zstd -xvf $f -C /tmp/gpustack-images docker load -i /tmp/gpustack-images/$(basename $f .tar.zst).tar done # 2. 校验关键镜像存在 docker images | grep -E gpustack|ollama || { echo 关键镜像缺失; exit 1; } # 3. 设置私有仓库tag如果HARBOR变量非空 if [ -n $HARBOR ]; then docker tag ghcr.io/gpustack/gpustack:v0.4.0 $HARBOR/gpustack/gpustack:v0.4.0 docker push $HARBOR/gpustack/gpustack:v0.4.0 fi echo 镜像准备完成脚本不用写得花哨把它当作离线包的一部分一并交付能大幅减少现场手动操作的失误率。我记得第一次离线交付时没有脚本三台节点手动load有一台节点漏掉了最新的runtime镜像以至于模型服务在该节点上始终无法调度最终靠逐台比对镜像列表才查出来。从那以后我坚持把所有镜像操作脚本化。5. 模型文件也要“离线化”HuggingFace加速与Ollama导入5.1 模型下载加速HF_ENDPOINT环境变量部署GPUStack最终要加载模型。很多开源模型的权重文件放在HuggingFace上内网机器下载不现实所以模型文件的离线准备同样要提前完成。这里推荐使用HuggingFace的国内镜像站点把下载源切换到镜像后速度能提升到可接受的范围。export HF_ENDPOINThttps://hf-mirror.com # 使用huggingface_hub下载模型快照 python -c from huggingface_hub import snapshot_download snapshot_download( repo_idQwen/Qwen2.5-7B-Instruct, local_dir/data/models/qwen2.5-7b-instruct, ignore_patterns[*.bin, *.pt] ) 这里有一个重要的模型文件取舍逻辑GPUStack底层推理运行时如果是Ollama它通常只需要GGUF格式的量化模型文件不需要原始的safetensors完整权重。所以在下载前先确认模型的运行方式能省下大量不必要的下载流量。如果决定用完整精度权重则要注意磁盘剩余空间7B模型的全精度权重至少需要15GB左右量化版本则小得多。5.2 Ollama怎么加载本地模型如果你打算通过GPUStack配合Ollama部署模型可以直接在联网环境里先把模型文件下载好再用Ollama的本地导入机制把它创建成本地模型。具体做法是准备一个Modelfile指向本地已有的GGUF文件然后执行ollama create将模型注册进本地模型库。FROM /data/models/qwen2.5-7b-instruct/qwen2.5-7b-instruct-q4_k_m.ggufollama create qwen2.5-7b:q4_k_m -f Modelfile执行完后模型会被存放在Ollama的默认模型目录中通常位于/root/.ollama/models或由环境变量OLLAMA_MODELS指定的位置。把整个模型目录一并拷贝到离线节点的对应路径即可完成“离线模型导入”。GPUStack要认得这个模型需要确保运行Ollama的worker节点能读取到该目录并且目录的属主和权限正确否则加载时会出现权限报错。我实际遇到过这样一种情况模型文件通过NFS挂载到GPU节点结果Ollama没有权限读取挂载目录中的文件日志里报的是“failed to load model”排查半天才发现是挂载参数的noexec和权限掩码把进程限制住了。处理办法是把模型文件放在本地磁盘或者把NFS挂载参数调整为符合Ollama运行用户权限的配置。5.3 模型清单与校验一个不能少模型文件比镜像更占空间而且下载过程中极易出现文件损坏。所以我的习惯是把每个模型的下载来源、文件大小、sha256值记进一个表格作为离线交付文档的一部分。到了内网环境后用sha256sum -c checksums.txt批量校验一遍确认所有文件完好再开始部署。cd /data/models sha256sum -c checksums.txt如果校验失败大概率是下载过程中文件被截断不要存侥幸心理直接重新下载该文件。模型文件损坏在推理阶段表现为加载失败或输出乱码很难排查前置校验是最廉价的保险。6. 完整离线部署实录与避坑清单6.1 一次真实的三节点离线部署时间线我以最近一次项目交付为例环境是三台GPU服务器加一台联网中转机内网网段不互通所有安装包必须手工带入。在联网中转机上我先配好Docker加速源用脚本拉取GPUStack官方镜像和Ollama运行时镜像导出后压缩成tar.zst。随后用HF_ENDPOINT环境变量从HuggingFace镜像站下载了7B量化模型并将Ollama模型目录打包。整个过程大约花掉大半天时间主要耗时在模型下载上镜像反而很快。离线现场的操作分三步先给三台节点装上Docker和GPU驱动确认nvidia-smi输出正常然后把镜像包分发到所有机器并逐一load完毕启动K3s节点后再检查GPUStack server和worker是否成功注册最后把模型文件放到指定目录在GPUStack界面创建模型实例并发出推理请求验证通断。现场操作实际只花了一下午比预期顺利。6.2 我踩过的五个比较典型的坑第一个坑是镜像架构不对。我在拉取镜像时没指定平台默认拉到了x86版本结果导入到一台ARM架构的测试节点后容器直接报exec format error。第二个坑是tag不相同GPUStack安装脚本期望的镜像名带了版本后缀但我导出的镜像没有重新打tag导致Pod一直拉取不到镜像。第三个坑是ghcr.io拉取超时反复重试浪费时间后来直接用云服务器中转解决。第四个坑是模型文件在NFS上的权限问题Ollama进程根本无法读取模型最终改为本地存储解决。第五个坑是Harbor的TLS配置遗漏K3s节点拉取私有仓库镜像时报证书错误必须提前把registries.yaml写好。这五个坑没有一个涉及复杂原理全部是“细节没提前想清楚”的典型问题。把它们写进交付Checklist后续项目基本不会再栽在同样的地方。6.3 常见问题速查表问题现象可能原因排查命令或手段解决办法容器启动报exec format error镜像架构与节点CPU架构不匹配docker image inspect 镜像jq .ArchitecturePod一直ImagePullBackOff镜像tag与脚本期望不一致kubectl describe pod查看镜像名称用docker tag重命名镜像从私有仓库拉镜像报证书错误未配置insecure-registries或registries.yamlcrictl pull 私有仓库/镜像复现配置TLS跳过或配置证书Ollama加载模型报文件不存在模型目录权限或路径挂载问题ollama list、stat查看文件权限修正权限放到可读目录模型输出乱码或日志出现损坏提示模型文件传输损坏sha256sum -c校验重新下载并替换损坏文件所有镜像拉取极慢或超时未配置国内加速或目标仓库是ghcrdocker info查看加速器配置registry-mirror或中转拉取6.4 离线包里建议附带的所有东西除了镜像tar包和模型文件离线交付包最好还包含以下内容GPU驱动安装包版本必须和节点内核匹配、Docker或containerd的安装包、GPUStack安装脚本及配置文件、Harbor离线安装包如果走私有仓库路线、镜像清单和校验和文件、模型清单及校验和文件。把这些全部整理到一个目录下目录结构固定现场就不太可能临时缺东少西。gpustack-offline/ ├── images/ │ └── gpustack-images.tar.zst ├── models/ │ ├── qwen2.5-7b/ │ └── checksums.txt ├── drivers/ │ └── NVIDIA-Linux-x86_64-535.154.run ├── packages/ │ ├── docker/ │ ├── k3s/ │ └── gpustack-installer/ ├── configs/ │ ├── daemon.json │ └── registries.yaml └── scripts/ └── bootstrap.sh这样的组织方式让交付现场非常清爽也方便对接方在一开始就能理解所有组件之间的关系。7. 离线部署不是镜像搬运而是供应链管理离线部署GPUStack这件事表面上是在搬运镜像和模型文件实际上是在搭建一条脆弱的软件供应链。镜像版本、架构、校验值、私有仓库配置、模型格式选择任何一个环节没有锁死现场就会以各种奇怪的方式报错。而国内加速源能帮你大幅缩短联网准备阶段的耗时却不能替代“提前验证、锁版本、留校验”这套基本流程。我个人在实际操作中的体会是第一次做GPUStack离线部署至少预留出两到三天的准备时间其中大部分时间会花在模型下载和镜像源对接上但只要把交付目录和脚本固化下来第二次项目基本上一天内就能完成全部打包工作。最后再分享一个小技巧在所有tar包和模型文件的旁边放一个sha256sums.txt让现场导入前先自动比对一遍主要是因为它真的能省掉很多无谓的排障时间。