k3s一键部署教程（快速安装轻量k8s）

@土豆2026-04-22 9:03

k3s一键部署教程（快速安装轻量k8s）

一、一键部署脚本（国内镜像版）

脚本采用国内镜像加速，默认配置阿里云镜像仓库，有效解决官方源下载缓慢、国外镜像拉取失败等问题，适配国内服务器环境，提供两个版本供按需选择，无需手动适配架构，助力快速安装轻量k8s。

版本1：指定k3s稳定版本（v1.34.6+k3s1）

bash 复制代码 
#!/bin/bash
# 一键部署k3s单节点（国内镜像版，适配x86_64/arm64架构，快速安装轻量k8s）
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | 
     INSTALL_K3S_MIRROR=cn 
     INSTALL_K3S_VERSION=v1.34.6+k3s1 
     INSTALL_K3S_EXEC="--system-default-registry=registry.cn-hangzhou.aliyuncs.com" 
     sh -

版本2：默认安装最新稳定版（无需指定版本）

bash 复制代码 
#!/bin/bash
# 一键部署k3s单节点（国内镜像版，适配x86_64/arm64架构，快速安装轻量k8s）
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | 
     INSTALL_K3S_MIRROR=cn 
     INSTALL_K3S_EXEC="--system-default-registry=registry.cn-hangzhou.aliyuncs.com" 
     sh -

实际部署日志及场景说明

以下为v1.34.6+k3s1版本实际部署完整日志，标注关键场景及说明，帮助理解部署过程、排查常见情况：

bash 复制代码 
[root@master ~]#
[root@master ~]# curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | 
>      INSTALL_K3S_MIRROR=cn 
>      INSTALL_K3S_VERSION=v1.34.6+k3s1 
>      INSTALL_K3S_EXEC="--system-default-registry=registry.cn-hangzhou.aliyuncs.com" 
>      sh -
[INFO]  Using v1.34.6+k3s1 as release  # 确认使用指定的k3s版本
[INFO]  Downloading hash rancher-mirror.rancher.cn/k3s/v1.34.6-k3s1/sha256sum-amd64.txt  # 下载国内镜像的版本校验哈希
[INFO]  Skipping binary downloaded, installed k3s matches hash  # 关键场景：已安装相同版本k3s，跳过二进制文件下载（无需处理）
[INFO]  Finding available k3s-selinux versions  # 自动查找适配的k3s-selinux政策版本
Loaded plugins: fastestmirror, langpacks
Loading mirror speeds from cached hostfile
 * base: mirrors.aliyun.com
 * extras: mirrors.aliyun.com
 * updates: mirrors.aliyun.com
Package yum-utils-1.1.31-54.el7_8.noarch already installed and latest version  # yum-utils已安装，无需重复安装
Nothing to do
Loaded plugins: fastestmirror, langpacks
Command line error: no such option: --refresh  # 轻微异常：yum版本不支持--refresh参数，不影响部署（可忽略）
Loaded plugins: fastestmirror, langpacks
Loading mirror speeds from cached hostfile
 * base: mirrors.aliyun.com
 * extras: mirrors.aliyun.com
 * updates: mirrors.aliyun.com
rancher-k3s-common-stable                                                                                                                                                        | 2.9 kB  00:00:00
Package k3s-selinux-1.6-1.el7.noarch already installed and latest version  # k3s-selinux已安装最新版本，无需重复安装
Nothing to do
[INFO]  Skipping /usr/local/bin/kubectl symlink to k3s, already exists  # 关键场景：kubectl工具已存在，跳过符号链接创建（无需处理）
[INFO]  Skipping /usr/local/bin/crictl symlink to k3s, already exists  # 关键场景：crictl工具已存在，跳过符号链接创建（无需处理）
[INFO]  Skipping /usr/local/bin/ctr symlink to k3s, already exists  # 关键场景：ctr工具已存在，跳过符号链接创建（无需处理）
[INFO]  Creating killall script /usr/local/bin/k3s-killall.sh  # 创建k3s进程终止脚本（用于卸载前终止进程）
[INFO]  Creating uninstall script /usr/local/bin/k3s-uninstall.sh  # 创建k3s卸载脚本（对应教程第四章节操作）
[INFO]  env: Creating environment file /etc/systemd/system/k3s.service.env  # 创建systemd服务环境配置文件
[INFO]  systemd: Creating service file /etc/systemd/system/k3s.service  # 创建k3s systemd服务文件
[INFO]  systemd: Enabling k3s unit  # 设置k3s服务开机自启
[INFO]  systemd: Starting k3s  # 启动k3s服务
[root@master ~]#

