手把手教你在企业内网离线部署Kubernetes集群：镜像抓取、私有Harbor与配置调校全指南

许多企业的核心生产环境，为了严格的安全管控，往往被置于一个与互联网完全隔绝的内网中。当你接到任务，要在这个“信息孤岛”里，一次性部署起一个包含操作系统、中间件、数据库乃至全套监控组件的 Kubernetes集群 时，第一个冒出来的念头可能就是：那些成千上万的Docker镜像，该怎么弄进来？

离线部署完整K8S集群的本质，是一场精心策划的“镜像大迁移”，核心目标是把外部世界的所有依赖，安全、完整地搬运并安置到内部私有仓库中。

这篇指南不会空谈理论，而是聚焦于可落地的操作。我会假设你手头有一台能临时连接外网的跳板机，然后一步步带你完成镜像抓取、安全传输和配置适配的全过程，所有命令你都可以直接复制粘贴，用到自己的环境里。

第一步：跳板机行动——镜像的全面抓取与打包

这台能上外网的跳板机，是你此次行动唯一的“采购窗口”。它的任务很明确：把部署整个K8S集群所需的所有容器镜像，一个不落地下载并打包好。

首先，你得有一份清晰的“采购清单”，也就是所有必需的镜像列表。如果你计划使用Kubespray部署，可以运行它的脚本 contrib/offline/generate_list.sh 来生成。如果选用Helm，则需要仔细梳理每个Chart的 values.yaml 文件，把里面定义的镜像地址提取出来。最终，你得到一个像 images.txt 这样的文件，内容大致如下：

k8s.gcr.io/pause:3.2
docker.io/nginx:1.21.1
quay.io/coreos/etcd:v3.4.13

接下来是批量下载。这里强烈推荐使用 skopeo 工具，因为它不依赖本地Docker守护进程，可以直接操作镜像仓库，非常适合批量作业。安装skopeo后，可以用一个简单的循环命令完成抓取：

mkdir -p offline-images
while IFS= read -r image;do
# 将镜像复制到本地目录格式，目录名即为镜像名（需处理斜杠）
 target_dir=$(echo "$image"| sed 's|[/:]|_|g')
 skopeo copy docker://"$image" dir:./offline-images/"$target_dir"
done < images.txt

使用skopeo的dir格式存储镜像，保留了完整的元数据，并且每个镜像独立存放，方便后续检查和部分更新，这是比直接打包成一个tar文件更灵活的策略。

当然，如果你对Docker命令行更熟悉，也可以选择传统方式。但务必确保所有镜像都已拉取到本地：

# 先拉取所有镜像
xargs -L1 docker pull < images.txt
# 然后将所有镜像打包成一个文件
docker save $(docker images --format="{{.Repository}}:{{.Tag}}"| grep -v "<none>") -o all-images.tar

无论用哪种方法，最终你都在跳板机上得到了一个完整的镜像包，准备踏上前往内网的旅程。

第二步：架起桥梁——自动化搬运与私有仓库导入

如何把跳板机上的“战利品”安全送进内网，并让私有Harbor仓库接纳它们，是这一步要解决的核心问题。手动搬运不仅效率低，还容易出错，因此编写一个自动化脚本至关重要。

假设内网已经部署好了Harbor，地址是 harbor.your-company.com。我们的脚本需要完成两段工作：一是在跳板机上打包并传输，二是在内网机器上接收并导入。

跳板机端脚本（例如 transfer.sh）可能包含以下内容：

#!/bin/bash
# 1. 压缩镜像目录
tar -czf k8s-offline-images-$(date +%Y%m%d).tar.gz ./offline-images/

# 2. 计算校验和，确保传输完整性
md5sum k8s-offline-images-*.tar.gz > image-package.md5

# 3. 使用scp安全拷贝到内网中转服务器（需提前配置好ssh免密登录）
INTERNAL_SERVER="user@10.0.0.100"
REMOTE_PATH="/tmp/offline-packages/"
scp k8s-offline-images-*.tar.gz image-package.md5 $INTERNAL_SERVER:$REMOTE_PATH

echo “镜像包已传输至内网服务器。”

内网服务器端脚本（例如 import_to_harbor.sh）则负责解压和导入：

#!/bin/bash
HARBOR_HOST="harbor.your-company.com"
HARBOR_PROJECT="library"
PACKAGE_PATH="/tmp/offline-packages/"

