K3s 搭建教程：轻量 Kubernetes 集群部署实战

摘要

K3s 是经过裁剪的轻量 Kubernetes 发行版，单个二进制文件即可运行，资源占用远低于标准发行版，适合学习验证、边缘场景和中小规模部署。本文完成单节点与多节点 K3s 集群的搭建，涵盖资源规划、控制节点与工作节点部署、kubectl 配置、应用发布与外部访问、以及节点异常和镜像拉取失败的排查方法。

一、K3s 与标准 Kubernetes 的差异

K3s 保留了 Kubernetes 的核心 API 和使用方式，学到的操作可以直接迁移到标准集群。它的裁剪主要体现在：

• 把控制平面组件打包成单个进程，部署和运维大幅简化。
• 默认使用轻量的嵌入式数据库，不必单独部署和维护 etcd 集群。
• 移除了部分云厂商专用组件和已弃用特性。
• 内置了容器运行时、网络插件、入口控制器和本地存储，开箱即用。

适用判断：

需要说清楚的是，自建集群的运维成本不只是搭起来那一下。控制平面高可用、证书轮换、版本升级、节点故障处理、监控告警都要自己负责。生产业务如果没有专职的运维投入，使用托管容器服务通常更合适——它把控制平面的稳定性交给平台承担。本文的定位是学习验证和中小规模自建场景。

二、资源规划

单节点集群（学习和开发用）

多节点集群

控制节点建议 2 核 4 GB，工作节点按实际负载确定。节点之间需要网络互通，建议放在同一私有网络内，通过内网通信既快又不产生公网流量费用。

需要放通的端口：

这里有个重要的安全要点：6443 端口是集群的控制入口，持有凭据即可操作整个集群。这个端口只应对工作节点所在的内网网段放通，绝对不要对公网开放。轻量应用服务器在实例详情页的「防火墙」页签添加规则时可指定来源；云服务器 CVM 在安全组入站规则中同样支持按网段限定来源。

节点之间的通信建议通过内网地址完成，把这些端口的放通范围限制在私有网络内部。

三、部署控制节点

在作为控制节点的机器上执行安装脚本：

curl -sfL https://get.k3s.io | sh -

安装完成后服务会自动启动。确认状态：

sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes

节点状态显示 Ready 说明控制平面已就绪。

如果访问境外地址较慢，可以使用国内镜像源安装，具体地址以项目文档为准。

安装时可以按需调整默认组件。例如不需要内置的入口控制器时：

curl -sfL https://get.k3s.io | sh -s - --disable traefik

学习阶段建议保留默认组件，它们能让你快速看到完整效果。

获取工作节点接入所需的凭据：

sudo cat /var/lib/rancher/k3s/server/node-token

这个令牌要妥善保管，持有它就能把节点加入集群。

四、部署工作节点

在每台工作节点上执行，替换其中的控制节点地址和令牌：

curl -sfL https://get.k3s.io | \
  K3S_URL=https://控制节点内网IP:6443 \
  K3S_TOKEN=上一步获取的令牌 \
  sh -

注意这里填的是内网 IP。用公网 IP 会导致节点间流量走公网，既慢又产生费用，还需要把 6443 暴露到公网，不安全。

安装完成后在控制节点上验证：

sudo k3s kubectl get nodes -o wide

应能看到所有节点且状态为 Ready。新加入的节点可能需要等待一两分钟才变为就绪。

五、配置 kubectl 本地访问

在控制节点上可以直接用 k3s kubectl，但每次带前缀不方便。配置标准的 kubectl：

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config
chmod 600 ~/.kube/config

验证：

kubectl get nodes
kubectl get pods -A

从本地电脑管理集群时，把配置文件复制到本地，并修改其中的服务器地址：

scp 用户名@控制节点IP:~/.kube/config ~/.kube/k3s-config

编辑该文件，把 server 字段中的地址改为可访问的地址。

这里要再次强调安全问题：这个配置文件包含集群的管理员凭据，泄露等于集群被完全控制。文件权限要设为仅自己可读，不要提交到代码仓库，不要通过不安全的渠道传输。

如果需要从外部管理集群，更稳妥的做法是通过 SSH 端口转发，而不是把 6443 暴露到公网：

ssh -L 6443:127.0.0.1:6443 用户名@控制节点IP

六、部署应用并验证

用一个完整的部署验证集群是否真正可用。

创建部署清单 demo.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: demo-web
  template:
    metadata:
      labels:
        app: demo-web
    spec:
      containers:
        - name: web
          image: nginx:alpine
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 200m
              memory: 128Mi
---
apiVersion: v1
kind: Service
metadata:
  name: demo-web
spec:
  selector:
    app: demo-web
  ports:
    - port: 80
      targetPort: 80

resources 中的请求和限制值建议养成习惯填写。不设限制时，一个异常容器可能占满节点资源，把其他工作负载一起拖垮。

应用清单：

kubectl apply -f demo.yaml
kubectl get pods -o wide
kubectl get svc

