当前位置：首页 > news >正文

轻量级Kubernetes部署实战：k3s与Docker的融合方案

news 2026/8/16 7:29:29

1. 项目概述：为什么选择 k3s + Docker 的组合？

在容器编排领域，Kubernetes 无疑是王者，但其庞大的体量和复杂的部署过程常常让个人开发者、边缘计算场景或中小团队望而却步。这时候，轻量级的 k3s 就成为了一个绝佳的选择。k3s 是 Rancher Labs 发布的一个经过 CNCF 认证的 Kubernetes 发行版，它最大的特点就是“轻”——二进制文件小于 100MB，内存占用极低，并且默认使用 containerd 作为容器运行时。但今天我们要聊的，是一个在特定场景下更具吸引力的变体：k3s 的 Docker 版本。

你可能会问，k3s 不是自带 containerd 吗，为什么还要用 Docker？这背后有几个非常实际的考量。首先，生态兼容性。Docker 作为容器技术的普及者，拥有最庞大的用户基础和最成熟的工具链。很多现有的 CI/CD 流水线、监控工具（如 cAdvisor）、日志收集方案，甚至是开发者的肌肉记忆，都是围绕 Docker 构建的。其次，镜像构建与管理。Dockerfile 和 Docker Compose 的易用性在构建和测试阶段无可替代。最后，本地开发体验。对于需要在本地模拟生产环境进行开发的团队，使用 Docker 作为运行时的 k3s 集群，可以无缝使用docker命令行工具来调试容器、查看日志，这种便利性是 containerd 的ctr命令难以比拟的。

因此，“k3s部署-docker版”这个项目，核心目标就是搭建一个既拥有 Kubernetes 强大编排能力，又保留 Docker 友好生态和工具链的轻量级集群。它非常适合用于个人学习、开发测试环境、IoT/边缘设备，或者作为中小型应用在资源受限环境下的生产部署方案。接下来，我将带你从零开始，完整走一遍部署流程，并分享我在多次部署中积累的实战经验和避坑指南。

2. 部署前的核心准备与环境规划

在动手敲命令之前，花点时间做好规划和准备，能避免后续很多不必要的麻烦。部署一个稳定可用的 k3s Docker 版集群，不仅仅是安装软件那么简单。

2.1 硬件与系统需求分析

k3s 以其轻量著称，但对硬件仍有一定要求。对于单节点测试集群（All-in-One），我建议至少准备：

CPU: 1 核（最低），2 核或以上为佳，确保能流畅运行多个容器。
内存: 1 GB（绝对最低限度，仅能运行核心组件），2 GB 可以运行一些基础应用，4 GB 以上体验会好很多。
磁盘: 20 GB 可用空间，用于存放系统、Docker 镜像和 k3s 数据。

对于多节点生产集群，每个节点（包括 Master 和 Worker）都应满足以上要求，并且 Master 节点对内存和稳定性的要求更高。

操作系统方面，主流的 Linux 发行版都可以，我个人最推荐Ubuntu Server LTS（22.04 或 20.04）或CentOS/Rocky Linux/AlmaLinux 8+。它们拥有长期支持，社区资源丰富，遇到问题容易找到解决方案。本次演示将以 Ubuntu Server 22.04 为例。

注意：务必确保你的系统是干净的，没有安装过旧版本的 Docker 或 Kubernetes 组件，否则可能会产生冲突。如果是在旧系统上操作，建议先彻底清理。

2.2 网络与防火墙策略预配置

网络是集群的血管，必须提前疏通。k3s 集群内部组件之间需要通过特定端口通信。

