6.17 边缘计算入门——K3s 轻量 Kubernetes 部署

预计阅读时间：18 分钟

6.2：Kubernetes 入门 介绍了标准 Kubernetes。边缘计算场景（IoT 网关、零售门店、工厂车间）需要在资源受限的设备上运行容器化应用。K3s 是 SUSE 开发的轻量 K8s 发行版，单二进制、占用 <512MB 内存，是边缘场景的标准选择。

学习目标

学完本章，你将能够：

• 掌握 K3s 一行安装、Server / Agent 节点加入与 kubeconfig 配置
• 理解 K3s 与标准 K8s 在组件、数据库、内存占用上的取舍
• 掌握通过 --disable 禁用内置组件构建边缘极简集群
• 掌握 Hub-Spoke 边缘部署模式与 KubeEdge / Fleet 中心化管理
• 掌握 config.yaml 资源优化（max-pods、eviction-hard、system-reserved）
• 理解边缘场景的 OTA 更新、镜像预拉取与离线容错设计

前置知识

• 6.2：Kubernetes 入门 Kubernetes 容器编排入门——Pod、Deployment 与集群概念
• 3.1：Docker 容器入门 Docker 容器入门——镜像、容器与基础运维命令
• 6.1：容器底层原理 容器底层原理——namespace 与 cgroups 资源隔离机制
• 5.2：Docker 生产实践 Docker 生产实践——多阶段构建、瘦镜像与资源限制

K3s vs 标准 K8s

K3s 多节点架构

K3s 采用 Server / Agent 两级架构，对应标准 K8s 的 Master / Worker，但控制面被压缩进一个二进制：Server 节点聚合 API Server、Controller Manager、Scheduler 与数据存储，Agent 节点只保留 kubelet、containerd 与 CNI 插件。

• Server 节点——运行 k3s server 进程，负责全部控制面职责与数据存储（默认 SQLite），对外监听 6443（API）、10250（kubelet）等端口。
• Agent 节点——运行 k3s agent 进程，通过 6443 端口与 Server 通信，使用 node-token 完成注册，在本地调度容器。
• 注册流程——Agent 启动时携带 K3S_URL 与 K3S_TOKEN 访问 Server 注册端点，Server 校验 token 后下发 kubelet 证书与加入信息。
• 角色边界——任意节点可同时运行 server 与 agent 进程（默认安装即 server + agent 合一），边缘单机模式正是利用这一点。

数据存储选型

# 嵌入式 etcd：第一台 Server 指定 --cluster-init 初始化
curl -sfL https://get.k3s.io | sh -s - server \
  --cluster-init --token=K3sClusterSecret

# 后续 Server 以 --server 参数加入 etcd 集群
curl -sfL https://get.k3s.io | sh -s - server \
  --server https://server1:6443 --token=K3sClusterSecret

# 查看 etcd 快照与成员状态
sudo k3s etcd-snapshot list

注意：单 Server + SQLite 是最常见的边缘形态，但它没有高可用——Server 宕机后 Agent 上的 Pod 继续运行，但集群 API 不可写、无法再调度。边缘场景通常可以接受"控制面中断、数据面不停"。

Flannel 网络模式

K3s 内置 flannel 作为默认 CNI，按后端不同适配不同的边缘网络形态：

• VXLAN（默认）——UDP 封装，跨三层网络通信，任何边缘设备都适用，封装开销略高。
• host-gateway——二层直通，性能最好，要求所有节点在同一二层网络，适合门店/车间的局域网。
• wireguard-native——加密隧道，适合公网互联的多地边缘，要求内核支持 WireGuard（5.6+）。
• ipsec——IPSec 加密隧道，兼容老内核，性能低于 WireGuard。

# host-gateway 模式（同二层网络）
curl -sfL https://get.k3s.io | sh -s - server \
  --flannel-backend=host-gateway

# wireguard 加密隧道模式（公网互联）
curl -sfL https://get.k3s.io | sh -s - server \
  --flannel-backend=wireguard-native

