前阵子去一个客户的隔离机房做CubeStudio私有化交付进场之前一切看着都很正常进场之后才发现问题比想象中大这个环境属于典型的信创隔离网机器装的是麒麟V10CPU架构是ARM64和办公网完全物理断开。没有外网就意味着没有apt源、没有pip源、没有Docker Hub连一个依赖包都要先确认能不能拿到介质。CubeStudio本身的部署其实不难难的是在“完全无外网”这几个字下面把镜像、依赖、仓库、运行时一整条链路全部打通。这篇文章不是产品功能介绍而是把我们实际跑通的离线部署全流程整理出来怎么用Harbor搭内网私有镜像仓库怎么在出口机上下载和导出镜像怎么通过合规的摆渡方式把数据导入隔离内网以及最后怎么推送、部署和验证。不管你是正在做信创投标的售前还是被安排进场干活的实施工程师或是负责这类隔离环境日常运维的同学这篇应该都能帮你绕开不少弯路。1. 先搞清楚交底这类环境到底卡在什么地方1.1 隔离网环境下的“三无”现实信创项目里的“无外网”和我们平时说的“没网”完全是两码事。日常环境下在某台机器上下载一个tar包、跑一个pip install都是顺手的事但在隔离机房里网络策略是经过安全审计和流程审批的任何数据进出都要走登记流程。我这次遇到的客户机房属于物理隔离所有机器只有内网IP没有一根网线连到办公网唯一的出口是一台经过审批的“出口机”负责从外网下载指定软件包再用移动介质导入内网。这类环境有几个硬约束进场第一天就得想清楚无软件源。操作系统自带仓库没有更新也没有三方软件源所有安装包都要自己带进去。无公共镜像源。Docker Hub、GHCR、Quay这些外部仓库全部不可达Harbor本身也要自己搭。无外网DNS解析。内网通常有自建DNS但域外解析往往是断的配置任何服务都要优先考虑用IP访问。这里的核心难点不是技术本身有多高深而是“预判能力”。先把所有需要下载的东西列成清单在出口机上一次性备齐否则到场后一台机器卡住整个工期就全乱了。别问我怎么知道的我们这次就因为在介质审批上多等了两天。1.2 两条链路决定方案设计交付链路和运行链路离线部署要想清楚两条链路。第一条是“交付链路”软件包怎么从外网进入隔离内网第二条是“运行链路”内网里的机器怎么获取所需的镜像和依赖。这两条链路如果只在部署当天临时想一定出乱子。我见过不少项目交付的时候把tar包拷进去docker load完就完事结果后面扩容一台机器、升级一个组件又要重新申请出口机下载来回折腾。所以方案设计的核心是交付链路用“出口机移动介质”一次性把物资备齐运行链路用Harbor作为内网镜像源统一供给。这样后续任何一台机器拉镜像都只需要访问内网Harbor而不再依赖外部网络。后面的所有步骤都是围绕这个思路展开的。2. 方案选型为什么最终落在这套组合拳上2.1 镜像分发为什么不是直接拷tar包现场最简单的办法其实是把镜像docker save成tar包拷进内网每台机器docker load一遍也能跑起来。那为什么还要多搭一个Harbor原因主要有三个。第一是可维护性。CubeStudio这类平台一般由网关、任务调度、元数据、算法引擎等多个镜像组成版本升级、回滚、节点扩容都是常态。如果靠tar包分发每次都要重新打包、摆渡、导入不同节点上的镜像tag很容易不一致时间一长谁也说不清哪个节点跑的是哪个版本。Harbor里所有镜像有统一的仓库列表和tag版本一目了然。第二是权限和审计。隔离网项目通常有等保和验收要求镜像来源、谁拉的什么镜像、什么时间拉的Harbor的审计日志都能覆盖。tar包则完全没有这些痕迹出了问题很难追溯。第三是多架构支持。信创环境里ARM和x86混部很常见Harbor可以在项目下按架构区分镜像配合docker的--platform参数更容易控制拉取的架构。我列个对比表方便你们做决策对比项裸tar包 docker loadHarbor私有仓库多节点分发每台机器手动load节点统一从Harbor拉取版本管理靠人工记录文件名仓库列表 tag UI操作权限控制基本没有用户 / 机器人账号 / RBAC操作审计无完整操作日志扩容与升级每次重新摆渡节点加上仓库地址即可适用场景1-2台机器临时验证正式交付、多节点、长期运维如果项目特别小、只有一两台机器那我不反对直接用tar包方案但只要超过三台机器或者后续有扩容和升级计划Harbor的投入一定值得。2.2 “出口机”的定位是数据摆渡不是流量通道很多实施文档把这种模式叫“出口机代理”听着很玄实际上就是物理隔离网络里一台经过审批、允许外联的机器。它的职责非常单一在外网下载指定的软件包和容器镜像生成校验值写入授权介质再通过审批过的流程导入隔离内网。它不承担任何流量转发也不改动任何网络路由更不涉及绕过网络安全管控的操作。这一步在实际项目里最容易被忽视我建议进场第一天就去确认出口机的使用流程谁审批、用哪种介质、登记表长什么样。别看这是“行政事项”在实际项目里它比技术方案更容易卡进度。我们这次下载了一堆包结果发现介质容量不够又回去重新换了更大的安全U盘白等了半天。提醒一句整个操作过程要留痕。申请单、操作日志、介质登记、导入记录能带上的都带上不然等保检查或项目验收的时候缺一样都要补流程。2.3 版本选型决定“能不能装上”的三个关键点离线部署最忌讳版本拍脑袋。有三个点必须在出口机下载之前就定下来。第一CPU架构要明确。在部署机上执行uname -mx86_64对应amd64镜像aarch64对应arm64镜像。信创环境常见的是鲲鹏、飞腾这种ARM平台海光和兆芯虽然指令集兼容x86但最好也按官方认证的镜像版本走。镜像拉错架构启动时直接报exec format error这是最典型的翻车现场后面常见问题部分也会专门说。第二操作系统版本和内核。麒麟V10、统信UOS 20这些常见信创系统有基于Debian的也有基于CentOS的容器运行时对cgroup版本、iptables兼容性都不一样。如果后面要跑Kubernetes容器引擎的cgroup driver必须配成systemd否则kubelet会一路报错。第三Harbor版本。建议选择2.x较新的长期维护版本2.11及以上的安装包依赖Docker Compose v2。很多老教程还在用docker-composev1在新版本Harbor上会直接安装失败。我们这次用的是harbor-offline-installer-v2.11.0.tgz在出口机上下载后带进内网后面细说。这三个点落实了后面才是纯粹的“体力活”。3. 离线部署实操全流程3.1 阶段一在出口机整理清单并下载物资先把所有需要的外网资源列成一张清单宁可多下也不要少下。我这次整理的清单大概长这样类别物件备注容器运行时docker-24.0.9.tgz官方静态二进制包不依赖系统软件源编排工具docker-compose-plugin、helm二进制按CubeStudio交付方式准备镜像仓库harbor-offline-installer-v2.11.0.tgzHarbor离线安装包平台镜像cube-studio相关的全量镜像按架构区分arm64/amd64基础镜像ubuntu、python、node、jdk等如果客户会用平台跑自定义任务强烈建议提前备好辅助工具jq、curl、vim、tar等系统不自带的工具提前准备好下载顺序建议是先和厂商确认CubeStudio交付包形式和Harbor版本再根据内部镜像清单拉取基础镜像。为了避免架构踩坑在出口机上拉取CubeStudio镜像时尽量用docker pull --platformlinux/arm64这样的参数把目标架构固定下来。如果出口机是Ubuntu/Debian系另一个省事的办法是直接下载Docker官方提供的静态二进制tar包解压后放到/usr/bin即可不需要处理发行版的软件源依赖问题。这也是我在Harbor主机和应用服务器上统一采用的方式后面不再为缺少某个依赖包发愁。3.2 阶段二镜像导出、压缩、分卷与校验镜像导出看着简单但大镜像在摆渡环节最容易出问题。安全U盘或者刻录光盘有容量限制介质在携带过程中也可能损坏所以导出这一步一定要做三件事压缩、分卷、校验。在出口机上的操作大致是这样# 拉取目标架构的镜像 docker pull --platformlinux/arm64 registry.example.com/library/cube-studio:2.1.0 # 导出并压缩按4GB分卷 docker save registry.example.com/library/cube-studio:2.1.0 | gzip | split -b 4G -d -a 2 - cube-studio_2.1.0.tar.gz.part # 生成校验文件 sha256sum cube-studio_2.1.0.tar.gz.part* cube-studio_2.1.0.SHA256SUMS这里拆开说一下。split -b 4G -d -a 2表示按4GB切分、数字后缀、两位编号生成.part00、.part01这样的文件。为什么选4GB因为很多安全介质和审批流程对单个文件大小有限制4GB是一个比较通用的上限。校验文件一定不能省目标机导入之前先跑一遍sha256sum -c防止介质损坏导致脏数据进入内网。导入的时候在目标机上反向操作cat cube-studio_2.1.0.tar.gz.part* | gzip -d | docker load docker images | grep cube-studio注意一个细节docker load会把镜像的原始tag信息带进来也就是出口机上带域名或IP的原始仓库地址。走到这一步镜像已经在目标机上了后面还需要重新打tag推到Harbor所以先不用纠结原始tag是什么。3.3 阶段三在内网部署Harbor私有仓库Harbor主机我习惯单独给一台配置不用太高CPU 4核、内存8GB、磁盘按镜像增长计划预留200GB以上基本够用。部署前先确认机器能不能装Docker。以静态二进制方式安装Docker为例tar -xzf docker-24.0.9.tgz cp docker/docker docker/dockerd docker/containerd docker/containerd-shim-runc-v2 docker/runc /usr/bin/ # 创建docker systemd unit然后启动 systemctl daemon-reload systemctl enable --now docker这里有一个细节容易被忽略静态二进制方式安装的dockerd默认数据目录是/var/lib/docker。如果系统盘分区不大一定要先把数据目录迁到独立数据盘比如在/etc/docker/daemon.json里设置data-root: /data/docker。Harbor自身的业务数据会放在安装目录下的/data目录比如/opt/harbor/data这个也要提前规划好磁盘和挂载点。然后把Harbor离线安装包拷进去解压编辑harbor.ymlhostname: 192.168.209.133 http: port: 80 # 如果内网不需要TLS直接注释掉https段 # https: # port: 443 # certificate: /your/cert.pem # private_key: /your/key.pem harbor_admin_password: YourStrongPassword data_volume: /opt/harbor/data这里有几个容易踩坑的点单独说下。hostname必须写成其他节点都能访问到的内网IP或域名不要写localhost否则后面所有节点推镜像都会失败。如果不打算用TLS就把https段整体注释掉只保留http段。自签名证书方案我不是很推荐因为证书分发到所有节点本身就是一件麻烦事隔离网里一张证书漏发了某个节点就会一直报x509错误。改完配置之后执行安装./install.sh安装脚本会检查docker compose版本和端口占用。如果系统里没有docker compose命令脚本会直接报错需要先把compose plugin装上或者下载docker-compose静态二进制放到/usr/local/bin目录。install完成之后直接验证curl -s http://192.168.209.133/v2/ docker compose ls访问/v2/返回{}就说明registry API已经正常起来了。3.4 阶段四把镜像推送到Harbor并部署CubeStudioHarbor起来之后先在Web界面上创建一个项目我这里叫cstudio。然后把阶段二load进来的本地镜像重新打tag并推送docker tag registry.example.com/library/cube-studio:2.1.0 192.168.209.133/cstudio/cube-studio:2.1.0 docker login 192.168.209.133 -u admin -p YourStrongPassword docker push 192.168.209.133/cstudio/cube-studio:2.1.0如果推送时报http: server gave HTTP response to HTTPS client几乎可以确定是dockerd默认走https而Harbor只开了http。解决办法是在每台应用服务器的/etc/docker/daemon.json里配置insecure-registries{ insecure-registries: [192.168.209.133], data-root: /data/docker, exec-opts: [native.cgroupdriversystemd] }然后systemctl restart docker。注意这一步会让该机器上已有容器重启或停止生产环境务必提前安排维护窗口别在业务高峰期动daemon配置。如果CubeStudio是用docker compose交付的把官方给的compose文件拷到目标机把里面的image字段全部替换成192.168.209.133/cstudio/...再执行docker compose pull docker compose up -d如果CubeStudio是Kubernetes/Helm方式交付同样是在出口机上下载helm二进制和chart包在values文件里覆盖镜像仓库地址和imagePullSecrets再执行helm install。以K8s方式部署时先创建一个私有仓库的拉取凭据kubectl create secret docker-registry harbor-secret \ --docker-server192.168.209.133 \ --docker-usernameadmin \ --docker-passwordYourStrongPassword \ -n cstudio然后在Deployment里加上imagePullSecrets引用。哪个方式不是本质本质是让所有镜像来源都指向内网Harbor这样后续所有节点的镜像拉取行为都是可控、可追踪的。3.5 阶段五验证、备份与交付物整理部署完不能只看容器状态。我一般按这个顺序验证docker compose ps或kubectl get pods确认没有异常退出的容器检查业务端口是否监听例如CubeStudio的控制台和API端口登录控制台走一遍登录、创建、运行的最小流程确认日志没有持续报错特别是依赖数据库、消息队列的模块在另一台应用服务器上执行docker pull 192.168.209.133/cstudio/...验证Harbor作为内网镜像源的可用性。验证通过之后第一时间备份Harbor的配置和数据目录。Harbor的data_volume目录是整个仓库的根后续恢复全靠它应该纳入客户的备份体系。备份命令很简单把整个目录打包拷贝走就行。交付物这块我强烈建议最终交付资料里至少包含三样东西完整镜像清单含sha256、部署操作手册含yaml和命令、运维排障速查表。隔离网环境下排查问题不容易文档做厚一点后面的人会感谢你。4. 常见问题与排查技巧实录4.1 推送报错get https://192.168.209.133/v2/: dial tcp 192.168.209.133: connect: connection refused这个错误在Harbor现场几乎每天都能看到。拆解一下docker客户端以为Harbor是可信任的https仓库所以去访问443端口但对方服务根本没起来或者压根没有监听443于是TCP连接被拒绝。排查顺序是先看Harbor容器有没有正常运行执行docker compose ps再看端口有没有监听执行ss -tlnp | grep 80最后从应用服务器上curl测试。如果Harbor机器本机curl是通的换一台机器就不通那就要查防火墙、安全组和交换机ACL了。还有一种隐藏情况Harbor的install.sh安装过程中如果数据库或Redis初始化失败Harbor核心容器会反复重启端口时通时断。这时候要去看Harbor容器日志比如docker compose logs core和docker compose logs db通常会给出明确的报错信息。4.2 镜像拉取报“x509: certificate signed by unknown authority”这个问题常出在自签名证书场景。如果Harbor启用了https但没有把CA证书分发到所有节点docker就会因为不信任该证书而拒绝连接。内网环境我优先建议直接走httpinsecure-registries省掉维护证书的环节。如果监管要求必须走TLS那就要统一给所有需要拉镜像的节点配置Harbor的CA证书。Linux节点放到/etc/docker/certs.d/harbor地址/ca.crt配置好后systemctl restart docker。注意目录名一定是Harbor的hostname和端口比如/etc/docker/certs.d/192.168.209.133:443/ca.crt写错路径一样不生效。4.3 登录后推镜像还是报401 UnauthorizedHarbor的项目默认是私有的docker login成功了推送到一个当前用户没有权限的项目也会被拒绝。还有一个容易忽略的点如果使用了Harbor的机器人账号机器人账号只对它被授权的项目有效。本地凭据缓存也是一个坑。可以用docker logout退出再重新docker login一次排除旧凭据干扰。在批量部署节点时建议给每一台节点都配置独立的机器人账号或统一账号避免一个账号多设备登录被Harbor的登录策略限制住。4.4 容器起来报exec format error架构没有对号入座这个报错的意思很直接二进制和CPU架构不匹配。ARM机器上跑amd64镜像就会这样。赶紧用docker inspect image --format {{.Architecture}}看镜像架构用uname -m确认机器架构。提醒一个实际操作中的细节如果你在出口机上用x86机器拉取ARM镜像一定要加--platformlinux/arm64否则docker会按当前机器架构拉取。如果已经拉错了可以先docker rmi删掉再重新拉。信创环境多架构并存很常见建议所有镜像清单里都把架构字段写明避免时间久了搞混。4.5 Windows Server 2022上跑WSL containers的离线准备现在也有不少边缘节点是Windows Server 2022客户要求用WSL containers方式跑Linux容器。这种环境离线部署更繁琐WSL的内核更新包msi和发行版rootfs都要在出口机上下载好然后在目标机离线安装WSL并手动注册Linux发行版。容器引擎本身用containerd或Docker静态二进制。如果客户环境用了这种方式建议在项目交付前做一次预验证因为Windows安全补丁和WSL内核版本经常互相牵制很容易遇到“WSL启动正常但containerd起不来”的情况。能不用WSL containers就尽量不要用纯Linux物理机或虚拟机部署的稳定度要高一个量级。4.6 Harbor版本升级的几个坑Harbor版本升级最怕的是数据卷丢失。升级前先执行docker compose down注意千万别加-v参数-v是删卷的会把数据库和registry数据全清掉。然后打包备份data_volume整个目录再用新版本的offline installer解压到新的目录执行./install.sh。Harbor会自动检测已有数据并保留。升级时还有一个常见问题很多人直接替换了harbor.yml导致数据库密码、Redis密码和已有组件不一致Harbor起不来。正确做法是先备份原harbor.yml再按官方模板逐项对比修改只改必要的hostname、端口和数据目录其他密码字段不要动。最后再说几句这个流程跑通之后我自己最大的感受是隔离网部署拼的不是技巧而是前置准备和文档沉淀。出口机的流程确认、镜像清单的整理、校验值的留存这些事看着琐碎却是整个项目能不能按时交付的关键。后续如果要扩容或升级版本直接照着交付包里的部署手册和镜像清单走一遍就行不用再临时下载任何东西。也建议所有做信创交付的团队都把自己常用的离线部署包做成统一模板每一次项目都往模板里补充新的依赖和踩过的坑用着用着你就会发现最复杂的现场反而变成了最标准化的现场。
