企业官网建设流程全解析

简介：ks-core-1.1.3.tgz 是一份面向 Kubernetes 运维与平台研发人员的 Helm Chart 资源包，主要解决在离线或受控网络环境下快速部署集群核心组件、以及按需调整默认配置的问题。压缩包体积 80KB，包含 120 个文件，其中 yaml 文件承担工作负载与服务配置，tpl 模板负责把参数渲染为最终资源清单，sh 脚本封装安装、卸载等生命周期操作，rego 文件用于策略评估，配套的 README 与 helmignore 也让定制与发布更规范。对希望深入 K8s 生态的读者而言，这份资源提供了一个结构完整、体量轻巧的真实案例，可以从中学习 Helm Chart 的目录组织、变量传递和钩子脚本设计。目前已有 260 人学习/下载，适合用来比对不同版本 ks-core 的差异，或在本地解析扩展规则与自定义资源过滤器，作为二次开发和离线部署的参考资料。

1. 拿到 ks-core-1.1.3.tgz 之后，先搞清楚它是什么

1.1 从包名看门道：tgz、版本号、组件定位

先说说这个文件名的构成。ks-core-1.1.3.tgz拆开看就是三个信息：ks-core是项目名，1.1.3是版本号，.tgz是打包格式——本质是 tar 归档后用 gzip 压缩，在 Linux 服务器上最常见的那种分发格式，等价于.tar.gz。对于做容器平台运维的人来说，看到 tgz 基本就能猜到，这八成是离线安装包或者 Helm Chart 的压缩分发版本。

那么ks-core到底是什么？这里要引入一个背景：KubeSphere 是目前国内使用率很高的开源容器管理平台，它的架构不是一个大单体，而是拆成了很多组件协同工作。其中ks-core是 KubeSphere 4.x 之后的核心控制面组件，负责整个平台自身的生命周期管理，包括 Console 控制台、认证鉴权、多租户管理、扩展组件（Extension）的安装与卸载等。换句话说，KubeSphere 的很多外围功能模块都是通过 ks-core 来调度安装的，它相当于整个平台的操作系统内核。

所以拿到这个 tgz，你要做的第一件事不是急着解压，而是先确认它是给什么环境用的、解决了什么问题。ks-core-1.1.3.tgz这个版本主要面向 KubeSphere 4.x 的离线部署场景，适合那些网络隔离、无法直接访问公共镜像仓库的生产环境，或者需要在已有 Kubernetes 集群上快速拉起一套 KubeSphere 底座的情况。你要是还在用 KubeSphere 3.x 那套 ks-installer 的方式，那和 4.x 的 ks-core 完全是两条路线，千万别搞混。

1.2 为什么 KubeSphere 把核心能力单独打包成一个 Chart

在 KubeSphere 4.x 里，官方把原来 kr-installer 的职责做了拆分，核心能力收敛到ks-core这个 Helm Chart 里，外围功能全部改成通过扩展机制动态安装。这个设计变化其实非常关键，我们作为使用者需要理解背后的逻辑，否则在实际部署时很容易迷茫。

第一，降低安装耦合度。老版本的 KubeSphere 把监控、日志、告警、服务网格等一堆组件全部揉在安装流程里，即使你只需要一个简单的多租户管理面，它也把所有组件都拉起来，资源占用大、失败率高。ks-core 只保留最核心的底座能力，把可选组件全部后置，这样安装时你只需要关注最小集，跑起来之后按需再装。

第二，适配离线交付场景。企业内网环境普遍扫描不了外部镜像仓库，而 tgz 格式的 Chart 包加配套的镜像 tar 包，是现在离线交付的主流做法。官方发布 ks-core 的 tgz，就是要配合helm install直接消费这个包，或者通过 KubeSphere 的扩展市场在离线环境下导入。

第三，版本迭代更轻量。核心控制面和外围模块解耦之后，升级核心组件不会牵连业务插件，回滚的爆炸半径也变小了。在 1.1.3 这个版本里，你可以看到 ks-core 对 Kubernetes 版本兼容性、KubeSphere 扩展 API 的稳定性都有明确的约束，这些在安装前都要仔细对一遍。

提示：如果你拿到的是 ks-core 而不是 ks-installer，说明你走的 KubeSphere 4.x 部署路线。不要在 3.x 的文档里搜安装方法，也不要拿 ks-installer 的账号密码配置逻辑来套 ks-core，版本不对，操作全白费。

2. 拆包与内容解读：拿到 tgz 之后的第一件事

2.1 安全校验与解包：别急着 tar xf

