一个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，提供API
apiVersion: 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部分作为$2
3.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: "100m"4.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 "upgrade"4.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. 常见问题排查指南
即使配置看起来完美，实际部署时仍可能遇到各种问题。以下是几个常见问题及解决方法：
问题1：API请求返回404
- 检查Ingress控制器的日志：
kubectl logs -n ingress-nginx <controller-pod> - 验证Service选择器是否正确匹配后端Pod标签
问题2：前端路由刷新后404
- 确保
configuration-snippet中的重写规则正确 - 检查前端构建配置，通常需要设置publicPath为
/
问题3：WebSocket连接立即断开
- 确认所有必要的proxy_set_header注解已添加
- 检查后端是否支持WebSocket协议
问题4：上传大文件失败
- 除了proxy-body-size，还要检查后端服务的上传限制
- 对于Spring Boot应用，需要设置
spring.servlet.multipart.max-file-size
7. 进阶技巧：多环境差异化配置
在实际开发中，我们通常需要为不同环境(开发、测试、生产)配置不同的参数。可以通过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: "100m"7.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。