K3s 配置参数完整手册📘 K3s 配置参数完整手册 📖 目录 K3s 简介与架构配置方式概述 Server 节点

📘 K3s 配置参数完整手册

版本: 适用于 K3s v1.27+ (2026年最新)
文档类型: 完整配置参考手册

📖 目录

K3s 简介与架构
配置方式概述
Server 节点配置参数
Agent 节点配置参数
通用配置参数
配置文件格式
环境变量对照表
常见场景配置示例
故障排查与调试

1. K3s 简介与架构

1.1 什么是 K3s？

K3s 是一个轻量级 Kubernetes 发行版，由 Rancher Labs 开发，具有以下特点：

特性	说明
二进制大小	< 100 MB
内存占用	约为标准 K8s 的一半
存储后端	默认 SQLite，支持 etcd3/MySQL/PostgreSQL
适用场景	Edge、IoT、CI/CD、开发环境、ARM 嵌入式
认证状态	CNCF 认证的 Kubernetes 发行版

1.2 架构组件

┌─────────────────────────────────────────────────────────────┐
│                    K3s Server (控制平面)                      │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │ kube-apiserver│ │ scheduler   │ │ controller- │            │
│  │             │ │             │ │ manager     │            │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │ datastore   │ │ cloud-ctrl  │ │ agent       │            │
│  │ (SQLite/etcd)│ │ manager     │ │ components│            │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ TLS Tunnel
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    K3s Agent (工作节点)                       │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │ kubelet     │ │ containerd  │ │ CNI (Flannel)│           │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
└─────────────────────────────────────────────────────────────┘

2. 配置方式概述

K3s 支持三种配置方式，优先级从高到低：

CLI 命令行参数 > 配置文件 > 环境变量

2.1 CLI 命令行参数

# Server 节点
k3s server --token mytoken --flannel-backend=none

# Agent 节点
k3s agent --server https://master:6443 --token mytoken

2.2 配置文件 (YAML)

# Server 配置文件位置
/etc/rancher/k3s/config.yaml

# Agent 配置文件位置
/etc/rancher/k3s/agent-config.yaml

2.3 环境变量

# 所有环境变量以 K3S_ 为前缀
export K3S_TOKEN="mytoken"
export K3S_KUBECONFIG_MODE="644"

3. Server 节点配置参数

3.1 集群与认证

参数	环境变量	默认值	说明
`--token value`	`$K3S_TOKEN`	自动生成	集群认证令牌，用于 Agent 加入
`--token-file value`	`$K3S_TOKEN_FILE`	-	从文件读取集群令牌
`--agent-token value`	`$K3S_AGENT_TOKEN`	同 token	仅用于 Agent 加入的令牌
`--agent-token-file value`	`$K3S_AGENT_TOKEN_FILE`	-	从文件读取 Agent 令牌
`--cluster-init`	`$K3S_CLUSTER_INIT`	false	初始化集群（用于 HA 第一个节点）
`--server value`	`$K3S_URL`	-	加入现有集群的 Server URL

3.2 网络配置

参数	环境变量	默认值	说明
`--flannel-backend value`	`$K3S_FLANNEL_BACKEND`	`vxlan`	Flannel 后端：vxlan/host-gw/wireguard/none
`--flannel-conf value`	`$K3S_FLANNEL_CONF`	`/etc/flannel-channel.yaml`	Flannel 配置文件路径
`--flannel-ipv6-masq`	`$K3S_FLANNEL_IPV6_MASQ`	false	启用 IPv6 伪装
`--cluster-cidr value`	`$K3S_CLUSTER_CIDR`	`10.42.0.0/16`	Pod 网络 CIDR
`--service-cidr value`	`$K3S_SERVICE_CIDR`	`10.43.0.0/16`	Service 网络 CIDR
`--cluster-dns value`	`$K3S_CLUSTER_DNS`	`10.43.0.10`	集群 DNS 服务 IP
`--cluster-domain value`	`$K3S_CLUSTER_DOMAIN`	`cluster.local`	集群域名
`--disable-network-policy`	`$K3S_DISABLE_NETWORK_POLICY`	false	禁用 NetworkPolicy
`--disable-flannel`	`$K3S_DISABLE_FLANNEL`	false	禁用 Flannel CNI
`--flannel-iface value`	`$K3S_FLANNEL_IFACE`	自动检测	指定 Flannel 使用的网络接口

