边缘集群部署（KubeEdge 云-边）
本目录讲如何用 KubeEdge 把本地 / 专线 / 独立机房的边缘节点接入云端 K8s 集群，由 CubeStudio 统一调度：云端做训练，边缘做推理。
适用形态：边缘设备（英伟达 ARM 盒子、商城/门店机房的独立子网服务器或 PC）算力分散、不希望把数据回传中心、又想集中管理。
内容来源：
docs/部署/kubeedge部署边缘集群cube-studio.md（一次从零到可用的跨公网云-边完整实录，约 1000 行）+docs/部署/边缘集群方式部署平台.md（原理与 superedge / kubesphere 等其它建集群方式）+install/kubernetes/kubeedge/README.md（一键脚本说明）。
📌 四个最大坑（任一个没处理都会失败，务必先看）
| 坑 | 症状 | 解决 |
|---|---|---|
| 1. edge 节点 label 必须空值 | kubectl describe pod 只有 Scheduled、无后续事件；cloudcore 日志刷 there are 0 nodes need to sync |
node-role.kubernetes.io/edge=（空字符串，不能是 =true），脚本 40-edge-fix-label.sh。详见 06-验证与最大坑-label硬编码 |
| 2. edge 上 /opt/cni/bin 只有 flannel，缺 loopback/bridge | failed to find plugin "loopback"，pod sandbox 建不起来 |
装 containernetworking/plugins v1.4.0，脚本 30-edge-join.sh 会自动装。详见 05-边缘节点接入与项目组配置 |
| 3. kube-proxy kubeconfig 默认走云端私网 IP | 边缘上 iptables-save 空无规则；service ClusterIP / NodePort / external IP 在边缘节点上都不通 |
把 kube-system/kube-proxy configmap 的 server: 改成公网 IP，脚本 45-fix-kube-proxy.sh |
| 4. kubeadm init 时 SAN 必须含公网 IP | 即使改了 kube-proxy server，证书不匹配照样握手失败 | 云端 K8s 初始化时加 --apiserver-cert-extra-sans=<公网 IP> |
两条路径
- 一键脚本（推荐先看）：如果云端 K8s 已就绪、且 kubeadm init 时加过公网 SAN，用
install/kubernetes/kubeedge/下的编号脚本几条命令接入。见 02-一键脚本部署。 - 从零手工部署：公网云主机从裸机装 K8s + NFS + cube-studio + CloudCore，再把 NAT 后的边缘节点接进来。详见 03 ~ 06 各子文档。
子文档目录（TOC）
| 文档 | 内容 |
|---|---|
| 01-原理与适用场景 | 适用场景、支持设备、网络访问方向限制（中心↔边缘单向）、云-边架构；以及 superedge / kubesphere+kubeedge 等其它建边缘 K8s 集群的方式 |
| 02-一键脚本部署 | install/kubernetes/kubeedge/ 编号脚本（00~50）的用途、快速流程、卸载 |
| 03-云端环境准备-K8s与NFS | 交付前要替换的变量、安全组端口、Phase A 云端 kubeadm+containerd 装 K8s、Phase B 云端 NFS 服务端 |
| 04-云端CubeStudio与CloudCore | Phase C 云端部署 CubeStudio（改 config/start.sh、ccr 鉴权、istio Service）、Phase D 装 CloudCore（KubeEdge） |
| 05-边缘节点接入与项目组配置 | Phase E 边缘 keadm join + CNI + kube-proxy 修复、Phase F CubeStudio 边缘项目组配置与调度代码位置 |
| 06-验证与最大坑-label硬编码 | Phase G 端到端验证；最大坑：edge 节点 label 硬编码（KubeEdge 源码定位 + 修复） |
| 07-踩坑速查 | 其它踩过的坑（CNI / kube-proxy / 单向不通 / 镜像大小 / NFS stale handle 等）+ 常见坑附录 + 版本命令速查 |
访问方向（by-design，不是 bug）
- Cloud → Edge pod 方向走不通：云端 flannel 没法建 VXLAN 到 NAT 后的边缘，公网经 istio ingress → ClusterIP → edge pod 这条路返回 502。
- Edge 内网用户可用：CubeStudio 给边缘 service 配的访问地址默认就是
http://<边缘内网 IP>:<NodePort>（如192.168.3.22:20038），供同子网用户使用。 - 详细原理见 01-原理与适用场景 与 07-踩坑速查。
视频教程：边缘计算方式部署和调度（B 站）。具体命令/镜像名/版本以源码与各子文档为准。