Master 节点（Server 节点）需要开放的端口：
- TCP 6443: Kubernetes API Server 端口，这是最重要的端口，Worker 节点和外部工具（如 kubectl）都通过它连接。
- TCP 10250: Kubelet API 端口，用于 Master 与 Worker 上 Pod 的通信（如 exec, logs, port-forward）。
- UDP 8472: Flannel VXLAN 网络后端默认使用的端口，用于 Pod 跨节点网络通信。如果你使用其他 CNI（容器网络接口），端口可能不同。
- TCP 2379-2380: 如果使用内嵌的 etcd 作为数据存储（多 Server 高可用模式），需要开放这些端口。单节点部署通常不需要。
- TCP 30000-32767: NodePort 服务的端口范围。如果你计划使用 NodePort 方式暴露服务，需要确保这些端口在主机防火墙上可访问。
Worker 节点（Agent 节点）需要开放的端口：
- TCP 10250: Kubelet API。
- UDP 8472: Flannel VXLAN。

实操建议：在开始安装前，最好先配置好系统的防火墙。以 Ubuntu 使用ufw为例，你可以选择在 Master 节点上放行必要端口：

sudo ufw allow 6443/tcp sudo ufw allow 10250/tcp sudo ufw allow 8472/udp sudo ufw allow ssh # 务必保留SSH端口 sudo ufw enable

或者，对于简单的测试环境，你也可以暂时禁用防火墙（sudo ufw disable），但生产环境绝不推荐。

2.3 关键工具与依赖安装

我们的部署将分为两大步：先安装 Docker，再安装指定使用 Docker 作为运行时的 k3s。

第一步：安装 Dockerk3s 对 Docker 版本有要求，建议安装较新的稳定版。这里使用 Docker 官方提供的便捷脚本安装，适合大多数情况。

# 更新软件包索引 sudo apt-get update # 安装必要的依赖，允许 apt 通过 HTTPS 使用仓库 sudo apt-get install -y ca-certificates curl gnupg lsb-release # 添加 Docker 的官方 GPG 密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gosu tee /etc/apt/keyrings/docker.asc > /dev/null # 设置 Docker 稳定版仓库 echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 再次更新，并安装 Docker 引擎 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 启动 Docker 并设置开机自启 sudo systemctl enable --now docker # 将当前用户加入 docker 组，避免每次使用 sudo sudo usermod -aG docker $USER # 重要：退出当前 SSH 会话并重新登录，使组权限生效

安装完成后，运行docker version和docker run hello-world来验证 Docker 是否安装成功并可以拉取镜像。

3. 核心部署流程详解与参数解析

环境准备就绪，现在进入核心的 k3s 安装环节。k3s 提供了极其灵活的安装方式，我们将聚焦于使用 Docker 作为运行时的单节点部署。

3.1 单节点 All-in-One 部署实战

这是最简单、最快速的入门方式。k3s 的安装脚本install.sh可以通过一个命令完成所有工作。为了让 k3s 使用 Docker 而非内置的 containerd，我们需要设置一个关键的环境变量：INSTALL_K3S_EXEC。

执行以下命令：

# 使用国内镜像加速下载，并指定使用 docker 作为容器运行时 curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ INSTALL_K3S_EXEC="--docker" \ sh -

让我们拆解这个命令：

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh: 从 Rancher 的国内镜像站下载安装脚本，速度更快更稳定。
INSTALL_K3S_MIRROR=cn: 告诉安装脚本使用中国境内的镜像源来下载 k3s 二进制文件和必要的镜像。
INSTALL_K3S_EXEC="--docker":这是最核心的参数。它向 k3s 服务传递--docker标志，指示 k3s 使用系统中已安装的 Docker 引擎作为容器运行时。
sh -: 执行下载的脚本。

脚本运行后，它会自动：

下载 k3s 二进制文件。
安装 k3s 相关的系统服务（k3s.service）。
生成集群访问凭证：/etc/rancher/k3s/k3s.yaml。
安装kubectl命令行工具（通过符号链接/usr/local/bin/kubectl）。

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

sudo systemctl status k3s

你应该看到active (running)的状态。现在，你可以使用 kubectl 了：

sudo kubectl get nodes