# 双栈（IPv4 + IPv6）
curl -sfL https://get.k3s.io | sh -s - server \
  --cluster-cidr=10.42.0.0/16,fd00:42::/56 \
  --service-cidr=10.43.0.0/16,fd00:43::/112

1. 安装 K3s

# 一行安装（Server 节点，内嵌 SQLite）
curl -sfL https://get.k3s.io | sh -

# 安装后自动配置 kubeconfig
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

# 验证
kubectl get nodes
kubectl get pods -A

Agent 节点加入集群

# 在 Server 节点获取 token
sudo cat /var/lib/rancher/k3s/server/node-token
# 输出类似：K1084d...::server:xxxxx

# 在 Agent 节点加入
curl -sfL https://get.k3s.io | K3S_URL=https://server-ip:6443 \
  K3S_TOKEN=K1084d...::server:xxxxx sh -

禁用内置组件（边缘极简模式）

# 安装时禁用不需要的组件
curl -sfL https://get.k3s.io | sh -s - server \
  --disable servicelb \
  --disable traefik \
  --write-kubeconfig-mode 644 \
  --tls-san=192.168.1.100

2. 边缘部署模式

单节点边缘（最简）

# 边缘设备上直接运行
curl -sfL https://get.k3s.io | sh -
# 无需 Agent，单机运行所有控制面 + 工作负载

Hub-Spoke 模式（中心管理 + 边缘执行）

# 中心集群（Hub）：标准 K8s
# 边缘集群（Spoke）：K3s
# 通过 Fleet/KubeEdge 管理

# KubeEdge 部署方式
# 注意：EdgeCore 是独立组件，经 CloudCore 接入，不是用 K3S_URL 加入的 K3s 节点
# 中心云侧（CloudCore）
helm install cloudcore edgeinfra/cloudcore --namespace kubeedge

# 边缘设备侧（EdgeCore）：下载二进制、配置 cloudcore 地址与 token
# wget https://github.com/kubeedge/kubeedge/releases/download/v1.20.0/edgecore-linux-amd64.tar.gz
# 修改 /etc/kubeedge/config/edgecore.yaml 中 cloudcore 地址与 token 后：
# systemctl enable --now edgecore

# 而 K3s 边缘节点是标准 K3s agent（与中心集群同一套控制面）
curl -sfL https://get.k3s.io | K3S_URL=https://hub:6443 \
  K3S_TOKEN=xxx sh -

多节点拓扑：中心 / 区域 / 边缘三层

• 中心层（Hub）——标准 K8s 或 K3s 嵌入式 etcd 集群，承载控制面、镜像仓库、监控聚合与发布编排。
• 区域层（Regional）——按区域/省份部署 K3s 集群，内网组网（host-gateway），就近缓存镜像与日志。
• 边缘层（Edge）——门店/车间的单节点或双节点 K3s，SQLite 存储，故障时独立运行不依赖上行链路。

规模参考：10 台以内单节点直连 Hub；10-100 台建议加区域层；超过 100 台必须用 Fleet/KubeEdge 做分组发布，逐组灰度。

嵌入式场景实战

边缘设备形态差异巨大：从 1GB 内存的树莓派到带 GPU 的 Jetson 盒子，部署参数完全不同。以下按常见设备类型给出参考配置与注意事项：

极简组件清单

内存紧张时按需裁剪内置组件，以下是完整可禁用清单（每个组件约省 20-50MB 内存）：

curl -sfL https://get.k3s.io | sh -s - server \
  --disable traefik \          # 默认 Ingress 控制器
  --disable servicelb \        # Service LoadBalancer
  --disable metrics-server \   # 指标服务（外部监控代替）
  --disable local-storage \    # 内置 local-path provisioner
  --disable coredns \          # 内置 DNS（慎用）
  --disable helm-controller \
  --disable-cloud-controller \
  --write-kubeconfig-mode 644