我见过不少人拿到 tgz 就直接tar xf解压，然后丢到服务器上开始配，这是有隐患的。一是你无法确认这个包在传输过程中有没有被篡改，二是不知道 Chart 内部的 values 默认值是否符合你的集群环境。所以拿到ks-core-1.1.3.tgz之后，建议先走一遍校验和解包流程。

如果你是从官方 Release 页面下载的，旁边通常会有对应的sha256校验值。在 Linux 上执行：

$ sha256sum ks-core-1.1.3.tgz

把输出的哈希值和官方页面给的比对，一致再继续。这一步看起来多此一举，但在生产环境，尤其是内网离线环境，包经常是经过多次拷贝、U盘搬运、甚至通过不同网段中转的，任何一步出错都可能导致安装时出现奇怪的异常。校验一次花不了十秒钟，能省掉后面几小时的排查时间。

校验通过后，解包：

$ tar xzf ks-core-1.1.3.tgz $ tree -L 2 ks-core

解压出来你会看到标准的 Helm Chart 目录结构，核心的东西是Chart.yaml、values.yaml、templates/目录。这里我建议把Chart.yaml打开看一眼，确认apiVersion、appVersion、kubeVersion这几个字段和你用的 Kubernetes 集群版本是否匹配。

2.2 Chart 内部目录结构解析

解压之后，重点看这三个文件：

Chart.yaml里记录的是 Chart 元数据。ks-core-1.1.3这个包的kubeVersion约束一般是>=1.23.0，如果你用的是 1.20 或更老的集群，直接安装会报兼容性错误。这个字段是 Helm 在安装阶段就会校验的，提前看清楚能避免无谓的报错。

values.yaml是整个安装的核心，里面定义了 ks-core 启动后的所有可调参数，包括镜像仓库地址、镜像拉取策略、服务类型（NodePort 还是 LoadBalancer）、控制台访问地址、存储类、资源配额等。我建议在安装前完整读一遍这个文件的注释，尤其是下面几个关键项：

• imageRegistry和imagePullSecret：指定镜像仓库地址和拉取凭证，离线环境必须把仓库指向内网镜像源，否则安装时会去公网拉镜像导致超时失败。
• console配置段：控制台暴露方式和域名配置，涉及到你之后怎么访问 KubeSphere 界面。
• extension配置段：要不要启用扩展市场，离线环境下这个通常先关闭，等核心组件装好后再手动导入扩展包。

templates/目录下是渲染 Kubernetes 资源的模板，这个不建议改动，除非你有特殊的定制需求。你要是对 Helm 模板语法不熟，改坏的代价远大于收益。

注意：values.yaml 里改参数时，注意 YAML 的缩进格式。我见过太多人因为复制粘贴时 Tab 和空格混用，导致helm install的时候 YAML 解析直接报错。建议统一用两个空格缩进，用vim编辑时打开set expandtab。

3. 部署实操：从 tgz 到一套可用的 KubeSphere

3.1 环境准备与前置条件核对

开始安装之前，先把环境对一遍。按照我实际的部署经验，需要确认以下条件：

第一，Kubernetes 集群本身要健康。执行kubectl get nodes，确保所有节点状态是 Ready，kubectl get pods -n kube-system看核心系统组件是否稳定。如果集群本身有问题，比如 CoreDNS 挂掉、kube-proxy 异常，那 ks-core 装上去也不会正常跑。

第二，确认有足够的资源。ks-core 最小安装大概需要 2 核 CPU、4G 内存，如果还要跑 KubeSphere 的监控和日志组件，建议至少准备 4 核 8G。资源不够的话，安装过程中 Pod 会一直 Pending，看着就像卡住了。

第三，确认存储类。KubeSphere 需要一套可用的 StorageClass 来创建 PVC。用kubectl get sc查看集群里有没有默认的 StorageClass，如果显示<none>，要么装一个，要么在 values 里显式指定。

第四，准备镜像仓库。离线环境一定要有一个内网镜像仓库，比如 Harbor，然后把 ks-core-1.1.3 配套的镜像全部推到内网。如果官方给你的是镜像 tar 包，用docker load导进来，再重新 tag 推到内网仓库，这一步不能省。

这些前置条件看起来麻烦，但每一项都是踩过坑换来的。我最早做离线部署时，以为直接把包丢上去装就行，结果镜像拉不下来、存储类没配、节点资源不足，三个问题轮流出现，装了三遍才成功。所以别嫌麻烦，先花十分钟把环境对好，后面一次过。

3.2 使用 Helm 安装 ks-core

环境准备好之后，安装本身其实不复杂。先创建一个独立的命名空间，建议用kubesphere-system：

$ kubectl create namespace kubesphere-system

然后在解压出来的 ks-core 目录下，用 Helm 安装：

