k3s轻量级Kubernetes实战：低配Ubuntu服务器部署微服务全指南

最近被问得最多的问题，不是“Kubernetes 怎么学”，而是“我就一台 2G 内存的 Ubuntu 服务器，能装 K8s 跑微服务吗”。直接上标准 K8s 集群当然费劲，但换用 k3s 这种轻量级 Kubernetes 发行版，完全可以在低配机器上把一套可用的集群跑起来，还能按照生产习惯部署微服务。这篇文章就是我基于实际使用过程整理的一套操作记录，从 why 到 how 都有，环境是 Ubuntu 20.04，用 k3s 做集群底座，再部署几个微服务，同时把我在配置、排错过程中踩过的坑和最终沉淀下来的最佳实践一起写出来。适合刚入门 K8s、想在自己服务器上搭一套真实环境的人，也适合有一定容器基础、想省资源但不想牺牲 K8s 核心功能的人。

1. 为什么选 k3s：轻量集群的选型思考

先说结论：k3s 不是玩具，它是把 Kubernetes 控制平面和运行时做进一个单文件的发行版，由 Rancher 团队维护，很多边缘项目直接拿它做生产底座。我最早接触 k3s 是因为手上一批北京的服务器都是 2C4G，跑完整 K8s 集群加一个 etcd 就已经喘不过气，换 k3s 之后资源占用立刻降了一个量级。

1.1 k3s 与标准 K8s 的差异在哪儿

标准 Kubernetes 的控制平面组件是独立进程，包括 kube-apiserver、kube-controller-manager、kube-scheduler 和 etcd。k3s 把这些组件合并成一个二进制文件，默认数据存储从 etcd 换成了 SQLite，并且把运行时自带为 containerd。这意味着安装极其简单，一条 curl 命令就能装完 master。

k3s 还内置了 ServiceLB（Klipper）、Traefik Ingress、CoreDNS、local-path provider 等组件，开箱即用。当然，它裁掉了一些东西，比如部分云厂商的控制器插件、老的 API 版本，但对绝大多数微服务场景影响很小。如果单节点部署，k3s 内存占用可以压到 500MB 左右；标准 K8s 单控制平面至少 1.5G 以上，这差距在低配服务器上非常明显。

从兼容性来看，k3s 是通过了 CNCF 一致性认证的 K8s 发行版，你写出来的 Deployment、Service、Ingress 清单可以无缝迁移到标准 K8s，这让它特别适合作为学习和预发环境。我自己的经验是：本地用 k3s 模拟，上了云再无缝迁移到托管集群，实践和成本的平衡点就在这里。

1.2 什么样的业务适合用 k3s

任何中小规模的微服务架构都适合，尤其是节点数在 20 台以内的集群。比如我现在维护的一个业务系统，里面拆了网关、用户、订单、消息四个服务，总共十几个 Pod，在 k3s 上跑得非常稳定。

如果你只有一个 master 节点，那 k3s 也能提供完整 K8s API，但 master 本身不能出问题。按生产要求，至少三节点：一个控制节点、两个工作节点，并建议用外部数据库或内置 etcd 做数据存储。k3s 在单节点模式默认用 SQLite，简单省事；多节点后可以用--datastore-endpoint挂 etcd 集群，或者用一个独立 MySQL/PostgreSQL 做数据存储。这样既保证轻量，又保留高可用能力。

再说一下不适合场景：如果你要做复杂多租户、超大规模集群、深度定制 K8s 内部调度逻辑，那标准 K8s 更合适。k3s 的定位是“够用且轻”，不要期待它能承受几千节点。很多项目把 k3s 当边缘网关用，也是看中它的轻量和部署速度。

1.3 环境规划与资源配置建议

我建议按下面的规格起步：

