树莓派上部署KubeEdge：云边协同与ARM架构避坑实践

这阵子折腾了几天终于把KubeEdge成功跑在了树莓派上。整个过程比我想象中要曲折一些尤其是ARM架构带来的各种镜像和二进制兼容问题还有云边通信的证书、Token配置踩了不少坑。这篇文章就把我完整的实操过程、遇到的坑和解法都记录下来给同样想在树莓派上玩KubeEdge的朋友一个参考。KubeEdge是云原生边缘计算框架核心思路是把云端Kubernetes的编排管理能力延伸到边缘节点。树莓派作为边缘节点通过EdgeCore接入云端Kubernetes集群实现云边协同、边缘自治和设备接入。适合做边缘计算实验、IoT原型验证或者想学习云原生技术栈的朋友。1. 项目概述与环境规划1.1 先搞懂KubeEdge的架构再动手很多人在树莓派上装KubeEdge失败根本原因是对架构理解不够。KubeEdge分为云端和边缘端两部分云端部署在Kubernetes集群上核心是CloudCore组件边缘端部署在树莓派上核心是EdgeCore组件。CloudCore内部包含CloudHub、EdgeController、DeviceController、SyncController等模块。CloudHub负责与边缘端建立WebSocket连接EdgeController负责监听云端Kubernetes API Server的资源变化并同步到边缘DeviceController管理设备映射SyncController处理云边数据同步的确认机制。EdgeCore内部包含EdgeHub、Edged、EventBus、DeviceTwin、ServiceBus等模块。EdgeHub负责与CloudHub通信Edged是边缘端的轻量化kubelet负责Pod生命周期的管理、容器运行时的调用、节点状态的上报。EventBus和DeviceTwin用于设备数据的管理。这意味着树莓派上完全不需要安装完整的kubelet和kubeadmEdgeCore的Edged替代了kubelet的角色资源占用比标准Kubernetes节点小很多。这也是KubeEdge适合边缘设备的原因——标准Kubernetes对资源要求太高树莓派这种设备跑不动完整的节点组件。1.2 硬件选型与系统选择树莓派的型号直接决定了你的折腾难度。我用的树莓派4B4GB内存版本刷的是Raspberry Pi OS Lite 64位系统。在选择之前我把几款常见型号的定位梳理了一下。型号内存架构建议树莓派3B/3B512MB/1GBarmv7l32位不推荐内存太小EdgeCore加上容器运行时会很吃力树莓派4B 2GB2GBarm64勉强能跑但建议只跑1~2个轻量Pod树莓派4B 4GB/8GB4GB/8GBarm64推荐跑EdgeCoreDocker几个测试Pod没有问题树莓派54GB/8GBarm64更充裕性能接近入门级NUC系统方面一定要选64位版本原因有两个KubeEdge官方发布的EdgeCore二进制对arm64支持最完善armv7版本经常没跟上更新节奏容器镜像生态也以arm64为主很多镜像已经放弃armv7构建了。系统镜像直接用Raspberry Pi Imager烧录就行注意在Imager里提前开启SSH设置好用户名密码这样烧录完直接SSH登录不用外接显示器和键盘。1.3 版本兼容性规划版本匹配是KubeEdge安装最容易翻车的地方。CloudCore运行在云端Kubernetes集群里EdgeCore运行在树莓派上三者版本必须兼容。我选的是KubeEdge v1.15.0版本对应的Kubernetes集群是v1.27.x。选版本的时候一定要查官方文档里的版本兼容矩阵不要随手装最新版。最新版KubeEdge支持的Kubernetes版本范围更靠前如果你的云端Kubernetes集群还是老版本装了新版EdgeCore会出现握手失败或者资源同步异常。云端Kubernetes集群我直接用kubeadm部署了一个单节点集群主节点是x86架构的云主机。树莓派作为边缘节点通过CloudCore接入这个集群。整个拓扑就是云端集群包含控制面和CloudCore边缘端树莓派只运行EdgeCore和容器运行时不与Kubernetes API Server直接通信所有通信都走CloudCore中转。2. 云端CloudCore部署2.1 云端集群准备CloudCore需要部署到一个已经可用的Kubernetes集群上。我这里用的是单节点集群操作步骤和其他部署一样关键点是kubeconfig配置要准备好因为keadm init命令需要读取kubeconfig来连接Kubernetes API Server。先确认kubectl能正常访问集群kubectl get nodes kubectl get pods -A如果集群一切正常可以开始安装keadm。keadm是KubeEdge的安装管理工具相当于Kubernetes世界的kubeadm云端初始化、边缘节点加入、证书管理、组件清理都靠它。下载keadm的方式很简单直接在GitHub Release页面找到对应版本的可执行文件。我这里用的是v1.15.0curl -LO https://github.com/xxx/kubeedge/releases/download/v1.15.0/keadm-v1.15.0-linux-amd64.tar.gz tar -zxvf keadm-v1.15.0-linux-amd64.tar.gz mv keadm-v1.15.0-linux-amd64/keadm /usr/local/bin/keadm把keadm放到PATH里之后先gettoken前确认一下版本输出正常。2.2 keadm init初始化CloudCore云端初始化命令如下keadm init --advertise-address192.0.2.10 --kubeedge-versionv1.15.0--advertise-address参数必须填云端节点对外的IP地址也就是树莓派能够访问到的地址。这里有个细节如果云端节点有多个网卡或者在内网环境填错了IP会导致树莓派的EdgeHub始终连不上CloudHub排查起来还不好发现。init成功后keadm会自动在Kubernetes集群里创建kubeedge命名空间部署CloudCore相关Pod。验证一下kubectl get pods -n kubeedge kubectl get svc -n kubeedge正常情况下会看到cloudcore的Pod处于Running状态。CloudCore的Service类型是NodePort对外暴露的端口要看具体的Service定义。默认情况下CloudHub的WebSocket端口是10000这个端口就是树莓派EdgeCore要连接的端口。CloudCore部署完先检查日志有没有报错kubectl logs -f deployment/cloudcore -n kubeedge这一步很关键如果CloudCore启动就异常边缘节点后面加入必然失败。我遇到过因为Kubernetes集群的CNI网络插件没装好导致CloudCore Pod一直ContainerCreating这种基础问题要提前解决。2.3 获取Token和开放端口云端和边缘端的认证机制是Token证书。初始化CloudCore后会自动生成一个Token查询方式keadm gettoken --kube-config/root/.kube/configToken是一个比较长的字符串后面keadm join的时候要用。Token过期或者节点信息变了可以重新生成。云端防火墙要放行10000端口这个端口是CloudHub的WebSocket端口。如果使用了Tunnel模式还需要放行对应的隧道端口。我在云主机的安全组里放行了10000/tcp然后验证一下端口是否真的能通。别在安全组放行了却忘了iptables或者系统防火墙没关树莓派那边连不上CloudCore节点状态就会一直卡在NotReady。3. 树莓派边缘节点准备3.1 刷系统与基础初始化树莓派系统是Raspberry Pi OS Lite 64位烧录完成后第一次SSH登录建议先把系统源更新一遍apt update apt upgrade -y然后修改主机名方便后面在Kubernetes集群里识别节点。默认主机名是raspberrypi改成edge-node-01比较清晰。hostnamectl set-hostname edge-node-01关键的一步是设置静态IP。树莓派如果走DHCP重启后IP变了EdgeCore连接CloudCore会失败而且Kubernetes节点状态会变成NotReady。改静态IP最省事的方式是编辑/etc/dhcpcd.conf或者NetworkManager配置取决于你用的系统版本。我用的Bookworm版本是基于NetworkManager的直接用nmcli设置静态IP。时间同步也要处理。树莓派没有板载实时时钟断电重启后时间回退会导致证书校验失败EdgeCore和CloudCore之间的TLS握手直接报错。系统装好后确认NTP服务是启用的timedatectl status timedatectl set-ntp true这个坑非常隐蔽如果KubeEdge一直证书报错先看看树莓派的时间是否正确。我实测过断电重启后系统时间差了好几个小时EdgeCore根本连不上CloudCore。3.2 容器运行时安装与选择EdgeCore的Edged组件通过CRI容器运行时接口与容器运行时通信所以树莓派上必须要有一个容器运行时。可选的主要是Docker和containerd。Docker安装最简单apt install -y docker.io systemctl enable --now docker装完后检查一下Docker能正常拉取镜像。containerd方式适合喜欢精简环境的人安装配置会多一点。需要注意containerd的/etc/containerd/config.toml里SystemdCgroup参数默认可能是false但Kubernetes生态默认期望systemd cgroup驱动不一致会导致Edged启动报错。我的建议是直接上Docker在树莓派上别折腾containerd的cgroup配置省掉一个排查点。容器运行时装好后确认cgroup驱动配置。EdgeCore的edged默认cgroup驱动是cgroupfsDocker默认也是cgroupfs这两个能对上。如果后面你改了Docker的exec-opts把cgroup驱动改成了systemd那EdgeCore这边也要同步修改否则Pod调度上去会启动失败。3.3 关闭swap与内核参数Kubernetes节点通常要求关闭swap。树莓派系统默认可能没有启用swap但检查一下最保险free -h swapoff -a sed -i /swap/d /etc/fstab然后检查内核模块。Edged启动容器时会用到overlay文件系统确认overlay模块已经加载。执行lsmod | grep overlay没有的话modprobe overlay。同时确认iptables相关内核参数sysctl net.bridge.bridge-nf-call-iptables1这些细节不处理后面Pod启动或者网络配置会报一些莫名其妙的错误。4. EdgeCore加入云端集群4.1 keadm join实操树莓派上也要下载keadm注意下载ARM64版本不是x86的curl -LO https://github.com/xxx/kubeedge/releases/download/v1.15.0/keadm-v1.15.0-linux-arm64.tar.gz tar -zxvf keadm-v1.15.0-linux-arm64.tar.gz mv keadm-v1.15.0-linux-arm64/keadm /usr/local/bin/keadm加入集群的命令如下keadm join --cloudcore-ipport192.0.2.10:10000 --token上一步获取的token --kubeedge-versionv1.15.0--cloudcore-ipport就是云端IP地址和CloudHub端口。加入过程会自动下载EdgeCore二进制、生成配置、启动edgecore服务。等待几十秒后正常情况下edgecore服务已经运行。查看边缘端服务状态systemctl status edgecore journalctl -f -u edgecore日志里如果看到Connected to CloudCore之类的输出说明云边通道已经建立。如果一直报连接拒绝或者超时先检查IP和端口用nc或者telnet从树莓派测端口连通性nc -vz 192.0.2.10 100004.2 edgecore.yaml核心配置项解读EdgeCore的配置文件在/etc/kubeedge/config/edgecore.yaml这个文件是keadm join自动生成的大部分情况下不用改但理解关键配置项是排查故障的前提。配置里最重要的模块是modules.edged它包含cgroupDriver配置要和容器运行时的cgroup驱动保持一致。remote-runtime-endpoint配置的是容器运行时监听的socket路径如果是Docker就是unix:///var/run/docker.sock如果是containerd就是unix:///var/run/containerd/containerd.sock。modules.edgehub配置了云端的连接地址、WebSocket端口、证书引用。如果后续要换云端IP改这里的配置然后重启edgecore就行。modules.edged里还有一个nodeLabels字段可以给节点打自定义标签这样调度Pod的时候可以精确指定。这个字段很有用比如你在多个树莓派上部署了不同型号的传感器可以用nodeLabels区分。4.3 云端确认节点加入树莓派EdgeCore启动后回到云端在Kubernetes集群里查看节点状态kubectl get nodes -o wide如果一切正常会看到edge-node-01这个节点状态是Ready架构是arm64。刚加入的时候可能会显示NotReady需要等一小会儿让节点心跳上报成功。然后给边缘节点打上角色标签方便后续资源管理kubectl label node edge-node-01 node-role.kubernetes.io/edge kubectl label node edge-node-01 node.kubernetes.io/edgetrue到这里KubeEdge的云边通道已经打通树莓派作为一个边缘节点正式加入云端Kubernetes集群。5. 验证与边缘应用部署5.1 部署第一个边缘Pod节点Ready了必须实际跑一个业务容器验证全链路不然心理不踏实。在云端创建一个测试Deployment注意nodeSelector要选到树莓派节点镜像我用的nginx:alpine官方镜像支持arm64。nginx:alpine的好处是镜像小、多架构支持好在树莓派上拉取速度也快。yaml内容如下apiVersion: apps/v1 kind: Deployment metadata: name: nginx-edge-test spec: replicas: 1 selector: matchLabels: app: nginx-edge-test template: metadata: labels: app: nginx-edge-test spec: nodeSelector: kubernetes.io/arch: arm64 containers: - name: nginx image: nginx:alpine ports: - containerPort: 80应用之后观察Pod运行状态kubectl apply -f nginx-edge-test.yaml kubectl get pods -o wide -w看到Pod运行在edge-node-01上并且状态是Running说明调度、镜像拉取、容器创建整个链路都通了。这个实验看起来简单实际验证了云端控制面到边缘端EdgeCore到容器运行时之间的完整流程。5.2 验证边缘自治能力KubeEdge卖点之一是边缘自治云端断连时边缘节点上已有的Pod继续运行。我把云端CloudCore的Pod删掉模拟断连观察树莓派上运行中的nginx容器会不会受影响。实测结果是容器进程不会退出Pod在边缘本地继续运行。重新拉起CloudCore后边缘状态自动恢复。这验证了边缘自治的能力核心原理是EdgeCore的Edged有本地缓存机制不依赖实时云边通信也能维持业务。这个特性对生产环境意义很大边缘设备经常处于不稳定网络环境云边断连不能导致关键业务中断。但注意断连期间如果在云端执行kubectl delete pod由于云端控制面连不到边缘节点Pod删除事件无法同步到EdgeCorePod不会真正被删除恢复后会兜底处理。5.3 设备接入场景延伸KubeEdge不仅仅是Pod调度它的设备接入能力值得单独说。通过Device Controller和DeviceTwin可以管理边缘端的IoT设备数据。具体机制是通过CRD创建DeviceModel和Device然后在Device中指定要绑定的边缘节点。设备侧需要一个Mapper程序负责把物理设备的数据转换成标准格式提交给EdgeCore的EventBus模块。如果之后想把树莓派上的传感器数据接入云端走这条链路是标准的KubeEdge方案。Mapper开发的工作量不小但对做IoT原型验证的人很有价值。这部分内容做安装验证时可以暂时跳过但心里有个数KubeEdge安装完成只是开始设备接入才是边缘计算真正的业务价值所在。6. 常见问题与排查技巧实录6.1 节点状态一直NotReady节点NotReady是最常见的问题排查思路按层次来。先看edgecore服务本身状态journalctl日志里有没有连接异常再测TCP层连通性nc -vz测10000端口然后看证书文件是否过期或者权限不对。我在树莓派上遇到过一次是Docker安装后没有启动containerd依赖服务导致Edged调用CRI失败。排查发现edgecore日志里一直报找不到runtime的情况重启Docker服务后正常。表现可能原因排查命令或手段edgecore日志报connection refused云端IP/端口不通nc -vz 云IP 10000edgecore日志报TLS handshake timeout树莓派时间不准timedatectl statusedgecore日志报permission denied证书或目录权限问题ls -l /etc/kubeedge/edged报runtime not ready容器运行时没起来或socket路径错systemctl status docker6.2 证书过期与续期KubeEdge边缘节点的证书默认有效期是一年。证书过期了EdgeCore日志会报证书相关错误节点状态变NotReady。处理方法是在边缘端清理旧的证书文件然后重新加入集群。注意Token过期的情况如果token已经过期或者被重新生成过需要在云端执行keadm gettoken拿新Token边缘端重新join。有一个教训是用yaml或者脚本自动化部署时把token写死在脚本里是最大的坑三个月后token过期你会懵。建议在安装文档里明确标注Token获取步骤或者把init和join做成可交互的方式。6.3 镜像拉取失败与ARM架构问题在树莓派上拉取镜像经常遇到manifest unknown原因是你拉的镜像是amd64专用。EdgeCore本身是arm64不容许amd64的镜像运行。解决办法是选多架构镜像或者看镜像是arm64。镜像是否支持arm64说明nginxx:alpine支持我实测过eclipse-mosquitto支持IoT测试常用busybox支持轻量调试镜像gcr.io的很多镜像不支持或很慢尽量选Docker Hub合理的镜像如果真的需要一个只有amd64版本的软件可以在树莓派上用qemu-user-static模拟x86构建镜像但运行性能很差不推荐在生产场景使用。6.4 树莓派资源瓶颈与性能心得树莓派4B 4GB版本跑EdgeCoreDocker再加2~3个轻量Pod整体内存占用会到2GB左右。树莓派3B时代512MB内存真的不够用Edged本身就占不少内存配置要精细控制。我在树莓派上限制Pod的requests和limits确保不会把内存打爆导致系统卡死。如果做IoT数据采集建议把实时数据转发到MQTTBroker上树莓派上不做数据持久化用SSD或者外设存储会更好。关于性能测试我用arm64版本的nginx镜像做了一个简单的压测树莓派4B的CPU处理几百个并发连接没有问题但比起x86服务器差距明显。边缘场景本来就是设备侧轻量处理所以这个结果符合预期。6.5 升级与清理后续想升级KubeEdge版本云端先更新CloudCore边缘端再升级EdgeCore。边缘端清理可以用keadm reset这个命令会停止并删除edgecore服务同时清理相关配置文件。不建议直接删文件和systemd服务残留的iptables规则和socket文件会干扰下次安装。最后分享一个小心得KubeEdge安装完毕后我最常用的三个排查命令是kubectl get nodes -o wide、journalctl -u edgecore -f和kubectl logs -n kubeedge deployment/cloudcore。云边通信的任何问题沿着这三条线索查基本都能定位。树莓派上的EdgeCore日志是用中文还是英文不重要关键是日志里给出的错误码和超时信息要先读清楚很多问题本身已经把原因写明白了只是有人习惯跳过去不读。