日志关键说明：上述日志中出现的「跳过二进制下载」「工具已存在」「metrics警告」均为正常场景，无需额外操作；只要最终kubectl get no命令输出节点状态为「Ready」，即说明k3s部署成功。

二、部署结果验证

部署完成后，执行以下命令，快速验证轻量k8s是否正常运行：

bash 复制代码 
[root@master ~]# kubectl get no
E0421 12:49:01.992912   13868 memcache.go:287] couldn't get resource list for metrics.k8s.io/v1beta1: the server is currently unable to handle the request  # 常见警告：metrics插件未就绪，不影响节点运行（可忽略）
E0421 12:49:02.094961   13868 memcache.go:121] couldn't get resource list for metrics.k8s.io/v1beta1: the server is currently unable to handle the request
E0421 12:49:02.147140   13868 memcache.go:121] couldn't get resource list for metrics.k8s.io/v1beta1: the server is currently unable to handle the request
E0421 12:49:02.205937   13868 memcache.go:121] couldn't get resource list for metrics.k8s.io/v1beta1: the server is currently unable to handle the request
NAME     STATUS   ROLES           AGE   VERSION
master   Ready    control-plane   25d   v1.34.6+k3s1  # 部署成功：节点状态为Ready，可正常使用
[root@master ~]#

若命令输出节点信息，且节点状态为「Ready」，则说明轻量k8s（k3s）部署成功，可直接开展后续k8s相关测试操作。补充说明：若执行命令后出现metrics.k8s.io/v1beta1相关警告，属于metrics插件未就绪，不影响k3s核心功能使用，无需处理。

三、部署注意事项

  • 镜像加速说明：脚本默认使用国内镜像（rancher-mirror.rancher.cn），专门解决官方源在国内服务器下载缓慢的问题，完美适配国内网络环境，大幅提升轻量k8s的安装效率。部署时会自动下载对应版本的哈希文件进行校验，确保二进制文件完整性。

  • 版本选择建议：版本1指定固定k3s版本（v1.34.6+k3s1），稳定性更强，适合对版本有明确要求的轻量k8s安装场景；版本2默认安装最新稳定版，可获取最新功能，适合无需固定版本的快速安装测试。若已安装相同版本k3s，部署脚本会自动跳过二进制下载，仅更新相关配置和脚本。

  • 镜像仓库配置：脚本中--system-default-registry=registry.cn-hangzhou.aliyuncs.com参数，用于配置阿里云镜像仓库，避免国外镜像拉取失败，确保轻量k8s部署过程顺畅无卡顿。

  • 国内模式开启：INSTALL_K3S_MIRROR=cn参数用于开启国内镜像模式，脚本会自动适配国内下载节点，优化k3s二进制文件及相关依赖的下载速度，助力快速完成轻量k8s安装，对应日志中「Downloading hash rancher-mirror.rancher.cn/...」场景。

  • 架构适配说明：脚本自动适配x86_64、arm64等主流服务器架构，无需手动修改任何参数，直接执行对应版本的部署命令即可完成轻量k8s安装。

  • 后续操作提示：部署完成后，kubectl、crictl、ctr等工具会自动创建符号链接（若工具已存在则跳过），无需额外操作，可直接开展轻量k8s相关测试工作。

  • 环境依赖补充：部署前需确保服务器已安装curl或wget工具（用于下载资源），若未安装，可先执行对应系统的安装命令（如CentOS：yum install -y curl，Ubuntu：apt install -y curl），避免影响轻量k8s安装。部署过程中会自动检查并安装k3s-selinux政策（若已安装则跳过）。

  • 权限说明：部署命令需以root权限执行，或使用sudo授权，否则会因权限不足导致轻量k8s安装失败。

  • 异常处理：若部署过程中出现下载失败，可重新执行部署命令；若出现SELinux相关报错，可添加参数INSTALL_K3S_SKIP_SELINUX_RPM=true跳过SELinux RPM安装（仅测试环境建议使用），确保轻量k8s顺利安装。日志中出现的「yum --refresh参数错误」属于轻微异常，不影响部署，可忽略。

四、k3s卸载操作

当测试完成需清理环境时，可通过一键卸载命令彻底删除k3s及相关组件，结合你当前服务器/usr/local/bin目录下已存在的卸载脚本（k3s-uninstall.sh），具体操作步骤如下：

1. 确认卸载脚本位置

首先确认k3s卸载脚本（k3s-uninstall.sh）已存在于默认安装目录，可执行以下命令查看：

