跳转至

1. K3s 基础部署

本章将指导您在 Linux 环境下完成 K3s 集群的安装。我们将涵盖单节点（All-in-One）和多节点（Master-Worker）两种模式，并重点解决国内网络环境下的安装痛点。

1.1 环境准备

1.1.1 系统要求

  • 操作系统：Ubuntu 20.04/22.04 LTS (推荐), CentOS 7.6+, Rocky Linux 8/9, Debian 10/11
  • 硬件配置：
    • CPU: 1 Core (推荐 2 Cores+)
    • 内存: 512MB (推荐 2GB+)
    • 磁盘: 足够存放容器镜像即可
  • 网络：节点间网络互通，且能访问互联网（离线安装除外）

1.1.2 检查清单

在所有节点上执行以下检查：

# 1. 检查主机名（确保每个节点唯一）
hostnamectl set-hostname <node-name>

# 2. 关闭防火墙（测试环境建议关闭，生产环境需放行 6443/tcp, 8472/udp, 10250/tcp）
systemctl stop ufw && systemctl disable ufw  # Ubuntu
systemctl stop firewalld && systemctl disable firewalld # CentOS

# 3. 检查时间同步
date
# 如果时间不准，安装 chrony 进行同步

1.2 单节点安装 (All-in-One)

最简单的安装方式，适用于开发测试。

1.2.1 官方脚本安装

curl -sfL https://get.k3s.io | sh -

1.2.2 国内加速安装（推荐）

由于网络原因，直接使用官方脚本可能会超时。我们使用国内镜像源（Rancher 官方提供）：

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

预期输出： 

[INFO]  Finding release for channel stable
[INFO]  Using v1.28.x+k3s1 as release
[INFO]  Downloading hash https://rancher-mirror.rancher.cn/k3s/v1.28.x+k3s1/sha256sum-amd64.txt
[INFO]  Downloading binary https://rancher-mirror.rancher.cn/k3s/v1.28.x+k3s1/k3s
...
[INFO]  systemd: Starting k3s

1.2.3 验证安装

# 查看节点状态
sudo kubectl get nodes

# 查看系统 Pod 状态
sudo kubectl get pods -A

1.3 多节点安装 (Master + Worker)

构建一个包含 1 个 Master 和 2 个 Worker 的集群。

1.3.1 初始化 Master 节点

在 Master 节点执行：

# 安装并获取 Token
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

# 获取 Node Token (Worker 加入集群需要)
sudo cat /var/lib/rancher/k3s/server/node-token
# 输出示例：K10abc...::server:def123...

1.3.2 加入 Worker 节点

在 Worker 节点执行（替换变量）：

export K3S_URL=https://<MASTER_IP>:6443
export K3S_TOKEN=<NODE_TOKEN>

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn K3S_URL=$K3S_URL K3S_TOKEN=$K3S_TOKEN sh -

1.4 核心配置文件

安装完成后，核心文件位于：

  1. 二进制文件：/usr/local/bin/k3s
  2. Kubeconfig：/etc/rancher/k3s/k3s.yaml (用于 kubectl 连接)
  3. Systemd 服务：
    • Server: /etc/systemd/system/k3s.service
    • Agent: /etc/systemd/system/k3s-agent.service
  4. 数据目录：/var/lib/rancher/k3s

1.5 故障排除

Q: kubectl 命令未找到？ A: K3s 自动将 kubectl 别名绑定到 k3s kubectl。如果提示未找到，请检查 /usr/local/bin 是否在 PATH 中，或手动执行： 

echo "alias kubectl='k3s kubectl'" >> ~/.bashrc
source ~/.bashrc

Q: 节点状态 NotReady？ A: 检查 Agent 日志： 

journalctl -u k3s-agent -f # Worker节点
journalctl -u k3s -f       # Master节点
常见原因：防火墙未关闭、时间不同步、Token 错误。

1.6 自动化辅助脚本

我们提供了一个交互式安装脚本 scripts/install_k3s.sh，支持自动检测 OS、选择镜像源和节点类型。

# 下载脚本
wget https://raw.githubusercontent.com/USERNAME/k3s-guide/main/scripts/install_k3s.sh
chmod +x install_k3s.sh

# 运行
./install_k3s.sh