输出应该显示一个Ready状态的节点，名字是你的主机名。同时，你也可以用 Docker 命令查看容器：

sudo docker ps

你会看到一系列以k8s_为前缀的容器在运行，这些就是 k3s 的核心组件（如 apiserver, scheduler, controller-manager 等），它们现在都运行在 Docker 容器中。

3.2 多节点集群的构建与节点加入

生产环境通常需要多节点以保证高可用。k3s 采用 “Server”（Master）和 “Agent”（Worker）的架构。

第一步：初始化 Master (Server) 节点在第一台机器上，我们不仅指定--docker，还需要获取一个用于 Agent 节点加入的令牌（Token）。

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ INSTALL_K3S_EXEC="server --docker" \ K3S_TOKEN=my_super_secret_token \ sh -

这里多了两个参数：

server --docker: 明确指定以 Server 模式运行，并使用 Docker。
K3S_TOKEN=my_super_secret_token: 自定义一个加入集群的令牌。请务必将其替换为一个强密码并妥善保管。如果省略，脚本会随机生成一个，记录在/var/lib/rancher/k3s/server/node-token文件中。

安装完成后，在 Master 节点上，你需要找到两个关键信息：

Master 节点 IP 地址：使用ip addr或hostname -I查看。
集群令牌：如果你没有通过K3S_TOKEN环境变量设置，则查看文件：sudo cat /var/lib/rancher/k3s/server/node-token。

第二步：添加 Worker (Agent) 节点在另一台已经安装好 Docker 的机器上，运行以下命令：

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ K3S_URL=https://<MASTER_IP>:6443 \ K3S_TOKEN=<MASTER_TOKEN> \ INSTALL_K3S_EXEC="agent --docker" \ sh -

请替换：

<MASTER_IP>: 第一步中获取的 Master 节点 IP 地址。
<MASTER_TOKEN>: 第一步中获取或设置的令牌。
agent --docker: 指定以 Agent 模式运行，并使用 Docker。

等待命令执行完成。回到 Master 节点，运行kubectl get nodes，你应该能看到两个节点，并且状态都是Ready。

3.3 关键配置解析与优化建议

安装只是第一步，合理的配置能让集群更稳定、更高效。k3s 的配置主要位于/etc/rancher/k3s/config.yaml（如果不存在可以创建）。

常用配置示例：

# /etc/rancher/k3s/config.yaml write-kubeconfig-mode: "0644" # 放宽 kubeconfig 文件权限，方便非root用户使用 node-ip: 192.168.1.100 # 显式指定节点IP，防止在多网卡环境下出错 docker: true # 明确使用 Docker 运行时，这是我们的核心配置>sudo systemctl restart k3s

关于网络插件：k3s 默认集成 Flannel。如果你对网络有更高要求（如网络策略、性能优化），可以禁用 Flannel 并使用其他 CNI，如 Calico 或 Cilium。这需要在安装时传递--flannel-backend=none参数，并在安装后自行部署 CNI 插件。对于大多数中小规模场景，默认的 Flannel 已经足够。

4. 部署后的验证、管理与运维要点

集群跑起来了，但这只是开始。如何验证它工作正常？如何高效管理？日常运维要注意什么？

4.1 集群状态验证与基础操作

首先，进行一个全面的健康检查：

# 1. 查看所有节点状态 kubectl get nodes -o wide # 确保 STATUS 为 Ready，并且 INTERNAL-IP 正确。 # 2. 查看所有系统 Pod 状态（在 kube-system 命名空间） kubectl get pods -n kube-system # 确保所有 Pod 都是 Running 状态，且 READY 列显示为 1/1, 2/2 等。 # 3. 查看核心组件状态 kubectl get cs # 显示 scheduler, controller-manager, etcd 的健康状态（新版K8s可能已弃用，更推荐看Pod） # 4. 部署一个测试应用 kubectl create deployment nginx-test --image=nginx:alpine kubectl expose deployment nginx-test --port=80 --type=NodePort # 获取 NodePort 端口 kubectl get svc nginx-test # 使用节点的 IP 和分配的 NodePort 访问，应能看到 Nginx 欢迎页。