3.3 存储配置

参数	环境变量	默认值	说明
`--datastore-endpoint value`	`$K3S_DATASTORE_ENDPOINT`	SQLite	外部存储：etcd/mysql/postgres
`--datastore-cafile value`	`$K3S_DATASTORE_CAFILE`	-	数据存储 TLS CA 证书
`--datastore-certfile value`	`$K3S_DATASTORE_CERTFILE`	-	数据存储 TLS 客户端证书
`--datastore-keyfile value`	`$K3S_DATASTORE_KEYFILE`	-	数据存储 TLS 客户端密钥
`--data-dir value`	`$K3S_DATA_DIR`	`/var/lib/rancher/k3s`	数据存储目录
`--default-local-storage-path value`	`$K3S_DEFAULT_LOCAL_STORAGE_PATH`	-	默认本地存储路径

3.4 组件控制

参数	环境变量	默认值	说明
`--disable value`	`$K3S_DISABLE`	-	禁用组件：traefik,servicelb,metrics-server,local-storage
`--disable-cloud-controller`	`$K3S_DISABLE_CLOUD_CONTROLLER`	false	禁用云控制器
`--disable-kube-proxy`	`$K3S_DISABLE_KUBE_PROXY`	false	禁用 kube-proxy
`--disable-scheduler`	`$K3S_DISABLE_SCHEDULER`	false	禁用调度器
`--disable-controller-manager`	`$K3S_DISABLE_CONTROLLER_MANAGER`	false	禁用控制器管理器
`--disable-apiserver`	`$K3S_DISABLE_APISERVER`	false	禁用 API Server

3.5 API Server 配置

参数	环境变量	默认值	说明
`--api-port value`	`$K3S_API_PORT`	`6443`	API Server 监听端口
`--bind-address value`	`$K3S_BIND_ADDRESS`	`0.0.0.0`	API Server 绑定地址
`--advertise-address value`	`$K3S_ADVERTISE_ADDRESS`	-	API Server 通告地址
`--advertise-port value`	`$K3S_ADVERTISE_PORT`	-	API Server 通告端口
`--tls-san value`	`$K3S_TLS_SAN`	-	TLS 证书额外 SAN（域名/IP）
`--kube-apiserver-arg value`	`$K3S_KUBE_APISERVER_ARG`	-	传递参数给 kube-apiserver
`--kube-controller-manager-arg value`	`$K3S_KUBE_CONTROLLER_MANAGER_ARG`	-	传递参数给 controller-manager
`--kube-scheduler-arg value`	`$K3S_KUBE_SCHEDULER_ARG`	-	传递参数给 scheduler

3.6 证书配置

参数	环境变量	默认值	说明
`--cert-dir value`	`$K3S_CERT_DIR`	`/var/lib/rancher/k3s/server/tls`	证书存储目录
`--service-node-port-range value`	`$K3S_SERVICE_NODE_PORT_RANGE`	`30000-32767`	NodePort 端口范围

4. Agent 节点配置参数

4.1 连接配置

参数	环境变量	默认值	说明
`--server value`	`$K3S_URL`	-	K3s Server URL（必须）
`--token value`	`$K3S_TOKEN`	-	集群认证令牌（必须）
`--token-file value`	`$K3S_TOKEN_FILE`	-	从文件读取令牌

4.2 节点配置

参数	环境变量	默认值	说明
`--node-name value`	`$K3S_NODE_NAME`	主机名	节点名称
`--with-node-id`	`$K3S_WITH_NODE_ID`	false	在节点名后添加随机 ID
`--node-label value`	`$K3S_NODE_LABEL`	-	节点标签（可多次使用）
`--node-taint value`	`$K3S_NODE_TAINT`	-	节点污点（可多次使用）
`--node-ip value`	`$K3S_NODE_IP`	自动检测	节点 IP 地址
`--node-external-ip value`	`$K3S_NODE_EXTERNAL_IP`	-	节点外部 IP 地址

4.3 容器运行时配置

参数	环境变量	默认值	说明
`--docker`	`$K3S_DOCKER`	false	使用 Docker 作为运行时
`--container-runtime-endpoint value`	`$K3S_CONTAINER_RUNTIME_ENDPOINT`	-	容器运行时端点
`--pause-image value`	`$K3S_PAUSE_IMAGE`	`rancher/mirrored-pause`	Pause 容器镜像
`--snapshotter value`	`$K3S_SNAPSHOTTER`	`overlayfs`	容器快照驱动

