必须先关闭firewalld和SELinux，这是硬性前提而非建议；firewalld拦截2379、6443等关键端口导致etcd卡在Waiting for etcd to be ready，SELinux阻止容器挂载路径引发permission denied或kubelet启动失败。
kk create cluster卡在Waiting for etcd to be ready？先关firewalld和SELinux
这不是建议，是硬性前提。KubeKey内部组件（etcd、Calico、kubelet）通信端口多且动态，firewalld默认拦截2379、10250、6443等关键端口，直接导致etcd初始化失败；SELinux则会阻止容器挂载/etc/kubernetes、/var/lib/kubelet等路径，报错常为permission denied或failed to run Kubelet。
- 临时关闭：
systemctl stop firewalld && setenforce 0 - 永久禁用（重启生效）：
sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config，改完必须重启 - 别信“只开几个端口就行”——kk不暴露全部端口列表，关防火墙是最稳解法
--with-kubernetes和--with-kubesphere版本填错？查官方兼容表再执行
填错组合是ks-installer崩溃的头号原因。比如v3.4.1 KubeSphere只验证过v1.25.12或v1.26.10 Kubernetes，填v1.27.x会导致镜像拉取失败，日志反复出现ImagePullBackOff或failed to patch clusterconfiguration。
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- 单机部署最稳组合：
--with-kubernetes v1.25.12 --with-kubesphere v3.4.1 - 查兼容表唯一可靠方式：访问
https://kubesphere.io/docs/v3.4/installing-on-linux/introduction/kubekey/（URL中版本号必须与你要装的匹配） - 漏掉
--with-kubesphere参数，kk只装裸Kubernetes，不会部署任何KubeSphere组件
安装完打不开https://IP:30880？盯住三个端口和服务状态
页面打不开 ≠ 安装失败。真正决定能否访问的是底层服务是否就位，不是浏览器报错就重装。
-
30880：必须由kk自动创建ks-consoleService（NodePort类型），绑定到节点IP；若云服务器，需在安全组放行30000–32767端口范围 -
6443：验证API Server是否可用：kubectl get node能通但页面打不开，大概率是ks-consolePod没起来，执行kubectl get pod -n kubesphere-system | grep console看状态 - 若Pod处于
Pending，检查kubectl describe pod -n kubesphere-system，常见原因是NodePort被占用或节点资源不足（内存
生成配置文件后直接跑kk create cluster -f config-sample.yaml？至少改这三处
kk生成的默认配置不能直接用，尤其新手容易忽略以下几项，否则集群起不来或组件缺失。
-
user和password字段必须真实有效，推荐填root，避免sudo权限问题 -
roleGroups.etcd至少含一个节点，且该节点必须同时出现在control-plane列表里；多节点分离部署需额外配LB，新手别碰 -
containerManager字段必须显式设为docker或containerd，不能留空；选containerd时，所有节点需提前执行containerd config default | sudo tee /etc/containerd/config.toml并把SystemdCgroup = true
swapoff -a只是临时关闭，必须注释/etc/fstab里含swap的行，否则重启后kubeadm层直接拒绝初始化。 