磁盘必须用 SSD，机械盘跑 etcd 或 SQLite 会直接拖垮 API 响应。安装前关闭 swap，不是强制的，但能避免很多内存换页导致的卡顿。如果开了防火墙，需要放通 6443、8472、10250 端口。默认 k3s 的 Flannel 使用 VXLAN 845 端口，可配置为 UDP 8472，另外还有 kubelet 的 10250，访问节点的其他端口也按需开。

我踩过一个坑：服务器有多个网卡，k3s 默认选第一块内网 IP，如果你的 master 和 worker 在不同网段，直接用默认配置会导致节点失联。最好明确指定私有 IP，比如安装时设置--advertise-address和--node-ip。这是很多新手第一次 k3s 装完发现NotReady的最大原因。

2. 在 Ubuntu 20.04 上安装 k3s 集群

安装过程比我第一次装 K8s 时简单太多。Ubuntu 20.04 自带的软件源比较稳定，前提是你对服务器有 root 权限，或者 sudo 可用。下面是我实际操作时完整走了一遍的流程。

2.1 安装前的环境准备

先更新系统，保证基础依赖可用：

sudo apt update && sudo apt upgrade -y sudo apt install -y curl vim git sudo swapoff -a

如果swap在 fstab 里存在，建议直接注释掉，或者让 k3s 自动忽略。关闭 swap 后确认一下：

free -h

然后确认主机名和 hosts 解析。我习惯把集群节点的主机名设置得有辨识度，比如k3s-master、k3s-worker1，并让它们通过局域网互相 ping 通。如果只有 IP 没有 DNS，可以在安装时用 IP 连接，问题不大。

在 Ubuntu 20.04 上，另一个容易忽略的点是ufw。默认 Ubuntu 可能没启 ufw，但如果你启用了，最好先关掉或者配置放通规则。k3s 官方脚本会自动打开部分端口，但和 ufw 的集成并不完美，直接sudo ufw disable最省心。如果是生产环境，一定不要盲目关防火墙，只放通需要的端口。

2.2 安装 Master 节点并初始化

官方安装脚本只管一条命令。我需要以普通用户后续运行 kubectl，所以加了--write-kubeconfig-mode 644，让 kubeconfig 文件允许普通用户读取，否则每次都要 sudo，烦到怀疑人生：

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --write-kubeconfig-mode 644 --node-name k3s-master" sh -

执行完观察输出，出现k3s.service started就基本成功了。检查一下服务：

sudo systemctl status k3s kubectl get nodes

我安装后的输出类似下面，状态是Ready：

NAME STATUS ROLES AGE VERSION k3s-master Ready control-plane,master 3m v1.28.5+k3s1

如果你想让 k3s 在安装时绑定到指定 IP，可以在INSTALL_K3S_EXEC里加--advertise-address 192.168.1.10 --node-ip 192.168.1.10，避免多网卡误选。另外，k3s 默认会把kubectl软链到/usr/local/bin/kubectl，安装脚本已经处理好了，不需要额外装 kubectl。

2.3 添加 Worker 节点

在 master 上拿到 token：

sudo cat /var/lib/rancher/k3s/server/node-token

然后去 worker 节点执行：

curl -sfL https://get.k3s.io | K3S_URL=https://<master-ip>:6443 K3S_TOKEN=<token> INSTALL_K3S_EXEC="agent --node-name k3s-worker1" sh -

注意K3S_TOKEN拷贝较长的 token 时容易漏字符，粘贴后最好先echo $K3S_TOKEN核对一下。worker 安装完成后，在 master 上执行：

kubectl get nodes -o wide

如果看到两个节点都Ready，说明集群已经通了。我经常遇到 worker 报NotReady，大部分原因是 token 不完整或者防火墙没放通 8472 端口。这种情况下先看 master 的 k3s 日志：

sudo journalctl -u k3s -f

如果日志里大量出现failed to connect to ...这类内容，基本就是网络层问题，回到防火墙和route上排查。

2.4 验证集群状态并跑一个测试服务

安装完集群，先确认所有系统 Pod 是否正常：

kubectl get pods -A

