news 2026/8/6 17:32:28

KubeSphere学习笔记：部署nginx

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
KubeSphere学习笔记：部署nginx

📝本文首发于 栏轩·阁

欢迎访问阅读原文，获取更好的阅读体验。

一、前言

本文在已有 KubeSphere 环境和 K8s 集群的基础上，记录如何通过 KubeSphere 部署一个完整的 Nginx 网站。

适用场景

  • 已在本地通过 Docker Desktop 启用 K8s 集群
  • 已安装 KubeSphere（ks-core）
  • 希望通过可视化界面 + 命令行结合的方式管理网站部署

本文重点

  • 创建配置字典（ConfigMap）管理 Nginx 配置文件
  • 创建持久卷（PVC）挂载网站静态文件
  • 创建工作负载（Deployment）并配置挂载
  • 创建 LoadBalancer 服务暴露到宿主机
  • 通过kubectl cp上传 HTML 文件

二、整体架构

用户访问 → localhost:8888 → envoy 代理容器(LoadBalancer) → K8s NodePort → Pod:80(Nginx) ├── /usr/share/nginx/html (PVC 持久卷) └── /etc/nginx/conf.d/ (ConfigMap 配置)

三、创建配置字典（ConfigMap）

3.1 什么是配置字典

配置字典（ConfigMap）是 K8s 中用来存储配置文件的资源对象。这里用来存储 Nginx 的配置文件，挂载到 Pod 中后 Nginx 可以直接读取。

3.2 创建步骤

在 KubeSphere 项目中进入配置 → 配置字典，点击创建。

3.3 nginx.conf（主配置）

用来控制 Nginx 的全局行为，包括工作进程数、日志格式、事件模型等：

