企业官网建设流程全解析

• 云原生
• 运维
• CLI

k3sup（读作 "ketchup"，番茄酱之意）是一个用 Go 编写的轻量级工具，只需 SSH 访问和一个k3sup二进制文件，就能在任何本地或远程虚拟机上从零到 KUBECONFIG，在约 60 秒内让你在自己的电脑上运行kubectl get pods。本文以当前仓库的 README.md 为核心，结合 main.go 与cmd/下的命令实现源码，系统讲解 k3sup 的工作原理、CE（社区版）与 Pro 的全部命令用法、两种 HA 多主架构的搭建流程、Raspberry Pi 实战，以及故障排查方法，帮助你完整掌握这套以 SSH 为唯一前置条件的 K3s 引导方案。

概念架构：k3sup 在你的本地机器上运行，通过 SSH 把 K3s 安装到任意 VM（如 AWS EC2、DigitalOcean 等），并把 kubeconfig 拉回本地。

一、k3sup 是什么，解决了什么问题

k3sup 通过ssh将k3s安装到远程 Linux 主机，也可以把已有的 Linux 主机作为agents（K3s 术语中的 worker/节点）加入 k3s 集群。整个过程中你永远不需要登录到远程服务器。

工具本身是 Go 编写的静态二进制，交叉编译支持 Linux、Windows、macOS，甚至 Raspberry Pi。安装流程大致是：先用 Rancher 提供的官方脚本安装k3s，同时传入主机公网 IP 以保证 TLS 正常工作；随后从服务器取回kubeconfig并改写，使你可以从笔记本上用kubectl连接。

也许你会问：这些用 bash 也能做，为什么还需要专门工具？README 的解释是：k3sup 把对许多开发者而言非常手动、容易出错的流程自动化了——一旦你用惯用的工具创建好 VM，k3sup让你距离在本地跑kubectl get pods只差 60 秒。如果目标就是本机，还可以用k3sup install --local完全绕过 SSH。

从源码看，命令体系由 main.go 注册：install、join、ready、update、plan、node-token、get-config、get（含get pro）与pro等命令全部基于 Cobra 框架构建，其中k3sup get pro会从容器镜像仓库拉取 Pro 二进制（见下文 Pro 章节）。

典型使用场景

• 用k3sup install在任意 VM 上引导 K3s 集群——无论是手动、CI 中还是通过cloud-init；
• 在裸金属、Raspberry Pi、VM、AWS EC2、Google Cloud、DigitalOcean、Civo、Linode、Scaleway 等平台从零到kubectl；
• 构建高可用（HA）多主（多 server）集群；
• 用k3sup-pro get-config从已有集群拉取 KUBECONFIG；
• 用k3sup join把节点加入已有 k3s 集群；
• 用k3sup plan+ 一份包含 IP 地址的 JSON 文件，构建面向自动化与规模化测试的大集群。

二、k3sup 的工作原理：四条核心步骤

README 用一张 ASCII 图清晰描述了 k3sup 的完整工作流程：

k3sup install +---------------------+ +-----------------------------+ | | 1. SSH | | | Your Laptop / +---------------->| Remote Server (VM/RPi) | | Workstation | | | | | 2. Install | +---------------------+ | | +----------------+ | k3s -------->| | k3s (server/agent) | | | | kubectl | | | +---------------------+ | | +----------------+ | 3. Fetch | | | | kubeconfig |<-+ kubeconfig | | | +----------------+ | +-----------------------------+ | | +---------------------+ k3sup join +-------------------->+-----------+ | | Agent 1 | +-------------------->+-----------+ | | Agent 2 | +-------------------->+-----------+ | Agent n | +-----------+

四步分别是：

1. k3sup install：SSH 进入服务器并安装 k3s；
2. kubeconfig：自动抓取 kubeconfig 到你的笔记本；
3. k3sup join：通过 SSH 把 agent 节点加入集群；
4. kubectl：从笔记本直接使用。

