K3s实战：从单机到生产集群部署全指南与避坑要点

上一期我们聊了K3s的定位，不少朋友反馈说官方文档参数太多，希望能有一份更直接、能“抄作业”的安装教程。那么今天，我们就直接动手实践。

我敢保证，只要你有一台能联网的Linux机器（哪怕是虚拟机），跟随本指南操作，半小时内必定能启动一个带Ingress和存储的K8s集群。

当然，这不仅仅是一个安装脚本那么简单。作为运维，我们知道在实际生产环境中会遇到哪些坑：比如内网隔离、镜像拉取失败、证书过期、节点无法加入等等。本文将基于我的经验，帮你把这些坑一一填平。

准备好了吗？打开你的终端，我们开始。

第一阶段：环境准备（关键步骤，不可跳过）

很多新手一上来就直接运行安装脚本，结果被各种报错搞到怀疑人生。其实，90%的问题都源于环境没有准备好。

在运行任何K3s命令之前，请务必检查并处理以下几项：

1. 主机名（Hostname）
K3s（以及K8s）对主机名非常敏感。不要使用 localhost 这种通用名，也不要使用带下划线 _ 的格式。
请将其改为符合DNS标准的格式，例如 node-1 或 k3s-master。

hostnamectl set-hostname k3s-master-01
# 修改后，建议退出当前终端重新登录，或者执行 source /etc/profile 使环境变量生效

2. 关闭防火墙与Swap
虽然K3s声称支持Swap，但为了稳定性（尤其是新手），建议直接关闭。
防火墙是另一个大坑。如果你不熟悉复杂的iptables或firewalld转发规则，最简单的方法就是直接关闭它们。

systemctl stop firewalld
systemctl disable firewalld
swapoff -a
# 重要：记得编辑 /etc/fstab 文件，注释掉swap相关的行，否则重启后swap又会自动启用

3. 时间同步
这一点我必须再三强调。集群节点之间的时间差如果超过几秒，会导致认证证书失效，所有节点状态都可能变为 NotReady。安装一个时间同步服务（如chrony）只需要一分钟。

这些准备工作看似简单，却是成功部署K3s、避免后期出现各种诡异问题的基石。

第二阶段：单机极速部署（用于测试与开发）

如果你只是想在自己的笔记本、虚拟机或开发环境中快速体验，单机模式是最佳选择。

官方的安装脚本是 curl -sfL https://get.k3s.io | sh -。

但是！ 如果你在国内网络环境下，直接运行这个脚本很可能会卡在下载二进制文件或拉取 pause 镜像的步骤上。

我们可以使用一个“改良版”命令，利用国内镜像进行加速：

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
  INSTALL_K3S_MIRROR=cn \
  sh -

这样就结束了吗？是的，单机安装就是这么简单。
不过，作为一个有经验的老手，我通常会添加几个参数，让后续操作更符合习惯：

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
  INSTALL_K3S_MIRROR=cn \
  INSTALL_K3S_EXEC="--write-kubeconfig-mode 644 --disable-cloud-controller" \
  sh -

解释一下这两个参数（都是经验之谈）：

• --write-kubeconfig-mode 644：这个参数非常重要。默认情况下，K3s生成的kubeconfig文件只有root用户可读。当你切换到普通用户想运行 kubectl 时，会直接提示 Permission denied。加上这个参数，就省去了后续手动执行 chmod 的麻烦。
• --disable-cloud-controller：因为我们通常是在裸机或虚拟机上运行，不需要连接AWS、阿里云等云服务商的云控制器。禁用它，可以为系统节省一点内存。

如何验证安装成功？
安装完成后，等待几十秒（取决于你的网络拉取镜像速度），然后运行：

kubectl get nodes

如果看到节点状态为 Ready，恭喜你，你的单节点K3s集群已经成功运行！

第三阶段：生产级集群搭建（Server + Agent 模式）

好了，现在我们来搭建一个更贴近生产环境的多节点集群。假设你有三台机器：