正常情况下会有 coredns、traefik、local-path-provisioner、metrics-server 等 Pod 处于Running。我用一个 nginx 快速验证集群调度和容器网络是否正常：

kubectl create deployment nginx-test --image=nginx kubectl expose deployment nginx-test --port=80 --target-port=80 --type=NodePort

看到 Pod 启动后，通过kubectl get svc查看 NodePort 端口，再用浏览器或 curl 访问任意节点 IP 加端口，能打开 nginx 默认页就说明集群链路 OK。验证完成后删掉测试资源：

kubectl delete deployment nginx-test kubectl delete svc nginx-test

3. 微服务部署前的架构准备

集群搭好了，重点就变成怎么把微服务高效益地跑上去。很多人把 K8s 当虚拟机用，直接往里塞一堆容器，结果服务发现、配置管理、故障恢复全都没有，这等于没吃到集群红利。下面这几个步骤是我反复总结后的“必要前置动作”。

3.1 微服务拆分与部署策略

微服务拆分不能只看业务，还得看运维成本。我见过有人把一个用户模块拆成 8 个微服务，每个服务只有两三个接口，结果服务发现和 tracing 的成本比业务本身还高。拆分的原则应该是：独立部署、独立扩展、独立故障。参考成熟的开源脚手架，比如若依微服务 plus 这种典型项目，常见的划分就是网关、认证、系统管理、文件服务、定时任务等，每个服务可以单独启动，数据库和缓存通过中间件隔离。

服务拆分完成后的部署策略同样重要。无状态业务用Deployment，有状态组件（数据库、Redis、MinIO）用StatefulSet。服务之间通过 Service 名称通信，不要直连 Pod IP。滚动更新和回滚是 K8s 自带的优势，必须配合资源配置限制和探针才能安心使用。上线新版本时要保证至少有 2 个副本，否则滚动更新过程中流量会断。

部署每个微服务时，我建议遵循“一服务一 Deployment + 一 Service + 一 ConfigMap + 一 Secret（如果需要）”，这样职责清晰。如果服务数量变多，再去用 Helm 或 Kustomize 做模板化，否则 YAML 文件就会爆炸。

3.2 命名空间与资源配额

命名空间是逻辑隔离的第一道屏障。我把环境拆成 dev、prod 两个，dev 的权限小、资源限额低，prod 的资源配额更高，并且部署了更严格的探针。创建命名空间：

kubectl create ns dev kubectl create ns prod

光创建命名空间还不够，必须加上资源限制。下面的 YAML 给dev命名空间设置了一个 Pod 最大内存 1G、最大 CPU 1 核，并且每个容器默认请求 128Mi 内存：

apiVersion: v1 kind: ResourceQuota metadata: name: dev-quota namespace: dev spec: hard: requests.cpu: "4" requests.memory: 4Gi limits.cpu: "8" limits.memory: 8Gi pods: "20" --- apiVersion: v1 kind: LimitRange metadata: name: dev-limits namespace: dev spec: limits: - type: Container defaultRequest: cpu: 100m memory: 128Mi default: cpu: 500m memory: 512Mi

这样做的好处是：某个微服务因为内存溢写疯狂重启时，不会把整个节点打挂。我遇到过服务因为对象未释放把内存顶到 4G，如果没有配额，节点直接 OOM，同节点上的其他微服务全部遭殃；有了限额，最多就是那个 Pod 被杀掉重启。

3.3 镜像仓库与私有化

微服务发布必然涉及镜像管理。默认情况下 k3s 的 containerd 可以从 Docker Hub 拉镜像，但生产环境最好不要从公网拉，一方面网络不可控，另一方面镜像安全性无法保证。建议搭一套 Harbor 或者用云厂商的镜像仓库。

k3s 的 containerd 配置和 Docker 不同，它默认读取/var/lib/rancher/k3s/agent/etc/containerd/config.toml。需要配置私有仓库时，在/etc/rancher/k3s/registries.yaml里写：