在 cmd/install.go 的实现中，makeInstallExec会拼接INSTALL_K3S_EXEC='server --tls-san <host> ...'形式的安装环境变量，最终执行形如curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC=... sh -的远程命令（getScript常量定义于 cmd/install.go）。抓取 kubeconfig 的远程命令则是sudo cat /etc/rancher/k3s/k3s.yaml。

Tip：在 Mac、Linux 与 WSL2 上，可以配合 SlicerVM 快速创建单节点或多节点 K3s 集群。

三、下载与安装 k3sup CE

k3sup 以静态 Go 二进制分发，MacOS 和 Linux 可用官方安装脚本，Windows 用户可直接下载可执行文件：

curl -sLS https://get.k3sup.dev | sh sudo install k3sup /usr/local/bin/ k3sup --help

Windows 用户可以用普通的 "Windows command prompt" 直接运行k3sup install和k3sup join。

四、前置条件：服务器的免密 sudo

部分 Linux 主机已配置允许sudo免密执行；没有配置的主机需要做如下修改（README 中的标准做法）：

# sudo visudo # 在文件底部添加一行 # 把 "alex" 换成你的用户名，例如 "ubuntu" alex ALL=(ALL) NOPASSWD: ALL

大多数情况下，Ubuntu 及其他发行版的云镜像默认已满足此要求，无需额外配置。如果只需要单台服务器，也可以交互式登录后改用k3sup install --local，彻底绕开 SSH 与 sudo 前置条件。

五、CE 核心命令：k3sup install部署 K3s 服务器

创建好运行 Ubuntu、Debian、Raspbian 等兼容系统的新 VM，并确保已把注册的 SSH 密钥自动复制到新主机（也可以用ssh-copy-id user@IP手动复制），即可开始安装。

假设 IP 为192.168.0.1、用户名为ubuntu：

export IP=192.168.0.1 k3sup install --ip $IP --user ubuntu # 或者用主机名 + SSH 密钥（EC2 场景） export HOST="ec2-3-250-131-77.eu-west-1.compute.amazonaws.com" k3sup install --host $HOST --user ubuntu \ --ssh-key $HOME/ec2-key.pem

安装完成后即可验证：

export KUBECONFIG=`pwd`/kubeconfig kubectl get node

注意应始终使用pwd/拼出完整路径，之后可随意切换目录。

install的全部可选参数

以下是 README 与 cmd/install.go 中定义并行的完整参数清单：

运行k3sup install --help可以看到更多选项。

源码级细节：kubeconfig 是如何被改写的

cmd/install.go 中的rewriteKubeconfig是理解 k3sup 魔力的关键：它用strings.NewReplacer把服务器返回的 k3s.yaml 中的127.0.0.1、localhost替换为实际主机地址，并把 context 名default替换为--context指定的值。也就是说，服务器上生成的 kubeconfig 原本指向本机回环地址，k3sup 负责把它"翻译"成你的笔记本可以直连的公网地址。

当指定--merge时，mergeConfigs 会把新集群配置写入临时文件，通过设置KUBECONFIG=<主文件>:<临时文件>环境变量，调用kubectl config view --merge --flatten完成合并（Windows 下路径分隔符为;）。最终写盘时文件权限为0600（writeConfig），保证 kubeconfig 的敏感内容不被其他用户读取。

六、检查集群是否就绪：k3sup ready

有多种方式确认集群可用。k3sup 通过 KUBECONFIG 执行 "kubectl get nodes"，检查每个节点（含 agent/worker）的 "Ready" 状态。

在节点上直接安装并检查：

k3sup install \ --local \ --context localk3s k3sup ready \ --context localk3s \ --kubeconfig ./kubeconfig

检查保存在本地文件的远程服务器：

k3sup install \ --ip 192.168.0.101 \ --user pi k3sup ready \ --context default \ --kubeconfig ./kubeconfig

检查默认 KUBECONFIG 中的合并 context：

k3sup install \ --ip 192.168.0.101 \ --user pi \ --context pik3s \ --merge \ --local-path $HOME/.kube/config # $HOME/.kube/config 是 kubeconfig 的默认位置 k3sup ready --context pik3s

