K3s轻量级Kubernetes单节点集群搭建指南-代码聚汇网

K3s轻量级Kubernetes单节点集群搭建指南

K3sKubernetes单节点集群

|难度：普通|阅读约 16 分钟

1. 为什么选择K3s搭建单节点K8s集群

在容器编排领域，Kubernetes（K8s）已经成为事实标准，但完整的K8s集群对资源要求较高，特别是在开发测试环境中部署时显得过于"重型"。这就是K3s的价值所在——一个经过CNCF认证的轻量级Kubernetes发行版，专为资源受限环境设计。

我最近在本地开发环境中需要快速搭建一个K8s集群来测试微服务架构，经过对比最终选择了K3s。相比minikube等其他轻量方案，K3s有以下突出优势：

资源占用极低：单节点运行时内存占用仅需512MB左右，而完整K8s至少需要2GB
内置组件精简：默认使用containerd替代Docker，用SQLite替代etcd（也支持etcd）
一键安装：无需复杂配置，一条命令即可完成部署
生产就绪：虽然是轻量版，但完全兼容标准Kubernetes API

提示：如果你只需要本地开发测试环境，K3s的单节点模式是最佳选择；如果需要模拟生产环境的多节点集群，K3s也支持轻松扩展。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备与前置条件

2.1 硬件与操作系统要求

我使用的是阿里云ECS实例进行测试，具体配置如下：

操作系统：CentOS 7.9（内核版本3.10.0-1160.el7.x86_64）
CPU：2核
内存：2GB
磁盘：40GB SSD

K3s对系统的要求非常宽松，理论上任何能运行Linux的x86_64或ARM设备都可以部署。以下是官方推荐的最低配置：

环境类型	CPU	内存	磁盘
开发测试	1核	512MB	10GB
生产环境	2核	2GB	50GB

2.2 必要的系统配置

在安装K3s前，需要确保系统满足以下条件：

关闭Swap：Kubernetes默认要求禁用Swap

bash复制sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

配置防火墙：开放必要的端口

bash复制sudo firewall-cmd --permanent --add-port=6443/tcp  # Kubernetes API
sudo firewall-cmd --permanent --add-port=8472/udp  # Flannel VXLAN
sudo firewall-cmd --reload

设置主机名解析（重要！）

bash复制sudo hostnamectl set-hostname k3s-master
echo "127.0.0.1 k3s-master" | sudo tee -a /etc/hosts

安装基础依赖

bash复制sudo yum install -y curl vim git

3. 安装K3s与核心组件

3.1 一键安装K3s服务端

K3s提供了极简的安装方式，使用官方脚本即可完成部署：

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

这个命令会：

下载并安装K3s二进制文件
配置systemd服务
启动K3s服务
生成kubeconfig文件（位于/etc/rancher/k3s/k3s.yaml）

安装完成后，检查服务状态：

bash复制sudo systemctl status k3s

如果一切正常，你应该能看到类似这样的输出：

code复制● k3s.service - Lightweight Kubernetes
   Loaded: loaded (/etc/systemd/system/k3s.service; enabled)
   Active: active (running) since Wed 2026-03-23 14:30:21 CST; 1min ago

3.2 配置kubectl访问

默认情况下，kubeconfig文件只有root用户有读取权限，我们需要调整权限并设置环境变量：

bash复制mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
export KUBECONFIG=~/.kube/config

验证集群状态：

bash复制kubectl get nodes

你应该能看到类似这样的输出：

code复制NAME        STATUS   ROLES                  AGE   VERSION
k3s-master  Ready    control-plane,master   5m    v1.28.5+k3s1

3.3 安装常用工具（可选）

虽然K3s已经包含了运行Kubernetes所需的核心组件，但你可能还需要以下工具：

helm：Kubernetes包管理工具

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

k9s：终端UI管理工具

bash复制wget https://github.com/derailed/k9s/releases/download/v0.27.4/k9s_Linux_amd64.tar.gz
tar xvf k9s_Linux_amd64.tar.gz
sudo mv k9s /usr/local/bin/

4. 关键组件解析与配置调优

4.1 K3s的架构特点

K3s采用了高度集成的设计，将多个Kubernetes组件合并为单个进程：

标准K8s组件	K3s替代方案
kube-apiserver	内置
etcd	默认使用SQLite（可选etcd）
kubelet	内置
containerd	内置（也可配置Docker）
kube-proxy	内置
CNI插件	默认使用Flannel

这种设计使得K3s的启动速度极快，在我的测试中，从安装到完全启动仅需30秒左右。

4.2 存储配置优化

默认情况下，K3s使用/var/lib/rancher/k3s作为数据目录。如果系统盘空间有限，可以修改数据目录位置：

bash复制curl -sfL https://get.k3s.io | sh -s - --data-dir /data/k3s

对于生产环境，建议配置持久化存储。K3s支持所有标准Kubernetes存储方案，最简单的本地路径存储配置如下：

bash复制mkdir -p /data/k3s/storage
cat <<EOF | kubectl apply -f -
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: local-path
provisioner: rancher.io/local-path
volumeBindingMode: WaitForFirstConsumer
EOF