4.4 Kubelet 配置

参数	环境变量	默认值	说明
`--kubelet-arg value`	`$K3S_KUBELET_ARG`	-	传递参数给 kubelet
`--resolv-conf value`	`$K3S_RESOLV_CONF`	`/etc/resolv.conf`	resolv.conf 文件路径
`--rootless`	`$K3S_ROOTLESS`	false	以 rootless 模式运行
`--protect-kernel-defaults`	`$K3S_PROTECT_KERNEL_DEFAULTS`	false	保护内核默认参数

4.5 镜像配置

参数	环境变量	默认值	说明
`--private-registry value`	`$K3S_PRIVATE_REGISTRY`	`/etc/rancher/k3s/registries.yaml`	私有镜像仓库配置
`--image-credential-provider-config value`	`$K3S_IMAGE_CREDENTIAL_PROVIDER_CONFIG`	-	镜像凭证提供者配置
`--image-credential-provider-bin-dir value`	`$K3S_IMAGE_CREDENTIAL_PROVIDER_BIN_DIR`	-	镜像凭证提供者二进制目录

5. 通用配置参数

5.1 日志配置

参数	环境变量	默认值	说明
`--v value`	`$K3S_V`	`0`	日志详细程度（0-9）
`--vmodule value`	`$K3S_VMODULE`	-	文件过滤日志
`--log value, -l value`	`$K3S_LOG`	-	日志文件路径

5.2 系统配置

参数	环境变量	默认值	说明
`--data-dir value`	`$K3S_DATA_DIR`	`/var/lib/rancher/k3s`	数据目录
`--config value, -c value`	`$K3S_CONFIG`	-	配置文件路径
`--write-kubeconfig value`	`$K3S_WRITE_KUBECONFIG`	`/etc/rancher/k3s/k3s.yaml`	kubeconfig 写入路径
`--write-kubeconfig-mode value`	`$K3S_KUBECONFIG_MODE`	`600`	kubeconfig 文件权限
`--selinux`	`$K3S_SELINUX`	false	启用 SELinux
`--lb-server-port value`	`$K3S_LB_SERVER_PORT`	`6444`	负载均衡器端口

5.3 代理配置

参数	环境变量	默认值	说明
`--http-proxy value`	`$K3S_HTTP_PROXY`	-	HTTP 代理地址
`--https-proxy value`	`$K3S_HTTPS_PROXY`	-	HTTPS 代理地址
`--no-proxy value`	`$K3S_NO_PROXY`	-	不使用代理的地址列表

6. 配置文件格式

6.1 Server 配置示例 (`/etc/rancher/k3s/config.yaml`)

# 集群认证
token: "my-secret-token"
agent-token: "my-agent-token"

# 网络配置
flannel-backend: "vxlan"
cluster-cidr: "10.42.0.0/16"
service-cidr: "10.43.0.0/16"
cluster-dns: "10.43.0.10"
cluster-domain: "cluster.local"

# 存储配置
datastore-endpoint: "mysql://user:pass@tcp(192.168.1.100:3306)/k3s"
datastore-cafile: "/etc/ssl/mysql-ca.crt"
datastore-certfile: "/etc/ssl/mysql-client.crt"
datastore-keyfile: "/etc/ssl/mysql-client.key"

# 禁用组件
disable:
  - traefik
  - servicelb
  - metrics-server

# API Server 配置
api-port: 6443
bind-address: "0.0.0.0"
advertise-address: "192.168.1.100"
tls-san:
  - "k3s.example.com"
  - "192.168.1.100"

# 组件参数
kube-apiserver-arg:
  - "feature-gates=RemoveSelfLink=false"
  - "audit-log-path=/var/log/k3s/audit.log"
kube-controller-manager-arg:
  - "node-cidr-mask-size=24"
kube-scheduler-arg:
  - "profiling=true"

# 其他
data-dir: "/var/lib/rancher/k3s"
write-kubeconfig-mode: "0644"

6.2 Agent 配置示例 (`/etc/rancher/k3s/agent-config.yaml`)

# 连接配置
server: "https://192.168.1.100:6443"
token: "my-secret-token"

# 节点配置
node-name: "worker-01"
node-label:
  - "node-type=worker"
  - "zone=us-west-1"
