KubeSphere v3.4.1 单节点部署教程

递归侠学算法

573人浏览 · 2026-06-05 13:39:14

递归侠学算法 · 2026-06-05 13:39:14 发布

KubeSphere v3.4.1 单节点部署教程

1. 部署方案

操作系统：Ubuntu 24.04
部署方式：KubeKey 一键安装
KubeKey 版本：v3.1.2
Kubernetes 版本：v1.28.8
KubeSphere 版本：v3.4.1
集群类型：单节点 All-in-One
容器运行时：Docker
网络插件：Calico
镜像仓库：registry.cn-beijing.aliyuncs.com/kubesphereio

这套方案的关键点有两个：

KubeKey 要使用 v3.1.2
安装命令前必须带上 KKZONE=cn，这样会优先使用国内加速源下载二进制和依赖

2. 开始前先确认

本文默认你的服务器已经满足下面这些前提：

服务器网络可以访问外网
服务器里已经装好 Docker，并且 docker --version 能正常输出版本

如果你的机器还没有安装 Docker，请先把 Docker 装好，再继续本文。
因为你这次成功日志走的是 Docker + cri-dockerd 这条路线，不是 containerd 纯运行时路线。

另外说明一下：
本文没有把 ufw 防火墙配置写进主流程，因为你日志里那部分并不是最终稳定跑通的关键步骤。
如果你的服务器开启了 UFW、云安全组或其他防火墙，请你自行放通至少这些端口：

6443：Kubernetes API Server
30880：KubeSphere Web 控制台
10250：kubelet
30000-32767：NodePort 范围

3. 服务器基础准备

3.1 更新系统

先更新系统包：

sudo apt update && sudo apt upgrade -y

3.2 设置主机名

把主机名改成一个容易识别的名字，例如：

sudo hostnamectl set-hostname kubesphere-master

改完后建议重新开一个终端，或者执行：

hostname

确认主机名已经生效。

3.3 关闭 Swap

Kubernetes 默认要求关闭 Swap。

先临时关闭：

sudo swapoff -a

再把开机自动挂载 Swap 的配置注释掉：

sudo sed -i '/swap/s/^/#/' /etc/fstab

你可以用下面命令检查：

free -h

如果 Swap 一栏是 0B，说明已经关闭成功。

3.4 加载 Kubernetes 需要的内核模块

创建模块配置文件：

cat <<'EOF' | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
ip_tables
ip6_tables
EOF

立即加载模块：

sudo modprobe overlay
sudo modprobe br_netfilter
sudo modprobe ip_tables
sudo modprobe ip6_tables

3.5 配置内核转发参数

创建 sysctl 配置：

cat <<'EOF' | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
vm.swappiness = 0
EOF

让配置立即生效：

sudo sysctl --system

执行完成后，只要没有明显报错，就可以继续下一步。

4. 检查 Docker 是否正常

因为这次成功方案使用的是 Docker，所以先确认 Docker 正常：

docker --version
docker info | grep -i "Cgroup Driver"

如果 docker --version 能正常输出版本号，就说明当前环境至少具备继续安装的基础条件。

5. 下载 KubeKey

建议单独建一个目录存放安装文件：

mkdir -p ~/kubekey-v3
cd ~/kubekey-v3

先设置国内下载环境变量：

export KKZONE=cn

下载官方安装脚本：

curl -fsSL https://get-kk.kubesphere.io -o get-kk.sh

使用日志里最终成功的版本下载 KubeKey：

VERSION=v3.1.2 bash get-kk.sh

给 kk 加执行权限：

chmod +x kk

6. 生成默认配置文件

执行下面命令生成 KubeSphere 安装配置：

./kk create config --with-kubesphere v3.4.1 --with-kubernetes v1.28.8

执行完成后，当前目录会生成一个 config-sample.yaml。

7. 修改安装配置