实际部署中建议保留 CoreDNS 与 kube-proxy：多数工作负载依赖服务发现，没有 DNS 的集群几乎不可用。先禁用 traefik 与 servicelb 即可获得大部分收益。

GPU 节点支持

# Agent 节点安装完成后，验证 GPU 是否被识别
kubectl get nodes -o json | jq '.items[].status.capacity'
# 期望输出中包含 nvidia.com/gpu: 1

# 安装 NVIDIA device plugin（DaemonSet，官方清单）
kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/main/nvidia-device-plugin.yml

# 为 GPU 工作负载声明资源
apiVersion: apps/v1
kind: Deployment
metadata:
  name: inference
spec:
  template:
    spec:
      containers:
      - name: model
        image: nvcr.io/nvidia/tritonserver:24.05-py3
        resources:
          limits:
            nvidia.com/gpu: 1

离线安装（airgap）

工厂车间、门店等内网环境无法访问公网，需要提前下载安装包与镜像后离线导入：

# 1. 在联网机器上下载 k3s 二进制与 airgap 镜像包
wget https://github.com/k3s-io/k3s/releases/download/v1.32.2+k3s1/k3s
wget https://github.com/k3s-io/k3s/releases/download/v1.32.2+k3s1/k3s-airgap-images-amd64.tar

# 2. 拷贝到离线设备
scp k3s k3s-airgap-images-amd64.tar root@edge-device:/tmp/

# 3. 离线设备上安装（跳过网络下载）
sudo install -m 755 k3s /usr/local/bin/k3s
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp k3s-airgap-images-amd64.tar /var/lib/rancher/k3s/agent/images/
INSTALL_K3S_SKIP_DOWNLOAD=true curl -sfL https://get.k3s.io | sh -s - server

# 4. 业务镜像离线导入（ctr 或 crictl 均可）
sudo k3s ctr images import /tmp/business-images.tar
# 后续节点重复第 2-3 步即可加入集群

3. 资源优化

# K3s 配置优化（适用于 1GB RAM 设备）
# /etc/rancher/k3s/config.yaml
write-kubeconfig-mode: "0644"
kube-apiserver-arg:
  - "max-requests-inflight=50"         # 减少并发请求
  - "event-ttl=1h"                      # 缩短事件保留
kubelet-arg:
  - "max-pods=50"                       # 限制 Pod 数量
  - "eviction-hard=nodefs.available<10%" # 内存不足时驱逐
  - "system-reserved=cpu=100m,memory=256Mi" # 预留系统资源

# 精简镜像（使用 distroless/distroless 基础镜像）
# 多阶段构建减小镜像体积
FROM golang:1.22 AS builder
RUN CGO_ENABLED=0 go build -o /app .

FROM gcr.io/distroless/static:nonroot
COPY --from=builder /app /app
ENTRYPOINT ["/app"]

组件内存占用对比

cgroup 与配额限制

# 宿主机层：用 systemd 限制 k3s 进程内存（防止 OOM 拖垮整机）
sudo systemctl set-property k3s.service MemoryMax=768M
sudo systemctl set-property k3s-agent.service MemoryMax=512M

# 工作负载层：每个 Pod 必须声明 requests 与 limits
apiVersion: apps/v1
kind: Deployment
metadata:
  name: edge-worker
spec:
  template:
    spec:
      containers:
      - name: app
        image: myapp:1.2.0
        imagePullPolicy: IfNotPresent
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 256Mi

边缘设备上最危险的不是容器超限，而是容器无限——没有 limits 的 Pod 会在宿主机内存耗尽时拖垮 kubelet，导致整机 NotReady。

存储：local-path 与 NFS 对比

# 查看默认 local-path StorageClass
kubectl get sc

# 部署 NFS 动态供给作为第二存储类
helm install nfs nfs-subdir-external-provisioner/nfs-subdir-external-provisioner \
  --set nfs.server=192.168.1.50 --set nfs.path=/data/k8s \
  --set storageClass.name=nfs

网络性能调优