mirrors: docker.io: endpoint: - "https://registry-1.docker.io" myregistry.example.com: endpoint: - "https://myregistry.example.com" configs: myregistry.example.com: auth: username: admin password: password

修改后重启 k3s：

sudo systemctl restart k3s

注意这个文件只在安装时或重启时生效。配置私有仓库时，镜像 URL 要写完整，比如myregistry.example.com/backend/user-service:v1.0.0，否则 containerd 会默认去 Docker Hub 拉，拉不到一脸迷茫。把镜像仓库打通后，微服务 CI/CD 流水线推送镜像，集群滚动更新，整个部署链路就顺了。

4. 核心环节：在 k3s 上部署微服务

这一节是实操重点。我会用一个简单的用户服务作为示例，展示在 k3s 上部署微服务的完整 YAML 和思路。实际项目中你只需要把镜像地址、端口、环境变量换成自己的。

4.1 用 Deployment 部署无状态微服务

无状态微服务是 K8s 里最常见的工作负载。下面的 YAML 是一个用户微服务的 Deployment，包含副本数、资源限制、探针、更新策略：

apiVersion: apps/v1 kind: Deployment metadata: name: user-service namespace: prod labels: app: user-service spec: replicas: 2 selector: matchLabels: app: user-service strategy: type: RollingUpdate rollingUpdate: maxSurge: 1 maxUnavailable: 0 template: metadata: labels: app: user-service spec: containers: - name: user-service image: myregistry.example.com/backend/user-service:v1.2.0 imagePullPolicy: IfNotPresent ports: - containerPort: 8080 env: - name: SPRING_PROFILES_ACTIVE value: "prod" resources: requests: cpu: 200m memory: 256Mi limits: cpu: 500m memory: 512Mi readinessProbe: httpGet: path: /actuator/health/readiness port: 8080 initialDelaySeconds: 20 periodSeconds: 10 livenessProbe: httpGet: path: /actuator/health/liveness port: 8080 initialDelaySeconds: 60 periodSeconds: 15

关键参数逐个说：

• replicas: 2：保证任意一个 Pod 挂掉还有另一个抗流量。如果你的实例数为 1，滚动更新时会先停旧再启新，存在短暂不可用。
• strategy：maxSurge: 1表示更新时最多额外多出一个新 Pod；maxUnavailable: 0表示旧 Pod 不能同时全部不可用，保证不掉线。
• resources：requests 是调度依据，limits 是运行限制。不写 resources 的 Pod 在节点内存紧张时会被随机杀掉，K8s 对不设限的容器并不友好。
• 探针：readiness 决定 Pod 是否接入 Service 流量，liveness 决定是否重启已经僵死的容器。生产环境必须配置，否则发布时就只能靠玄学。

应用后检查：

kubectl apply -f user-service.yaml kubectl get pods -n prod -o wide

4.2 服务发现与负载均衡

每个微服务要暴露给其他微服务调用，就需要 Service。最常用的类型是ClusterIP：

apiVersion: v1 kind: Service metadata: name: user-service namespace: prod spec: selector: app: user-service ports: - protocol: TCP port: 8080 targetPort: 8080 type: ClusterIP

配置后，其他微服务在集群内可以通过http://user-service:8080访问，k3s 内置的 CoreDNS 会自动解析。这就是 K8s 的天然服务发现机制，不需要额外注册中心。如果你的微服务架构基于 Spring Cloud Alibaba 那种 Nacos 注册中心，也可以保留，两种方案不冲突；但 K8s 本身的 Service 更简单，链路故障时还能省去注册中心探活的复杂度。

Service 的负载均衡是 kube-proxy 通过 iptables/IPVS 规则实现的，Pod 增加减少会自动更新规则，不需要我们干预。我在实际部署中喜欢加一个端到端 curl 验证，比如进入另一个 Pod 里执行：

kubectl exec -it deploy/gateway-service -n prod -- curl http://user-service:8080/actuator/health

