Debian12上使用K3s部署Kubernetes集群

这里使用两个主机 2h2g 40GB存储

Master （192.168.10.101），Node0 （192.168.10.103）

1. 准备工作（两台主机均需执行）

在开始之前，确保两台机器可以互相通信，并且防火墙允许必要的流量。

更新系统：
1
sudo apt update && sudo apt upgrade -y
停止并禁用防火墙（可选，但建议初学者操作以避免连接问题）： Debian 默认可能没有启用 ufw，但如果有，请确保开放端口 6443（API Server）和 10250（Kubelet Metrics）。

确认主机名： 建议分别设置主机名为 master 和 node0 方便识别。

1 2	`sudo hostnamectl set-hostname master # 在101上执行 sudo hostnamectl set-hostname node0 # 在103上执行`

2. 部署 Master 节点 (192.168.10.101)

在 Master 节点上，我们将运行安装脚本并将其配置为集群的主控节点。

执行安装命令：

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

# 中国用户，可以使用以下方法加速安装：

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

获取 Node Token： 安装完成后，你需要获取一个“令牌”，用于将 Node0 加入集群。
1
sudo cat /var/lib/rancher/k3s/server/node-token
复制保存这个字符串，稍后在 Node0 上会用到。
检查状态：
1
sudo kubectl get nodes
此时你应该能看到 master 节点处于 Ready 状态。

3. 部署 Node 节点 (192.168.10.103)

现在切换到 Node0 主机，将其作为工作节点连接到 Master。

执行安装命令： 请将下方命令中的 <MASTER_TOKEN> 替换为你刚才在 Master 上获取的字符串。
1
2
curl -sfL https://get.k3s.io | K3S_URL=https://192.168.10.101:6443 \ K3S_TOKEN=<MASTER_TOKEN> sh -

4. 验证集群状态

回到 Master 节点，运行以下命令验证 Node0 是否已成功加入：

1	`sudo kubectl get nodes`

预期输出：

sudo kubectl get nodes
NAME     STATUS   ROLES                  AGE   VERSION
master   Ready    control-plane,master   32m   v1.33.6+k3s1
node0    Ready    <none>                 30m   v1.33.6+k3s1

配置国内镜像

Master节点

创建或编辑配置文件：

1	`sudo nano /etc/rancher/k3s/registries.yaml`

填入

mirrors:
  docker.io:
    endpoint:
      - "https://docker.1ms.run"
  registry.k8s.io:
    endpoint:
      - "https://k8s.m.daocloud.io"

重启K3s

1	`sudo systemctl restart k3s`

Node节点

1 2	`sudo mkdir -p /etc/rancher/k3s sudo nano /etc/rancher/k3s/registries.yaml`

配置完成

1	`sudo systemctl restart k3s-agent`

如何卸载K3s

如果需要重新开始：

Master: sudo /usr/local/bin/k3s-uninstall.sh
Node: sudo /usr/local/bin/k3s-agent-uninstall.sh

部署 Nginx 验证集群

我们创建一个简单的 Nginx 服务，并使用 K3s 自带的 ServiceLB 让它在 80 端口跑起来。

在 Master 节点上创建配置文件：
1
nano nginx-test.yaml

粘贴以下内容：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 2 # 会在两个节点上各跑一个
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  type: LoadBalancer
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80

应用配置：
1
sudo kubectl apply -f nginx-test.yaml
验证： 等待几分钟后，访问 http://192.168.10.101 或 192.168.10.103，你应该能看到 Nginx 的欢迎页面。

5.安装管理面板 (Portainer)

对于 K3s 这种轻量级集群，Portainer 是最推荐的面板。它比官方 Dashboard 更美观，比 Rancher 更省资源。

创建 Portainer 命名空间：

1	`sudo kubectl create namespace portainer`

使用 Helm 或直接使用 Manifest 安装： 这里我们使用最简单的官方远程脚本安装：
1
sudo kubectl apply -n portainer -f https://raw.githubusercontent.com/portainer/k8s/master/deploy/manifests/portainer/portainer-lb.yaml
验证与访问
1. 检查 Pod 运行状态：
  1
  kubectl get pods -n portainer
  等待状态变为 Running。