$ cd ks-core $ helm install ks-core . -n kubesphere-system \ --set imageRegistry=harbor.example.com/kubesphere \ --set imagePullSecret=kubesphere-registry-secret \ --set console.type=NodePort \ --set console.nodePort=30880

这里解释一下关键的参数：

• imageRegistry：指向你内网镜像仓库的地址，确保 ks-core 的所有镜像从这个源拉取。
• imagePullSecret：如果内网仓库是私有的，需要先创建这个 Secret，否则 Pod 拉镜像时没权限会一直 ImagePullBackOff。
• console.type=NodePort和console.nodePort=30880：通过节点端口暴露 KubeSphere 控制台，这是离线环境里最常见的访问方式。如果你在云上装了 LoadBalancer 插件，也可以改成LoadBalancer模式。

执行helm install后，它会返回提示信息，告诉你 release 的名称、命名空间、以及如何查看安装状态。等待 Pod 拉起来，用下面命令观察：

$ kubectl get pods -n kubesphere-system -w

正常情况下你会看到ks-apiserver-*、ks-console-*、ks-controller-manager-*这组 Pod 依次进入 Running 状态。等待的时间取决于内网镜像源的速度，通常 1 到 3 分钟就能全部就绪。

3.3 验证安装并获取初始账号

安装完成后，验证一下核心服务是否正常。先看 Pod 状态，再用curl探测一下 API 接口：

$ kubectl get pods -n kubesphere-system $ curl -I http://<任意节点IP>:30880

如果返回HTTP/1.1 200 OK，说明控制台已经可以访问了。默认的初始账号是admin，密码需要从 Kubernetes Secret 里取：

$ kubectl get secret -n kubesphere-system ks-console-secret -o jsonpath="{.data.password}" | base64 -d

这里的逻辑是，ks-core 在初始化时会自动生成一个随机密码并存入 Secret，取出来就是首次登录的凭证。登录后系统会强制让你修改密码，这个流程跟主流平台的初始密码逻辑一致。

提示：初始密码取出来建议立刻修改。另外，如果是纯离线环境，控制台登录后可能提示“无法访问扩展中心”，这是正常的，因为扩展中心需要外网连接。你需要把扩展包离线导入才能使用完整功能。

4. 版本升级与回滚：1.1.3 如何落位到存量环境

4.1 从旧版本升级到 1.1.3

如果你之前已经部署了 ks-core 的旧版本，比如 1.1.2 或 1.1.1，想在现有环境上升级到 1.1.3，不需要卸载重装，直接用 Helm 的升级命令即可。

首先，把新包解压出来，然后执行：

$ helm upgrade ks-core ./ks-core -n kubesphere-system \ --set imageRegistry=harbor.example.com/kubesphere \ --set imagePullSecret=kubesphere-registry-secret

升级前有一个非常重要的操作：备份现有配置。说白一点，就是把你当前的 values 参数导出来，防止升级时新默认值覆盖你之前调过的参数：

$ helm get values ks-core -n kubesphere-system > ks-core-values-backup.yaml

执行升级后，观察 Pod 的滚动更新情况。ks-core 的升级策略是滚动更新，理论上不会中断服务，但ks-apiserver重启的那几十秒里，正在执行的 API 请求会短暂失败，这个在业务高峰期升级时要留意。升级完成后，再次验证控制台访问和 API 状态。

4.2 回滚策略与数据保护

升级失败怎么办？Helm 天然支持版本回滚。升级前先记录一下当前 release 的版本号：

$ helm history ks-core -n kubesphere-system

如果升级后出现异常，通过--revision参数回滚到之前的版本：

$ helm rollback ks-core <上一个版本号> -n kubesphere-system

还有一个容易被忽略的点：ks-core 的配置存储在 ConfigMap 和 Secret 中，升级过程中 Helm 会渲染新的配置，如果新版模板对某个参数做了结构调整，旧参数可能被忽略，导致配置“感觉丢了”。所以回滚之后，最好核对一下关键配置是否还在。

另外，ks-core 本身管理了 KubeSphere 的自定义资源（CRD），升级时如果新增了 CRD，Helm 3 默认不会自动帮你删掉旧的 CRD，也不会更新已有 CRD 的 schema。遇到 CRD 相关问题，可能需要手动kubectl apply新包里的 CRD 文件。这一步往往是升级后出现“某些资源无法创建”的根源。

注意：回滚只解决 ks-core 自身的软件状态，如果你在升级过程中做过 CRD 迁移或数据目录的变更，回滚不会自动恢复数据。生产环境强烈建议升级前对 etcd 做一次快照备份，这是 Kubernetes 集群层面的兜底手段。

5. 常见问题与排查实录

5.1 安装卡在等待组件就绪