• 192.168.1.10 （Master/Server节点）
• 192.168.1.11 （Worker/Agent节点）
• 192.168.1.12 （Worker/Agent节点）

1. 启动 Master 节点
在 192.168.1.10 这台机器上执行以下命令：

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
  INSTALL_K3S_MIRROR=cn \
  INSTALL_K3S_EXEC="--node-ip 192.168.1.10 --flannel-iface eth0" \
  sh -

• --node-ip：明确指定节点的IP地址。这能防止在拥有多个网卡的环境中，K3s识别到错误的IP。
• --flannel-iface：指定Flannel网络组件使用哪个物理网口。这个参数极其重要！ 我见过太多集群网络不通的案例，就是因为Flannel自动选择了一个虚拟网卡或者错误的内部网卡。

2. 获取节点加入令牌（Token）
Master节点启动后，我们需要一个“令牌”才能让Worker节点加入集群。
在Master节点上执行：

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

你会得到一串类似 K10xxxxx::server:xxxx 的长字符串。请复制它。

3. 加入 Worker 节点
分别在 192.168.1.11 和 192.168.1.12 这两台机器上执行以下命令：

# 请将下面的 IP 和 TOKEN 替换为你的实际信息
export K3S_URL=https://192.168.1.10:6443
export K3S_TOKEN=你刚才复制的那串字符

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
  INSTALL_K3S_MIRROR=cn \
  sh -

现在，回到Master节点，多次执行 kubectl get nodes，你会看到新加入的两个节点状态逐渐从 NotReady 变为 Ready。

至此，一个分布式的K8s集群就组建完成了。对比原生的 kubeadm 安装方式，是不是感觉简单了很多？这正是K3s的魅力所在，它极大地简化了K8s集群的部署和维护门槛。如果你对更复杂的运维和生产环境问题感兴趣，可以到相关技术社区深入交流。

第四阶段：实战应用（部署、发布与存储）

集群搭建好了，不跑点应用岂不是浪费？我们来一套标准的“组合拳”：部署 Nginx、发布服务、挂载持久化存储。

1. 部署一个简单的 Nginx 应用
不要一开始就用复杂的Helm Chart，手写YAML文件是运维人员的基本功。
创建一个名为 my-nginx.yaml 的文件，内容如下：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-demo
  labels:
    app: nginx
spec:
  replicas: 2  # 运行两个副本，体验一下负载均衡
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80

执行部署命令：

kubectl apply -f my-nginx.yaml

查看Pod运行状态和分布：

kubectl get pods -o wide

你应该能看到两个Nginx Pod被调度到不同的节点上运行（如果调度策略正常的话）。

2. 通过 Ingress 对外暴露服务（利用内置的 Traefik）
K3s默认集成了Traefik作为Ingress Controller。它的好处在于，你无需额外安装Nginx Ingress Controller。
直接编写一个Ingress规则文件 ingress.yaml：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-ingress
  annotations:
    # 这一行很重要，明确指定使用traefik作为Ingress控制器
    kubernetes.io/ingress.class: "traefik"
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nginx-service
            port:
              number: 80

执行 kubectl apply -f ingress.yaml。

现在，神奇的事情发生了。打开你的浏览器，输入集群中任意一个节点的IP地址（例如 http://192.168.1.10）。

你应该能看到熟悉的Nginx欢迎页面。

为什么可以这样访问？因为K3s默认启用了Service LoadBalancer（通过svclb组件），而Traefik默认监听了宿主机的80和443端口。这就是“开箱即用”的便利之处，你无需再去配置丑陋的NodePort（例如 30080）。

3. 存储实战（使用 Local Path Provisioner）
存储管理是K8s中相对复杂的一环，通常你需要配置NFS、Ceph或云存储。
但在K3s中，它自带了一个名为 local-path 的StorageClass。简单来说，它允许将Pod的数据持久化存储到宿主机的一个本地目录中。