node-taint:
  - "dedicated=special:NoSchedule"
node-ip: "192.168.1.101"
node-external-ip: "203.0.113.10"

# 容器运行时
docker: false
container-runtime-endpoint: ""
pause-image: "rancher/mirrored-pause:3.6"

# Kubelet 配置
kubelet-arg:
  - "max-pods=110"
  - "pod-max-pids=100"
resolv-conf: "/etc/resolv.conf"

# 镜像配置
private-registry: "/etc/rancher/k3s/registries.yaml"

# 其他
data-dir: "/var/lib/rancher/k3s"

6.3 私有镜像仓库配置 (`/etc/rancher/k3s/registries.yaml`)

mirrors:
  docker.io:
    endpoint:
      - "https://registry-mirror.example.com"
  gcr.io:
    endpoint:
      - "https://gcr-mirror.example.com"
  quay.io:
    endpoint:
      - "https://quay-mirror.example.com"

configs:
  "registry.example.com":
    auth:
      username: "myuser"
      password: "mypass"
    tls:
      ca_file: "/etc/ssl/registry-ca.crt"
      cert_file: "/etc/ssl/registry-client.crt"
      key_file: "/etc/ssl/registry-client.key"
      insecure_skip_verify: false

7. 环境变量对照表

参数	环境变量	示例值
`--token`	`K3S_TOKEN`	`K3S_TOKEN="mytoken"`
`--server`	`K3S_URL`	`K3S_URL="https://master:6443"`
`--data-dir`	`K3S_DATA_DIR`	`K3S_DATA_DIR="/opt/k3s"`
`--flannel-backend`	`K3S_FLANNEL_BACKEND`	`K3S_FLANNEL_BACKEND="host-gw"`
`--cluster-cidr`	`K3S_CLUSTER_CIDR`	`K3S_CLUSTER_CIDR="10.100.0.0/16"`
`--service-cidr`	`K3S_SERVICE_CIDR`	`K3S_SERVICE_CIDR="10.101.0.0/16"`
`--disable`	`K3S_DISABLE`	`K3S_DISABLE="traefik,servicelb"`
`--node-label`	`K3S_NODE_LABEL`	`K3S_NODE_LABEL="app=web"`
`--kubelet-arg`	`K3S_KUBELET_ARG`	`K3S_KUBELET_ARG="max-pods=50"`
`--write-kubeconfig-mode`	`K3S_KUBECONFIG_MODE`	`K3S_KUBECONFIG_MODE="644"`

8. 常见场景配置示例

8.1 单节点开发环境

# 快速启动（默认配置）
curl -sfL https://get.k3s.io | sh -

# 或手动启动
k3s server --cluster-init

8.2 高可用集群（3 Server + 外部数据库）

# Server 1 (第一个节点)
k3s server \
  --cluster-init \
  --datastore-endpoint "mysql://user:pass@tcp(db:3306)/k3s" \
  --token "my-secret-token"

# Server 2 & 3
k3s server \
  --server "https://server1:6443" \
  --datastore-endpoint "mysql://user:pass@tcp(db:3306)/k3s" \
  --token "my-secret-token"

# Agent 节点
k3s agent \
  --server "https://server1:6443" \
  --token "my-secret-token"

8.3 边缘设备（资源受限）

k3s server \
  --disable traefik,servicelb,metrics-server \
  --flannel-backend=none \
  --disable-network-policy \
  --kubelet-arg "eviction-hard=memory.available<256Mi" \
  --kubelet-arg "max-pods=20"

8.4 使用 Docker 作为运行时

# 安装 Docker 后
k3s server --docker --disable traefik

# Agent 节点
k3s agent --docker --server https://master:6443 --token mytoken

8.5 内网/离线环境

# 下载镜像并保存
docker pull rancher/k3s:v1.27.4-k3s1
docker save -o k3s-airgap-images.tar rancher/k3s:v1.27.4-k3s1

# 离线安装
INSTALL_K3S_SKIP_DOWNLOAD=true \
INSTALL_K3S_SKIP_ENABLE=true \
./k3s-install.sh

# 将镜像放入 airgap 目录
mkdir -p /var/lib/rancher/k3s/agent/images/
cp k3s-airgap-images.tar /var/lib/rancher/k3s/agent/images/

8.6 自定义网络接口

