这个错误的核心原因是 你的客户端（你正在运行 kubectl 或 k3sup 等命令的电脑）无法与 K3s 服务器节点（Master 节点）建立网络连接。
下面我将从最常见到最不常见的顺序,为你提供一套完整的排查和解决方案。
第 1 步：定位问题根源
你需要明确你的操作是在哪台机器上执行的。
- 场景 A：你在 K3s 服务器节点（Master 节点）上操作。
- 如果直接在服务器上运行
kubectl get nodes报错，那通常是kubeconfig文件配置有问题。
- 如果直接在服务器上运行
- 场景 B：你在另一台客户端机器（比如你的笔记本电脑）上操作。
这是最常见的情况,问题几乎 100% 出在网络连接或配置文件上。
第 2 步：核心排查步骤（按顺序执行）
请按照以下步骤逐一排查,这能解决 90% 以上的问题。
检查 kubeconfig 文件路径和内容
kubectl 命令需要知道去哪里找 K3s 集群的信息，这些信息存储在 kubeconfig 文件中，默认情况下，K3s 会在服务器节点上创建一个配置文件。
-
检查
KUBECONFIG环境变量: 在你的终端中运行：echo $KUBECONFIG
如果有输出,说明
kubectl会使用这个路径的文件，如果为空，它会使用默认路径~/.kube/config。 -
检查配置文件是否存在:
（图片来源网络，侵删）# $KUBECONFIG 有值，使用它的值 # 否则检查默认路径 ls -l ~/.kube/config
如果文件不存在,或者你不确定，你需要从 K3s 服务器节点获取它。
-
从 K3s 服务器节点获取配置文件（关键步骤）: 登录到你的 K3s 服务器节点（Master 节点），找到
kubeconfig文件，它的默认位置是/etc/rancher/k3s/k3s.yaml。# 在 K3s 服务器节点上执行 sudo cat /etc/rancher/k3s/k3s.yaml
你会看到类似下面内容的输出：
apiVersion: v1 clusters: - cluster: certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t... server: https://<你的服务器IP>:6443 # <-- 这是最重要的部分！ name: default contexts: - context: cluster: default user: default name: default current-context: default kind: Config users: - name: default user: client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t... client-key-data: LS0tLS1CRUdJTiBSU0EgUFJJVkFURS0tLS0t... -
将配置文件复制到客户端机器: 在你的客户端机器上，创建或覆盖
~/.kube/config文件，并将上面输出的内容粘贴进去。# 在客户端机器上执行 mkdir -p ~/.kube # 使用你喜欢的编辑器（如 vim, nano）打开 ~/.kube/config 文件 # 粘贴从服务器节点获取的内容 vim ~/.kube/config
保存后，请务必修改文件权限，否则
kubectl会报权限错误：chmod 600 ~/.kube/config
检查 server 地址
在 ~/.kube/config 文件中，找到 clusters -> cluster -> server 这一行。
server: https://<你的服务器IP>:6443
<你的服务器IP>是什么？- 如果你和 K3s 服务器在同一个局域网内，请使用它的 内网 IP（
168.1.100或0.0.5）。不要使用0.0.1或localhost，除非你就在服务器上操作。 - 如果你需要从外网访问,你需要一个 公网 IP，并且确保防火墙和路由器已经正确配置了端口转发（6443 端口）。
- 如果你和 K3s 服务器在同一个局域网内，请使用它的 内网 IP（
- 端口是否正确？
默认端口是
6443，请确认没有修改过。
检查网络连通性（这是最常见的原因）
在客户端机器上,使用 telnet 或 nc 测试是否能连接到 K3s 服务器的 6443 端口。
# 使用 telnet (如果没有，可能需要安装 sudo apt-get install telnet) telnet <你的服务器IP> 6443 # 或者使用 nc (netcat) nc -zv <你的服务器IP> 6443
- 如果连接失败（
telnet: Unable to connect to remote host: Connection timed out）： 这说明网络不通，请继续下一步排查。 - 如果连接成功（会显示
Connected to ...）： 网络是通的，问题可能出在 K3s 服务器本身的配置或证书上，可以跳到第 5 步。
检查防火墙和云服务商安全组
如果网络测试失败,99% 的原因是防火墙挡住了连接。
-
在 K3s 服务器节点上检查系统防火墙:
-
Ubuntu/Debian (使用 UFW):
# 检查 UFW 状态 sudo ufw status # 如果是 ACTIVE，允许 6443 端口 sudo ufw allow 6443/tcp # 重启 UFW 使规则生效（可选） sudo ufw reload
-
CentOS/RHEL (使用 Firewalld):
# 检查 Firewalld 状态 sudo firewall-cmd --state # 如果是 running，允许 6443 端口 sudo firewall-cmd --permanent --add-port=6443/tcp sudo firewall-cmd --reload
-
云服务商安全组（如阿里云、腾讯云、AWS、DigitalOcean）: 这是非常容易被忽略的一点！登录你的云服务商控制台，找到你 K3s 服务器所在实例的 “安全组” 或 “防火墙” 规则。
- 必须添加一条入站规则：
- 端口范围:
6443 - 协议:
TCP - 源 IP:
0.0.0/0(允许任何 IP 访问，不安全但便于测试) 或者你客户端的公网 IP (更安全)。
- 端口范围:
- 必须添加一条入站规则：
-
检查 K3s 服务器状态和证书
如果网络通了,但 kubectl 仍然报错，可能是服务器端的问题。
-
检查 K3s 服务状态: 在 K3s 服务器节点上执行：
sudo systemctl status k3s
如果状态不是
active (running)，说明 K3s 服务本身有问题，查看日志获取更多信息：sudo journalctl -u k3s -f
-
检查证书是否过期: 有时证书问题也会导致连接失败，在服务器上检查 API Server 证书：
# 检查证书有效期 openssl x509 -in /etc/rancher/k3s/agent/server-token-ca.crt -noout -dates
如果证书过期,你需要重新初始化 K3s 或手动更新证书，通常情况下，K3s 会自动处理证书续订。
第 3 步：其他可能的原因
如果以上步骤都无法解决问题,可以考虑以下几点：
- DNS 问题: 确保你使用的 IP 地址是正确的，并且没有 DNS 解析错误。
- 代理问题: 如果你或服务器处在公司网络或代理后面，可能会阻止
6443端口的通信，尝试暂时关闭代理进行测试。 k3sup用户: 如果你使用的是k3sup工具，请确保它在执行k3sup install或k3sup join时，能够正确地通过 SSH 连接到服务器，并且服务器上的/etc/rancher/k3s/k3s.yaml文件存在且内容正确。k3sup会自动处理kubeconfig的下载和配置。
总结与快速自查清单
当你遇到 "k3 远程服务器不存在或不可用" 时，按这个清单快速检查：
kubeconfig文件: 确认~/.kube/config文件存在、内容正确（特别是server地址）、权限为600。server地址: 确认 IP 地址是 内网 IP（局域网访问）或 公网 IP（外网访问），并且端口是6443。- 网络连通性: 在客户端用
telnet <服务器IP> 6443测试，看是否能通。 - 防火墙: 检查 系统防火墙 (UFW/Firewalld) 和 云服务商安全组，确保
6443/TCP端口已开放。 - K3s 服务状态: 在服务器上用
sudo systemctl status k3s检查 K3s 是否正在运行。
按照这个流程,你大概率可以定位并解决问题，如果问题依旧，请提供更多细节，
- 你在什么操作系统上操作（客户端和服务器）？
- 你是如何安装 K3s 的（单节点、多节点）？
- 你使用的具体命令是什么（
kubectl get nodes还是k3sup ...）？ telnet测试的结果是什么？
