K3s 安装教程及常见问题解决大全 | 轻量K8s部署指南

2025-07-05 约 3002 字预计阅读 6 分钟次阅读

简介

作为 Rancher 推出的轻量级 Kubernetes 发行版，K3s 凭借体积小、资源占用低的优势，成为边缘计算、小型集群部署的首选。

关于 k3s 的完整介绍，请移步官方文档介绍：什么是 K3s?

本文基于 linux Centos 7、Centos 8 、OpenCloud OS 8/9 等操作系统进行实操，踩了不少 K3s 安装的坑，整理了这份实操指南，带你一步一步的安装部署使用 k3s ，并且解决常见安装问题，希望能够帮助大家少走弯路

一、安装前准备

（一）系统要求确认

先明确服务器基础配置，避免后续踩坑：

CPU：至少 1 核（生产环境建议 2 核及以上）
内存：至少 1G（生产环境建议 2G 及以上）
系统：CentOS 7/8、OpenCloud OS 8/9（已测试通过）
网络：服务器能访问外网（用于拉取镜像和安装包），节点间网络互通

（二）环境预处理

不同系统的依赖安装和环境配置略有差异，分开说明：

CentOS 7 / OpenCloud OS 8

        
        
        
    
# 升级系统包（可选，建议执行）
yum update -y

# 安装必要依赖
yum install -y curl wget socat conntrack

# 关闭防火墙（开发测试环境，生产环境需配置规则）
systemctl stop firewalld
systemctl disable firewalld

# 关闭 SELinux
setenforce 0
sed -i 's/^SELINUX=enforcing$/SELINUX=disabled/' /etc/selinux/config

# 关闭 swap（K8s 要求，必须执行）
swapoff -a
sed -i '/swap/s/^/#/' /etc/fstab

CentOS 8 / OpenCloud OS 9

        
        
        
    
# 升级系统包（可选）
dnf update -y

# 安装依赖（CentOS 8 用 dnf 替代 yum）
dnf install -y curl wget socat conntrack

# 关闭防火墙
systemctl stop firewalld
systemctl disable firewalld

# 关闭 SELinux
setenforce 0
sed -i 's/^SELINUX=enforcing$/SELINUX=disabled/' /etc/selinux/config

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

# 解决 CentOS 8 镜像源问题（部分系统默认源失效）
dnf install -y https://mirrors.aliyun.com/epel/epel-release-latest-8.noarch.rpm
sed -i 's|^#baseurl=https://download.fedoraproject.org/pub/epel/$releasever/Everything/$basearch|baseurl=https://mirrors.aliyun.com/epel/$releasever/Everything/$basearch|' /etc/yum.repos.d/epel.repo
sed -i 's|^metalink|#metalink|' /etc/yum.repos.d/epel.repo

二、K3s 安装步骤

K3s 支持单节点和多节点部署，单节点适合开发测试，多节点用于生产环境，分别讲解：

（一）单节点安装

服务器仅1台

单节点安装最简单，用官方脚本一键部署，默认会安装 server 端和 agent 端：

        
# 国内服务器建议用阿里云镜像源，加速安装
curl -sfL http://rancher-mirror.cnrancher.com/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

# 验证安装结果
k3s kubectl get nodes

# 若输出类似以下内容，说明安装成功
# NAME         STATUS   ROLES                  AGE     VERSION
# localhost    Ready    control-plane,master   2m30s   v1.28.6+k3s1

（二）多节点安装

多节点需要先部署主节点（server 端），再将从节点（agent 端）加入集群，步骤如下：

部署主节点

        
# 主节点安装，指定节点名称（可自定义，比如 k3s-master）
curl -sfL http://rancher-mirror.cnrancher.com/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -s - node-name k3s-master

# 查看主节点状态
k3s kubectl get nodes

# 获取加入集群的 token（后续从节点需要用到）
cat /var/lib/rancher/k3s/server/node-token

部署从节点

从节点需要先完成「环境预处理」，再执行加入命令，注意替换命令中的主节点 IP 和 token：

        
# 替换为主节点的实际 IP 和刚才获取的 token
export MASTER_IP="192.168.1.100"
export NODE_TOKEN="K10xxxxxxxxx"

