hugo-blog/content/posts/k3s-cluster-install.md

date, draft, title, tags, categories

date	draft	title	tags	categories
2026-05-24T09:30:00+08:00	false	k3s 高可用集群安装与配置（国内镜像加速版）	k3s kubernetes tailscale 运维	技术

前言

本文记录在多台服务器上部署 k3s 高可用集群的完整过程，包括镜像加速配置、Tailscale VPN 组网、嵌入式镜像仓库等。

环境准备

节点规划

节点角色	节点名	IP	系统
Server (etcd + control-plane)	server-jz2	100.100.1.13	Debian 13
Server (etcd + control-plane)	server-jz	100.100.1.12	Debian 13
Server (etcd + control-plane)	server-zen	100.100.1.11	Debian 13
Agent	agent-ali	100.100.1.10	Debian 12
Agent	agent-uc	100.100.1.101	Debian 12

所有节点通过 Tailscale VPN 组网（100.100.x.x 网段）。

安装 Server 节点

第一个 Server 节点（初始化集群）

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=8.152.2.199 \
--vpn-auth="name=tailscale,joinKey=tskey-xxx"

关键参数说明：

• --embedded-registry：启用内置镜像仓库（zot），本地缓存镜像
• --cluster-init：初始化集群（仅第一个节点需要）
• --data-dir /www/k3s：指定数据目录
• --tls-san：添加 TLS 证书的 SAN（包括内网 IP 和公网 IP）
• --vpn-auth：集成 Tailscale VPN

安装完成后，获取节点 Token：

cat /www/k3s/server/node-token

其余 Server 节点加入

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-xxx"

同样的方式加入第三个 Server 节点：

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-xxx"

安装 Agent 节点

海外 Agent

curl -sfL https://get.k3s.io | \
K3S_NODE_NAME=agent-uc \
K3S_URL=https://100.100.1.13:6443 \
K3S_TOKEN=K101fe... \
sh -s - agent \
--node-ip=100.100.1.101 \
--node-external-ip=100.100.1.101 \
--vpn-auth="name=tailscale,joinKey=tskey-xxx"

国内 Agent

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-xxx"

配置 Kubernetes 访问

将 Server 节点的配置复制到本地：

cp /etc/rancher/k3s/k3s.yaml ~/.kube/config

通过环境变量指定配置：

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get pods --all-namespaces
helm ls --all-namespaces

配置镜像加速（国内源）

在中国大陆部署时，镜像拉取是最大的痛点。通过配置 registries.yaml 可以解决：

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
sudo systemctl restart k3s   # 重启 Server
sudo systemctl restart k3s-agent  # 重启 Agent

每个镜像源都配置了多个备用 endpoint，按优先级依次尝试。

卸载节点

# 卸载 Server 节点
/usr/local/bin/k3s-uninstall.sh

# 卸载 Agent 节点
/usr/local/bin/k3s-agent-uninstall.sh

验证集群

集群安装完成后，可以运行以下命令验证：

kubectl get nodes
kubectl get pods --all-namespaces

总结

通过以上步骤，我们成功搭建了一个 3 Server + 2 Agent 的 k3s 高可用集群，特点包括：

1. 高可用：3 个控制平面节点，任何单节点故障不影响集群
2. 国内加速：配置了多个国内镜像源，解决拉取超时问题
3. 嵌入式镜像仓库：启用 --embedded-registry，提升镜像分发效率
4. Tailscale 组网：通过 VPN 实现跨地域节点互联
5. 灵活的 Agent 部署：国内和海外节点使用不同的安装源