能返回 JSON 说明服务发现和网络策略没有问题。

4.3 ConfigMap 与 Secret：微服务配置管理

微服务数量一多，配置散在镜像里就是灾难。K8s 提供了 ConfigMap 和 Secret，分别是非敏感配置和敏感配置。下面示例把数据库地址和连接池参数放到 ConfigMap：

apiVersion: v1 kind: ConfigMap metadata: name: user-service-config namespace: prod data: application-prod.yml: | spring: datasource: url: jdbc:mysql://mysql.prod.svc.cluster.local:3306/user_db username: user_svc password: ${DB_PASSWORD} redis: host: redis.prod.svc.cluster.local

然后在 Deployment 里通过 volumes 挂载，或者通过envFrom注入。密码这种敏感信息不能直接写进 ConfigMap，用 Secret:

kubectl create secret generic user-db-secret \ --from-literal=DB_PASSWORD='P@ssw0rd!' \ -n prod

YAML 中使用envFrom把 Secret 注入成环境变量：

envFrom: - configMapRef: name: user-service-config - secretRef: name: user-db-secret

这样一个服务重启或缩扩容，配置始终从 Kubernetes 上读取，而不是依赖镜像里的配置文件。另外要提醒的是，Secret 只是做了 Base64 编码，不是加密，敏感程度极高的数据最好用 Sealed Secrets 或外部的密钥管理服务，别把私钥放 Secret 里就以为万事大吉。

4.4 用 Ingress 统一暴露微服务入口

内部服务通过 Service 通信，但外部流量进来不能每个服务暴露一个 NodePort，否则端口管理就是灾难。k3s 默认自带 Traefik Ingress Controller，我们可以直接用 Ingress 资源把网关服务暴露出去。

假设有一个 gateway 微服务，Deployment 和 Service 都有了，创建 Ingress：

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: gateway-ingress namespace: prod annotations: traefik.ingress.kubernetes.io/router.entrypoints: web spec: rules: - host: api.example.com http: paths: - path: / pathType: Prefix backend: service: name: gateway-service port: number: 8080

通过kubectl get ingress -n prod查看 Ingress 地址，然后配置 DNS 解析到任意节点 IP。所有外部请求先进 Traefik，由网关统一路由到各个业务微服务，这样微服务的边界就清晰了。

实际操作中，TLS 证书建议用 cert-manager 自动申请，或者把证书放到 Secret 里供 Ingress 引用。HTTP/2、灰度发布这些也可以在 Ingress 层的 Traefik 上配置。如果你有多个域名或者多套环境，Ingress 规则需要按照环境和域名分开管理，避免规则冲突。

5. 常见问题与排查实录

无论安装还是部署，都会遇到问题。我把实际踩过的坑列在这里，基本都是 Unicode 级别的教训，希望对你有帮助。

5.1 节点状态 NotReady 的排查套路

最典型的问题：worker 加入后一直是NotReady。第一步先看 worker 的 k3s 服务状态：

sudo systemctl status k3s-agent

如果服务正常，再看日志里出现的关键字。我遇到的情况是 Master 使用内网 IP 安装，但 worker 连不上，原因就是 Master 的--advertise-address没设置，k3s 选择了错误的网卡 IP。可在 Master 的/etc/rancher/k3s/config.yaml里添加：

node-ip: 192.168.1.10 advertise-address: 192.168.1.10

重启 k3s 后重新获取 node-token，重新加入节点。另一个常见原因是主机时间不同步，尤其两个节点时间差超过 30 秒时，证书校验会失败，日志里常见x509: certificate has expired or is not yet valid。处理方式是集群内所有节点都配置 NTP 时间同步：

sudo apt install -y ntpdate sudo ntpdate time.google.com

5.2 Pod 一直 Pending 或 CrashLoopBackOff

Pending多半是资源不够。执行kubectl describe pod <pod-name> -n prod，在事件末尾通常有0/3 nodes are available: 1 Insufficient cpu, 2 Insufficient memory，这是 requests 设置得比节点可用资源高。解决方法是调整 Deployment 里的 resources 或增加节点。