# 指定 Flannel 使用的网络接口
k3s server \
  --flannel-iface eth1 \
  --node-ip 192.168.1.100 \
  --node-external-ip 203.0.113.10

8.7 启用审计日志

k3s server \
  --kube-apiserver-arg "audit-log-path=/var/log/k3s/audit.log" \
  --kube-apiserver-arg "audit-log-maxage=30" \
  --kube-apiserver-arg "audit-log-maxbackup=10" \
  --kube-apiserver-arg "audit-log-maxsize=100"

9. 故障排查与调试

9.1 查看日志

# Systemd 服务日志
journalctl -u k3s -f
journalctl -u k3s-agent -f

# 增加日志详细程度
k3s server --v 4
k3s agent --v 5

9.2 常用诊断命令

# 检查节点状态
kubectl get nodes -o wide

# 检查 Pod 状态
kubectl get pods -A

# 检查网络连通性
kubectl run test --rm -it --image=busybox -- ping -c 3 kubernetes.default

# 检查 DNS
kubectl run test --rm -it --image=busybox -- nslookup kubernetes.default

# 查看证书信息
k3s certificate check

# 旋转证书
k3s certificate rotate
k3s certificate rotate-ca

9.3 常见问题

问题	可能原因	解决方案
Agent 无法加入	Token 错误/网络不通	检查 token 和防火墙
Pod 无法启动	镜像拉取失败	配置镜像加速器/私有仓库
网络不通	CNI 配置问题	检查 flannel-backend 配置
证书过期	证书有效期到	运行 `k3s certificate rotate`
存储不足	本地磁盘满	清理 `/var/lib/rancher/k3s`

9.4 卸载 K3s

# 使用官方卸载脚本
/usr/local/bin/k3s-uninstall.sh

# Agent 节点卸载
/usr/local/bin/k3s-agent-uninstall.sh

# 手动清理
systemctl stop k3s
rm -rf /var/lib/rancher/k3s
rm -rf /etc/rancher/k3s
rm -rf /usr/local/bin/k3s

📎 附录：端口参考

端口	协议	服务	说明
6443	TCP	API Server	Kubernetes API
6444	TCP	Load Balancer	内部负载均衡
10250	TCP	Kubelet	节点管理
10256	TCP	Kube-Proxy	服务代理
8472	UDP	Flannel	VxLAN 网络
4789	UDP	Flannel	VxLAN 数据
30000-32767	TCP/UDP	NodePort	服务暴露

提示: 本手册基于 K3s 官方文档整理，具体参数可能随版本更新有所变化。建议定期查阅官方文档获取最新信息。

K3s 配置参数完整手册

📘 K3s 配置参数完整手册

📖 目录

1. K3s 简介与架构

1.1 什么是 K3s？

1.2 架构组件

2. 配置方式概述

2.1 CLI 命令行参数

2.2 配置文件 (YAML)

2.3 环境变量

3. Server 节点配置参数

3.1 集群与认证

3.2 网络配置

3.3 存储配置

3.4 组件控制

3.5 API Server 配置

3.6 证书配置

4. Agent 节点配置参数

4.1 连接配置

4.2 节点配置

4.3 容器运行时配置

4.4 Kubelet 配置

4.5 镜像配置

5. 通用配置参数

5.1 日志配置

5.2 系统配置

5.3 代理配置

6. 配置文件格式

6.1 Server 配置示例 (/etc/rancher/k3s/config.yaml)

6.2 Agent 配置示例 (/etc/rancher/k3s/agent-config.yaml)

6.3 私有镜像仓库配置 (/etc/rancher/k3s/registries.yaml)

7. 环境变量对照表

8. 常见场景配置示例

8.1 单节点开发环境

8.2 高可用集群（3 Server + 外部数据库）

8.3 边缘设备（资源受限）

8.4 使用 Docker 作为运行时

8.5 内网/离线环境

8.6 自定义网络接口

8.7 启用审计日志

9. 故障排查与调试

9.1 查看日志

9.2 常用诊断命令

9.3 常见问题

9.4 卸载 K3s

📎 附录：端口参考

6.1 Server 配置示例 (`/etc/rancher/k3s/config.yaml`)

6.2 Agent 配置示例 (`/etc/rancher/k3s/agent-config.yaml`)

6.3 私有镜像仓库配置 (`/etc/rancher/k3s/registries.yaml`)