一个Ingress搞定前后端分离：实战配置将API请求转发后端，静态页面留给前端

一个Ingress搞定前后端分离实战配置将API请求转发后端静态页面留给前端在前后端分离架构成为主流的今天如何优雅地部署应用成了开发者必须面对的挑战。想象一下用户访问你的网站时浏览器应该加载React或Vue构建的静态资源而当页面需要数据时又需要无缝对接后端API服务。传统做法可能需要配置多个域名或复杂的代理规则但在Kubernetes生态中Ingress-Nginx提供了一种更简洁的解决方案。本文将深入探讨如何通过单个Ingress资源实现前后端流量的智能路由。无论你是正在搭建全新项目还是优化现有部署这套方案都能显著简化你的基础设施配置。我们会从基础概念讲起逐步深入到正则表达式路由、路径重写等高级技巧最后还会分享几个真实场景中的性能调优经验。1. 理解前后端分离的流量路由需求现代Web应用通常由两部分组成静态前端和动态API后端。前端可能是一个React单页应用(SPA)打包后生成HTML、CSS和JavaScript文件后端则是处理业务逻辑的API服务可能用Spring Boot、Django或Node.js实现。这种架构下流量路由需要满足两个核心需求静态资源服务当用户访问根路径(如/)或直接输入URL时应该返回前端应用的入口文件(index.html)API请求代理所有以/api开头的请求应该被转发到后端服务同时最好去掉/api前缀# 理想的路由效果示例 / → 前端静态服务 /about → 前端静态服务 (SPA路由) /api/users → 后端服务 (实际接收到 /users)这种配置带来的好处显而易见只需要维护一个域名和SSL证书前端代码中可以统一使用相对路径调用API简化了本地开发和生产环境的一致性2. 基础Ingress配置区分前后端路径让我们从最基础的配置开始。假设我们有两个Kubernetes服务frontend-service: 端口80提供静态文件backend-service: 端口8080提供APIapiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: unified-ingress annotations: nginx.ingress.kubernetes.io/use-regex: true spec: rules: - host: example.com http: paths: - path: / pathType: Prefix backend: service: name: frontend-service port: number: 80 - path: /api pathType: Prefix backend: service: name: backend-service port: number: 8080这个配置虽然简单但存在两个明显问题API请求会保留/api前缀传递给后端前端路由(如/about)会返回404因为Nginx会尝试查找对应的静态文件3. 高级路由配置重写路径与SPA支持要解决上述问题我们需要引入两个关键注解rewrite-target重写请求路径configuration-snippet添加Nginx特定配置3.1 去除API前缀的配置apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: advanced-ingress annotations: nginx.ingress.kubernetes.io/rewrite-target: /$2 nginx.ingress.kubernetes.io/use-regex: true spec: rules: - host: example.com http: paths: - path: /api(/|$)(.*) pathType: ImplementationSpecific backend: service: name: backend-service port: number: 8080 - path: /(.*) pathType: Prefix backend: service: name: frontend-service port: number: 80关键点解析use-regex: true启用正则表达式路径匹配rewrite-target: /$2将捕获组的第二部分作为新路径/api(/|$)(.*)会匹配/api/xxx或/api并将xxx部分作为$23.2 支持前端路由的补充配置对于React Router或Vue Router的history模式还需要添加以下注解annotations: nginx.ingress.kubernetes.io/configuration-snippet: | if ($uri !~ ^/api) { rewrite ^(.*)$ /index.html break; }这个配置确保所有非API请求都返回index.html让前端路由可以接管URL解析。4. 性能优化与特殊场景处理基础功能实现后我们还需要考虑性能和特殊场景。以下是几个实战中总结的经验4.1 文件上传大小限制默认情况下Ingress-Nginx限制上传文件大小为1MB。对于需要处理大文件的应用annotations: nginx.ingress.kubernetes.io/proxy-body-size: 100m4.2 WebSocket连接配置实时应用可能需要WebSocket支持annotations: nginx.ingress.kubernetes.io/proxy-read-timeout: 3600 nginx.ingress.kubernetes.io/proxy-send-timeout: 3600 nginx.ingress.kubernetes.io/proxy-http-version: 1.1 nginx.ingress.kubernetes.io/proxy-set-header: | Upgrade $http_upgrade Connection upgrade4.3 超时设置调优不同端点可能需要不同的超时设置annotations: nginx.ingress.kubernetes.io/configuration-snippet: | location ~ ^/api/long-task { proxy_read_timeout 600s; }5. 完整配置示例与测试方法下面是一个整合所有优化点的完整配置示例apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: production-ingress annotations: nginx.ingress.kubernetes.io/rewrite-target: /$2 nginx.ingress.kubernetes.io/use-regex: true nginx.ingress.kubernetes.io/proxy-body-size: 100m nginx.ingress.kubernetes.io/configuration-snippet: | if ($uri !~ ^/api) { rewrite ^(.*)$ /index.html break; } location ~ ^/api/stream { proxy_buffering off; proxy_read_timeout 3600s; } spec: rules: - host: myapp.example.com http: paths: - path: /api(/|$)(.*) pathType: ImplementationSpecific backend: service: name: backend-service port: number: 8080 - path: /(.*) pathType: Prefix backend: service: name: frontend-service port: number: 80测试你的配置是否生效# 测试前端路由 curl -I https://myapp.example.com/about # 测试API路由 (应该返回后端响应) curl https://myapp.example.com/api/users # 测试API前缀是否被正确移除 (后端应该收到 /users) # 需要在后端日志中验证6. 常见问题排查指南即使配置看起来完美实际部署时仍可能遇到各种问题。以下是几个常见问题及解决方法问题1API请求返回404检查Ingress控制器的日志kubectl logs -n ingress-nginx controller-pod验证Service选择器是否正确匹配后端Pod标签问题2前端路由刷新后404确保configuration-snippet中的重写规则正确检查前端构建配置通常需要设置publicPath为/问题3WebSocket连接立即断开确认所有必要的proxy_set_header注解已添加检查后端是否支持WebSocket协议问题4上传大文件失败除了proxy-body-size还要检查后端服务的上传限制对于Spring Boot应用需要设置spring.servlet.multipart.max-file-size7. 进阶技巧多环境差异化配置在实际开发中我们通常需要为不同环境(开发、测试、生产)配置不同的参数。可以通过Kustomize或Helm实现配置差异化7.1 使用Kustomize覆盖注解# base/ingress.yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app-ingress annotations: nginx.ingress.kubernetes.io/proxy-body-size: 1m # overlays/production/ingress-patch.yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app-ingress annotations: nginx.ingress.kubernetes.io/proxy-body-size: 100m7.2 Helm模板中的条件配置annotations: nginx.ingress.kubernetes.io/proxy-body-size: {{ .Values.ingress.proxyBodySize }} {{- if .Values.production }} nginx.ingress.kubernetes.io/configuration-snippet: | # 生产环境特定配置 {{- end }}在最近的一个电商项目迁移中我们采用了这套配置方案。原本需要三个独立的Ingress资源(前端、API、管理后台)现在合并为一个不仅简化了配置管理还减少了约30%的SSL握手开销。特别是在移动端网络环境下统一域名的优势更加明显页面加载时间平均缩短了400ms。