ready命令（cmd/ready.go）默认尝试--attempts 25次、每次间隔--pause 2s，通过kubectl get nodes -o=jsonpath='{.items..status.conditions[-1:].status}'判断所有节点是否为True，随后还会等待 default service account 创建完成（这是 CI 场景下曾引发失败的环节），可用--quiet抑制每次尝试的输出。

七、把集群合并进你的 KUBECONFIG

远程集群默认的 context 名是default，但可以用下面的方式覆盖并合并进主配置文件$HOME/.kube/config，然后用kubectl config get-contexts或kubectx管理：

k3sup install \ --ip $IP \ --user $USER \ --merge \ --local-path $HOME/.kube/config \ --context my-k3s

此后即可kubectl config use-context my-k3s或kubectx my-k3s切换。

八、k3sup join：把 agent 节点加入集群

假设已有服务器并执行过：

export SERVER_IP=192.168.0.100 export USER=root k3sup install --ip $SERVER_IP --user $USER

接着把一个或多个agent加入集群：

export AGENT_IP=192.168.0.101 export SERVER_IP=192.168.0.100 export USER=root k3sup join --ip $AGENT_IP --server-ip $SERVER_IP --user $USER

如果 SSH 登录 agent 与 server 的用户名不同，必须通过--server-user参数提供 server 的用户名。执行完上面的命令，你就拥有了一个两节点集群——无论是在本地 VM、Raspberry Pi、64 位 ARM 还是 EC2 云 VM 上。

源码级细节：join 如何获取令牌并安装 agent

cmd/join.go 展示了 join 的两段式流程：若未通过--node-token或--node-token-path预置令牌，k3sup 会先 SSH 到 server，执行sudo cat /var/lib/rancher/k3s/server/node-token（数据目录可用--server-data-dir覆盖，默认/var/lib/rancher/k3s/）取回节点令牌并尽早关闭该连接；随后 makeJoinExec 构造K3S_URL='https://<server>:6443'、K3S_TOKEN='<token>'与INSTALL_K3S_EXEC等环境变量，以curl -sfL https://get.k3s.io | ... sh -s -的方式在目标节点安装 agent（serverAgent=false）或额外 server（serverAgent=true时追加server --server <url>，并可选--tls-san）。

join还支持--server-url指定与--server-ip/--server-host不同的加入 URL、--server-ssh-port指定连接 server 的独立 SSH 端口，以及--k3s-extra-args（如'--node-taint key=value:NoExecute'）。

九、使用硬件认证 / 2FA 或 SSH Agent

以下情况建议使用ssh-agent：

• SSH 密钥受密码保护，不想每次 k3sup 命令都输入密码；
• 使用 YubiKey 之类的硬件认证设备进行 SSH 会话认证。

启用方法：

$ eval $(ssh-agent) Agent pid 2641757

如果密钥是加密的，可选执行ssh-add ~/.ssh/id_rsa。此后运行任何 k3sup 命令，SSH 密钥会从 ssh-agent 请求而非默认位置。也可以用--ssh-key指定特定密钥对。

从源码看（cmd/install.go 的connectOperator），连接时会优先尝试仅使用 SSH Agent 认证（MacOS/Linux 上读取SSH_AUTH_SOCK环境变量），失败后才回退到解析默认或指定的私钥文件；若私钥带密码短语，会先尝试从 ssh-agent 匹配公钥，否则交互式提示输入密码短语。

十、HA 多主集群（一）：外部 SQL 数据存储

K3s 多主（HA）模式搭配外部存储最简易的测试方式是使用 DigitalOcean 托管 MySQL。

• 从 DigitalOcean 控制台拿到连接串并改写。改写前：

mysql://doadmin:80624d3936dfc8d2e80593@db-mysql-lon1-90578-do-user-6456202-0.a.db.ondigitalocean.com:25060/defaultdb?ssl-mode=REQUIRED

改写后：

mysql://doadmin:80624d3936dfc8d2e80593@tcp(db-mysql-lon1-90578-do-user-6456202-0.a.db.ondigitalocean.com:25060)/defaultdb