基础管理命令：

kubectl cluster-info: 查看集群信息。
kubectl describe node <node-name>: 查看节点的详细信息，包括资源、事件和污点。
kubectl logs <pod-name> [-c <container-name>]: 查看 Pod 或容器日志。
kubectl exec -it <pod-name> -- /bin/sh: 进入 Pod 的容器内执行命令。

4.2 Kubectl 配置与权限管理

安装后，kubeconfig 文件默认位于/etc/rancher/k3s/k3s.yaml，且权限为600（仅 root 可读）。为了在普通用户下使用kubectl，有两种方式：

使用 sudo：每次命令前加sudo，如sudo kubectl get pods。

复制并修改权限（推荐用于个人环境）：

mkdir -p ~/.kube sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config sudo chown $(id -u):$(id -g) ~/.kube/config # 修改配置文件中的 server 地址，如果从非 master 节点访问，需将 127.0.0.1 改为 master 节点的 IP sed -i 's/127.0.0.1/<MASTER_IP>/g' ~/.kube/config

之后，你就可以直接使用kubectl命令了。

4.3 镜像管理与加速策略

由于网络原因，从 Docker Hub 拉取镜像可能很慢。k3s 使用 Docker 后，镜像拉取策略完全由 Docker 控制。因此，我们需要配置 Docker 镜像加速器。

编辑或创建 Docker 守护进程配置文件/etc/docker/daemon.json：

{ "registry-mirrors": [ "https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com", "https://mirror.baidubce.com" ], "exec-opts": ["native.cgroupdriver=systemd"], "log-driver": "json-file", "log-opts": { "max-size": "100m" }, "storage-driver": "overlay2" }

配置说明：

registry-mirrors: 添加国内镜像加速地址，可以多个。
native.cgroupdriver=systemd: 确保 Docker 的 cgroup 驱动与 k3s（默认使用 systemd）一致，避免警告。
storage-driver: 推荐使用overlay2。

修改后，重启 Docker 生效：

sudo systemctl daemon-reload sudo systemctl restart docker

之后，无论是 k3s 拉取系统镜像，还是你通过kubectl部署应用，都会通过加速器拉取，速度会有显著提升。

5. 常见问题深度排查与解决方案实录

在实际部署和运维中，你一定会遇到各种问题。下面是我总结的几个最常见的问题及其排查思路。

5.1 节点 NotReady 状态排查

当kubectl get nodes显示节点状态为NotReady，这是最常遇到的问题。

排查步骤：

检查 k3s 服务状态：在问题节点上执行sudo systemctl status k3s。如果服务失败，查看详细日志sudo journalctl -u k3s -f。
检查容器运行时：执行sudo docker ps。如果 Docker 本身没有运行，k3s 的组件容器就无法启动。确保 Docker 服务是活跃的：sudo systemctl status docker。
检查网络插件 Pod：kubectl get pods -n kube-system | grep flannel（或你使用的其他 CNI）。如果 Flannel Pod 处于 CrashLoopBackOff 或 Error 状态，通常是网络配置或镜像拉取失败。
- 镜像拉取失败：在节点上手动拉取镜像sudo docker pull rancher/mirrored-flannelcni-flannel:v1.22.2（版本需匹配）。检查 Docker 加速器配置。
- 网络冲突：检查主机网络是否与 Pod 网段（默认10.42.0.0/16）或 Service 网段（默认10.43.0.0/16）冲突。可以在安装时通过--cluster-cidr和--service-cidr参数修改。
检查节点详情：kubectl describe node <node-name>。在Conditions部分，会明确显示是MemoryPressure、DiskPressure、PIDPressure还是NetworkUnavailable导致 NotReady。
检查防火墙：这是多节点集群的常见杀手。确保 Master 和 Worker 节点之间按2.2章节所述的必要端口是互通的。可以使用telnet <MASTER_IP> 6443在 Worker 节点上测试。

