1. 项目缘起与整体部署思路拆解1.1 为什么会有这个需求CubeStudio 是一套面向机器学习场景的一站式云原生开发平台集成了 Notebook 在线开发、任务流编排、模型训练、推理服务部署等能力。它的架构天然依赖 Kubernetes、Docker 镜像仓库、对象存储、MySQL、Redis 等一整套组件。在普通互联网环境下官方提供了一键安装脚本拉镜像、装依赖、起服务基本半小时能跑起来。但问题来了——很多金融、能源、政务类企业的生产环境是完全物理隔离的内网没有外网出口甚至连内网 DNS 都不通外网。这种环境下所有在线拉取镜像、在线下载依赖的操作全部失效。更麻烦的是信创环境往往还叠加了国产 CPU 架构鲲鹏、飞腾、海光等 ARM 或 x86 变体和国产操作系统麒麟、统信 UOS镜像的架构匹配问题会让整个部署难度再上一个台阶。我最近刚在一个典型信创内网环境里完整落地了一套 CubeStudio 私有化部署从零开始踩了不少坑。这篇文章就把整个离线部署的全流程拆开讲清楚包括镜像怎么导出、Harbor 怎么在内网搭建、出口机怎么做代理中转、以及那些官方文档里不会写的细节问题。1.2 整体架构设计思路离线部署的核心矛盾只有一个内网机器拿不到外网的资源。解决这个矛盾的方式本质上就是找一个中间人——一台既能访问外网、又能和内网通信的机器我们通常叫它出口机或者跳板机。整个部署链路可以拆成三个阶段资源准备阶段在外网机器上把所有需要的 Docker 镜像、二进制包、配置文件全部下载好打包成离线包。资源传输阶段通过出口机把离线包传入内网或者直接在出口机上搭建临时 Harbor 做镜像中转。内网部署阶段在内网搭建 Harbor 仓库把镜像推入 Harbor然后修改 CubeStudio 的部署配置让所有组件从内网 Harbor 拉取镜像。这里有个关键决策点Harbor 到底部署在哪我的建议是直接部署在内网出口机只做临时的镜像中转。原因很简单——Harbor 本身也需要持久化存储和稳定运行放在出口机上既不稳定也不安全而且后续 CubeStudio 的 Notebook 镜像、训练镜像都需要频繁推拉内网 Harbor 才是长期方案。另一个决策点是镜像导出方式。有两种选择用docker save导出成 tar 包再docker load或者用skopeo直接同步。前者简单粗暴但文件巨大后者更优雅但需要额外装工具。在信创环境下我倾向于用docker save因为 skopeo 在国产 OS 上的兼容性不一定好而且 tar 包传输更直观出问题好排查。1.3 信创环境的特殊考量信创环境不是简单的没外网它还有几个额外的坑CPU 架构问题。如果你的内网是鲲鹏 920ARM64或飞腾ARM64那么你导出的所有镜像必须是 ARM64 架构的。很多官方镜像默认只有 AMD64你需要找 ARM64 版本或者自己构建。我遇到过最坑的情况是镜像 manifest 里同时包含 AMD64 和 ARM64但docker save默认只导出当前架构的导致内网 load 之后发现架构不对。操作系统差异。麒麟 V10、统信 UOS 这些系统的 Docker 版本可能比较老对镜像格式的支持有限。比如某些用 OCI 格式构建的镜像在老版本 Docker 上可能 load 失败。建议在内网机器上先确认 Docker 版本然后在外网导出时用兼容性更好的格式。安全策略限制。信创内网通常有严格的安全策略比如禁止 root 登录、限制端口访问、强制密码复杂度等。这些都会影响 Harbor 和 CubeStudio 的部署配置需要提前和运维确认。2. 外网资源准备与镜像导出实操2.1 环境准备与工具清单在外网准备机器上你需要先装好以下工具Docker版本尽量和内网一致建议 20.10.x 以上docker-composeHarbor 部署需要skopeo可选用于镜像同步足够的磁盘空间CubeStudio 全量镜像大概 50-80GB先确认外网机器的架构uname -m # 输出 x86_64 或 aarch64这个结果决定了你后续拉取镜像时要指定对应的 platform。如果外网机器是 x86 但内网是 ARM你需要在拉取时加--platform linux/arm64参数。2.2 CubeStudio 镜像清单梳理CubeStudio 的镜像分为几大类我按重要性排个序镜像类别典型镜像名用途大小参考核心服务cube-studio/backend后端 API 服务1.5GB前端cube-studio/frontendWeb UI500MBNotebookcube-studio/notebook-*在线开发环境5-10GB训练镜像cube-studio/train-*模型训练5-15GB推理镜像cube-studio/inference-*模型服务3-8GB基础组件mysql/redis/minio依赖服务各 500MB实际镜像清单以你部署的 CubeStudio 版本为准建议直接看官方docker-compose.yaml或 Helm chart 里的 image 字段把所有镜像名提取出来。提取镜像列表的命令grep -rh image: ./cube-studio-deploy/ | awk {print $2} | sort -u image-list.txt2.3 镜像拉取与导出脚本拿到镜像列表后写一个批量拉取和导出的脚本。这里要注意几个细节#!/bin/bash # pull-and-save.sh ARCHarm64 # 根据内网架构调整 OUTPUT_DIR./images mkdir -p $OUTPUT_DIR while read image; do echo Pulling $image ... docker pull --platform linux/$ARCH $image # 把镜像名里的 / 和 : 替换成 _ 作为文件名 filename$(echo $image | sed s/[\/:]/_/g) echo Saving $image to $filename.tar ... docker save -o $OUTPUT_DIR/$filename.tar $image done image-list.txt注意docker save导出的 tar 包会保留镜像的完整层级文件会比较大。如果磁盘紧张可以在 save 之后用 gzip 压缩但 load 时需要先解压。拉取过程中最容易出问题的是架构不匹配。如果某个镜像没有 ARM64 版本docker pull --platform linux/arm64会直接报错。这时候你有两个选择找替代镜像或者用docker buildx自己构建一个 ARM64 版本。2.4 镜像导出后的校验导出完成后一定要做校验否则传到内网才发现问题就白折腾了# 检查每个 tar 包是否能正常读取 for f in ./images/*.tar; do echo Checking $f ... docker load -i $f --quiet echo OK || echo FAILED done更严谨的做法是记录每个镜像的 digest在内网 load 之后对比docker inspect --format{{.RepoDigests}} $image3. 内网 Harbor 搭建与镜像入库3.1 Harbor 离线包准备Harbor 官方提供离线安装包直接下载harbor-offline-installer-vX.X.X.tgz即可。下载地址在 GitHub Releases 页面选择对应架构的包。注意Harbor 的离线包本身包含了所有需要的 Docker 镜像所以不需要额外拉取。把离线包传到内网后解压tar -xzf harbor-offline-installer-v2.9.0.tgz cd harbor3.2 Harbor 配置文件修改复制配置模板并修改cp harbor.yml.tmpl harbor.yml vim harbor.yml关键配置项hostname: 192.168.209.133 # 内网 IP 或域名 http: port: 80 # 如果内网有证书配置 https否则注释掉 https 段 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path harbor_admin_password: YourStrongPassword123 data_volume: /data/harbor注意hostname不要用localhost或127.0.0.1否则其他机器无法访问。用内网实际 IP。3.3 Harbor 安装与验证执行安装脚本./install.sh安装完成后用浏览器访问http://192.168.209.133用admin和你设置的密码登录。如果能正常打开说明 Harbor 起来了。接下来在 Harbor 里创建一个项目比如叫cube-studio用于存放 CubeStudio 的镜像。3.4 镜像推送到 Harbor在内网机器上先把之前导出的 tar 包 load 进来for f in ./images/*.tar; do docker load -i $f done然后给每个镜像打上 Harbor 的 tag 并推送#!/bin/bash # push-to-harbor.sh HARBOR192.168.209.133 PROJECTcube-studio while read image; do # 提取镜像名和 tag name$(echo $image | awk -F: {print $1}) tag$(echo $image | awk -F: {print $2}) # 新的镜像名 new_image$HARBOR/$PROJECT/$name:$tag docker tag $image $new_image docker push $new_image done image-list.txt推送过程中最常见的错误就是热词里提到的harbor 推送失败 get https://192.168.209.133/v2/: dial tcp 192.168.209.133: connect: connection refused这个错误的原因通常是 Docker 默认用 HTTPS 访问 Harbor但 Harbor 配置的是 HTTP。解决方法是在内网机器的/etc/docker/daemon.json里加上{ insecure-registries: [192.168.209.133] }然后重启 Dockersystemctl restart docker提示如果内网机器是麒麟或统信系统daemon.json 的位置可能不同用docker info | grep Docker Root Dir确认一下。4. 出口机代理中转方案4.1 出口机的角色定位出口机是整个离线部署的桥梁。它需要满足两个条件能访问外网或者能拿到外网资源同时能和内网机器通信。在实际项目中出口机通常是一台双网卡机器一张网卡连外网一张连内网。出口机的主要工作下载外网资源镜像、安装包、依赖把资源传输到内网可选搭建临时 Harbor 做镜像中转4.2 临时 Harbor 中转方案如果内网 Harbor 还没搭好或者你想先把镜像传到内网再慢慢处理可以在出口机上临时搭一个 Harbor# 在出口机上 docker run -d -p 5000:5000 --name registry registry:2然后在外网机器上把镜像推到出口机的 registrydocker tag $image export-machine-ip:5000/$image docker push export-machine-ip:5000/$image内网机器再从出口机拉取docker pull export-machine-ip:5000/$image docker tag export-machine-ip:5000/$image 192.168.209.133/cube-studio/$image docker push 192.168.209.133/cube-studio/$image这个方案的好处是不用传大文件但要求出口机和内网机器网络互通且出口机的 registry 端口对内网开放。4.3 文件传输方案如果网络不通或者安全策略不允许开端口那就只能用文件传输。常见方式U 盘/移动硬盘最原始但最可靠适合物理隔离环境内网文件服务器如果内网有 FTP/SFTP 服务器可以先传到那里光盘刻录某些高安全环境只允许光盘传输文件传输时要注意校验完整性# 生成校验文件 md5sum ./images/*.tar images.md5 # 内网校验 md5sum -c images.md54.4 出口机代理配置的注意事项如果出口机需要做 HTTP 代理中转配置时要注意代理只对特定域名或 IP 生效不要全局代理代理端口不要用常见端口避免被安全策略拦截代理日志要定期清理避免泄露信息注意信创内网通常有严格的安全审计任何代理行为都需要提前报备。不要私自搭建未经批准的代理服务。5. CubeStudio 部署配置改造5.1 修改镜像地址CubeStudio 的部署配置里所有镜像地址都需要从官方地址改成内网 Harbor 地址。以 docker-compose 部署为例services: backend: image: 192.168.209.133/cube-studio/backend:latest frontend: image: 192.168.209.133/cube-studio/frontend:latest # ... 其他服务如果是 Helm 部署修改values.yaml里的image.repository和image.registry。5.2 配置 imagePullSecrets如果 Harbor 项目是私有的需要在 Kubernetes 里创建 secretkubectl create secret docker-registry harbor-secret \ --docker-server192.168.209.133 \ --docker-usernameadmin \ --docker-passwordYourPassword \ --namespacecube-studio然后在 Deployment 或 Pod 模板里引用spec: imagePullSecrets: - name: harbor-secret5.3 依赖服务的离线配置CubeStudio 依赖的 MySQL、Redis、MinIO 等如果也用容器部署同样需要从内网 Harbor 拉取。如果内网已有这些服务直接改连接配置即可。数据库初始化 SQL 需要提前准备好在内网 MySQL 里执行mysql -h 内网MySQL地址 -u root -p init.sql5.4 部署验证与常见问题部署完成后按以下顺序验证所有 Pod 是否 Runningkubectl get pods -n cube-studio后端 API 是否可访问curl http://内网IP:端口/health前端页面是否正常打开创建一个测试 Notebook确认能正常启动常见问题排查表问题现象可能原因解决方法Pod 一直 ImagePullBackOff镜像地址错误或 secret 未配置检查 image 地址和 imagePullSecretsPod CrashLoopBackOff依赖服务连不上检查 MySQL/Redis 连接配置前端 502后端未启动查看后端 Pod 日志Notebook 启动失败镜像架构不匹配确认镜像架构与节点一致Harbor 推送 443 错误Docker 默认 HTTPS配置 insecure-registries6. 实操心得与避坑指南6.1 镜像导出的三个坑坑一架构不匹配。这是最常见的。外网机器是 x86内网是 ARM导出的镜像 load 之后跑不起来。解决方法是在拉取时明确指定--platform并且在内网 load 后用docker inspect确认架构。坑二镜像层丢失。用docker save导出多个镜像时如果它们共享基础层save 会重复导出导致 tar 包巨大。可以用docker save -o all.tar image1 image2 image3一次性导出Docker 会自动去重。坑三tag 丢失。docker save默认保留所有 tag但如果镜像有多个 tagload 之后可能只保留一个。建议导出前先确认每个镜像的 tag必要时手动重新打 tag。6.2 Harbor 部署的注意事项Harbor 的data_volume一定要放在大磁盘上因为所有镜像都存这里。我见过有人默认放在/data结果系统盘满了导致 Harbor 挂掉。Harbor 的数据库PostgreSQL和 Redis 是内置的如果 Harbor 重启后数据丢失通常是 volume 挂载有问题。建议用 docker-compose 部署时明确指定 volume 路径。如果内网有多个 Harbor 节点需要配置复制策略。但大多数场景单节点就够了。6.3 出口机使用的安全建议出口机是安全敏感点建议出口机不存储敏感数据只做中转传输完成后及时清理临时文件出口机的访问日志定期审计不要在内网机器上直接配置外网代理6.4 信创环境的额外检查项在信创环境部署前建议先做以下检查# 确认 CPU 架构 uname -m # 确认操作系统版本 cat /etc/os-release # 确认 Docker 版本 docker version # 确认内核版本某些老内核不支持新特性 uname -r # 确认磁盘空间 df -h # 确认内存 free -h这些信息决定了你后续的镜像选择和配置调整。比如麒麟 V10 SP1 的内核是 4.19对某些新版本的 Kubernetes 支持有限可能需要降级部署。6.5 部署后的性能调优建议CubeStudio 跑起来之后如果发现 Notebook 启动慢、训练任务排队久可以从几个方面调优镜像预热把常用镜像提前拉到所有节点避免每次启动都拉取Harbor 缓存Harbor 本身有缓存机制确保它运行在 SSD 上资源限制给每个 Notebook 设置合理的 CPU/内存 limit避免单个用户占满资源存储优化MinIO 或 NFS 的 IO 性能直接影响 Notebook 的读写体验我在实际项目里遇到过一次 Notebook 启动要 5 分钟的情况排查后发现是镜像太大15GB加上 Harbor 磁盘是机械盘。换成 SSD 并预热镜像后启动时间降到 30 秒以内。6.6 后续维护的几点建议离线环境的维护比在线环境麻烦得多因为不能随时拉取更新。建议建立镜像版本管理机制每次更新都记录版本号和变更内容保留至少一个上一个版本的完整镜像包方便回滚定期检查 Harbor 磁盘使用率及时清理旧镜像出口机的传输记录要存档方便追溯这套流程我在三个不同规模的信创环境里都跑过从单节点测试到 20 节点集群核心逻辑是一样的。区别只在于镜像数量、Harbor 规模和网络配置的复杂度。把上面这些步骤走一遍基本能覆盖 90% 的离线部署场景。剩下的 10% 通常是特定环境的特殊限制需要具体问题具体分析。