4.3 网络配置调整

K3s默认使用Flannel作为CNI插件，采用VXLAN后端。如果需要修改网络配置：

查看当前网络配置

bash复制kubectl get pods -n kube-system -l app=flannel

修改Flannel配置（如改用host-gw后端）

bash复制sudo sed -i 's/--vxlan/--ip-masq --ip-masq-agent=true --iface=eth0/' /var/lib/rancher/k3s/server/manifests/flannel.yaml
sudo systemctl restart k3s

5. 常见问题排查与解决方案

5.1 安装失败排查步骤

如果安装过程中出现问题，可以按照以下步骤排查：

检查服务日志
```
bash复制journalctl -u k3s -xe
```
查看容器运行时状态
```
bash复制sudo crictl ps -a
```
常见错误及解决方案：

错误现象	可能原因	解决方案
端口6443被占用	已有K8s集群运行	停止现有服务或使用--https-listen-port参数
cgroup配置问题	系统未启用cgroup	在启动参数添加--kubelet-arg="cgroup-driver=systemd"
镜像拉取失败	网络问题	配置国内镜像源或使用--docker-mirror参数

5.2 节点NotReady状态处理

如果kubectl get nodes显示节点状态为NotReady，通常是因为网络插件或容器运行时问题：

首先检查kubelet日志

bash复制journalctl -u k3s -l | grep kubelet

检查网络插件Pod状态

bash复制kubectl get pods -n kube-system

常见修复方法：

重启Flannel Pod
重新安装CNI插件

bash复制kubectl delete -f /var/lib/rancher/k3s/server/manifests/flannel.yaml
kubectl apply -f /var/lib/rancher/k3s/server/manifests/flannel.yaml

5.3 资源清理与卸载

如果需要完全卸载K3s：

bash复制/usr/local/bin/k3s-uninstall.sh

这个脚本会：

停止K3s服务
移除相关文件和目录
清理iptables规则
删除容器和镜像

注意：卸载操作不可逆，请确保已备份重要数据。特别是/var/lib/rancher/k3s目录包含了所有集群数据。

6. 生产环境进阶配置建议

虽然本文主要介绍单节点安装，但K3s同样适合生产环境。以下是一些进阶配置建议：

6.1 高可用部署

K3s支持多种高可用方案，最简单的是使用嵌入式etcd的多节点集群：

bash复制# 第一个节点
curl -sfL https://get.k3s.io | sh -s - server --cluster-init

# 后续节点
curl -sfL https://get.k3s.io | sh -s - server --server https://<第一个节点IP>:6443

6.2 负载均衡配置

对于生产环境，建议在K3s集群前部署负载均衡器：

使用Nginx作为反向代理示例配置：

nginx复制stream {
    upstream k3s_servers {
        server 192.168.1.100:6443;
        server 192.168.1.101:6443;
        server 192.168.1.102:6443;
    }

    server {
        listen 6443;
        proxy_pass k3s_servers;
    }
}

配置K3s使用负载均衡器

bash复制curl -sfL https://get.k3s.io | sh -s - server --tls-san <负载均衡器IP>

6.3 监控与告警

虽然K3s轻量，但监控同样重要。推荐使用Prometheus-Operator：

bash复制helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install kube-prometheus prometheus-community/kube-prometheus-stack

配置完成后，可以通过以下命令访问Grafana：

bash复制kubectl port-forward svc/kube-prometheus-grafana 3000:80

7. 实际应用部署示例

为了验证集群功能，我们来部署一个简单的Nginx应用：

7.1 创建部署

bash复制kubectl create deployment nginx --image=nginx:alpine
kubectl scale deployment nginx --replicas=3

检查Pod状态：

bash复制kubectl get pods -o wide

7.2 暴露服务

bash复制kubectl expose deployment nginx --port=80 --type=NodePort

获取访问URL：

bash复制export NODE_PORT=$(kubectl get svc nginx -o jsonpath='{.spec.ports[0].nodePort}')
echo "访问地址: http://$(hostname -I | awk '{print $1}'):$NODE_PORT"

7.3 使用Ingress（可选）

如果需要域名访问，可以安装Ingress控制器：

安装Traefik（K3s默认已安装）

bash复制kubectl apply -f /var/lib/rancher/k3s/server/manifests/traefik.yaml

创建Ingress资源

bash复制cat <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx
spec:
  rules:
  - host: nginx.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nginx
            port:
              number: 80
EOF

8. 性能优化与资源管理

即使是单节点集群，合理的资源管理也能显著提升性能。

8.1 系统参数调优

编辑/etc/sysctl.conf，添加以下参数：

conf复制vm.swappiness = 1
net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-iptables = 1
fs.file-max = 6553560

应用配置：

bash复制sudo sysctl -p

8.2 K3s内存限制

默认情况下，K3s会尽可能使用可用内存。可以通过以下参数限制内存使用：

bash复制curl -sfL https://get.k3s.io | sh -s - --kubelet-arg="eviction-hard=memory.available<500Mi"

8.3 节点资源预留

确保系统关键进程有足够资源：