我们来试用一下。创建一个PVC（持久卷声明）文件 pvc.yaml：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: local-path-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: local-path
  resources:
    requests:
      storage: 1Gi

应用这个PVC：kubectl apply -f pvc.yaml，然后执行 kubectl get pvc。你会发现其状态立即变成了 Bound。
这里你不需要手动创建PV（持久卷），也无需配置NFS服务器。

数据存储在哪里？默认情况下，在宿主机的 /var/lib/rancher/k3s/storage/ 目录下。
这对于运行数据库测试、临时文件存储等场景来说，简直是太方便了。这种轻量化的存储方案，非常适合边缘计算或资源受限的环境。

第五阶段：进阶与避坑指南

如果文章只写到上面，那充其量只是个不错的入门教程。下面这些内容，才是我在生产环境中摸爬滚打总结出的经验。

1. 如何进行离线安装（Airgap）？
企业内网通常是隔离的，无法直接访问外网。直接运行在线安装脚本肯定会失败。
你需要准备三样东西：

1. 从GitHub Releases页面下载 k3s 二进制文件。
2. 下载 k3s-airgap-images-$(ARCH).tar 镜像包（如k3s-airgap-images-amd64.tar）。
3. 下载 install.sh 安装脚本。

关键步骤：

• 将 k3s 二进制文件放到 /usr/local/bin/ 目录，并赋予执行权限。
• 将镜像包放到 /var/lib/rancher/k3s/agent/images/ 目录下（如果目录不存在则创建）。
• 执行脚本时，添加环境变量 INSTALL_K3S_SKIP_DOWNLOAD=true。

这样，K3s在启动时会自动导入tar包中的镜像，整个过程完全不需要连接互联网。

2. 用 Docker 还是 Containerd？
K3s默认使用Containerd作为容器运行时。很多习惯了 docker ps、docker logs 的朋友可能会感到不习惯。
你可以使用 crictl 命令来替代：

• crictl ps 对应 docker ps
• crictl images 对应 docker images
• crictl logs 对应 docker logs

如果你因为某些原因必须使用Docker（例如一些旧的CI/CD脚本依赖docker.sock），可以在安装时加上 --docker 参数。但我强烈建议你尝试适应Containerd，它更为轻量，且是K8s生态未来的发展方向。深入了解容器化技术，有助于你更好地驾驭整个云原生体系。

3. 证书过期了怎么办？
K3s生成的证书默认有效期为一年。在旧版本中，这是一个大坑，集群运行满一年后可能突然瘫痪，日志里全是x509证书错误。
好消息是，新版本的K3s在服务重启时会自动轮转证书。
只要你没有整整一年都不重启K3s服务，基本上不会遇到这个问题。如果实在不放心，可以在crontab中添加一个计划任务，每月重启一次K3s服务：systemctl restart k3s。

4. 如何彻底卸载（从头再来）？
环境被折腾乱了？想彻底重装？
K3s非常贴心地提供了一键卸载脚本：

• 在Server（Master）节点运行：/usr/local/bin/k3s-uninstall.sh
• 在Agent（Worker）节点运行：/usr/local/bin/k3s-agent-uninstall.sh

执行后，K3s相关的文件和服务会被清理干净，就像从未安装过一样。

总结

朋友们，K3s确实是一个非常优秀的工具。它将Kubernetes的门槛大大降低，使得我们每个人都能在成本可控的服务器甚至开发机上实践云原生。

不要只是收藏文章，真正的理解来自于动手实践。建议你找个虚拟机，严格按照上述步骤操作一遍。当你看到Nginx欢迎页面在浏览器中成功加载时，你会真切地感受到，Kubernetes并没有想象中那么遥不可及。

如果在安装过程中遇到任何问题，或者想探讨更高级的主题（如K3s高可用、对接外部数据库等），欢迎在技术社区进行交流。更多的实战经验和资源分享，你可以在 云栈社区 这样的开发者平台找到。

动起来，才是掌握技术的唯一捷径。