这是整篇教程最关键的一步。
下面这份配置，就是根据你最终成功的日志整理出来的单节点可用版本。

直接用编辑器打开：

vim config-sample.yaml

把内容改成下面这样：

apiVersion: kubekey.kubesphere.io/v1alpha2
kind: Cluster
metadata:
  name: sample
spec:
  hosts:
  - {name: node1, address: 192.168.0.244, internalAddress: 192.168.0.244, user: your_user, password: "YOUR_SSH_PASSWORD"}

  roleGroups:
    etcd:
    - node1
    control-plane:
    - node1
    worker:
    - node1

  controlPlaneEndpoint:
    domain: lb.kubesphere.local
    address: ""
    port: 6443

  kubernetes:
    version: v1.28.8
    clusterName: cluster.local
    autoRenewCerts: true
    containerManager: docker

  etcd:
    type: kubekey

  network:
    plugin: calico
    kubePodsCIDR: 10.233.64.0/18
    kubeServiceCIDR: 10.233.0.0/18
    multusCNI:
      enabled: false

  registry:
    privateRegistry: "registry.cn-beijing.aliyuncs.com"
    namespaceOverride: "kubesphereio"
    registryMirrors: []
    insecureRegistries: []

  addons: []

---
apiVersion: installer.kubesphere.io/v1alpha1
kind: ClusterConfiguration
metadata:
  name: ks-installer
  namespace: kubesphere-system
  labels:
    version: v3.4.1
spec:
  persistence:
    storageClass: ""
  authentication:
    jwtSecret: ""
  local_registry: ""
  namespace_override: kubesphereio
  etcd:
    monitoring: false
    endpointIps: localhost
    port: 2379
    tlsEnable: true
  common:
    core:
      console:
        enableMultiLogin: true
        port: 30880
        type: NodePort
    redis:
      enabled: false
      enableHA: false
      volumeSize: 2Gi
    openldap:
      enabled: false
      volumeSize: 2Gi
    minio:
      volumeSize: 20Gi
    monitoring:
      endpoint: http://prometheus-operated.kubesphere-monitoring-system.svc:9090
      GPUMonitoring:
        enabled: false
    gpu:
      kinds:
      - resourceName: "nvidia.com/gpu"
        resourceType: "GPU"
        default: true
    es:
      enabled: false
      logMaxAge: 7
      elkPrefix: logstash
      basicAuth:
        enabled: false
        username: ""
        password: ""
      externalElasticsearchHost: ""
      externalElasticsearchPort: ""
    opensearch:
      enabled: false
      logMaxAge: 7
      opensearchPrefix: whizard
      basicAuth:
        enabled: false
        username: ""
        password: ""
      externalOpensearchHost: ""
      externalOpensearchPort: ""
      dashboard:
        enabled: false
  alerting:
    enabled: false
  auditing:
    enabled: false
  devops:
    enabled: false
    jenkinsCpuReq: 0.5
    jenkinsCpuLim: 1
    jenkinsMemoryReq: 4Gi
    jenkinsMemoryLim: 4Gi
    jenkinsVolumeSize: 16Gi
  events:
    enabled: false
    ruler:
      enabled: true
      replicas: 2
  logging:
    enabled: false
    logsidecar:
      enabled: true
      replicas: 2
  metrics_server:
    enabled: false
  monitoring:
    storageClass: ""
    node_exporter:
      port: 9100
    gpu:
      nvidia_dcgm_exporter:
        enabled: false
  multicluster:
    clusterRole: none
  network:
    networkpolicy:
      enabled: false
    ippool:
      type: none
    topology:
      type: none
  openpitrix:
    store:
      enabled: false
  servicemesh:
    enabled: false
    istio:
      components:
      - name: istio-ingressgateway
        enabled: false
      cni:
        enabled: false
  edgeruntime:
    enabled: false
    kubeedge:
      enabled: false
      cloudCore:
        cloudHub:
          advertiseAddress:
          - ""
        service:
          cloudhubNodePort: "30000"
          cloudhubQuicNodePort: "30001"
          cloudhubHttpsNodePort: "30002"
          cloudstreamNodePort: "30003"
          tunnelNodePort: "30004"
      iptables-manager:
        enabled: true
        mode: "external"
  gatekeeper:
    enabled: false
  terminal:
    timeout: 600

