核心概念与架构
理解K3s的架构和核心概念，是正确部署和运维的基础。
核心特性：K3s是一个轻量级的Kubernetes发行版（由Rancher/SUSE推出），它将所有Kubernetes控制平面组件封装在一个不足100MB的单一二进制文件中，极大简化了部署和运维。
K3s如何实现轻量化？
移除：删减了大量K8s原生的in-tree代码（如云厂商驱动、存储插件），这些都可以通过out-of-tree的CSI/CCI插件按需安装。
替换：使用containerd替换了Kubelet中对Docker的依赖；使用Flannel作为默认CNI；使用CoreDNS等。
打包：将API Server, Controller Manager, Scheduler, Kubelet等组件编译打包进一个进程（k3s server）中运行，极大降低了管理开销。
节点类型：
Server节点：运行 k3s server 命令的主机，负责管理控制平面和数据存储组件。
Agent节点：运行 k3s agent 命令的主机，主要负责运行工作负载（Kubelet, Containerd），不具备控制平面组件。
数据存储模式：
单节点模式：默认使用嵌入式SQLite数据库，非常简单，适用于开发或测试。
高可用模式：推荐使用外部数据库（如MySQL、PostgreSQL）或多个Server节点使用嵌入式etcd数据存储。
安装与部署
K3s的安装非常灵活，你可以根据网络环境和集群规模选择合适的方式。
- 快速在线安装
这是最常见的方式，使用官方提供的安装脚本。
安装Server节点：在目标机器上执行 curl -sfL https://get.k3s.io | sh - 。
国内用户，可以使用加速镜像：curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh - 。
加入Agent节点：在其他机器上，使用从Server节点获取的Token（位于 /var/lib/rancher/k3s/server/node-token）执行：curl -sfL https://get.k3s.io | K3S_URL=https://:6443 K3S_TOKEN= sh - 。
- 离线环境安装
对于无法直接连接互联网的环境（这在信息安全和物理隔离项目中很常见），你需要提前准备。
从K3s GitHub Release页面获取对应版本的镜像tar文件（k3s-airgap-images-$ARCH.tar.gz）和K3s二进制文件。
将镜像文件放置在 /var/lib/rancher/k3s/agent/images/ 目录下。
将K3s二进制文件放在 /usr/local/bin 并确保拥有可执行权限。
使用 INSTALL_K3S_SKIP_DOWNLOAD=true 参数运行安装脚本：INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh 。
- 搭建高可用（HA）集群
生产环境强烈建议高可用配置。K3s提供两种主流HA方案：
方案一：使用外部数据库（推荐）
这是最简单可靠的HA方式，所有Server节点共享同一个外部数据库状态。
创建外部数据库：首先准备一个外部的MySQL、PostgreSQL或etcd数据库。
启动Server节点：在所有Server节点上运行安装命令，并指定数据存储端点。例如，使用MySQL时：
curl -sfL https://get.k3s.io | sh -s - server \
--token=SECRET_TOKEN \
--datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"
配置固定注册地址（重要）：为了让Agent节点和后续Server节点总能找到集群，建议在Server节点（端口6443）前配置一个负载均衡器或固定DNS作为统一入口，并通过 --tls-san 参数将该地址添加到TLS证书中。
方案二：使用嵌入式Etcd（原生HA）
此方案不依赖外部数据库，K3s会自己维护一个etcd集群。
启动第一个Server节点：使用 --cluster-init 参数初始化集群：
curl -sfL https://get.k3s.io | sh -s - server \
--cluster-init \
--token=SECRET_TOKEN
加入其他Server节点：在其他Server节点上（推荐至少3个Server节点），使用 --server 参数加入集群：
curl -sfL https://get.k3s.io | sh -s - server \
--server https://:6443 \
--token=SECRET_TOKEN
Agent节点加入：Agent节点可以指向任意一个Server节点或配置好的LB地址。
- 集群升级与版本管理（重要）
K3s的升级相对简单，但生产环境务必谨慎。
手动升级：最直接的方式是重新运行安装脚本。脚本会检测到已安装的K3s并进行升级。
升级到最新稳定版
curl -sfL https://get.k3s.io | sh -
升级到指定版本
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.28.4+k3s1 sh -
自动升级（推荐）：K3s社区提供了 System Upgrade Controller。你可以通过CRD（自定义资源）来定义升级计划（Plan），控制器会自动协调各个节点的升级过程，实现滚动更新。
- 重要的安装参数
在执行安装脚本时，可以通过环境变量或CLI参数精细控制K3s的行为：
--docker：如指南所述，使K3s使用Docker（如果已安装）而不是默认的containerd。
--flannel-backend=none：禁用默认的Flannel CNI。
--disable-network-policy：禁用网络策略控制器（如果CNI不支持）。
--disable=traefik：禁用默认安装的Traefik Ingress。
--node-taint：如指南所述，给节点添加污点。
--tls-san：为API Server的TLS证书添加额外的主机名或IP，在高可用或外部访问时必须设置。
组件与工具
K3s开箱即用，并内置了大量实用工具。
内置组件：K3s默认集成了Traefik（Ingress控制器）、CoreDNS（服务发现）、Local Path Provisioner（动态存储分配）等核心组件，覆盖了大部分基础需求。
容器运行时：K3s默认使用containerd作为容器运行时。
内置CLI工具：K3s二进制文件内置了丰富的命令行工具：
k3s kubectl: 用于与集群交互。
k3s crictl: 用于调试容器运行时（CRI）问题。
k3s etcd-snapshot: 用于对etcd数据进行按需备份（仅限使用嵌入式etcd时）。
k3s certificate: 用于管理K3s证书。
k3s token: 用于管理和创建加入集群的Token。
网络（CNI）详解
网络是K3s（及所有K8s）的核心。
默认Flannel：K3s默认使用Flannel (VXLAN模式)，它简单、稳定，能满足基本的Pod间通信，但不（默认）支持Kubernetes的NetworkPolicy（网络策略）。
替换CNI：在生产环境或需要网络隔离时，你可能需要替换为Calico或Cilium。
方法：在安装K3s Server时，使用 --flannel-backend=none 和 --disable-network-policy 参数禁用默认配置。
安装Calico/Cilium：K3s安装完成后，手动kubectl apply -f Calico或Cilium的YAML清单文件。
注意：Calico等CNI需要集群CIDR（--cluster-cidr），确保与K3s的配置一致。
存储（CSI）详解
存储是有状态应用的关键。
Local Path Provisioner (默认)：
工作方式：它会在节点本地文件系统（HostPath）上创建PersistentVolume。
局限性（非常重要）：它提供的不是网络存储。如果一个Pod被重新调度到另一个节点，它将无法访问之前的数据，导致数据丢失。
适用场景：仅适用于开发、测试，或那些数据无需持久化的应用。
生产级存储方案：
Longhorn：Rancher官方推荐的、开源的、云原生分布式块存储解决方案。它易于部署（一个Helm搞定），提供数据复制、快照、备份等功能，非常适合K3s。
Rook-Ceph：功能强大的Ceph集群的K8s Operator，提供块、文件和对象存储，但相对复杂。
NFS/CIFS：如果已有NFS/CIFS服务器，可以使用nfs-subdir-external-provisioner等插件。
云厂商CSI：如果K3s部署在公有云上，应安装对应云厂商的CSI驱动以使用云硬盘。
进阶配置
Kubeconfig的访问与配置：
位置：K3s Server安装后，会在 /etc/rancher/k3s/k3s.yaml 生成kubeconfig文件。
权限：该文件默认只对root可读。你需要sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config并sudo chown $(id -u):$(id -g) ~/.kube/config，才能让普通用户使用kubectl。
远程访问：该文件中的server地址默认是127.0.0.1。如果你想从外部机器访问API Server，需要将其IP改为Server节点的内网或公网IP。
配置HTTP代理：如果服务器需要通过代理访问外网，可以编辑K3s的systemd环境文件（如 /etc/systemd/system/k3s.service.env），设置 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 等环境变量。
证书管理：K3s客户端和服务器证书有效期为365天，在过期前90天内会自动更新。你可以使用 k3s certificate 命令系列手动轮换。
节点注册与污点：确保集群中所有节点的主机名是唯一的。如果希望Server节点只运行控制平面，使用 --node-taint 参数为其添加污点。
生产环境建议
将K3s用于生产环境时，请特别关注以下几点：
启用高可用：必须使用外部数据库或嵌入式etcd HA架构。
安全加固：
定期轮换证书和Token。
使用 k3s secrets-encrypt 命令启用静态Secret数据加密。
网络策略：如需隔离命名空间或Pod，请替换为支持NetworkPolicy的CNI（如Calico）。
CIS基准：K3s提供了加固脚本（k3s-cis-config）并支持--profile=cis-1.23（取决于版本）参数来自动应用CIS安全基准，强烈推荐使用。
数据备份与恢复：
对于使用嵌入式etcd的集群，定期备份至关重要。使用 k3s etcd-snapshot 命令创建快照，并配置--etcd-snapshot-schedule（定时备份）和--etcd-snapshot-retention（保留策略）。
对于使用外部数据库的集群，请使用数据库自身的备份工具（如mysqldump）进行备份。
生态与周边工具
K3s拥有一个活跃且实用的生态系统。
K3d：一个非常棒的工具，用于在Docker中快速运行本地K3s集群。非常适合本地开发和CI/CD流水线。
K3sup (ketchup)：由Alex Ellis开发的轻量级CLI，可以通过SSH在任何远程主机（包括树莓派）上快速部署K3s集群，极大简化了多节点部署。
Rancher集成：K3s可以无缝地被Rancher（多集群管理平台）导入和管理。K3s也可以作为Rancher Server自身的运行底座。
Helm Controller：K3s内置了Helm Controller，允许你通过HelmChart CRD以声明式（GitOps）的方式管理应用部署，而无需在客户端安装Helm CLI。
故障排查
遇到问题时，可以按照以下思路排查：
检查节点与Pod状态：kubectl get nodes 和 kubectl get pods -A -o wide。
查看日志（K3s服务）：使用journalctl -u k3s（Server）或journalctl -u k3s-agent（Agent）查看K3s服务的启动和运行日志。
查看日志（Pod）：使用 kubectl logs -n 查看具体Pod的日志。
查看日志（容器运行时）：sudo k3s crictl logs 。
检查网络：确认Flannel等网络插件正常工作，Pod间网络是否通畅。
重置节点：如果节点状态异常，可以尝试使用 /usr/local/bin/k3s-agent-uninstall.sh（Agent节点）或 /usr/local/bin/k3s-uninstall.sh（Server节点）脚本彻底卸载后重新加入。