逐层验证：

Pod 处于运行状态：

kubectl get pods

两个副本都应显示 Running。

集群内部可访问服务：

kubectl run test --rm -it --image=curlimages/curl --restart=Never -- \
  curl -s -o /dev/null -w "%{http_code}\n" http://demo-web

返回 200 说明服务发现和内部网络正常。

配置外部访问。K3s 内置了入口控制器，创建入口规则：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-web
spec:
  rules:
    - host: demo.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: demo-web
                port:
                  number: 80

应用后从外部访问：

curl -H "Host: demo.example.com" http://控制节点公网IP

返回页面内容说明入口链路打通了。实际使用时把域名解析到节点 IP 即可。

验证副本自愈能力：手动删除一个 Pod，观察是否自动重建：

kubectl delete pod <某个pod名称>
kubectl get pods -w

能看到新 Pod 被创建，说明控制器工作正常。这一项验证了 Kubernetes 的核心价值。

七、常见问题与排查

工作节点无法加入集群

按顺序检查：控制节点 6443 端口是否对该节点所在网段放通；填写的是否为内网 IP；令牌是否完整且正确；两台机器时间是否同步（时间偏差过大会导致证书校验失败）。

查看节点上的日志：

sudo journalctl -u k3s-agent -n 50 --no-pager

Pod 一直处于等待状态

查看具体原因：

kubectl describe pod <pod名称>

事件部分会说明卡在哪一步。常见情况：镜像拉取失败、节点资源不足、调度约束无法满足。

镜像拉取失败

国内环境拉取境外镜像仓库经常超时。可以配置镜像加速。编辑 K3s 的镜像仓库配置：

sudo nano /etc/rancher/k3s/registries.yaml

mirrors:
  docker.io:
    endpoint:
      - "https://mirror.ccs.tencentyun.com"

重启服务生效：

sudo systemctl restart k3s

节点状态变为未就绪

kubectl describe node <节点名称>
sudo journalctl -u k3s -n 100 --no-pager

常见原因是节点资源耗尽、磁盘空间不足或网络中断。内存和磁盘压力会触发节点驱逐机制。

Pod 频繁重启

kubectl logs <pod名称> --previous

--previous 查看上一次崩溃前的日志。常见原因是应用自身报错、健康检查配置不当、内存超出限制被终止。

服务在集群内能访问但外部访问不通

检查入口规则是否正确、入口控制器是否运行、节点的 80 和 443 端口是否在控制台放通。

磁盘空间被镜像占满

sudo k3s crictl images
df -h

清理未使用的镜像：

sudo k3s crictl rmi --prune

八、维护与运维要点

备份集群状态

K3s 默认使用嵌入式数据库，数据位于 /var/lib/rancher/k3s/server/db。定期备份：

sudo tar -czf ~/k3s-backup-$(date +%Y%m%d).tar.gz \
  -C /var/lib/rancher/k3s/server db token

token 文件也要一并备份，恢复时需要它。把备份同步到对象存储，不要只留在本机。

更重要的是备份应用清单

集群可以重建，但你的部署配置不能丢。把所有清单文件纳入版本管理，这样即使集群完全损坏，也能在新集群上快速重新部署。这比备份集群数据库更实用。

kubectl get all -A -o yaml > ~/cluster-resources-$(date +%Y%m%d).yaml

变更前创建快照：升级 K3s 版本、调整集群配置前给实例创建快照。回滚会把整块系统盘恢复到快照时间点，之后写入的数据会被清除，运行中的实例会自动关机。使用存储型套餐的实例不支持创建快照。

多节点集群回滚时要注意节点之间的状态一致性，建议先排空节点再操作。

版本升级

K3s 支持重新执行安装脚本完成升级，指定目标版本：

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=目标版本 sh -

升级顺序是先控制节点再工作节点。升级前务必备份并阅读版本发布说明，确认是否有不兼容变更。

资源管理习惯

• 为所有工作负载设置资源请求和限制，避免单个应用拖垮节点。
• 使用命名空间隔离不同用途的工作负载。
• 定期清理不再使用的部署和镜像。

安全要点

• 6443 端口只对内网放通，不要暴露到公网。
• kubeconfig 文件包含管理员凭据，权限设为仅自己可读，不要提交到代码仓库。
• 节点接入令牌妥善保管。
• 容器镜像使用固定版本标签，不要用滚动标签，避免意外引入变更。
• 不要以特权模式运行容器，除非确有必要。

监控建议

自建集群缺少开箱的监控，建议部署监控组件采集节点和工作负载指标，至少要能看到节点资源水位和 Pod 重启次数。没有监控的集群，问题往往是用户先发现的。

集群跑起来之后，如果需要在其上部署监控告警体系，或建立从代码提交到集群发布的自动化流水线，可以作为下一步方向。

学习验证和中小规模自建场景，云服务器 CVM 的规格可按需调整，适合作为集群节点；规模化生产业务建议使用容器服务，把控制平面的稳定性和运维交给平台承担。