# 从节点加入集群，指定节点名称（比如 k3s-agent-1）
curl -sfL http://rancher-mirror.cnrancher.com/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn K3S_URL=https://$MASTER_IP:6443 K3S_TOKEN=$NODE_TOKEN sh -s - node-name k3s-agent-1

# 主节点验证集群状态（在主节点执行）
k3s kubectl get nodes

# 若所有节点 STATUS 都是 Ready，说明集群部署成功

（三）部署测试应用

验证集群可用性

用一个简单的 Go Web 应用测试集群是否能正常运行，创建部署文件 test-go-app.yaml：

        
        
        
    
apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-test-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: go-test
  template:
    metadata:
      labels:
        app: go-test
    spec:
      containers:
      - name: go-test
        image: golang:1.21-alpine
        command: ["go", "run", "-"]
        args:
        - 'package main;import("net/http");func main(){http.HandleFunc("/",func(w http.ResponseWriter,r*http.Request){w.Write([]byte("K3s Cluster Test Success!"))});http.ListenAndServe(":8080",nil)}'
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: go-test-service
spec:
  type: NodePort
  selector:
    app: go-test
  ports:
  - port: 8080
    targetPort: 8080
    nodePort: 30001

执行部署命令并验证：

        
# 部署应用
k3s kubectl apply -f test-go-app.yaml

# 查看 pod 状态（确保都是 Running）
k3s kubectl get pods

# 访问测试（替换为主节点或从节点 IP）
curl http://192.168.1.100:30001

# 若输出 "K3s Cluster Test Success!"，说明集群正常

三、特殊配置（选）

（一）使用 docker

k3s 默认使用的容器是 containerd

如果你需要使用 docker 作为底层容器，则需要先安装部署 docker

docker 安装：Linux安装 docker 教程

我这里习惯了使用 docker，因此我是按照了 docker，但是如果你不安装 docker 也不影响

如果你像我一样使用的 docker 作为 k3s 的底层容器，那么此步骤必须操作：

        
        
        
    
# 创建 K3s 配置文件目录
sudo mkdir -p /etc/rancher/k3s/

# 生成 K3s 配置文件（使用 Docker 作为运行时）
sudo tee /etc/rancher/k3s/config.yaml <<EOF
docker: true
write-kubeconfig-mode: 644
disable:
  - traefik
  - servicelb
node-name: k3s-node-$(hostname)
kubelet-arg:
  - "max-pods=100"      # 防止小内存节点 pod 超限
kube-controller-manager-arg:
  - "node-cidr-mask-size=24"  # 优化小集群网络
kube-proxy-arg:
  - "proxy-mode=iptables"     # 减少资源占用
EOF

（二）配置开机自启动

sudo systemctl enable --now k3s

强烈推荐设置开机自启动，否则一旦机器重启，你就需要手动去开启 k3s，部署的 pod 才会重新启动

（三）生成 kubeconfig

k3s 和 k8s 不同，不会自动生成 kubeconfig，需要我们手动生成 kubeconfig，强烈建议首次安装部署成功同时生成 kubeconfig，这样子，其他用户也可以操作 k3s 的集群

        
# 生成 kubeconfig 供普通用户使用
mkdir -p $HOME/.kube
sudo cp /etc/rancher/k3s/k3s.yaml $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
sed -i "s/127.0.0.1/$(hostname -I | awk '{print $1}')/" $HOME/.kube/config

（四）安装 Helm（可选）

helm 可以理解为一个 k8s/k3s 的应用市场（类似 go install、mac brew、linux rpm），可以直接搜索安装应用，比如 mysql，redis等，按需安装

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

到这里就基本安装完成了，可以使用 kubectl 来查看 pod 状态

kubectl get pod -A

应该是可以看到一些基础的 pod 服务

可以开始操作我们的服务了…

常见问题

Q1：安装时拉取镜像超时

现象：执行安装脚本后卡住，日志显示「image pull failed」或「timeout」。

原因：国外镜像源访问慢，尤其是非国内服务器未配置镜像加速。

解决：

        
# 1. 先停止已有的 K3s 服务（若安装失败）
systemctl stop k3s
systemctl disable k3s
rm -rf /var/lib/rancher/k3s

# 2. 用国内镜像源重新安装（已集成加速）
curl -sfL http://rancher-mirror.cnrancher.com/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