注意：去掉了?ssl-mode=REQUIRED，并把主机/端口包在tcp()中。这与 cmd/install.go 中的校验逻辑一致——源码会直接拒绝包含ssl-mode=REQUIRED的连接串，并要求 mysql 主机必须以tcp(host:port)形式给出。

export DATASTORE="mysql://doadmin:80624d3936dfc8d2e80593@tcp(db-mysql-lon1-90578-do-user-6456202-0.a.db.ondigitalocean.com:25060)/defaultdb

可以给命令前加两个空格，防止它被写入 bash history。

生成用于加密数据的 token（如果已有运行中的节点，可以登录节点查看/var/lib/rancher/k3s/server/token）：

# 生成 token 的最佳方式： export TOKEN=$(openssl rand -base64 64) # 无 openssl 的 Linux 主机备选： export TOKEN=$(tr -dc A-Za-z0-9 </dev/urandom | head -c 64) # 再不行就试试： export TOKEN=$(head -c 64 /dev/urandom|shasum| cut -d - -f 1)

创建三台 VM，两台作 server、一台作 agent：

export SERVER1=104.248.135.109 export SERVER2=104.248.25.221 export AGENT1=104.248.137.25

安装第一台 server：

k3sup install --user root --ip $SERVER1 --datastore="${DATASTORE}" --token=${TOKEN}

安装第二台 server：

k3sup install --user root --ip $SERVER2 --datastore="${DATASTORE}" --token=${TOKEN}

加入第一个 agent（加入任一 server 均可，此步骤不需要 datastore）：

k3sup join --user root --server-ip $SERVER1 --ip $AGENT1

如果 SSH 登录 agent 与 server 的用户名不同，同样需要--server-user参数。

此时执行kubectl get node会看到两个 master/server 与一个 agent：

kubectl get node NAME STATUS ROLES AGE VERSION k3sup-1 Ready master 73s v1.19.6+k3s1 k3sup-2 Ready master 2m31s v1.19.6+k3s1 k3sup-3 Ready <none> 14s v1.19.6+k3s1

不过 agent 是加入第一台 server 的——如果第一台 server 宕机，agent 实际也会离线。有两种方式消除对单台主机 IP 的依赖：一是创建云厂商的 TCP 负载均衡器，二是创建包含所有 server IP 的 DNS 轮询记录。

以 DigitalOcean 为例：在 Networking 菜单点击 "Load Balancer"，在与 Droplet、SQL 同区域创建，选择两台 Droplet，使用TCP端口6443。若还想用k3sup join指向 LB 的 IP，还需要额外放行TCP端口22，健康检查也设置为TCP+ 端口6443。把 LB 地址存入环境变量：

export LB=174.138.101.83

用 ssh 登录两台 server，编辑/etc/systemd/system/k3s.service，把--tls-san及其后的地址改为 LB 的地址：

ExecStart=/usr/local/bin/k3s \ server \ '--tls-san' \ '104.248.135.109' \

改为：

ExecStart=/usr/local/bin/k3s \ server \ '--tls-san' \ '174.138.101.83' \

然后执行并重启（两台 server 都要做）：

sudo systemctl daemon-reload && \ sudo systemctl restart k3s-agent

agent 侧可手动编辑/etc/systemd/system/k3s-agent.service.env，或（若 LB 已放行端口 22）再次执行：

k3sup join --user root --server-ip $LB --ip $AGENT1

最后用 LB 的 IP 重新生成 KUBECONFIG：

k3sup install --skip-install --ip $LB

登录第一台 server 执行sudo systemctl stop k3s模拟故障，然后确认 kubectl 依然可用：

export KUBECONFIG=`pwd`/kubeconfig kubectl get node -o wide NAME STATUS ROLES AGE VERSION k3sup-1 NotReady master 23m v1.19.6+k3s1 k3sup-2 Ready master 25m v1.19.6+k3s1 k3sup-3 Ready <none> 22m v1.19.6+k3s1