5.2 Docker 与 Containerd 冲突导致安装失败

如果你之前安装过 containerd 或旧版本的 Docker，可能会遇到冲突。错误信息可能包含“container runtime is not running”。

解决方案：

彻底清理旧的容器运行时：

sudo k3s-uninstall.sh # 如果安装过k3s sudo /usr/local/bin/k3s-killall.sh sudo systemctl stop docker sudo systemctl disable docker sudo apt-get purge -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo rm -rf /var/lib/docker sudo rm -rf /var/lib/containerd sudo rm -rf /etc/docker sudo rm -rf /var/lib/rancher sudo rm -rf /opt/containerd

重启主机。
然后按照本文3.1章节的步骤，重新安装 Docker 和 k3s。

5.3 镜像拉取缓慢或失败问题

除了配置 Docker 加速器，在 Kubernetes 层面还可以为 Pod 配置imagePullSecrets来从私有仓库拉取镜像。但对于公开镜像，更常见的是拉取超时。

临时解决方案：在节点上手动用 Docker 拉取镜像，因为 Docker 配置了加速器，成功率更高。

sudo docker pull nginx:alpine

然后，在 Deployment 的 YAML 文件中，为容器设置镜像拉取策略为IfNotPresent：

spec: containers: - name: myapp image: nginx:alpine imagePullPolicy: IfNotPresent # 优先使用本地镜像

这样，kubelet 会先检查本地是否存在该镜像，如果存在就不再拉取。

5.4 资源不足导致 Pod 无法调度

在资源有限的机器上，很容易遇到Insufficient cpu或Insufficient memory的错误。

排查与解决：

kubectl describe node查看节点的可分配资源（Allocatable）和已分配请求（Requests）。
优化应用资源配置：在 Deployment 中为容器设置合理的requests和limits。
```
resources: requests: memory: "64Mi" cpu: "250m" limits: memory: "128Mi" cpu: "500m"
```
requests是调度依据，limits是运行上限。不设置requests会导致调度器无法判断资源需求。
清理无用镜像和容器：sudo docker system prune -a -f可以清理 Docker 占用的磁盘空间。
考虑增加节点或升级机器配置。

5.5 存储与持久化卷的注意事项

k3s 默认使用local-path作为 StorageClass，它提供动态卷供应，但卷是节点本地存储。这意味着，如果你的 Pod 被调度到其他节点，它将无法访问之前节点上的数据。

对于有状态应用（如数据库）：

单节点场景：local-path可以满足测试需求。
多节点场景：必须配置网络存储，如 NFS、Ceph、Longhorn 等。Longhorn 是一个轻量级、云原生的分布式块存储系统，由 Rancher 开发，与 k3s 集成度非常好，是 k3s 生态中首选的持久化存储方案。你可以通过 Helm 轻松部署 Longhorn。

部署一个简单的 NFS 客户端 Provisioner 也是一个快速入门网络存储的方法，但这需要你先有一个 NFS 服务器。

6. 进阶配置：监控、日志与高可用考量

一个健壮的集群离不开可观测性。对于 k3s Docker 版，监控和日志收集有其特点。

6.1 监控方案：Prometheus 与 Grafana 部署

由于 k3s 核心组件运行在 Docker 容器中，传统的宿主机监控工具（如top）无法直接看到容器内进程的资源使用情况。我们需要部署基于 Kubernetes 的监控栈。

最经典的组合是 Prometheus + Grafana。你可以使用 Helm 包管理器来部署，但 k3s 默认不包含 Helm。我们可以先安装 Helm，或者使用社区维护的kube-prometheus-stack的简化部署方式。