# kube-proxy 换 ipvs 模式（高连接数场景）
curl -sfL https://get.k3s.io | sh -s - server \
  --kube-proxy-arg "proxy-mode=ipvs"

# conntrack 表满会导致新建连接丢包
sudo sysctl -w net.netfilter.nf_conntrack_max=655350
echo "net.netfilter.nf_conntrack_max = 655350" | sudo tee /etc/sysctl.d/99-k3s.conf

# 边缘链路 MTU 不匹配时，调整 kube-flannel-cfg ConfigMap 中的 VXLAN MTU（默认 1450）
# 例如双层叠加隧道环境改为 1400
kubectl edit cm kube-flannel-cfg -n kube-flannel

4. OTA 更新（边缘批量更新）

# 使用 K3s 的 System Upgrade Controller 实现滚动更新
apiVersion: upgrade.cattle.io/v1
kind: Plan
metadata:
  name: k3s-upgrade
  namespace: system-upgrade
spec:
  concurrency: 1
  cordon: true
  nodeSelector:
    matchExpressions:
    - key: k3s.io/hostname
      operator: Exists
  serviceAccountName: system-upgrade-controller
  upgrade:
    image: rancher/k3s-upgrade
  version: v1.32.2+k3s1

5. 边缘场景 Checklist

故障案例

边缘设备分散、无人值守，故障排查依赖可远程执行的命令与清晰的处置流程。以下是 5 个高频故障场景：

案例一：SQLite 损坏导致集群失联

现象：设备突然断电后 k3s 无法启动，日志报 database disk image is malformed。

# 确认故障
sudo journalctl -u k3s -e | grep -i sqlite

# 备份后重建控制面数据库（工作负载数据不受影响）
sudo systemctl stop k3s
sudo cp -a /var/lib/rancher/k3s/server/db /tmp/db.bak
sudo rm -rf /var/lib/rancher/k3s/server/db
sudo systemctl start k3s
# 重建后需重新加入 Agent 节点并重新 apply 工作负载清单

预防：避免突然断电（加装 UPS 或电池），数据目录放 SSD；生产边缘集群改用嵌入式 etcd 三节点。

案例二：证书过期导致 kubectl 无法认证

现象：kubectl 报 x509: certificate has expired or is not yet valid。K3s 控制面证书有效期 1 年，长时间运行的集群必然遇到。

# 检查所有证书有效期
sudo k3s cert check --expires

# 轮换控制面证书并重启
sudo k3s certificate rotate
sudo systemctl restart k3s

# 轮换 Agent 节点证书
sudo k3s certificate rotate && sudo systemctl restart k3s-agent

案例三：节点掉线后无法重连

现象：网络恢复后节点仍显示 NotReady，Pod 卡在 Unknown 状态。

# Server 侧观察节点状态与事件
kubectl describe node edge-01 | tail -30
kubectl get events -A --sort-by=.lastTimestamp | tail -20

# Agent 侧查看连接日志
sudo journalctl -u k3s-agent -e | grep -i "failed to connect"

# 调大失联容忍时间，避免短暂断网触发驱逐（config.yaml）
# kubelet-arg: "node-status-update-frequency=20s"
# kube-controller-manager-arg: "node-monitor-grace-period=90s"

案例四：磁盘写满导致节点 NotReady

现象：kubelet 报 disk pressure，节点进入 NotReady，日志落盘失败，Pod 反复 Evicted。

