k3s 与标准 Kubernetes 的根本区别在于其轻量集成设计：自带 containerd、无需 systemd、512MB 内存即可运行；安装脚本自动检测系统、cgroup 版本，下载二进制并生成 service 文件；常见问题包括未关闭 swap、缺少 iptables、SELinux 冲突及国内网络镜像拉取失败，需针对性处理。
k3s 不是“先装 Docker 再装 Kubernetes”，它自带 containerd、不用 systemd 也能跑，512MB 内存的树莓派或边缘设备就能起集群——这是它和标准 K8s 最根本的区别。直接跑安装脚本就行，但失败往往卡在几个具体环节。
curl | sh 脚本到底干了什么？别盲目执行
官方命令 curl -sfL https://get.k3s.io | sh - 看似简单，实则做了四件事：自动检测系统类型（Ubuntu/CentOS/Alpine）、判断 cgroup 版本（v1/v2）、下载二进制到 /usr/local/bin/k3s、生成 systemd service 文件到 /etc/systemd/system/k3s.service。它绕开包管理器，就是为了避免不同发行版依赖冲突。
常见踩坑点：
- 脚本执行前没关
swap：k3s 启动会直接失败，报错含failed to run kubelet: failed to create kubelet: misconfiguration: kubelet cgroup driver: "systemd" is not supported或类似提示，本质是 cgroup 配置不一致 - 系统没装
iptables或ip6tables：Alpine 用户必须提前apk add iptables，CentOS/RHEL 8+ 默认用 nftables，得手动装iptables-services并启用 - SELinux 报错如
container-selinux >= 3:2.191.0-1 needed：不是必须修复，加环境变量INSTALL_K3S_SKIP_SELINUX_RPM=true即可跳过
国内网络下安装失败？换镜像源 + 关掉 Traefik
默认脚本走 GitHub，国内常卡在 pause 镜像拉取或证书验证阶段。别硬等超时，直接切国内镜像源：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_EXEC="--disable traefik --write-kubeconfig-mode 644" sh -
为什么禁用 traefik？它默认占 80/443 端口，和你本地 nginx、Apache 冲突，且多数边缘场景用不到 Ingress 控制器。去掉后，kubectl get pods -A 里就不会出现反复 CrashLoopBackOff 的 traefik pod。
关键检查点：
- 确认
/etc/rancher/k3s/k3s.yaml文件存在且权限为 644（否则kubectl读不了） - 执行
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml后再跑kubectl get nodes，别依赖 root 权限硬调sudo k3s kubectl - 如果
kubectl get nodes返回空或NotReady，先看systemctl status k3s是否 active，再查journalctl -u k3s -n 50 --no-pager最后几行错误
节点加不进去？三个硬性条件必须同时满足
加 agent 节点不是配个 IP 就完事。失败基本锁定在这三处：
-
/var/lib/rancher/k3s/server/node-token必须从 server 节点原样复制，不能手输——里面含换行符，建议用cat /var/lib/rancher/k3s/server/node-token直接输出粘贴 - agent 启动命令里的 server 地址必须是 server 节点对外可访问的 IP，比如
https://192.168.1.100:6443，绝不能写https://127.0.0.1:6443或localhost - server 节点防火墙必须放通两个端口：
6443（kube-apiserver）和8472/udp（flannel VXLAN），CentOS 用firewall-cmd --add-port=6443/tcp --add-port=8472/udp --permanent && firewall-cmd --reload，Ubuntu 用ufw allow 6443 && ufw allow 8472/udp
验证集群真就绪，别只看 systemctl status
systemctl status k3s 显示 active ≠ 集群可用。真正要确认的是控制平面 API 和本地配置是否连通：
-
kubectl get nodes输出中 STATUS 列必须是Ready，不是NotReady或空白 -
kubectl get pods -A中kube-system命名空间下所有 pod 的 READY 列应为1/1，尤其盯住coredns和local-path-provisioner—— 如果是0/1，大概率是网络插件没起来或磁盘权限问题 - 如果
kubectl报The connection to the server localhost:8080 was refused，说明没设KUBECONFIG，或者设错了路径
最易被忽略的是：agent 节点加入后，kubectl get nodes 能看到节点名，但 STATUS 是 NotReady，此时 90% 是 flannel 没通，先查 kubectl get pods -n kube-system -l k8s-app=flannel 状态，再看对应节点上的 journalctl -u k3s -n 30 有没有 failed to find plugin "flannel" 类报错。
