本文首发于 栏轩·阁欢迎访问阅读原文获取更好的阅读体验。一、前言本文在已有 KubeSphere 环境和 K8s 集群的基础上记录如何通过 KubeSphere 部署一个完整的 Nginx 网站。适用场景已在本地通过 Docker Desktop 启用 K8s 集群已安装 KubeSphereks-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 配置)三、创建配置字典ConfigMap3.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持久卷PersistentVolumeClaimPVC用于持久化存储网站静态文件。这样即使 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.confnginx 配置字典/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 2hEXTERNAL-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/目录下的文件到 Podkubectlcp./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项目名称配置名称-oyaml9.3 查看持久卷PVCkubectl get pvc-n项目名称9.4 查看 Service 和 External-IPkubectl 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 下的工作原理能帮助我们更快排查问题。