如果底层用的是 docker，那么需要更换 docker 的镜像源

Q2：从节点无法加入主节点

现象：从节点执行加入命令后，主节点查看节点状态为「NotReady」或「NodeNotFound」。

原因：主从节点网络不通、token 错误、主节点端口未开放。

解决：

检查主从节点网络：在从节点 ping 主节点 IP，确保能通；
验证 token 正确性：重新在主节点执行 cat /var/lib/rancher/k3s/server/node-token，对比从节点使用的 token；

开放主节点端口：若开启防火墙，主节点需开放 6443、8472、2379 端口（生产环境建议配置）：

        
# 主节点开放端口示例（CentOS 7）
firewall-cmd --permanent --add-port=6443/tcp
firewall-cmd --permanent --add-port=8472/udp
firewall-cmd --permanent --add-port=2379/tcp
firewall-cmd --reload

重新加入从节点：先在从节点清理残留，再重新执行加入命令

        
        
        
    
# 从节点清理残留
systemctl stop k3s-agent
systemctl disable k3s-agent
rm -rf /var/lib/rancher/k3s
# 重新执行加入命令（替换 MASTER_IP 和 NODE_TOKEN）
curl -sfL http://rancher-mirror.cnrancher.com/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn K3S_URL=https://$MASTER_IP:6443 K3S_TOKEN=$NODE_TOKEN sh -s - node-name k3s-agent-1

Q3：pod 启动后状态为「CrashLoopBackOff」

现象：执行部署命令后，pod 反复启动又崩溃，状态显示「CrashLoopBackOff」。

原因：容器镜像错误、应用配置问题、资源不足。

解决：

        
        
        
    
# 1. 查看 pod 日志，定位具体错误
k3s kubectl logs -f <pod名称>

# 2. 常见错误处理：
# （1）镜像错误：确认镜像名称和版本正确，若为私有镜像，配置镜像拉取密钥；
# （2）资源不足：修改部署文件，减少 replicas 数量或降低资源请求，示例：
# 在 deployment.spec.template.spec 中添加资源配置
# resources:
#   requests:
#     cpu: "100m"
#     memory: "128Mi"
# （3）应用错误：检查应用代码或启动命令，比如本文的 Go 应用确保命令正确

Q4：执行 k3s 命令提示「command not found」

现象：安装完成后，执行 k3s kubectl get nodes 提示命令不存在。

原因：K3s 可执行文件路径未加入系统环境变量，或安装未成功。

解决方法：

        
# 1. 检查 K3s 是否安装成功
systemctl status k3s

# 2. 若服务正常，添加环境变量（临时生效）
export PATH=$PATH:/usr/local/bin/

# 3. 永久生效：编辑 /etc/profile 文件，添加以下内容
echo "export PATH=$PATH:/usr/local/bin/" >> /etc/profile
source /etc/profile

# 4. 再次验证命令
k3s kubectl get nodes

Q5：SELinux 导致 K3s 服务启动失败

现象：执行 systemctl start k3s 后，服务状态为「failed」，日志显示「permission denied」。

原因：SELinux 未关闭，限制了 K3s 的权限。

解决方法：

        
# 1. 临时关闭 SELinux（立即生效）
setenforce 0

# 2. 永久关闭 SELinux（重启后生效）
sed -i 's/^SELINUX=enforcing$/SELINUX=disabled/' /etc/selinux/config

# 3. 重启 K3s 服务
systemctl restart k3s
systemctl status k3s

总结

K3s 安装本身不复杂，关键是做好环境预处理和问题排查。

建议优先用镜像源加速，多节点部署时重点检查网络和 token 配置。

如果遇到本文没覆盖的问题，可通过 journalctl -u k3s -f 查看 K3s 服务日志，大部分问题都能从日志中找到线索。

如果大家有其他 K3s 相关的问题，欢迎在评论区交流，后续会持续更新问题解决方案～

未经授权，禁止转载本文章。
如需转载请保留原文链接并注明出处。即视为默认获得授权。
未保留原文链接未注明出处或删除链接将视为侵权，必追究法律责任！

本文原文链接： https://fiveyoboy.com/articles/k8s-k3s-install/

备用原文链接： https://blog.fiveyoboy.com/articles/k8s-k3s-install/