7.1 你必须改的地方

上面配置里，这几个字段一定要改成你自己的实际值：

address：改成你的服务器 IP
internalAddress：改成你的服务器内网 IP
user：改成你登录服务器的用户名
password：改成你的 SSH 密码

7.2 这份配置为什么能成功

这份配置里有几个非常关键的点：

containerManager: docker
说明这次成功方案走的是 Docker 路线，KubeKey 会自动安装 cri-dockerd
privateRegistry: "registry.cn-beijing.aliyuncs.com"
namespaceOverride: "kubesphereio"
namespace_override: kubesphereio

这三项会让镜像优先从阿里云镜像地址拉取，国内网络环境更稳。

port: 30880

KubeSphere Web 控制台会以 NodePort 方式暴露，后面浏览器访问时就用这个端口。

8. 开始安装

确认当前目录是 ~/kubekey-v3，然后执行：

export KKZONE=cn
sudo env KKZONE=cn ./kk create cluster -f config-sample.yaml

这里的 sudo env KKZONE=cn 很重要。
如果你只在当前普通用户终端执行了 export KKZONE=cn，但没有把这个变量传给 sudo，安装过程里仍然可能去国外地址下载，导致失败。

安装过程中如果看到：

Continue this installation? [yes/no]:

输入：

yes

然后回车继续。

9. 安装过程中你会看到什么

按照你的成功日志，正常情况下会依次看到这些关键动作：

下载 kubeadm、kubelet、kubectl
下载 kubecni、crictl、etcd
下载 cri-dockerd
预拉取 Kubernetes 和 Calico 镜像
执行 kubeadm init
部署 CoreDNS
部署 Calico
部署 OpenEBS 默认存储类
部署 KubeSphere ks-installer

日志里还出现了下面这条关键信息，说明 Kubernetes 主平面已经初始化成功：

Your Kubernetes control-plane has initialized successfully!

后面又继续执行了：

[DeployNetworkPluginModule] Deploy calico
[DeployKubeSphereModule] Apply ks-installer
Please wait for the installation to complete

看到这里不要着急关终端，继续等待即可。

10. 安装完成后怎么检查

10.1 查看节点状态

kubectl get nodes -o wide

正常情况下，单节点应该至少能看到：

节点名是你配置里的 node1
STATUS 为 Ready

10.2 查看 Pod 状态

kubectl get pods -A

新手这里最容易误判。
不是所有 Pod 都一定要永远显示 Running，有些 Job 类型任务显示 Completed 也是正常的。

你主要看两件事：

大部分核心组件是否已经 Running
是否还大量存在 CrashLoopBackOff、ImagePullBackOff、Pending

10.3 查看 KubeSphere 控制台端口

kubectl get svc -n kubesphere-system

如果 ks-console 的 NodePort 是 30880，就说明控制台端口和配置一致。

11. 登录 KubeSphere 控制台

浏览器访问：

http://你的服务器IP:30880

按这次配置举例，如果服务器 IP 是 192.168.0.244，那访问地址就是：

http://192.168.0.244:30880

默认管理员账号是：

用户名：admin
密码：P@88w0rd

首次登录后，系统通常会要求你修改默认密码，建议立刻修改。

12. 这次成功方案里最容易忽略的重点

12.1 不要用错 KubeKey 版本

本文最终成功的是 KubeKey v3.1.2。
如果你照着本文做，就不要自己随手换成别的主版本。

12.2 一定要保留 `KKZONE=cn`