# 定位磁盘占用
df -h && du -sh /var/lib/rancher/k3s/* 2>/dev/null | sort -rh | head

# 清理不用的镜像
sudo k3s crictl rmi --prune
# 清理 systemd 日志
sudo journalctl --vacuum-size=100M

# 根治：开启镜像垃圾回收（config.yaml）
# kubelet-arg:
#   - "image-gc-high-threshold=80"
#   - "image-gc-low-threshold=70"

案例五：内存不足 OOM 连环崩溃

现象：内存耗尽触发 systemd OOM-kill，k3s 进程反复重启，业务 Pod 全部被打断。

# 查看内核 OOM 记录
sudo journalctl -k | grep -i "out of memory" | tail

# 查看 k3s 进程实际内存
sudo systemctl status k3s | grep -i memory

# 找出内存大户 Pod
kubectl top pods -A --sort-by=memory | head -10

# 兜底：为 k3s 设置内存上限，并允许使用 swap
sudo systemctl set-property k3s.service MemoryMax=512M
sudo systemctl set-property k3s.service MemorySwapMax=512M

案例六：镜像仓库不可达导致滚动更新卡住

现象：门店网络专线抖动后，新版本滚动更新一直不完成——Pod 卡在 ImagePullBackOff，节点上又没有旧版本镜像的本地缓存。

# 1. 确认卡住原因：镜像拉取失败
kubectl get pods -A | grep -i imagepull
kubectl describe pod <name> | grep -A3 "ImagePull"

# 2. 网络恢复后手动触发重试
kubectl rollout restart deployment/edge-app

# 3. 根治（四件事）：
#    a. 部署本地镜像缓存仓库（如 Harbor 代理模式）到门店网络内
#    b. 工作负载 imagePullPolicy: IfNotPresent + 发布前预拉取
#    c. 中心发版前先在边缘节点预拉取（k3s crictl pull），
#       发布只做 imageTag 切换——拉取失败窗口从分钟级降到零
#    d. 边缘节点失联超过阈值时，发布自动暂停并告警（超时自动回滚）

生产落地 Checklist

从实验环境走向生产，需要在更新、备份、监控、安全四个维度补齐工程能力：

更新策略

• 固定补丁级升级——边缘集群只做 x.y.z+k3s1 补丁级升级，不做跨大版本；先在测试设备验证，再批量推行。
• 分批灰度——System Upgrade Controller 设置 concurrency: 1，cordon + drain 后逐节点升级，观察无异常再放行下一台。
• 回滚预案——升级前保存快照（etcd 模式）或备份 /var/lib/rancher/k3s 目录，并保留上一版本安装包，便于快速回退。

备份

# SQLite 单节点：冷备份（停服拷贝，最可靠）
sudo systemctl stop k3s
sudo tar czf /backup/k3s-full.tar.gz /var/lib/rancher/k3s
sudo systemctl start k3s

# 嵌入式 etcd：在线快照 + 定期清理
sudo k3s etcd-snapshot save --snapshot-dir=/backup/etcd
sudo k3s etcd-snapshot list --snapshot-dir=/backup/etcd
sudo k3s etcd-snapshot prune --snapshot-dir=/backup/etcd --keep 7

# 业务数据（PV）：rsync / restic 同步到中心存储
restic -r s3:s3.aliyun.com/bucket backup /var/lib/rancher/k3s/storage

监控（k3s + Prometheus）

# 边缘 Server 开启指标只读端口（config.yaml）
kubelet-arg:
  - "read-only-port=10255"

# 中心 Prometheus 配置抓取
scrape_configs:
  - job_name: edge-k3s
    scheme: https
    static_configs:
      - targets: ["edge-01:6443", "edge-02:6443"]
    bearer_token_file: /etc/prometheus/k3s.token
    tls_config:
      insecure_skip_verify: true

重点告警：节点 NotReady、磁盘剩余低于 10%、内存余量不足、kubelet 重启次数、etcd leader 切换次数。

安全加固

• Secrets 加密——K3s 默认 Secrets 明文存于 SQLite/etcd，开启 --secrets-encryption，加密配置生成于 /var/lib/rancher/k3s/server/cred/encrypt-config.json。
• RBAC 最小权限——为运维人员创建只读 RoleBinding；关闭匿名访问：--kube-apiserver-arg=anonymous-auth=false。
• 网络最小化——6443 与 10250 端口只对中心网络/管理网段开放；跨公网互联使用 WireGuard 隧道加密。
• 访问审计——边缘设备 SSH 仅允许密钥登录，开启 audit-log 记录 kubectl 操作，定期巡检。

常见错误

• kubectl 无法连接集群——确认 KUBECONFIG 环境变量指向 /etc/rancher/k3s/k3s.yaml，非 root 用户需拷贝到 ~/.kube/config 并修改文件权限为 600。
• Agent 节点加入失败——检查 Server 节点的 6443 端口是否可从 Agent 访问，确认 token 未过期（重新从 Server 获取），时钟偏差过大也会导致 TLS 握手失败。
• Pod 处于 Pending 状态——边缘设备资源不足时调度会失败，使用 kubectl describe pod 查看 Events，检查节点 kubectl top nodes 确认剩余资源，或缩减工作负载。
• 网络中断后 Pod 无法恢复——确认部署配置了 restartPolicy: Always，检查离线场景下镜像是否已预拉取到本地（k3s crictl images），否则网络恢复前 Pod 无法重建。
• K3s 服务启动失败——执行 journalctl -u k3s -f 查看日志，常见原因包括：SQLite 锁损坏（删 /var/lib/rancher/k3s/server/db 重建）、端口冲突（6443 被占用）、内存不足。
• 证书过期导致批量失联——K3s 证书有效期 1 年，长时间运行的边缘集群会集中过期。把 k3s cert check --expires 接入月度巡检，或联动 System Upgrade Controller 统一轮换。
• 离线节点更新后版本不一致——airgap 环境下直接改镜像 tag 会因仓库不可达拉取失败。离线更新必须走「先导入镜像包，再滚动切换」两步，并保留上一版本镜像直到全部节点确认健康。

最佳实践

• 边缘镜像预拉取——在网络中断前使用 k3s crictl pull 将所需镜像拉取到本地，确保工作负载在离线状态下仍可正常运行。
• 禁用不需要的组件——安装时通过 --disable 关闭 servicelb、traefik 等，减少内存占用，降低攻击面。
• 使用 distroless 基础镜像——多阶段构建配合 distroless 基础镜像，可将容器镜像从数百 MB 压缩到几 MB，显著降低边缘设备存储压力。
• 配置 OTA 滚动更新——使用 System Upgrade Controller 配合 concurrency 和 cordon 参数，实现边缘节点无停机批量升级。
• 统一监控上报——部署 Prometheus Remote Write 将边缘指标集中上报到中心集群，便于统一告警和故障排查。
• 边缘镜像三件套——本地缓存仓库 + 发布前预拉取 + imagePullPolicy: IfNotPresent，把「仓库不可达」从发布事故降级为无感事件。
• 分层监控上报——边缘节点只上报核心指标（节点状态、磁盘、内存、kubelet 重启次数），明细日志留在本地按需拉取，避免带宽成本失控。

练习题

1. 在两台虚拟机上部署 K3s（1 Server + 1 Agent），验证 kubectl get nodes 显示两个 Ready 节点，并在 Agent 节点上调度一个 Nginx Pod。
2. 编写 K3s config.yaml 配置文件，将 max-pods 限制为 20、system-reserved 设为 CPU 100m + 内存 128Mi，在 1GB RAM 的设备上验证配置生效。
3. 创建一个 OTA 升级 Plan YAML，将集群从 K3s v1.29 升级到 v1.30，设置 concurrency: 1 逐节点升级，并用 kubectl get plan 观察升级进度。
4. 模拟门店断网场景：断掉边缘节点到镜像仓库的网络，发起一次滚动更新，观察 ImagePullBackOff 与恢复过程，写出三种缓解手段的对比。

学习检查点

学完本章后，请检验自己是否掌握以下内容：

本章总结

K3s 以单二进制和 <512MB 内存占用把 Kubernetes 带到资源受限的边缘设备，保留标准 K8s 的 API 与工作负载模型。边缘部署的关键是裁掉不需要的组件、预拉取镜像保证离线可用，并用 OTA 滚动更新与统一监控管理分散节点。

延伸阅读