bash 复制代码 
ls /usr/local/bin | grep k3s-uninstall.sh

若输出k3s-uninstall.sh，说明脚本存在，可直接执行卸载操作；若未找到，可重新执行部署脚本后再进行卸载（部署脚本会自动创建该卸载脚本，对应日志中「Creating uninstall script /usr/local/bin/k3s-uninstall.sh」场景）。

2. 执行卸载命令

以root权限执行以下命令，一键卸载k3s及相关组件（包括k3s服务、kubectl、crictl等工具，以及相关配置文件）：

bash 复制代码 
/usr/local/bin/k3s-uninstall.sh

五、k3s默认kubeconfig文件说明

k3s部署完成后，会自动生成默认kubeconfig配置文件，用于kubectl工具与k3s集群建立连接，无需手动创建，以下是详细说明（结合k3s安装脚本默认配置）：

1. 默认文件路径

k3s默认kubeconfig文件路径固定为：/etc/rancher/k3s/k3s.yaml，该路径由k3s安装脚本自动配置，与脚本中FILE_K3S_ENV等环境配置文件路径保持一致，属于k3s默认的配置存储目录。

2. 文件核心作用

该文件包含集群地址、认证证书、访问令牌等关键信息，kubectl工具默认会读取此文件（需root权限），实现与k3s集群的通信，比如执行kubectl get no、kubectl get pods等命令时，无需手动指定配置文件路径。

3. 权限说明

默认情况下，kubeconfig文件（k3s.yaml）权限为600（仅root用户可读写），这是为了保障集群访问安全，防止非授权用户获取集群认证信息。普通用户执行kubectl命令时，需添加sudo授权，否则会提示权限不足。

4. 手动指定配置文件（可选）

若需在非root用户下使用kubectl，或需指定其他kubeconfig文件，可通过以下两种方式操作：

  • 临时指定：执行kubectl命令时，通过--kubeconfig参数指定文件路径，示例：
    sudo kubectl --kubeconfig /etc/rancher/k3s/k3s.yaml get no

  • 永久指定：将kubeconfig文件复制到当前用户的~/.kube/config路径下，并修改权限，示例：
    sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
    sudo chown $USER:$USER ~/.kube/config
    chmod 600 ~/.kube/config

5. 文件清理说明

执行k3s卸载命令（/usr/local/bin/k3s-uninstall.sh）时，会自动删除/etc/rancher/k3s/目录下的所有配置文件（包括k3s.yaml），无需手动清理；若手动删除kubeconfig文件，重新执行k3s部署脚本即可重新生成。

6. 关键补充

kubeconfig文件中的集群地址、证书等信息由k3s安装脚本自动生成，与k3s服务配置（/etc/systemd/system/k3s.service）保持一致，无需手动修改；若修改该文件，会导致kubectl无法正常连接k3s集群，需重新部署k3s生成新的配置文件。

相关推荐
雨奔2 小时前
Kubernetes PodSecurityPolicy 完全指南：Pod 安全准入控制核心
安全·容器·kubernetes
雨奔2 小时前
Kubernetes 实操：创建 CPU 约束的 LimitRange 与 Pod
云原生·容器·kubernetes
草木红2 小时前
Docker常用命令
运维·docker·容器
姜太小白2 小时前
【Ollama】Docker部署Ollama完整指南
运维·docker·容器
IT从业者张某某2 小时前
Docker部署伪分布Hadoop
hadoop·docker·容器
一叶飘零_sweeeet2 小时前
Spring Boot 4.0：云原生 Java 开发的范式革命
java·spring boot·云原生
笨手笨脚の2 小时前
云原生部署常见服务
redis·docker·云原生·kubernetes·redis-cluster
youyudehexie2 小时前
云原生与边缘计算融合驱动下一代互联网架构创新探索实践
云原生·架构·边缘计算
上海云盾第一敬业销售2 小时前
云原生时代的安全困境：容器化应用如何正确部署WAF防护？
安全·云原生
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点032026年4月AI大事件深度解读：大模型竞争进入“深水区“042026 年 AI 编程助手全面对比评测：Cursor vs Copilot vs Claude Code vs GitHub Copilot Free05近期有什么ai的新消息，新动态？ 2026.4月06AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析07Claude Code Windows 兼容性问题：指定版本 2.1.112 可解决08UBUNTU Claude Code 报错 claude native binary not installed09从限购到畅通：GLM-5.1 Coding Plan接入攻略10免费！不限量！用opencode接入英伟达（NVIDIA）大模型，轻松打造你的 AI 编程助手