你刚模拟了一台 master/server 的故障，而 kubectl 依然可以访问——一个具备韧性的 k3s 集群就这样建成了。

十一、HA 多主集群（二）：内嵌 etcd

从 k3sv1.19.5+k3s1开始，k3s 提供名为 "embedded etcd" 的多主（k3s 术语为多 server）配置。它需要 quorum（法定人数），即奇数个节点且至少三个。

初始化第一台 server（注意--cluster标志）：

export SERVER_IP=192.168.0.100 export USER=root k3sup install \ --ip $SERVER_IP \ --user $USER \ --cluster \ --k3s-version v1.19.1+k3s1

加入每台额外的 server（注意新的--server标志）：

export USER=root export SERVER_IP=192.168.0.100 export NEXT_SERVER_IP=192.168.0.101 k3sup join \ --ip $NEXT_SERVER_IP \ --user $USER \ --server-user $USER \ --server-ip $SERVER_IP \ --server \ --k3s-version v1.19.1+k3s1

查看kubectl get node：

kubectl get node NAME STATUS ROLES AGE VERSION paprika-gregory Ready master 8m27s v1.19.2-k3s cave-sensor Ready master 27m v1.19.2-k3s

如果首次安装时使用了--no-extras，每次 join 也要带上：

export USER=root export SERVER_IP=192.168.0.100 export NEXT_SERVER_IP=192.168.0.101 k3sup join \ --ip $NEXT_SERVER_IP \ --user $USER \ --server-user $USER \ --server-ip $SERVER_IP \ --server \ --no-extras \ --k3s-version v1.19.1+k3s1

在 cmd/join.go 的PreRunE中可以看到，--tls-san与--no-extras仅在--server模式下允许使用——这是源码层面的约束，防止对纯 agent 节点误传这些参数。

十二、Raspberry Pi（2、3 或 4）微教程

几分钟内即可在 Raspberry Pi 2/3/4 上把 Kubernetes 跑起来，最终在本地电脑拿到可远程访问集群的 KUBECONFIG 文件。

概念架构：k3sup 在本地运行，针对裸金属 ARM 设备部署。

1. 下载 etcher.io 用于烧录系统；
2. 用 Raspbian Lite 烧录 SD 卡；
3. 在 boot 分区创建名为ssh的空文件以启用 SSH；
4. 若还没有 SSH 密钥，用ssh-keygen生成（一路回车即可）；
5. 用ping -c raspberrypi.local找到 RPi 的 IP，然后export SERVER_IP=""填入该 IP；
6. 编辑/boot/cmdline.txt（Ubuntu 为/boot/firmware/cmdline.txt），在行末追加内核容器特性参数：cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory；
7. 复制 SSH 密钥：ssh-copy-id pi@raspberrypi.local；
8. 运行k3sup install --ip $SERVER_IP --user pi；
9. 指向配置文件并查看节点状态：

export KUBECONFIG=`pwd`/kubeconfig kubectl get node -o wide

此时你的笔记本已经可以通过 kubectl 访问运行着 k3s 的 Raspberry Pi。若要加入更多节点，为每台额外的 RPi 执行export IP=""后运行：

• k3sup join --ip $IP --server-ip $SERVER_IP --user pi

记住：所有这些命令都在你的电脑上运行，而不是在 RPi 上。

十三、K3sup Pro：plan / apply 驱动的 IaaC 与 GitOps

CE 版适合实验探索，而k3sup-pro为长期以来的 IaaC/GitOps 诉求而生：它新增plan与apply命令，可并行地自动化从小到大的安装；plan 文件可自定义并纳入 Git 维护与更新。支持所有 K3sup Pro 用户的渠道是 K3sup CE 仓库的 Issue Tracker。

Pro 版命令总览：

• activate：获取/刷新许可证密钥；商业用户直接把密钥放到~/.k3sup/LICENSE
• plan：读取一个或多个 JSON 文件，生成 HA 安装的 YAML 计划
• apply：并行执行安装，可选预先下载 K3s 二进制并通过 SSH 拷贝到各主机
• exec：在集群所有节点上运行命令
• get-config：从已有安装获取 kubeconfig
• uninstall：并行地从集群所有节点卸载 k3s

