Kubernetes Ingress配置/api/user路径时Spring Boot返回404问题

问题描述 #

在本地K3D环境部署Spring Boot API后，功能运行正常，但遇到以下异常：

• 当Ingress路径指定为/api/user时，访问localhost:9080/api/user返回Spring Boot的404白标错误页面（非Nginx 404）；
• 将路径改为/user时，可正常访问。

不生效的Ingress配置 #

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: user-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: localhost
    http:
      paths:
      - path: /api/user
        pathType: Prefix
        backend:
          service:
            name: user-service
            port:
              number: 8094

生效的Ingress配置 #

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: user-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: localhost
    http:
      paths:
      - path: /user
        pathType: Prefix
        backend:
          service:
            name: user-service
            port:
              number: 8094

原因分析 #

问题出在nginx.ingress.kubernetes.io/rewrite-target: /注解的行为上：

• 当Ingress路径设为/api/user且pathType为Prefix时，Nginx会匹配所有以/api/user开头的请求，但rewrite-target: /会将请求路径直接重写为根路径/；
• 你的Spring Boot API的接口路径是/user（比如GET /user），转发到服务的请求路径变成/，自然找不到对应接口，返回404白标页；
• 路径改为/user时能正常访问，是因为重写后的/刚好匹配到了API的对应接口（比如根路径映射了用户接口），但这属于巧合，并非正确配置方式。

解决方案 #

方案1：使用正则捕获组保留路径后缀 #

通过正则表达式捕获路径的后半部分，确保转发到Spring Boot的路径符合接口预期：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: user-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: localhost
    http:
      paths:
      - path: /api/user(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: user-service
            port:
              number: 8094

此配置会将/api/user重写为/，/api/user/123重写为/123，完美匹配Spring Boot的接口路径。

方案2：直接指定rewrite-target为接口前缀 #

如果你的Spring Boot接口统一以/user开头，可直接将重写目标设为/user：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: user-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /user
spec:
  rules:
  - host: localhost
    http:
      paths:
      - path: /api/user
        pathType: Prefix
        backend:
          service:
            name: user-service
            port:
              number: 8094

方案3：修改Spring Boot上下文路径 #

在Spring Boot的配置文件中添加：

server.servlet.context-path=/api/user

这样Ingress无需重写路径，直接转发即可，但会改变服务本身的路径前缀，需根据实际场景选择。

补充说明 #

Kubernetes官方文档明确提到，Ingress v1版本中rewrite-target注解需要结合正则捕获组使用，直接设置为/仅适用于简单的根路径转发，无法处理带多级前缀的场景。

内容的提问来源于stack exchange，提问作者Jovi Simons