1. 为什么已经有 spring-cloud-gateway 还要在前面挡一层 nginx很多同学在 SpringCloud 微服务里把 spring-cloud-gateway 配好路由之后会觉得网关这件事已经做完了动态路由有了、断言过滤器有了、注册中心也接上了为什么还要在它前面再放一个 nginx我一开始也这么想直到把静态资源和接口放在同一个域名下对外才发现问题不在“能不能转发”而在“谁来干哪一段活”。先说结论spring-cloud-gateway 是业务网关nginx 是流量入口网关两者不是替代关系而是分层协作。nginx 站在最外层负责统一入口、TLS 终止、静态资源、压缩、连接层面的高并发承载spring-cloud-gateway 站在内层负责动态路由、鉴权、限流、灰度这些和业务强相关的逻辑。客户端只认一个域名请求先到 nginx静态资源 nginx 直接返回动态接口再转发给 gateway由 gateway 按注册中心里的服务实例做二次路由。这个分层带来的直接好处是静态资源不占用 JVM 的连接和线程TLS 握手这种 CPU 密集但逻辑固定的活交给 nginxgateway 只处理它擅长的业务编排。本文就按“已有 gateway 路由需要在外层 nginx 做统一入口、TLS 终止与转发”这个场景交付一份可复制的 nginx.conf 与 gateway 路由骨架再给出 curl 验证链路和日志排查动作帮你确认两层网关真的协同生效了。适合谁看已经能跑通 spring-cloud-gateway 基础路由、准备把服务对外暴露、需要处理 HTTPS 和静态资源的后端同学。下面所有配置都可以直接改域名和端口后落地。2. 前置准备TaoToken 控制台拿 Key 与接入信息在开始写 nginx 和 gateway 配置之前先把后面验证链路要用到的接入信息准备好。我习惯用 TaoToken 来统一管理模型调用和 API Key这样在 gateway 里做鉴权透传、在本地用 curl 验证时都有统一的凭证来源不用到处散落密钥。你可以先打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 了解整体能力然后进入控制台创建项目。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在里面新建一个应用拿到对应的 API Key。这个 Key 后面会用在 gateway 的鉴权过滤器里也会出现在我们的 curl 验证命令中。如果你后面要做长期编码或者 Agent 类的调用可以顺手看一下 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续性的开发场景。单纯验证模型连通性的话用模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 就够了。API Key 的管理入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API 基础地址是 https://taotoken.net/api 这个不加 UTM。拿到 Key 之后先别急着写 nginx先在本地确认这个 Key 能正常调用避免后面把网络问题和鉴权问题混在一起排查。这一步用 curl 直接打 API 就行curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回里有正常的 choices 结构说明 Key 和网络都没问题。这一步过了我们再进入双层网关的配置。3. 可复制配置nginx.conf 与 gateway 路由骨架3.1 nginx 层统一入口 TLS 终止 静态资源 转发nginx 的职责边界很清晰对外只暴露 443做 TLS 终止静态资源自己返回动态接口转发给 gateway。下面这份配置可以直接改 server_name 和证书路径使用。# /etc/nginx/conf.d/micro-gateway.conf upstream spring_gateway { server 127.0.0.1:8080; keepalive 64; } server { listen 80; server_name api.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl; http2 on; server_name api.example.com; ssl_certificate /etc/nginx/certs/api.example.com.pem; ssl_certificate_key /etc/nginx/certs/api.example.com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; gzip on; gzip_types text/css application/javascript application/json image/svgxml; gzip_min_length 1024; # 静态资源nginx 直接返回不进 gateway location /static/ { root /var/www/frontend; expires 7d; add_header Cache-Control public, max-age604800; } # 动态接口转发给 spring-cloud-gateway location /api/ { proxy_pass http://spring_gateway; proxy_http_version 1.1; proxy_set_header Connection ; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_connect_timeout 3s; proxy_read_timeout 30s; } }这里有几个关键点值得单独说。proxy_http_version 1.1配合proxy_set_header Connection 是为了让 upstream 走长连接避免每个请求都重新建 TCP。X-Forwarded-Proto一定要带上否则 gateway 后面拼重定向地址时会以为是 http。静态资源用location /static/单独拦截这样图片和 js 根本不会打到 JVM。3.2 gateway 层动态路由 鉴权透传gateway 这边保持它擅长的动态路由同时把 nginx 传来的头信息接住。下面是一份 application.yml 骨架路由到具体的微服务。server: port: 8080 spring: application: name: spring-cloud-gateway cloud: gateway: discovery: locator: enabled: true lower-case-service-id: true routes: - id: user-service uri: lb://user-service predicates: - Path/api/user/** filters: - StripPrefix1 - AddRequestHeaderX-Gateway-Source, spring-cloud-gateway - id: order-service uri: lb://order-service predicates: - Path/api/order/** filters: - StripPrefix1lb://表示从注册中心拿实例做负载均衡StripPrefix1把/api前缀去掉再转发给下游服务。AddRequestHeader加一个来源标记方便下游服务在日志里区分请求是从哪一层进来的。3.3 两层职责对照能力nginx 层spring-cloud-gateway 层TLS 终止负责不负责静态资源直接返回不处理动态路由只转发到 gateway按服务实例路由鉴权可选粗粒度业务级细粒度限流连接级接口级/用户级灰度不擅长按用户/Header 灰度这张表就是分层的核心依据谁擅长什么就放什么别硬把 C 的活塞给 Java也别把业务逻辑写进 nginx。4. 验证请求curl 打通两层链路配置写完之后必须用 curl 从外到内验证一遍确认请求确实经过了 nginx 再到 gateway。先验证静态资源是否被 nginx 直接拦截curl -I https://api.example.com/static/app.js期望看到HTTP/2 200并且响应头里有Cache-Control: public, max-age604800。如果这个请求打到了 gateway说明location /static/没生效检查 root 路径和 location 匹配顺序。再验证动态接口是否经过两层转发curl -i https://api.example.com/api/user/1 \ -H Authorization: Bearer sk-你的Key期望返回业务数据同时响应头里能看到 gateway 加上的标记。为了确认链路可以在 gateway 的过滤器里临时加一个响应头或者在 nginx 的location /api/里加add_header X-Nginx-Hit 1;这样 curl 的响应头里同时出现 nginx 和 gateway 的痕迹就说明两层都走到了。如果要用模型接口验证鉴权透传可以这样打curl -X POST https://api.example.com/api/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:hello}]}这条链路走通说明 nginx 的 TLS、转发、头信息透传以及 gateway 的路由、鉴权都正常。想单独确认模型侧是否正常可以直接用模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 对照结果。5. 本篇常见错排查5.1 502 Bad Gateway最常见的原因是 nginx 的 upstream 指向的 gateway 端口不对或者 gateway 没起来。先在服务器上curl http://127.0.0.1:8080/actuator/health确认 gateway 活着再看 nginx error.log 里的connect() failed记录。如果 gateway 在容器里注意127.0.0.1在 nginx 容器里指向的是容器自己要改成服务名或宿主机 IP。5.2 请求到了 gateway 但路由 404多半是StripPrefix和Path断言没对齐。比如 nginx 转发的是/api/user/1gateway 断言写的是/user/**那就匹配不上。要么把断言改成/api/user/**要么在 nginx 里rewrite掉前缀。我建议前缀统一在 gateway 处理nginx 保持原样转发这样排查时路径更直观。5.3 静态资源返回 404 或走到了 gateway检查location /static/的root路径。root /var/www/frontend;配合请求/static/app.jsnginx 实际找的是/var/www/frontend/static/app.js。如果你想让/static/映射到/var/www/frontend/应该用alias而不是root。这个坑很常见改一个字就好。5.4 HTTPS 重定向循环如果 gateway 或下游服务根据X-Forwarded-Proto拼重定向地址而 nginx 没传这个头就会一直重定向到 http 再被 nginx 跳回 https形成循环。确认proxy_set_header X-Forwarded-Proto $scheme;存在并且 gateway 侧信任这个头。5.5 长连接没生效proxy_http_version 1.1和proxy_set_header Connection 必须成对出现只写一个没用。另外 upstream 块里的keepalive 64也要有否则连接池不生效。验证方法是在 nginx 日志里看 upstream 的连接复用情况或者压测时观察 TIME_WAIT 数量是否下降。6. 继续把两层网关用起来配置骨架跑通之后下一步就是按业务往里填。鉴权、限流、灰度这些逻辑优先放 gateway因为 Java 技术栈和 SpringCloud 组件对接顺畅TLS、静态资源、连接层优化留在 nginx。需要长期做编码和 Agent 调用的同学可以看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 把 Key 和调用配额统一管理起来。接入细节和参数说明都在文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里遇到鉴权或转发问题先翻文档再排查日志能省不少时间。