# 1. 验证文件完整性
cd $PACKAGE_PATH
md5sum -c image-package.md5

# 2. 解压镜像包
tar -xzf k8s-offline-images-*.tar.gz -C .

# 3. 遍历目录，使用skopeo将镜像推送到Harbor
for image_dir in offline-images/*/; do
# 从目录名还原镜像原始名称（根据之前替换的规则）
 original_image=$(basename "$image_dir"| sed 's|_|/|g'| sed 's|_|:|')
# 推送到Harbor
 skopeo copy dir:"$image_dir" docker://$HARBOR_HOST/$HARBOR_PROJECT/"$original_image" --dest-creds "admin:Harbor12345"
done

echo “所有镜像已成功导入Harbor仓库。”

这个自动化流程的精髓在于将传输和导入解耦，通过校验和确保数据一致性，并利用skopeo实现与仓库无关的镜像推送，使得整个搬运过程可靠且可重复。

第三步：关键调校——让部署配置指向内部仓库

镜像已经安然存放在内网的Harbor里了，但Kubernetes的部署工具（Helm或Kubespray）并不知道这一点。它们配置里写的还是诸如 k8s.gcr.io/pause:3.2 这样的公共地址。因此，我们必须给这些配置“换脑”，让它们指向我们的新家。

对于使用Helm部署的场景，你需要准备一份定制化的 values.yaml。一个高效的方法是编写脚本，基于原始的values文件进行全局替换：

#!/bin/bash
HARBOR_PREFIX="harbor.your-company.com/library"
ORIGINAL_VALUES="original-values.yaml"
CUSTOM_VALUES="custom-values.yaml"

# 使用sed命令替换所有镜像仓库地址
# 注意：这个正则表达式需要根据你values.yaml的实际格式进行调整，可能更复杂
sed "s|image: \([^:]*\)\(:[^\n]*\)|image: $HARBOR_PREFIX/\1\2|g; s|repository: \([^\n]*\)|repository: $HARBOR_PREFIX/\1|g" $ORIGINAL_VALUES > $CUSTOM_VALUES

# 然后使用这份定制化的values文件安装Chart
# helm install my-release ./my-chart -f $CUSTOM_VALUES

如果你选择Kubespray，配置修改则集中在它的变量文件里。你需要编辑 inventory/mycluster/group_vars/all/offline.yml（如果没有就创建）：

# 关键配置：指定私有仓库地址
registry_host: "harbor.your-company.com"
# 对于Kubernetes核心组件镜像
kube_image_repo: "{{ registry_host }}/library"
# 对于其他依赖镜像，如etcd, coredns等
etcd_image_repo: "{{ registry_host }}/library"
calico_image_repo: "{{ registry_host }}/library"
# ... 其他镜像仓库变量同理

# 确保设置为离线模式
offline_mode: true

配置替换绝非简单的字符串查找，你必须深入理解部署工具的配置结构，确保每一个可能拉取镜像的环节——包括初始化容器、网络插件、日志收集agent——都被正确覆盖，否则部署过程就会在等待一个永远拉不下来的镜像中卡死。

完成配置适配后，在内网环境中，你就可以运行最终的部署命令了，例如执行Kubespray的ansible-playbook，整个过程将不再需要访问任何外部网络。

收尾与展望：部署之后，运维之路才真正开始

当你看到第一个Pod成功进入Running状态，内网Kubernetes集群的脉搏开始跳动时，这次离线部署的攻坚战才算告一段落。但作为运维，心里都明白，部署成功只是故事的开始。

你需要建立一套机制，来应对后续的镜像更新。比如，定期在跳板机上执行一个同步脚本，抓取安全更新后的新镜像版本，然后重复搬运和导入流程。同时，内网Harbor的镜像扫描和漏洞管理功能也应该被充分利用起来。

真正的 运维自动化 能力，体现在将一次性的复杂操作沉淀为标准化、自动化的流程，并具备持续维护和演进这套离线资产的能力。

最后，别忘了文档。将这次过程中用到的镜像列表、脚本、配置修改点详细记录下来。这不仅是为了以后自己能快速复盘，更是为了当团队里有新人需要接手时，他们能循着清晰的路径，而非在迷宫里摸索。希望这份指南，能成为你构建稳定内网基础设施的一块坚实垫脚石。如果你在实践中遇到了更复杂的情况或有独到的见解，欢迎来 云栈社区 分享交流。