夜雨聆风# 🚀 K8s 集群安装避坑指南：镜像源、面板、踩坑全记录
> 在一台 10GB 磁盘、国内网络环境的 Ubuntu 虚拟机上，花了 2 小时把 K8s 集群从零跑到 Dashboard 面板，中途踩的坑全在这里。
---
## 一、最终成果
| 组件 | 状态 |
|------|------|
| K8s 控制平面（API/etcd/scheduler/controller） | ✅ 运行 |
| Calico 网络插件 v3.29.1 | ✅ 运行 |
| kube-proxy | ✅ 运行 |
| Kubernetes Dashboard v2.7.0 | ✅ 运行 |
| Pod CIDR | 10.244.0.0/16 |
---
## 二、可用镜像源（国内必备）
### 🟢 好用
| 镜像源 | 地址 | 适用场景 |
|--------|------|---------|
| **阿里云（K8s 组件）** | `registry.aliyuncs.com/google_containers` | apiserver、etcd、proxy、coredns、pause 等核心组件 |
| **DaoCloud 代理** | `docker.m.daocloud.io` | Docker Hub 代理，有白名单限制 |
| **腾讯云加速** | `mirror.ccs.tencentyun.com` | Docker Hub 加速器 |
### 🔴 已失效
| 镜像源 | 地址 | 失败原因 |
|--------|------|---------|
| Docker Hub 直连 | `docker.io` | 被墙，超时 |
| 网易镜像 | `hub-mirror.c.163.com` | DNS 不可解析（已下线） |
| dockerproxy | `dockerproxy.com` | 连接超时 |
---
## 三、Docker 镜像加速配置
```json
// /etc/docker/daemon.json
{
"registry-mirrors": [
"https://docker.m.daocloud.io",
"https://mirror.ccs.tencentyun.com",
"https://docker.1ms.run"
],
"exec-opts": ["native.cgroupdriver=systemd"]
}
```
配置后执行 `systemctl restart docker`。
---
## 四、第三方镜像拉取黄金法则
```bash
# 1. 先通过 DaoCloud 代理拉取
docker pull docker.m.daocloud.io/作者/镜像名:tag
# 2. 拉下来后打原生 tag（kubelet 只认原名）
docker tag docker.m.daocloud.io/作者/镜像名:tag 作者/镜像名:tag
# 3. 三次还拉不下来 → 果断放弃换方案
```
---
## 五、各组件安装镜像清单
### ✅ 成功安装（阿里云源）
```
kube-apiserver → registry.aliyuncs.com/google_containers/kube-apiserver:v1.30.14
kube-controller-manager → registry.aliyuncs.com/google_containers/kube-controller-manager:v1.30.14
kube-scheduler → registry.aliyuncs.com/google_containers/kube-scheduler:v1.30.14
kube-proxy → registry.aliyuncs.com/google_containers/kube-proxy:v1.30.14
etcd → registry.aliyuncs.com/google_containers/etcd:3.5.15-0
pause → registry.aliyuncs.com/google_containers/pause:3.9
```
### ✅ 成功安装（Docker Hub + 加速器）
```
calico/cni → v3.29.1
calico/node → v3.29.1
calico/kube-controllers → v3.29.1
kubernetesui/dashboard → v2.7.0 （通过 DaoCloud 拉取后 tag）
kubernetesui/metrics-scraper → v1.0.8
```
### ❌ 安装失败
```
eipwork/kuboard:v3 → Docker Hub 超时，不在 DaoCloud 白名单
kubesphereio/ks-console:v3.4.1 → 阿里云最后一层卡住 + 磁盘不足
```
---
## 六、核心避坑记录
### 1. CNI 网络插件未初始化
**症状**：crictl info 显示 `NetworkReady: false`，kubelet 日志 `PLEG is not healthy`
**原因**：`/etc/cni/net.d/` 目录为空，无 CNI 配置文件
**修复**：
- 安装 CNI 二进制到 `/opt/cni/bin/`
- 创建 CNI 配置到 `/etc/cni/net.d/`（至少一个 `.conflist` 文件）
### 2. kubelet 缺少关键启动参数
**症状**：kubelet 运行但 API server 静态 Pod 不启动
**原因**：`/var/lib/kubelet/kubeadm-flags.env` 缺少 `--config` 和 `--kubeconfig`
**修复**：
```
KUBELET_KUBEADM_ARGS="--container-runtime-endpoint=unix:///var/run/cri-dockerd.sock
--pod-infra-container-image=registry.aliyuncs.com/google_containers/pause:3.9
--config=/var/lib/kubelet/config.yaml
--kubeconfig=/etc/kubernetes/kubelet.conf"
```
### 3. Standalone 模式 Webhook 认证冲突
**症状**：kubelet 启动报错 `no client provided, cannot use webhook authentication`
**原因**：`/var/lib/kubelet/config.yaml` 中 webhook 认证在无 API server 时无法工作
**修复**：改为 `authentication.webhook.enabled: false`，`authorization.mode: AlwaysAllow`
### 4. Calico install-cni 容器报错
**症状**：`Unable to create token for CNI kubeconfig` → Service IP 不通
**原因**：kube-proxy 未安装，`10.96.0.1:443` 不可达
**修复**：先安装 kube-proxy，再装 Calico；或预创建 CNI 配置跳过 init 容器
### 5. Calico nodename 换行符
**症状**：`Failed to read Node from datastore: nodes "k8s-master\n" not found`
**原因**：`echo "k8s-master" > /var/lib/calico/nodename` 带了换行符
**修复**：用 `printf "k8s-master" > /var/lib/calico/nodename`
### 6. Pod CIDR 与主机网段冲突
**症状**：Calico 默认 `192.168.0.0/16` 与主机 `192.168.153.0/24` 冲突
**修复**：改为 `10.244.0.0/16`
### 7. RBAC 权限缺失
**症状**：`kubectl get nodes` 返回 `Forbidden`
**原因**：kubeadm 的 `kubernetes-admin` 证书 Organization 是 `kubeadm:cluster-admins`，未绑定到 `cluster-admin`
**修复**：
```bash
kubectl create clusterrolebinding kubeadm-cluster-admins \
--clusterrole=cluster-admin \
--group=kubeadm:cluster-admins
```
### 8. 磁盘空间不足
**症状**：Pod 被驱逐、节点出现 `disk-pressure` taint
**修复**：
```bash
docker system prune -af # 清理未用镜像容器
journalctl --vacuum-size=100M # 清理系统日志
```
> 建议 VM 磁盘至少 20GB+
---
## 七、Dashboard 面板安装
### 安装命令
```bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml
```
### 镜像加速（关键）
```bash
# 先走代理拉镜像
docker pull docker.m.daocloud.io/kubernetesui/dashboard:v2.7.0
docker pull docker.m.daocloud.io/kubernetesui/metrics-scraper:v1.0.8
# 打原生 tag
docker tag docker.m.daocloud.io/kubernetesui/dashboard:v2.7.0 kubernetesui/dashboard:v2.7.0
docker tag docker.m.daocloud.io/kubernetesui/metrics-scraper:v1.0.8 kubernetesui/metrics-scraper:v1.0.8
```
### 创建管理员账号 & NodePort
```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: admin-user
namespace: kubernetes-dashboard
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: admin-user
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- kind: ServiceAccount
name: admin-user
namespace: kubernetes-dashboard
---
apiVersion: v1
kind: Service
metadata:
name: kubernetes-dashboard-nodeport
namespace: kubernetes-dashboard
spec:
type: NodePort
selector:
k8s-app: kubernetes-dashboard
ports:
- port: 443
targetPort: 8443
nodePort: 30443
```
### 获取登录 Token
```bash
kubectl -n kubernetes-dashboard create token admin-user --duration=87600h
```
---
## 八、时间复盘
| 步骤 | 耗时 | 坑点 |
|------|------|------|
| 修复 CNI 网络 | ~20 min | CNI 插件和配置全缺 |
| 修复 kubelet 参数 | ~10 min | config/kubeconfig 缺失 |
| 安装 Calico | ~30 min | Service IP 不通、RBAC、init 容器报错、nodename 换行符 |
| 安装 kube-proxy | ~15 min | kubeconfig 挂载 + RBAC |
| 安装 Dashboard | ~20 min | 镜像拉取慢 |
| **尝试中文面板（失败）** | **~40 min** | **纯粹浪费时间** |
| **总计** | **~2h** | **1/3 时间浪费在中文面板** |
---
## 九、最终感悟
1. **K8s 组件走阿里云**，不要碰 Docker Hub 直连
2. **第三方镜像先走 DaoCloud 代理**，拉下来打 tag
3. **三次拉不到就停**，别像我一样浪费时间
4. **中文面板没必要强求**，Chrome 右键翻译够用
5. **VM 磁盘至少 20GB**，9.8GB 是给自己找麻烦
6. **kubelet 的 --config 和 --kubeconfig 一个都不能少**
7. **Calico 前先装 kube-proxy**，否则 Service IP 不通
---
> 📅 2026-06-12 · 环境：Ubuntu 22.04 / K8s v1.30.5 / Docker 28.3.2 + cri-dockerd