2. 获取访问端口： Portainer 默认映射了两个端口：
  - HTTP: 30777
  - HTTPS: 30779 (推荐使用)
3. 浏览器访问： 打开浏览器，输入 Master 或 Node 的 IP 地址：
  - https://192.168.10.101:30779
  - https://192.168.10.103:30779
注意： 初次登录需要你在 12 分钟内设置管理员密码，否则出于安全考虑，Portainer 服务会自动停止，届时需要重启 Pod。

6.拓展

kubernetes 常用命令

1. 基础信息查询 (Get & Describe)

这些命令用于查看集群资源的运行状态。

查看资源列表：
- kubectl get nodes (查看节点状态)
- kubectl get pods -A (查看所有命名空间的 Pod)
- kubectl get svc (查看服务)
- kubectl get ns (查看命名空间)
查看详细描述：
- kubectl describe pod <pod-name> (当 Pod 状态异常时，常用此命令查看错误事件)
查看日志：
- kubectl logs <pod-name> (查看容器标准输出日志)
- kubectl logs -f <pod-name> (持续跟踪日志)

2. 资源创建与修改 (Apply & Edit)

K8s 推荐使用“声明式”管理资源。

通过文件创建/更新：
- kubectl apply -f <filename.yaml> (最常用的部署命令)
直接编辑运行中的资源：
- kubectl edit deployment <deployment-name>
临时修改镜像：
- kubectl set image deployment/<name> <container-name>=<new-image>:<tag>

3. 故障排除与调试 (Debug)

当应用出现问题时，这些工具能帮你进入内部查看。

进入 Pod 内部：
- kubectl exec -it <pod-name> -- /bin/bash
端口转发： (将本地端口映射到集群内部)
- kubectl port-forward <pod-name> 8080:80
查看资源占用 (需安装 Metrics Server)：
- kubectl top node
- kubectl top pod

4. 扩缩容与滚动更新 (Scale & Rollout)

管理应用的副本数量和发布版本。

手动扩缩容：
- kubectl scale deployment <name> --replicas=5
查看更新状态：
- kubectl rollout status deployment/<name>
版本回滚：
- kubectl rollout undo deployment/<name> (回滚到上一个版本)

5. 常用技巧与别名

为了提高效率，建议在你的终端配置文件（如 .bashrc 或 .zshrc）中添加别名：

1	`alias k='kubectl'`

常用缩写对照表：

全称	缩写
`pods`	`po`
`nodes`	`no`
`deployments`	`deploy`
`services`	`svc`
`namespaces`	`ns`
`configmaps`	`cm`

💡 一个典型的排错流程示例：

kubectl get pods (查看状态是否为 Running)
如果是 Pending/Error，执行 kubectl describe pod <name> (查看 Events 报错)
如果是 CrashLoopBackOff，执行 kubectl logs <name> (查看程序崩溃原因)

7.Helm

1. Helm 是什么？

在没有 Helm 之前，部署一个复杂的应用（如 WordPress）需要手动编写和维护大量的 YAML 文件（Deployment, Service, Ingress, ConfigMap 等）。

Helm 的核心价值：

打包管理： 将多个 YAML 文件封装成一个名为 Chart 的包。
模板化： 支持变量（Values），同一个 Chart 可以通过不同的配置部署到开发、测试和生产环境。
版本控制： 像 Git 一样，你可以一键升级应用，或者在出问题时一键回滚（Rollback）。

2. 如何安装 Helm

Helm 只是一个二进制客户端工具，安装非常简单。

通过脚本快速安装：

1
2
3

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

注意： 安装完成后，运行 helm version 确认是否安装成功。

3. Helm 怎么用？ (常用命令)

使用 Helm 通常遵循：添加仓库 -> 搜索 -> 安装 -> 管理 的流程。

第一步：添加常用的 Chart 仓库

就像给手机加源一样，最常用的是 Bitnami 仓库。

Bash

1 2	`helm repo add bitnami https://charts.bitnami.com/bitnami helm repo update`

第二步：查找并安装应用

假设我们要安装一个 Redis：

# 搜索 Redis
helm search repo redis

# 安装 Redis (名称定为 my-redis)
helm install my-redis bitnami/redis

第三步：管理已安装的应用