user nginx; worker_processes 1; events { worker_connections 1024; } http { include /etc/nginx/mime.types; default_type application/octet-stream; log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for"'; access_log /var/log/nginx/access.log main; sendfile on; keepalive_timeout 65; include /etc/nginx/conf.d/*.conf; }

3.4 default.conf（站点配置）

用来配置具体的虚拟主机，定义监听端口、站点根目录等：

server { listen 80; server_name localhost; location / { root /usr/share/nginx/html; index index.html index.htm; } error_page 500 502 503 504 /50x.html; location = /50x.html { root /usr/share/nginx/html; } }

注意：站点根目录root指向/usr/share/nginx/html，这就是后面要挂载持久卷的位置。

四、创建持久卷（PVC）

持久卷（PersistentVolumeClaim，PVC）用于持久化存储网站静态文件。这样即使 Pod 重启，上传的 HTML 文件也不会丢失。

在 KubeSphere 中创建：进入存储 → 持久卷声明，点击创建。

容量按需设置（本例设为 10Gi），访问模式选择单节点读写（RWO）。存储卷创建后会自动绑定到后端的存储类（StorageClass）。

五、创建应用（工作负载）

5.1 镜像地址

docker.1ms.run/library/nginx:latest

使用国内镜像源加速拉取。如果使用 Docker Hub 官方镜像，地址为nginx:latest。

5.2 挂载持久卷

将上一步创建的 PVC 挂载到容器内 Nginx 的网页根目录，用于存放 HTML 静态文件。

字段值
挂载路径/usr/share/nginx/html
存储卷选择已创建的 PVC
读写权限读写

5.3 挂载配置字典

Nginx 有两个关键配置文件需要挂载，涉及多个路径，需分别配置：

存储卷容器内挂载路径子路径（Key 名称）
nginx 配置字典/etc/nginx/nginx.confnginx.conf
nginx 配置字典/etc/nginx/conf.d/default.confdefault.conf

六、两种挂载方式的区别

在配置字典挂载时，KubeSphere 提供了两种挂载方式，理解其区别非常重要：

6.1 指定子路径（subPath）

适用于精准挂载单个文件。当配置字典包含多个 Key 时，直接填写目标Key 名称（如nginx.conf），挂载路径填写容器内完整文件路径（如/etc/nginx/nginx.conf）。该方式仅替换指定文件，不会清空目标目录原有内容。

使用场景：只想替换某个配置文件，保留 Nginx 镜像自带的其余默认配置。

6.2 选择指定键（items 模式）

需先指定挂载路径为容器内的父目录，再逐一为配置字典里的每个 Key 单独分配容器内子路径名。该模式会先清空目标父目录，再放入指定文件。

使用场景：需要批量挂载多个配置文件，且不关心容器原有默认配置。

6.3 使用建议

  • 想要保留容器原有文件（如 Nginx 原生配置）、仅替换个别配置文件，优先使用指定子路径。
  • 需要批量挂载多个文件、且允许清空目标目录时，再使用选择指定键。
  • 二者不要同时勾选，避免挂载异常。

七、创建服务暴露到宿主机

7.1 创建 Service

工作负载部署完成后，需要创建 Service 才能外部访问。在 KubeSphere 中进入服务 → 服务，点击创建：

  • 服务类型：LoadBalancer
  • 端口映射：Pod 端口80→ Service 端口8888（或其他你想要的端口）
  • 注意不需要配置键值对标签，Docker Desktop 会自动创建 envoy 代理容器供外部访问。

7.2 LoadBalancer 原理说明

在 Docker Desktop 的 K8s 环境中，Service 改为 LoadBalancer 类型后，kind-cloud-provider组件会自动创建一个 envoy 代理容器，将宿主机端口映射到集群内部：

localhost:8888 → envoy 容器:8888 → NodePort → Pod:80

⚠️注意：如果 Host 端口和已有的 Docker 容器端口冲突（如本地已有 Nginx 占用了 80 端口），LoadBalancer 会卡在<pending>状态，需要手动指定一个空闲端口。

7.3 查看 Service 状态

kubectl get svc-n<项目名称>

Expected output:

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE nginx LoadBalancer 10.96.135.68 172.18.0.6 8888:31056/TCP 2h

EXTERNAL-IP出现 IP 地址（而非<pending>）代表 LoadBalancer 创建成功。

八、上传 HTML 文件

8.1 403 问题

Service 创建成功后访问http://localhost:8888会出现403 Forbidden，原因很简单——页面根目录/usr/share/nginx/html是空的，Nginx 找不到默认页面。

8.2 使用 kubectl cp 上传文件

首先查看 Pod 名称：

kubectl get pods-n<项目名称>

上传本地dist/目录下的文件到 Pod：

kubectlcp./dist/.<Pod名称>:/usr/share/nginx/html/-n<项目名称>

⚠️ 路径注意：

  • ./dist/.—— 把dist目录里面的内容上传到目标路径（正确）
  • ./dist/—— 把dist目录本身上传到目标路径，会变成html/dist/（错误）

8.3 删除或重新上传

如果传错目录结构，需要先清理再重新上传：

kubectlexec-n<项目名称><Pod名称>--rm-rf/usr/share/nginx/html/*

⚠️注意：rm -rf *通配符在部分 shell 环境中可能不生效，改用精确路径更可靠：

kubectlexec-n<项目名称><Pod名称>--rm-rf/usr/share/nginx/html/dist

命令说明：kubectl exec可以进入容器内部执行 Linux 命令，--后面跟的就是要在容器内执行的命令。

8.4 访问验证

文件上传后再次访问http://localhost:8888，可以看到页面正常显示。

九、常用运维命令

9.1 查看 Pod 状态和详情

# 查看项目下所有 Podkubectl get pods-n<项目名称># 查看 Pod 详细信息（包括挂载、事件等）kubectl describe pod-n<项目名称><Pod名称>

9.2 查看配置字典内容

kubectl get configmap-n<项目名称><配置名称>-oyaml

9.3 查看持久卷（PVC）

kubectl get pvc-n<项目名称>

9.4 查看 Service 和 External-IP

kubectl get svc-n<项目名称>

9.5 查看 Pod 内部文件结构

kubectlexec-n<项目名称><Pod名称>--ls-la/usr/share/nginx/html/

十、总结

阶段操作要点
配置创建 ConfigMap挂载时注意区分 subPath 和 items 模式
存储创建 PVC挂载到/usr/share/nginx/html
部署创建 Deployment配置镜像和挂载路径
暴露创建 LoadBalancer Service注意端口冲突，Docker Desktop 自动创建 envoy 代理
上传kubectl cp路径用./dist/.不是./dist/
运维kubectl exec进入容器执行命令，方便调试和管理

通过 KubeSphere 可视化界面结合kubectl命令行，可以很方便地在本地 K8s 环境中完成 Nginx 网站部署。理解 ConfigMap 挂载机制和 LoadBalancer 在 Docker Desktop 下的工作原理，能帮助我们更快排查问题。

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/8/6 17:27:26

5步轻松修复损坏二维码：QRazyBox终极指南拯救重要信息

5步轻松修复损坏二维码&#xff1a;QRazyBox终极指南拯救重要信息 【免费下载链接】qrazybox QR Code Analysis and Recovery Toolkit 项目地址: https://gitcode.com/gh_mirrors/qr/qrazybox 你是否遇到过模糊不清的二维码无法扫描&#xff1f;或者精心设计的二维码因部…

作者头像 李华
网站建设 2026/8/6 17:26:45

Move Mouse终极指南：Windows防休眠神器完全配置手册

Move Mouse终极指南&#xff1a;Windows防休眠神器完全配置手册 【免费下载链接】movemouse Move Mouse is a simple piece of software that is designed to simulate user activity. 项目地址: https://gitcode.com/gh_mirrors/mo/movemouse 你是否曾被突如其来的系统…

作者头像 李华
网站建设 2026/8/6 17:25:59

Python数据分析（十四）：Pandas 数据可视化

目录 一、为什么 Pandas 能画图 1. 底层机制 2. 为什么优先使用 Pandas 绘图 二、单变量图表绘制 1. 折线图 2. 柱状图 3. 直方图 4. 饼图 5. 面积图 三、双变量与多列数据可视化 1. 散点图 2. 蜂巢图 3. 堆叠图 四、综合案例 1. 模拟数据准备 2. 步骤一&#…

作者头像 李华
网站建设 2026/8/6 17:25:30

小说灵感生成工具，不同创作阶段的选型参考

很多写小说的人都会遇到相似困境。脑海里闪过零散脑洞&#xff0c;随手记录在各处&#xff0c;等到想要拓展故事框架时&#xff0c;很难把碎片化灵感串联成完整世界观。不少长期连载的网文作者&#xff0c;会借助扣子搭建专属创作项目&#xff0c;集中收纳零散脑洞&#xff0c;…

作者头像 李华
网站建设 2026/8/6 17:24:16

软件测试面试全攻略：从基础理论到实战技巧

1. 为什么软件测试面试需要专项准备&#xff1f; 在当前的IT就业环境下&#xff0c;软件测试岗位的竞争异常激烈。根据2023年行业调研数据显示&#xff0c;平均每个测试岗位会收到超过50份简历&#xff0c;而最终能进入技术面试环节的候选人通常不超过5人。这种高淘汰率使得面试…

作者头像 李华