这里提供一个使用原生 YAML 文件（来自 prometheus-operator 项目）的快速部署示例，但请注意，这可能需要根据你的 k3s 版本调整 API 版本：

克隆或下载 kube-prometheus 项目的 manifests。
应用核心监控组件：kubectl apply -f manifests/setup/然后kubectl apply -f manifests/。
暴露 Grafana 服务：kubectl patch svc grafana -n monitoring --type='json' -p '[{"op":"replace","path":"/spec/type","value":"NodePort"}]'。

更稳定和推荐的方式是使用 Helm：

# 添加 Prometheus 社区仓库 helm repo add prometheus-community https://prometheus-community.github.io/helm-charts helm repo update # 安装 kube-prometheus-stack helm install prometheus prometheus-community/kube-prometheus-stack -n monitoring --create-namespace

安装后，你可以通过 NodePort 或 Ingress 访问 Grafana（默认用户/密码：admin/prom-operator）来查看集群和应用的监控仪表盘。

6.2 日志收集方案选择

日志同样分散在各个 Docker 容器中。常见的方案有：

EFK Stack：Elasticsearch, Fluentd, Kibana。功能强大但资源消耗也大，对于轻量级 k3s 集群可能过重。
Loki Stack：Grafana Loki, Promtail。由 Grafana 实验室推出，设计理念是“为日志而生的 Prometheus”，索引小，资源占用低，与 Grafana 集成无缝，非常适合 k3s 这类轻量集群。

部署 Loki Stack 同样可以使用 Helm：

helm repo add grafana https://grafana.github.io/helm-charts helm repo update helm install loki grafana/loki-stack -n logging --create-namespace --set promtail.enabled=true,grafana.enabled=true

部署后，在 Grafana 中添加 Loki 数据源（地址为http://loki.logging:3100），就可以在 Grafana 中统一查询日志了。

6.3 向生产环境迈进：高可用与备份

单节点 Server 存在单点故障风险。k3s 支持两种高可用（HA）模式：

嵌入式 etcd 高可用（推荐）：在安装 Server 节点时，指定相同的K3S_TOKEN，并使用--cluster-init标志初始化第一个节点，后续 Server 节点使用--server参数指向集群。这种方式数据存储在多个节点内置的 etcd 中，部署简单。
```
# 第一个 Master 节点 curl ... | INSTALL_K3S_EXEC="server --cluster-init --docker" sh - # 后续 Master 节点 curl ... | K3S_URL=https://<第一个节点IP>:6443 K3S_TOKEN=<token> INSTALL_K3S_EXEC="server --docker" sh -
```
外部数据库高可用：使用外部的 MySQL、PostgreSQL 或 etcd 作为数据存储。所有 Server 节点在安装时指向同一个外部数据库。这种方式更适合已有数据库环境或需要更专业 etcd 运维的场景。

集群备份与恢复：对于嵌入式 etcd 的 HA 集群，k3s 提供了etcd-snapshot工具。你可以设置定时任务（CronJob）来定期执行备份：

# 手动创建快照 sudo k3s etcd-snapshot save --snapshot-compress # 快照文件默认保存在 /var/lib/rancher/k3s/server/db/snapshots/ # 设置定时备份（每日凌晨2点） sudo crontab -e # 添加一行：0 2 * * * /usr/local/bin/k3s etcd-snapshot save --snapshot-compress

恢复时，停止 k3s 服务，使用快照文件恢复，然后重启服务。

从单节点测试到多节点高可用生产集群，k3s with Docker 提供了极大的灵活性。它降低了 Kubernetes 的门槛，让你既能享受 K8s 生态的强大，又能利用 Docker 工具的便利。关键在于理解每个组件的作用，并根据自己的场景做出合适的配置选择。记住，监控和日志是你在生产环境中发现问题、定位问题的眼睛，越早搭建越好。

查看全文

http://www.cnnetsun.cn/news/4050539.html