经典 CE 命令（install、join）也保留在同一个二进制中，用于向后兼容与快速测试。

--predownload标志是迈向完全离线（airgapped）方案的第一步，同时能降低带宽、加快安装速度。

获取k3sup-pro

k3sup-pro二进制打包在容器镜像中而非 GitHub Releases。推荐用 K3sup CE 获取：

PRO=1 curl -sLS https://get.k3sup.dev | sudo -E sh

或者，若已有最新版 K3sup CE，可让它自我替换：

sudo k3sup get pro

k3sup get pro可通过--path指向你有写权限的目录来省略 sudo。该命令的实现（cmd/get_pro.go）会从容器镜像仓库拉取与当前系统架构匹配的镜像层、解包出k3sup-pro二进制，先执行version自检再安装到目标路径（默认/usr/local/bin/）。如需特定版本，可先查看镜像仓库中的版本列表，再通过--version指定。

激活 K3sup Pro

运行k3sup-pro activate用 GitHub.com 验证身份，只需在笔记本/工作站上做一次，托管 K3s 的机器无需额外步骤。商业用户把许可证密钥放在$HOME/.k3sup/LICENSE即可，无需运行activate。

plan/apply：自动化与大规模安装

k3sup-pro plan读取包含主机信息的 JSON 文件并生成可编辑的 YAML 计划。示例输入文件：

[ { "hostname": "k3s-server-1", "ip": "192.168.129.138" }, { "hostname": "k3s-server-2", "ip": "192.168.129.128" }, { "hostname": "k3s-server-3", "ip": "192.168.129.131" }, { "hostname": "k3s-agent-1", "ip": "192.168.129.130" }, { "hostname": "k3s-agent-2", "ip": "192.168.129.127" } ]

下面这条命令将创建 1 台主 server + 2 台附加 server（组成 HA etcd 集群），最后两台作为 agent：

k3sup pro plan ./n100.json ./n200.json \ --user ubuntu \ --servers 3 \ --svclb=false \ --server-extra-args "--disable traefik" \ --agent-extra-args "--node-label worker=true"

生成的示例 plan.yaml：

version: k3s_channel: stable server_options: user: ubuntu ssh_port: 22 k3s_extra_args: --disable traefik parallel: 5 traefik: true agent_options: k3s_extra_args: --node-label worker=true hosts: - name: k3s-1 role: server host: 192.168.138.2 architecture: x86_64 - name: k3s-2 role: server host: 192.168.138.3 architecture: x86_64 - name: k3s-3 role: server host: 192.168.138.4 architecture: x86_64 - name: k3s-agent-1 role: agent host: 192.168.137.2 architecture: x86_64 - name: k3s-agent-2 role: agent host: 192.168.137.3 architecture: x86_64 - name: k3s-agent-3 role: agent host: 192.168.137.4 architecture: x86_64

YAML 计划文件可编辑并提交到 Git，用于后续维护与升级。准备好后执行k3sup-pro apply并行安装：

• --predownload：先把 k3s 二进制下载到本地，再通过 SSH 拷贝到每台主机，加速安装；
• --parallel：设置同时运行的安装步骤数。

k3sup pro apply \ --predownload \ --parallel 10

安装后可用k3sup-pro get-config获取 kubeconfig，然后合并进主 KUBECONFIG：

k3sup pro get-config \ --local-path $HOME/.kube/config \ --context my-k3s \ --merge

或输出为本地文件：

k3sup pro get-config \ --local-path ./kubeconfig export KUBECONFIG=`pwd`/kubeconfig

补充说明：CE 中的k3sup plan（cmd/plan.go）是 Pro 的前身思路——读取 JSON 主机清单，直接生成一段包含k3sup install/k3sup join调用的 shell 脚本：第一台主机执行install --cluster并导出NODE_TOKEN=$(k3sup node-token ...)，前 N 台（--servers，默认 3）作为 server 加入，其余作为 agent；--limit可限制使用的主机数量，--background让后续节点安装以后台方式并行执行，kubeconfig 存在时（--merge默认开启）自动附带--merge。

