如何通过NGINX Ingress Controller将Swagger index.html映射至根域名

架构老林

2026-7-21

解决方案

1. 修正Ingress配置，避免循环重定向

移除会触发循环的server-snippet反向重定向规则，仅保留根路径的定向逻辑，确保访问https://api.domain.com时直接转发到后端的/index.html：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api
  namespace: test
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      # 仅对根路径精确匹配，重写为index.html转发到后端
      location = / {
          rewrite ^ /index.html last;
      }
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - api.domain.com
  rules:
    - host: api.domain.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api
                port:
                  name: http-port

这个配置的核心逻辑：

只处理根路径的请求，不会干扰/v1/<endpoint>这类API路由
避免了之前双向重写导致的浏览器循环跳转问题

2. 保留现有.NET Swagger配置（无需修改）

你的后端配置已经正确设置了RoutePrefix = string.Empty，确保/index.html能返回Swagger UI页面；SwaggerEndpoint("v1/api.json", "API v1")使用相对路径，在根路径下会自动请求https://api.domain.com/v1/api.json，这和你能正常访问该JSON文档的情况匹配。

3. 排查Swagger UI报错的可能原因

如果重写生效后页面仍报错，可从以下方向检查：

静态资源加载：打开浏览器开发者工具，查看swagger-ui-bundle.js、swagger-ui.css等资源的请求状态。这些资源由.NET SwaggerUI中间件提供，路径为/swagger-ui/xxx，若Ingress或后端未正确转发这类请求，会导致页面渲染失败。
TLS/CORS配置：确认Ingress的TLS证书有效，后端API未设置限制静态资源加载的CORS规则。
Swagger JSON的服务器地址：检查v1/api.json中的servers字段，确保url值为https://api.domain.com或相对路径/，避免Swagger UI向错误地址发送请求。