# 查看已安装的应用列表
helm list

# 查看应用的配置参数
helm get values my-redis

# 升级应用 (比如修改了配置文件后)
helm upgrade my-redis bitnami/redis -f values.yaml

# 一键回滚到上一个版本
helm rollback my-redis 1

# 卸载应用
helm uninstall my-redis

Q&A

出现了下面问题
root@master:~# helm install kps prometheus-community/kube-prometheus-stack \
  -n monitoring 
Error: INSTALLATION FAILED: Kubernetes cluster unreachable: stat /root/.kube/config: no such file or directory
解决办法
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config
chmod 600 ~/.kube/config

8.安装 kube-prometheus-stack 监控栈

1.添加 Helm 仓库

首先，需要将 Prometheus 社区的 Helm 仓库添加到你的本地 Helm 客户端中。

1 2	`helm repo add prometheus-community https://prometheus-community.github.io/helm-charts helm repo update`

2.创建命名空间

为了保持集群整洁，建议为监控组件创建一个独立的 monitoring 命名空间。

1	`kubectl create namespace monitoring`

3.安装 Helm Chart

使用 Helm 安装监控栈。这里我们将该发布（Release）命名为 kps。

1	`helm install kps prometheus-community/kube-prometheus-stack -n monitoring`

4.验证 Pod 运行状态

确认所有组件（Prometheus, Grafana, Alertmanager 等）是否已成功启动。

1	`kubectl get pods -n monitoring`

预期输出： 你会看到类似下方的列表，确保所有 Pod 的状态均为 Running 且 READY 列显示正常（如 2/2 或 3/3）。

NAME                                                    READY   STATUS    RESTARTS      AGE
alertmanager-kps-kube-prometheus-stack-alertmanager-0   2/2     Running   2 (12m ago)   30m
kps-grafana-7c695669f4-mwsbg                            3/3     Running   0             30m
kps-kube-prometheus-stack-operator-7964756cb-mmfbr      1/1     Running   1 (12m ago)   30m
kps-kube-state-metrics-96dc6f854-vmwnn                  1/1     Running   0             30m
kps-prometheus-node-exporter-tzqg4                      1/1     Running   1 (12m ago)   30m
kps-prometheus-node-exporter-ztvnh                      1/1     Running   0             30m
prometheus-kps-kube-prometheus-stack-prometheus-0       2/2     Running   0             30m

5.访问 Grafana 面板

1. 获取 Grafana 管理员密码 默认用户名是 admin。运行以下命令获取自动生成的解码密码（提示：默认通常是 prom-operator）：

1	`kubectl get secret --namespace monitoring -l app.kubernetes.io/component=admin-secret -o jsonpath="{.items[0].data.admin-password}" \| base64 --decode ; echo`

2. 端口转发（Port-forward） 为了从外部访问集群内部的服务，我们需要映射端口。（临时访问）

注意： --address 0.0.0.0 允许你通过服务器的 IP 访问，而不仅仅是 localhost。

1	`kubectl port-forward --address 0.0.0.0 -n monitoring svc/kps-grafana 3000:80`

3. 浏览器登录 访问你的服务器 IP 和端口（例如：http://192.168.122.42:3000）：

用户名 (Username): admin
密码 (Password): 使用上方命令获取到的字符串。

6.持久化运行

将 Grafana 服务的类型从 ClusterIP 改为 NodePort，这样你可以通过集群中任何节点的 IP + 指定端口直接访问，无需运行任何命令。

修改服务：

1	`kubectl patch svc kps-grafana -n monitoring -p '{"spec": {"type": "NodePort"}}'`

获取暴露的端口：
1
kubectl get svc -n monitoring kps-grafana
在输出的 PORT(S) 列中，你会看到类似 80:31234/TCP 的内容。此时，你可以通过 http://<服务器IP>:31234 永久访问。

教程

#K3s #Kubernetes #Debian

Debian12上使用K3s部署Kubernetes集群

https://blog.quickso.cn/2025/12/26/Debian12上使用K3s部署Kubernetes集群/

作者

木子欢儿

发布于

2025年12月26日

许可协议

RustFS对象存储Docker部署上一篇

K3s集群以及KubePi安装、配置与使用下一篇