在树莓派（ARM 架构）上部署轻量级 K3s 边缘集群的完整指南如下：

一、前置准备

1. 硬件要求

   • 树莓派 3B+/4（推荐 4B 2GB+ 内存）
   • 至少 2 台设备（1 个 Server + 1 个 Agent）
   • 32GB+ 高速 MicroSD 卡
   • 稳定千兆网络环境

2. 系统配置

   # 所有节点执行
   sudo raspi-config nonint do_memory_split 16  # 分配 GPU 内存
   sudo raspi-config nonint do_expand_rootfs    # 扩展文件系统
   sudo sed -i 's/CONF_SWAPSIZE=100/CONF_SWAPSIZE=1024/' /etc/dphys-swapfile  # 调整交换空间
   sudo reboot
   

二、安装 K3s Server（主节点）

# 使用官方安装脚本（ARM64 架构）
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server" sh -s - \
  --disable traefik \
  --write-kubeconfig-mode 644 \
  --kubelet-arg="eviction-hard=memory.available<100Mi"

# 验证安装
sudo kubectl get nodes -o wide

三、安装 K3s Agent（工作节点）

1. 获取加入凭证
   在主节点执行：

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

2. 加入集群
   在工作节点执行（替换参数）：

   curl -sfL https://get.k3s.io | K3S_URL=https://<SERVER_IP>:6443 K3S_TOKEN=<NODE_TOKEN> sh -s - \
     --kubelet-arg="eviction-hard=memory.available<50Mi"
   

四、关键优化配置

1. 内核参数调整

   # 所有节点执行
   echo "vm.swappiness=10" | sudo tee -a /etc/sysctl.conf
   echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
   sudo sysctl -p
   

2. 持久化存储方案
   使用 local-path-provisioner（默认启用）：

   # storage-class.yaml
   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: local-path
   provisioner: rancher.io/local-path
   volumeBindingMode: WaitForFirstConsumer
   reclaimPolicy: Delete
   

五、部署示例应用

1. 创建测试部署

   kubectl create deploy nginx-test --image=nginx:alpine --replicas=2
   

2. 暴露服务

   kubectl expose deploy nginx-test --port=80 --type=NodePort
   

六、运维监控方案

1. 轻量级监控栈
   部署 k3s-prometheus-stack：

   helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
   helm install k3s-mon prometheus-community/kube-prometheus-stack \
     --set prometheus.prometheusSpec.resources.requests.memory=64Mi \
     --set grafana.resources.requests.memory=32Mi
   

2. 日志收集
   使用 Loki + Promtail：

   helm install loki grafana/loki-stack \
     --set promtail.enabled=true \
     --set loki.persistence.enabled=true \
     --set loki.persistence.size=1Gi
   

七、常见问题排查

1. 节点 NotReady

   journalctl -u k3s-agent -f | grep -i error  # Agent 节点
   sudo crictl ps -a                            # 检查容器状态
   

2. 资源不足处理

   kubectl top nodes  # 查看资源使用
   kubectl describe node | grep -A 10 Allocated  # 检查资源分配
   

八、架构建议

+-----------------+       +-----------------+
|  K3s Server     |<----->|  K3s Agent      |
| (Master)        |       | (Worker)        |
| - etcd 嵌入     |       | - 运行业务容器  |
| - API Server    |       +-----------------+
+-----------------+
       ^
       |
+-----------------+
| 外部访问入口    |
| (可选 LoadBalancer)
+-----------------+

注意：

1. 生产环境建议使用 3 个 Server 节点实现高可用
2. ARM 镜像需确认兼容性，可使用 docker.io/arm64v8/ 前缀
3. 定期执行 k3s etcd-snapshot save 备份集群状态

此方案在树莓派 4B 4GB 实测：

• 空载内存占用：Server 节点 ≈ 300MB，Agent 节点 ≈ 150MB
• 支持同时运行 15+ 个 Pod（1GB 内存限制）