CrashLoopBackOff的原因很多，环境变量缺失、启动命令错误、配置连不上数据库都有可能。最直接的排查方式是看日志：

kubectl logs <pod-name> -n prod --previous

--previous看上一次容器的日志，判断是不是配置文件调整后没生效。我在 Spring Boot 微服务里遇到最多的问题是健康检查接口返回 404，导致 readiness 探针一直失败，Pod 永远不进入 Ready。这时候先手动进入 Podwget或curl探针路径，确认服务本身在容器内是否正常响应。

5.3 网络与存储踩坑记录

k3s 默认的网络方案是 Flannel VXLAN，跨节点通信需要 8472/UDP。如果你只放通了 6443 和 10250，Pod 跨节点访问就会异常。尤其是检查kubectl get pods -A里 coredns 一直Pending，多半是 Flannel 出了网络问题。

存储方面，k3s 内置了local-pathprovisioner，可以直接声明 PVC 使用节点本地磁盘。比如给 MySQL 或者 MinIO 用：

apiVersion: v1 kind: PersistentVolumeClaim metadata: name: mysql-pvc namespace: prod spec: accessModes: - ReadWriteOnce storageClassName: local-path resources: requests: storage: 10Gi

但要注意local-path的数据绑定在节点上，节点挂了数据就没了。生产环境想持久化，建议挂 NFS 或者用云盘，再把 StorageClass 指向外部存储。我的建议是：数据库等有状态服务能外置就外置，k3s 集群更专注于跑无状态应用，否则备份和迁移都会很痛苦。

5.4 日常运维小技巧与资源调优

这里分享几个我常用的技巧。第一个是给 kubectl 配自动补全和别名：

source <(kubectl completion bash) alias k=kubectl

第二个是合理设置 Pod 的terminationGracePeriodSeconds，默认是 30 秒，对需要清理连接的微服务来说可能不够。如果你的服务有长连接，可以改成 60 或 90，保证优雅停机。

第三个是流量突发场景下善用 HPA。k3s 自带 metrics-server，可以直接做水平伸缩：

kubectl autoscale deployment user-service -n prod --cpu-percent=60 --min=2 --max=5

这比手动改 replicas 靠谱得多。但 HPA 的前提是 Deployment 里的 requests 必须设置合理，否则 CPU 指标会失真。

还有一个小细节：k3s 的默认 Traefik 和 local-path 会占用一部分资源，如果你只喜欢最精简的集群，安装时可以禁用：

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --disable traefik --disable servicelb" sh -

不过我不建议新手一开始就禁用，默认组件能帮很多忙。

最后说下资源调优。k3s master 节点的 kubelet 参数可以在/etc/rancher/k3s/config.yaml里调，比如放宽 Pod 上限：

kubelet-arg: - "max-pods=100"

单机跑很多微服务时，这个参数可以避免 Pod 因为默认 110 个的限制而无法创建。如果节点内存富裕，还可以给 containerd 提高镜像 GC 阈值，少占点磁盘，但这些都是锦上添花，先把集群稳定跑起来才是正事。

按照我这套流程，Ubuntu 20.04 上的 k3s 集群从零到有、从集群搭建到微服务部署，整个过程差不多半天就能搞定。我个人实际操作下来最大的体会是：k3s 把 K8s 的复杂安装简化掉了，但 K8s 的复杂逻辑一点没少，所以“轻量”不等于“不用学”。资源限制、探针、命名空间、配管这些基本功在 k3s 上一个都不能省。把这套基础打好，以后再接触完整的 K8s 或者云上的托管集群，你只会觉得那些东西更重，但不会觉得陌生。如果后续要扩展，我可以再写一篇如何给这套集群加监控告警，把 Prometheus 和 Grafana 塞进去，那才是微服务上生产的最后一块拼图。