k3sup-pro uninstall：快速卸载 / 重置

k3sup-pro uninstall会从集群所有节点卸载 k3s。若有 plan YAML 文件，用户名、SSH 端口与密钥文件都会从文件中读取，按顺序并行卸载：先移除 agent，再移除附加 server，最后移除主 server。

k3sup pro uninstall

如果只有设备 JSON 文件，可能还需要--user和/或--ssh-key：

k3sup pro uninstall \ --user ubuntu \ --ssh-key ~/.ssh/id_rsa

k3sup pro exec：在每台机器上运行命令

k3sup-pro exec可在集群所有节点运行命令，可用--servers或--agents限定范围。

在所有节点运行：

k3sup pro exec \ "free -h"

仅在 server 上运行：

k3sup pro exec \ --servers \ "sudo journalctl -u k3s -n 100"

仅在 agent 上运行：

k3sup pro exec \ --agents \ "sudo journalctl -u k3s-agent -n 100"

k3sup pro get-config：对接已有集群

k3sup-pro get-config无需任何安装步骤即可从已有 K3s 安装取回 kubeconfig。当你已经跑着 K3s、只想拿到集群配置，或当初生成了本地./kubeconfig而现在想以有意义的 context 名合并进主$HOME/.kube/config时非常有用。

从远程服务器获取 kubeconfig：

k3sup pro get-config \ --host 192.168.0.100 \ --user ubuntu \ --local-path ./kubeconfig

从本地安装获取：

k3sup pro get-config --local

合并进主 KUBECONFIG：

k3sup pro get-config \ --host 192.168.0.100 \ --user ubuntu \ --merge \ --local-path $HOME/.kube/config \ --context my-remote-cluster

使用自定义 SSH 密钥：

k3sup pro get-config \ --host 192.168.0.100 \ --user ubuntu \ --ssh-key $HOME/.ssh/my-key \ --local-path ./kubeconfig

如果还没有k3sup-pro，也可以用带--skip-install标志的k3sup install达到同样效果。CE 版同样内置k3sup get-config（cmd/get-config.go），支持--local、--merge、--context等参数，并复用与 install 相同的obtainKubeconfig改写逻辑。

K3sup Pro 路线图

首版 K3sup Pro 大体功能完备，商业用户还有以下规划特性：

• 通过 bastion 主机使用 K3sup Pro Plan/Apply；
• 先在本地机器下载软件包、再分发到目标机的离线（airgapped）安装。

十四、安全注意事项

如果使用公有云，务必参考 Rancher 团队关于防火墙 / 安全组的设置说明，尤其是 k3s 的端口开放要求（network 相关的安装要求章节）。K3s 集群通常需要放行 6443（API server）与 8472/51820 等节点间通信端口，具体以 k3s 官方文档为准。

十五、故障排查与支持

问题是否出在 K3s 本身？

遇到问题先想一下：这多半是 K3s 的问题而非 k3sup 的。k3sup 是一个非常成熟的项目，覆盖的几个使用场景表现稳定。K3s 的支持渠道包括 Rancher Slack 的#k3s频道，以及在 K3s 仓库提交 issue。

想装特定版本的 K3s？参见k3sup install --help的--k3s-version与--k3s-channel。系统是否满足 Kubernetes 运行要求？运行k3s check-config查看输出——README 作者定期用 Raspberry Pi OS 与 Ubuntu LTS 测试 K3sup。

常见问题

最常见的问题是漏掉了一步，好在大都能从 K3s 服务日志看出端倪：