这是这次成功安装里最重要的稳定器之一。
没有它，安装过程中下载 kubecni 这类依赖时，很容易卡在国外地址。

12.3 单节点就按单节点写，不要混进多节点配置

你这次最终成功的拓扑是：

etcd: node1
control-plane: node1
worker: node1

也就是说，一台机器同时承担所有角色。
新手第一次搭建，先把单节点跑通，是最稳的做法。

12.4 国内环境建议保留阿里云镜像仓库配置

下面三项不要删：

privateRegistry: "registry.cn-beijing.aliyuncs.com"
namespaceOverride: "kubesphereio"
namespace_override: kubesphereio

这三项是你这次成功方案里非常关键的一部分。

13. 可以直接复制执行的命令清单

如果你想按顺序快速执行，可以直接照下面这份清单操作。

sudo apt update && sudo apt upgrade -y
sudo hostnamectl set-hostname kubesphere-master

sudo swapoff -a
sudo sed -i '/swap/s/^/#/' /etc/fstab

cat <<'EOF' | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
ip_tables
ip6_tables
EOF

sudo modprobe overlay
sudo modprobe br_netfilter
sudo modprobe ip_tables
sudo modprobe ip6_tables

cat <<'EOF' | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
vm.swappiness = 0
EOF

sudo sysctl --system

docker --version

mkdir -p ~/kubekey-v3
cd ~/kubekey-v3
export KKZONE=cn
curl -fsSL https://get-kk.kubesphere.io -o get-kk.sh
VERSION=v3.1.2 bash get-kk.sh
chmod +x kk
./kk create config --with-kubesphere v3.4.1 --with-kubernetes v1.28.8

# 这里手动编辑 config-sample.yaml，替换成本文第 7 节给出的内容

export KKZONE=cn
sudo env KKZONE=cn ./kk create cluster -f config-sample.yaml

14. 最后总结

如果你只是想先把 KubeSphere 跑起来，最稳的方式就是：

先用单节点
先用 KubeKey v3.1.2
Kubernetes 固定用 v1.28.8
KubeSphere 固定用 v3.4.1
运行时走 Docker
安装命令前加 KKZONE=cn
镜像仓库改成阿里云 registry.cn-beijing.aliyuncs.com/kubesphereio

先把这套方案跑通，再考虑多节点、高可用、DevOps、服务网格这些进阶能力，会轻松很多。

在这里插入图片描述

openEuler 社区

openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目，面向数字基础设施四大核心场景（服务器、云计算、边缘计算、嵌入式），全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构

更多推荐

DNS 解析原理：当你在浏览器输入网址后发生了什么？

DNS 是互联网运行的基础设施之一。理解它的分层结构和解析流程，可以更好地排查访问异常、配置域名和优化网络。对于配置了多个子域名或需要频繁查看解析记录的场景，可以使用一些在线 DNS 查询工具（如通过网页进行 dig 查询）辅助验证。本文仅作技术分享，相关命令在不同操作系统下可能略有差异。

openEuler 社区

操作系统复习（六）

覆盖技术（Overlay）是早期计算机操作系统中，为了在物理内存容量极小（比如只有几十KB）的条件下，运行比物理内存大得多的程序，而采用的一种手动内存管理技术。简单来说，它的核心思想是：“内存装不下整个程序，那就把它拆成几块，哪块要用就加载哪块，不用的块就丢弃或覆盖掉。

openEuler 社区

第三视觉理解徐玉生与他的商业活动（23）

【摘要】文章解析了国家和合肥对徐玉生的"理性青睐"：在国家层面，其"气链操作系统"被视为新质生产力和生产关系变革的实践样本，通过"全域共享"等机制为深化改革提供微观验证；在合肥层面，其探索契合该市"验证-重仓"的创新模式，有望成为AI时代的差异化竞争力。这种双向认可本质上是国家战略与城市创新精神的共振——徐玉生通过技术