这是我在离线部署时遇到最多的问题。helm install执行后，几个 Pod 一直处于 Pending 或 ContainerCreating 状态，看起来就像卡死了一样。排查思路按顺序来：

第一步，先看 Pod 事件：

$ kubectl describe pod -n kubesphere-system <pod-name>

最常见的原因有三个：节点资源不足导致 Pending；PVC 无法绑定，因为没有可用的 StorageClass；镜像拉取失败，因为镜像仓库地址配错或者没有配 Secret。这三个问题通过describe的事件输出基本都能直接看出来。

第二步，看 kubelet 日志。如果 ContainerCreating 卡了很久，大概率是拉取镜像超时或者挂载卷失败。这种问题在公网环境不常见，但在内网离线环境，镜像仓库带宽低、镜像体积大，就很容易触发。

第三步，如果所有 Pod 都卡在 Init 阶段，重点看 init container 的日志，一般是 ks-core 在初始化数据库或等待依赖服务就绪。

5.2 镜像拉取失败的排查思路

离线环境镜像拉取失败是另一个高频问题。表现形式是 Pod 状态是ImagePullBackOff，执行kubectl describe pod能看到类似Failed to pull image的报错。

排查方向有这么几个：

• 确认imageRegistry参数指向的地址在当前集群所有节点上都能访问。有时你只在一台节点上测试了连通性，但其他节点访问不到内网仓库，就会出现一部分 Pod 正常、一部分拉取失败。
• 确认镜像仓库里确实有对应 tag 的镜像。ks-core 的镜像 tag 和 Chart 版本强关联，比如v1.1.3，不要想当然地用latest。
• 确认 Secret 是否存在且有效。私有仓库的认证信息如果过期了，也会报拉取失败。可以用kubectl get secret -n kubesphere-system检查，必要时重新创建。

如果实在排查不出，给你一个笨但有效的办法：手动在节点上docker pull一次对应镜像，把完整的错误信息贴到搜索引擎里查，比猜要快得多。

5.3 控制台无法访问

装好了但控制台打不开，这是最后一步最容易遇到的坑。确认访问地址对不对，路径、IP、端口都要核对。NodePort模式下访问的是任意节点 IP 加 NodePort，不是集群内部 IP，也不是 Pod IP。

如果地址没问题，看 Pod 日志：

$ kubectl logs -n kubesphere-system deploy/ks-console

控制台日志里如果有connection refused或proxy error，大概率是控制台连不上ks-apiserver。检查一下 Service 和 Endpoint 是否正常。我曾经遇到过一次 Control Plane 节点和 Worker 节点在安全组上没有放通 NodePort 端口，结果外部一直访问不通，防火墙规则把它挡掉了。

还有一个容易被忽视的小问题：浏览器缓存。老版本控制台的 JS 资源被浏览器缓存了，导致新版本界面渲染异常。这种情况清一下缓存或者用无痕模式验证一下，别一开始就怀疑服务有问题。

我把这些高频问题整理成一个速查表，方便你按图索骥：

6. 一些实操心得与扩展建议

最后分享几个我实际用下来的经验和建议。

第一，关于离线包的保存。ks-core-1.1.3.tgz这类 tgz 包体积不大，但配套的镜像包往往有几个 GB，最好是在内网机器上保留一份原始包和镜像包的双重备份，同时记录官方发布的 sha256 值，方便后续校验。

第二，关于配置管理。建议把安装时用的values.yaml单独存放到 Git 仓库里，和集群目录分开维护。这样不管是后续升级、重建环境，还是给别人交接，都能快速还原你的部署基线。我吃过亏，当时图省事没留 values 文件，后来集群出问题要重装，只能对着默认值一个个回忆之前改过什么。

第三，关于扩展组件。ks-core 装好后，建议先别急着在生产环境装扩展，先在测试环境把 KubeSphere 的扩展机制跑通一遍，理解扩展包的格式和依赖关系之后，再上生产。扩展包的安装顺序其实有讲究，某些扩展依赖其他扩展，装错顺序会有一堆奇怪的错误。

第四，关于日志和监控。ks-core 本身自带了一些基础状态指标，但是生产环境建议还是独立部署 Prometheus 和 Loki，不要依赖 KubeSphere 自带的轻量监控，因为大规模集群下，自带方案的性能和完整度都不够用。

这个内容后续还可以这样扩展：如果你对 KubeSphere 4.x 的架构感兴趣，可以再深入看看它的扩展 API 定义和自定义资源模型，搞懂这些之后，你甚至可以基于 ks-core 的扩展机制开发自己的内部组件，实现和 KubeSphere 平台的无缝集成。不过在动手之前，先把基础部署和运维做扎实，毕竟核心底座稳了，上层才能放心盖楼。

本文还有配套的精品资源，点击获取