• Raspberry Pi 未启用 cgroups：多半没改cmdline.txt以启用 CPU 与内存 cgroup，按本文 Raspberry Pi 章节的说明修改；
• 在节点上运行kubectl：不要这样做。k3sup 会把文件复制到你的本地工作站。除了查日志/升级系统，不要登录 agent 或 server；
• sudo: a terminal is required to read the password：为主机配置免密sudo，参见本文"前置条件"章节；
• 想不通过 SSH 直接在本机安装：用k3sup install --local，它不走 SSH 而是直接在主机上执行命令；
• K3s server 没启动：登录执行sudo systemctl status k3s或sudo journalctl -u k3s；
• K3s agent 没启动：登录执行sudo systemctl status k3s-agent；
• 在 etcd 集群中移除并重加 server 失败：这是已知问题，见 K3s 的 issue tracker；
• HA 使用了不支持的数据库版本：参见 Rancher 的 datastore 支持列表；
• join 节点报ssh: handshake failed：大概率是三种情况之一：
  • 没执行ssh-copy-id——先运行它，再用普通ssh确认可以无密码登录 server 与新节点；
  • RSA 公钥问题：Go 库存在底层 issue，请额外加--ssh-key ~/.ssh/id_rsa（或你的私钥所在路径）；
  • 登录 server 与待加入节点使用的用户名不同：为 server 提供--server-user参数。
• .ssh/config未被 k3sup 使用：k3sup 不使用ssh命令行的 config 文件，而是使用 CLI 标志，运行k3sup install/join --help查看支持哪些参数。

注意：把--no-deploy传给--k3s-extra-args已被 K3s 1.17 的安装器废弃，改用--disable或--no-extras。

找回 KUBECONFIG 访问

如果遇到需要sudo才能访问kubectl的情况：不要直接在装有 K3s 的主机上运行kubectl。k3sup 的设计目标就是把集群配置改写/合并到你的本地 KUBECONFIG 文件——kubectl 只应在笔记本/客户端机器上运行。如果弄丢了 kubeconfig，用k3sup get-config（配合--merge、--context等标志）即可找回。

智能卡与 2FA

警告：请求支持智能卡 / 2FA 的 issue 会被立即关闭。该功能已被验证可用，按现状提供。

智能卡或 YubiKey 等 2FA 安全密钥可用：只要正确配置好 ssh-agent，MacOS 与 Linux 上 k3sup 会交给 agent 建立连接。上文"SSH Agent / 2FA"章节已给出配置方法。

关于iptables的补充说明

k3s 目前存在一个涉及iptables >= 1.8的问题，可能影响网络通信（该问题已在 Debian Buster 上被观察到，其他发行版也可能受影响），可在 k3s 与 Kubernetes 的相关 issue 中查找信息与临时方案。

附：术语与同类工具辨析

术语对照：Kubernetes 使用 master/slave 术语，而 k3s 使用 server/agent。

• k3s：k3sup 安装的发行版，是一个合规、轻量、多架构的 Kubernetes 发行版，适合本地/远程开发与边缘场景；
• k3d：在本地笔记本的 Docker 容器中运行 k3s；
• kind：在 Docker 容器内运行 Kubernetes 集群做本地开发（k3s 可通过 k3d 达到类似目的；kind 不适合远程开发集群）；
• kubeadm：创建功能完整、生产就绪的 Kubernetes 集群（可带 HA），通常比 k3s 更重更慢，面向云 VM 或裸金属，在低功耗 ARM 设备上不一定好用。

结语

从单机install、多节点join、ready就绪检查，到外部 SQL 与内嵌 etcd 两种 HA 架构，再到面向 GitOps 的plan/apply与exec/uninstall/get-config，k3sup 用一条 SSH 连接串起了"从零到 KUBECONFIG"的全过程。本文所有命令均可对照仓库源码验证：命令注册见 main.go，核心安装逻辑见 cmd/install.go，节点加入见 cmd/join.go，就绪检查见 cmd/ready.go，计划生成见 cmd/plan.go，命令执行抽象见 pkg/operator/operator.go 与 pkg/operator/ssh_operator.go，测试用例见 cmd/install_test.go 与 cmd/join_test.go。项目采用 MIT 许可（见 LICENSE），Pro 版本的使用约束可查阅 EULA.md。

• 云原生
• 运维
• CLI