bash复制cat <<EOF | sudo tee /etc/rancher/k3s/config.yaml
kubelet-arg:
- "system-reserved=cpu=500m,memory=512Mi"
- "kube-reserved=cpu=500m,memory=512Mi"
EOF

重启服务生效：

bash复制sudo systemctl restart k3s

9. 安全加固建议

9.1 禁用Dashboard（如不需要）

K3s默认不安装Dashboard，但如果之前安装过，可以删除：

bash复制kubectl delete ns kubernetes-dashboard

9.2 配置网络策略

限制Pod间通信：

bash复制kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny
spec:
  podSelector: {}
  policyTypes:
  - Ingress
  - Egress
EOF

9.3 定期更新

K3s更新非常简单：

bash复制curl -sfL https://get.k3s.io | sh -
sudo systemctl restart k3s

建议设置自动安全更新：

bash复制sudo yum install -y yum-cron
sudo sed -i 's/apply_updates = no/apply_updates = yes/' /etc/yum/yum-cron.conf
sudo systemctl enable yum-cron --now

10. 备份与恢复策略

10.1 定期备份关键数据

K3s的关键数据位于/var/lib/rancher/k3s目录，建议定期备份：

bash复制sudo tar czvf k3s-backup-$(date +%Y%m%d).tar.gz /var/lib/rancher/k3s/server /etc/rancher/k3s

10.2 使用Velero进行应用备份

安装Velero备份工具：

bash复制wget https://github.com/vmware-tanzu/velero/releases/download/v1.10.1/velero-v1.10.1-linux-amd64.tar.gz
tar xvf velero-v1.10.1-linux-amd64.tar.gz
sudo mv velero-v1.10.1-linux-amd64/velero /usr/local/bin/

配置备份到本地目录：

bash复制velero install --provider aws --plugins velero/velero-plugin-for-aws:v1.6.0 \
    --bucket velero-backups \
    --secret-file ./credentials-velero \
    --use-volume-snapshots=false \
    --backup-location-config region=minio,s3ForcePathStyle="true",s3Url=http://minio.example.com:9000

创建每日备份：

bash复制velero schedule create daily-backup --schedule="@every 24h"

10.3 灾难恢复步骤

如果发生严重故障，可以按照以下步骤恢复：

在新节点安装相同版本的K3s

bash复制curl -sfL https://get.k3s.io | sh -
sudo systemctl stop k3s

恢复备份数据

bash复制sudo rm -rf /var/lib/rancher/k3s/server
sudo tar xzvf k3s-backup-20260323.tar.gz -C /

重启服务
```
bash复制sudo systemctl start k3s
```

验证集群状态

bash复制kubectl get nodes
kubectl get pods --all-namespaces

11. 与完整K8s的功能差异

虽然K3s兼容标准Kubernetes API，但仍有一些差异需要注意：

功能	K3s支持情况	说明
Alpha/Beta API	部分支持	默认禁用部分实验性API
In-Tree插件	移除	使用外部插件替代
Cloud Provider集成	有限支持	需要手动配置
网络策略	完整支持	依赖CNI插件实现
HPA	支持	需要metrics-server
StorageClass	支持	内置local-path-provisioner

在实际使用中，我发现K3s对标准工作负载的支持度几乎达到100%，只有在使用一些云厂商特定功能时才需要额外配置。

12. 个人实践中的经验总结

经过多次K3s部署和维护，我总结了以下实用技巧：

镜像加速：配置国内镜像源可以显著提升Pod启动速度

bash复制sudo mkdir -p /etc/rancher/k3s
sudo tee /etc/rancher/k3s/registries.yaml <<EOF
mirrors:
  "docker.io":
    endpoint:
      - "https://docker.mirrors.ustc.edu.cn"
EOF

日志管理：K3s默认日志会快速增长，建议配置日志轮转

bash复制sudo tee /etc/logrotate.d/k3s <<EOF
/var/log/k3s.log {
    rotate 7
    daily
    compress
    missingok
    notifempty
    copytruncate
}
EOF

开发技巧：使用kubectl的别名和自动补全能极大提高效率

bash复制echo 'alias k=kubectl' >> ~/.bashrc
echo 'complete -F __start_kubectl k' >> ~/.bashrc
source <(kubectl completion bash)

资源监控：安装kube-state-metrics可以获取更详细的集群指标
```
bash复制helm install kube-state-metrics bitnami/kube-state-metrics
```
调试技巧：当Pod无法启动时，使用crictl直接检查容器状态
```
bash复制sudo crictl ps -a
sudo crictl logs <container-id>
```

存储技巧：对于开发环境，可以使用hostPath卷方便调试

yaml复制volumes:
- name: test-volume
  hostPath:
    path: /data/test
    type: Directory

网络技巧：临时暴露服务可以使用port-forward
```
bash复制kubectl port-forward svc/nginx 8080:80
```
升级策略：先在一个节点测试新版本，确认无误后再滚动更新整个集群
备份策略：除了集群数据，别忘了备份/etc/rancher/k3s下的配置文件
安全实践：定期轮换证书（K3s证书有效期默认1年）
```
bash复制sudo k3s certificate rotate
```