--- date: '2026-05-24T09:00:00+08:00' draft: false title: 'k3s 高可用集群安装与配置（国内镜像加速版）' tags: - k3s - kubernetes - tailscale - haproxy - 运维 categories: - 技术 --- ## 前言 本文记录在多台服务器上部署 k3s 高可用集群的完整过程。集群架构为 **3 Server + 1 Agent**，通过 Tailscale 组建 overlay 网络，只有一台节点具有公网 IP，其余节点通过 HAProxy 代理访问。 ## 网络拓扑 ``` 公网 │ x.x.x.x ┌──────┴──────┐ │ agent-ali │ ← 唯一暴露公网的节点 │ (HAProxy) │ 运行 HAProxy 代理 k3s API └──────┬──────┘ │ Tailscale (100.100.x.x) ┌──────────────┼──────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ server-jz│ │server-jz2│ │server-zen│ │ 私有云 │ │ 私有云 │ │ 私有云 │ │ CP+etcd │ │ CP+etcd │ │ CP+etcd │ └──────────┘ └──────────┘ └──────────┘ ``` - **只有 `agent-ali` 有公网 IP**，其余节点均通过 Tailscale 内网互通 - **HAProxy** 运行在 agent-ali 上，将外部的 k3s API 请求负载均衡到 3 个 Server 节点 - 所有节点通过 **Tailscale VPN** 组网（`100.100.x.x` 网段） ## 节点规划 | 节点角色 | 节点名 | Tailscale IP | 公网 | 位置 | |---------|--------|-------------|:----:|:----:| | Server (etcd + control-plane) | server-jz | 100.100.1.12 | ❌ | 私有云 | | Server (etcd + control-plane) | server-jz2 | 100.100.1.13 | ❌ | 私有云 | | Server (etcd + control-plane) | server-zen | 100.100.1.11 | ❌ | 私有云 | | Agent | agent-ali | 100.100.1.10 | ✅ | 公有云 | ## 前置准备 ### 获取 Tailscale 密钥 在 [Tailscale 管理后台](https://login.tailscale.com/admin/settings/keys) 生成一个 **Auth Key**： 1. 进入 **Settings → Keys** 2. 点击 **Generate auth key** 3. 勾选 **Reusable**（可重用）和 **Ephemeral**（可选） 4. 复制生成的密钥，格式为 `tskey-auth-xxxxx` 该密钥用于节点自动加入 Tailscale 网络，无需手动登录。 ### Server 节点：依赖安装 所有 Server 节点需要安装 Tailscale： ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up --auth-key=tskey-auth-xxxxx ``` 确认节点上线： ```bash tailscale status ``` ## 第一步：在 agent-ali 上配置 HAProxy 在 agent-ali 上安装 HAProxy，将外部流量转发到 3 个 Server 节点的 k3s API： ```bash # 安装 HAProxy sudo apt update && sudo apt install -y haproxy ``` 配置 `/etc/haproxy/haproxy.cfg`： ```haproxy frontend k3s-frontend bind *:6443 mode tcp option tcplog default_backend k3s-backend backend k3s-backend mode tcp option tcp-check balance roundrobin default-server inter 10s downinter 5s server server-zen 100.100.1.11:6443 check server server-jz 100.100.1.12:6443 check server server-jz2 100.100.1.13:6443 check ``` 启动 HAProxy： ```bash sudo systemctl enable --now haproxy ``` 这样外部的 `kubectl` 只需要连接 `agent-ali:6443`，由 HAProxy 转发到健康的 Server 节点。 ## 第二步：初始化第一个 Server 节点 ```bash curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ K3S_NODE_NAME=server-jz2 \ sh -s server \ --embedded-registry \ --data-dir /www/k3s \ --cluster-init \ --node-ip=100.100.1.13 \ --advertise-address=100.100.1.13 \ --tls-san=100.100.1.13 \ --tls-san=x.x.x.x \ --vpn-auth="name=tailscale,joinKey=tskey-auth-xxxxx" ``` 关键参数说明： | 参数 | 说明 | |------|------| | `INSTALL_K3S_MIRROR=cn` | 使用国内镜像源 | | `--embedded-registry` | 启用内置镜像仓库（zot），本地缓存镜像 | | `--cluster-init` | 初始化集群（仅第一个节点需要） | | `--data-dir /www/k3s` | 指定数据目录 | | `--tls-san` | 添加证书 SAN，包含公网 IP（x.x.x.x） | | `--vpn-auth` | 集成 Tailscale 自动加入网络 | 安装完成后获取节点 Token： ```bash sudo cat /www/k3s/server/node-token ``` ## 第三步：加入其余 Server 节点 ```bash # server-jz curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ K3S_NODE_NAME=server-jz \ sh -s server \ --embedded-registry \ --data-dir /www/k3s \ --token K101fe... \ --server https://100.100.1.13:6443 \ --node-ip=100.100.1.12 \ --advertise-address=100.100.1.12 \ --vpn-auth="name=tailscale,joinKey=tskey-auth-xxxxx" # server-zen curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ K3S_NODE_NAME=server-zen \ sh -s server \ --embedded-registry \ --data-dir /www/k3s \ --token K101fe... \ --server https://100.100.1.13:6443 \ --node-ip=100.100.1.11 \ --advertise-address=100.100.1.11 \ --vpn-auth="name=tailscale,joinKey=tskey-auth-xxxxx" ``` ## 第四步：加入 Agent 节点 ```bash curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ K3S_NODE_NAME=agent-ali \ K3S_URL=https://100.100.1.13:6443 \ K3S_TOKEN=K101fe... \ sh -s - agent \ --node-ip=100.100.1.10 \ --node-external-ip=100.100.1.10 \ --vpn-auth="name=tailscale,joinKey=tskey-auth-xxxxx" ``` ## 配置 kubeconfig 从任意 Server 节点复制 kubeconfig 到本地： ```bash # 复制配置文件 sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config # 将 server 地址改为 HAProxy 的公网地址 kubectl config set-cluster default --server=https://x.x.x.x:6443 # 验证 export KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl get pods --all-namespaces helm ls --all-namespaces ``` > HAProxy 会将请求负载均衡到 3 个 Server 节点，即使单个 Server 宕机也不影响 API 访问。 ## 配置镜像加速 在中国大陆部署时，镜像拉取是最大的痛点。通过配置 `registries.yaml` 解决： ```bash sudo mkdir -p /etc/rancher/k3s sudo cat > /etc/rancher/k3s/registries.yaml << 'EOF' mirrors: docker.io: endpoint: - "https://docker.1ms.run" - "https://docker.xuanyuan.me" - "https://docker.m.daocloud.io" - "https://docker.chenby.cn" - "https://registry.aliyuncs.com" - "https://mirror.ccs.tencentyun.com" - "https://hub.luochen570.top" quay.io: endpoint: - "https://quay.m.daocloud.io" - "https://quay.tencentcloudcr.com" - "https://quay.registry.cyou" - "https://quay.chenby.cn" - "https://quay.luochen570.top" registry.k8s.io: endpoint: - "https://k8s.m.daocloud.io" - "https://registry.aliyuncs.com/google_containers" - "https://registry.lank8s.cn" - "https://lank8s.cn" - "https://k8s.registry.cyou" - "https://k8s.chenby.cn" - "https://k8s.luochen570.top" ghcr.io: endpoint: - "https://ghcr.m.daocloud.io" - "https://ghcr.registry.cyou" - "https://ghcr.chenby.cn" - "https://ghcr.luochen570.top" EOF ``` 每个节点都需要配置，然后重启 k3s 服务： ```bash sudo systemctl restart k3s # Server 节点 sudo systemctl restart k3s-agent # Agent 节点 ``` ## 卸载节点 ```bash # 卸载 Server 节点 /usr/local/bin/k3s-uninstall.sh # 卸载 Agent 节点 /usr/local/bin/k3s-agent-uninstall.sh ``` ## 验证集群 ```bash kubectl get nodes kubectl get pods --all-namespaces ``` ## 总结 最终集群架构： 1. **高可用**：3 个控制平面节点 + HAProxy 负载均衡，任意单节点故障不影响集群 2. **安全隐藏**：只有 agent-ali 暴露公网 IP，Server 节点通过 Tailscale 内网访问 3. **国内加速**：内置镜像源列表，解决拉取超时 4. **嵌入式镜像仓库**：启用 `--embedded-registry`，跨节点分发更快 5. **Tailscale 组网**：跨地域节点自动互联，无需手动配置 WireGuard