企业官网建设流程全解析

1. nginx pod 代理 traefik 后 502/404 的链路断点在哪

在 k8s 集群里用 nginx 的 pod 反向代理到 traefik，再由 traefik 按 IngressRoute 规则调度到后端业务 pod，这套结构本身很常见：nginx 负责统一入口和静态资源，traefik 负责动态服务发现和负载均衡。但真正跑起来之后，很多人会遇到一个很别扭的现象——刚部署完访问正常，改一次 Service 或者滚动更新一次 yaml，nginx 这边就开始 502 Bad Gateway 或者 404 Not Found，而直接访问 traefik 的 Service 又是通的。

这个问题的核心不是 nginx 配置写错了，也不是 traefik 的 IngressRoute 规则有问题，而是nginx pod 里 proxy_pass 指向的那个上游地址，在 Service 重建后 IP 变了，而 nginx 的 resolver 没有跟着更新。nginx 默认在启动时解析一次域名就缓存住，除非显式配置 resolver 和变量式 proxy_pass，否则它不会重新去查 CoreDNS。Service 被 replace 或者 selector 变更后 ClusterIP 重新分配，nginx 还拿着旧 IP 去连，自然 502。

另一个容易混淆的点是 404。404 通常不是 nginx 连不上，而是请求已经透传到 traefik 了，但 traefik 根据 Host 或者 Path 匹配不到对应的 IngressRoute，于是返回自己的 404 页面。这时候你要区分：502 是链路断在 nginx→traefik 这一段，404 是断在 traefik→后端 service 这一段。两者排查方向完全不同。

我试过在同一个集群里同时跑 nginx Deployment 和 traefik Deployment，用 nginx 的 configMap 挂载配置，改完配置 nginx reload 就能恢复，但过一段时间 Service 变动后又挂。后来才定位到是 ClusterIP 漂移 + nginx DNS 缓存的问题。这篇就把可复制的 nginx.conf 代理段、traefik IngressRoute YAML、固定 ClusterIP 的 Service 写法，以及用 TaoToken 统一 Key 核对上游鉴权头的验证命令都整理出来，让你从 nginx pod 到 traefik 后端这条链路稳定透传。

适合正在搭 k8s 入口层、被 nginx 反代 traefik 的 502/404 卡住的运维和 backend 同学，也适合想把 nodePort 换成更优雅方案的人。

2. 前置：TaoToken 统一 Key 与 API 通道准备

在排查 nginx→traefik 链路之前，先要把上游鉴权这一层理清楚。很多 502 其实不是网络不通，而是 traefik 后面的后端服务要求带 Authorization 头，nginx 转发时把 header 丢了，或者 Key 不对，后端直接拒绝。这时候用 TaoToken 的统一 Key 和 API 通道来核对请求头，能快速判断是链路问题还是鉴权问题。

TaoToken 是一个统一的大模型 API 接入通道，官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。它的作用是把你对不同模型服务的调用收敛到一个 Base URL 和一把 Key 上，这样在 k8s 里做上游鉴权核对时，不用来回切换多套凭证。

你需要准备的东西不多：一个 TaoToken 账号，一把 API Key，以及集群里能跑 curl 的 pod。Key 的获取路径是登录后进控制台，在 API Keys 页面创建。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，API Keys 页面是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建完把 Key 复制出来，后面在 nginx 的 proxy_set_header 里会用到。

这里要强调一个概念：TaoToken 的统一 Key 不是用来替代 traefik 的，而是用来做上游鉴权头的统一管理。你的 nginx pod 在 proxy_pass 到 traefik 时，可以带上这个 Key 作为 Authorization 头，traefik 再往后端转发。这样整条链路的鉴权凭证是一致的，排查时只要用同一个 Key 去 curl，就能判断是 nginx 没转发 header，还是 traefik 的 middleware 把 header 吃掉了。

如果你后面要做长期编码或者 Agent 类任务，可以了解 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。模型对话调试入口在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。Claude Code 相关的 Anthropic 接入说明在 https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite 。

前置准备清单：确认 CoreDNS 正常、确认 traefik 的 Service 有 ClusterIP、确认 nginx pod 能解析集群内域名、确认 TaoToken Key 已创建。这四件事做完，再往下配 nginx.conf 和 IngressRoute，排查效率会高很多。

3. 可复制配置：nginx.conf 代理段 + traefik IngressRoute + 固定 ClusterIP

这一节是整篇的核心，直接给可复制的配置。先说 nginx 的 configMap，关键是 resolver 和变量式 proxy_pass，这两点决定了 Service IP 变化后 nginx 能不能重新解析。

# nginx-configmap.yaml apiVersion: v1 kind: ConfigMap metadata: name: nginx-proxy-config namespace: default data: nginx.conf: | user nginx; worker_processes auto; error_log /var/log/nginx/error.log warn; pid /var/run/nginx.pid; events { worker_connections 1024; } http { include /etc/nginx/mime.types; default_type application/octet-stream; log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for" ' 'upstream=$upstream_addr'; access_log /var/log/nginx/access.log main; # 关键：指向 CoreDNS，让 nginx 能动态解析集群内 Service resolver kube-dns.kube-system.svc.cluster.local valid=10s ipv6=off; server { listen 80; server_name _; location /a1app/ { # 变量式 proxy_pass，强制每次请求走 resolver set $traefik_upstream "traefik.default.svc.cluster.local"; proxy_pass http://$traefik_upstream:80; proxy_http_version 1.1; 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; # 带上 TaoToken 统一 Key 作为上游鉴权头 proxy_set_header Authorization "Bearer sk-你的TaoTokenKey"; proxy_connect_timeout 5s; proxy_read_timeout 30s; proxy_send_timeout 30s; } } }

注意 resolver 那行的valid=10s，意思是 DNS 缓存 10 秒。Service IP 变了之后，最多 10 秒 nginx 就会重新解析。如果你不写变量式 proxy_pass，nginx 启动时解析一次就固定了，这就是为什么改 Service 后必须 reload 才能恢复。

然后是 traefik 的 IngressRoute，这里用 CRD 方式，比传统 Ingress 更灵活：

# traefik-ingressroute.yaml apiVersion: traefik.io/v1alpha1 kind: IngressRoute metadata: name: a1app-route namespace: default spec: entryPoints: - web routes: - match: PathPrefix(`/a1app`) kind: Rule services: - name: a1app-service port: 8080 middlewares: - name: auth-check --- apiVersion: traefik.io/v1alpha1 kind: Middleware metadata: name: auth-check namespace: default spec: headers: customRequestHeaders: X-Forwarded-By: "nginx-proxy"

再给固定 ClusterIP 的 Service 写法，这是解决 IP 漂移最直接的方式：

# nginx-service-fixed.yaml apiVersion: v1 kind: Service metadata: name: my-nginx namespace: default labels: app: my-nginx spec: clusterIP: 10.254.63.240 ports: - port: 80 targetPort: 80 protocol: TCP selector: app: my-nginx type: ClusterIP

把 clusterIP 写死之后，即使 Service 被 replace，只要这个 IP 没被占用，k8s 就会复用。这样 nginx 里 proxy_pass 指向的地址就稳定了。不过要注意，固定 IP 要选在 Service CIDR 范围内，且没被其他 Service 占用，否则创建会失败。

如果你用 Cline MCP 或者 Codex 的 auth.json 做本地调试，配置三件套是 Base URL、Key、Model ID。Base URL 填 https://taotoken.net/api ，Key 填你的 TaoToken Key，Model ID 按文档填对应模型标识。这三样对齐了，本地请求才能和集群内请求走同一套鉴权逻辑。

4. 验证请求：从 nginx pod 到 traefik 后端的 curl 命令

配置写完，必须验证。验证要分层做，从 nginx pod 内部往外打，一层层确认。

第一步，进 nginx pod：

kubectl exec -it deploy/my-nginx -- /bin/sh

第二步，在 pod 内解析 traefik 的 Service 域名，确认 CoreDNS 正常：

nslookup traefik.default.svc.cluster.local

正常应该返回 traefik Service 的 ClusterIP。如果这里就失败，说明 CoreDNS 或者 Service 有问题，先解决这个。

第三步，直接 curl traefik 的 Service，绕过 nginx：

curl -v http://traefik.default.svc.cluster.local/a1app/health \ -H "Authorization: Bearer sk-你的TaoTokenKey"

如果这一步返回 200，说明 traefik 和后端是通的，问题在 nginx 配置。如果返回 404，说明 traefik 的 IngressRoute 匹配规则有问题，检查 PathPrefix 和 Host。如果返回 502，说明 traefik 连不上后端 Service，检查后端 pod 的 readiness 和端口。

第四步，curl nginx 自己的入口，验证整条链路：

curl -v http://my-nginx.default.svc.cluster.local/a1app/health \ -H "Authorization: Bearer sk-你的TaoTokenKey"

这一步如果 502，回到 nginx pod 里看 error.log：

kubectl logs deploy/my-nginx --tail=50

重点看upstream=后面的地址，如果是一个已经不存在的旧 IP，那就是 DNS 缓存问题，确认 resolver 和变量式 proxy_pass 都写对了。

第五步，用 TaoToken 的模型对话接口做一次端到端验证，确认鉴权头透传正确：

curl -v https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的TaoTokenKey" \ -d '{ "model": "你的模型ID", "messages": [{"role": "user", "content": "ping"}] }'

这个请求如果返回正常，说明你的 Key 和 Base URL 是对的。然后把这个 Authorization 头原样放到 nginx 的 proxy_set_header 里，再走一遍 nginx→traefik 链路，对比结果。

实测下来，最容易出问题的是 header 大小写和空格。nginx 的 proxy_set_header 里Bearer后面必须有一个空格，Key 不能有多余换行。traefik 的 middleware 如果配了 customRequestHeaders，可能会覆盖掉 nginx 传过来的 Authorization，这时候要么去掉 middleware 里的覆盖，要么在 middleware 里显式保留。

验证通过的标准是：从集群外访问 nginx 的 nodePort 或者 LoadBalancer，能稳定拿到后端响应，且 Service 滚动更新后不需要手动 reload nginx。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

这一节把真实会撞到的报错列出来，对照着查。

401 Unauthorized：这个最常见。表现是 nginx 返回 401，但 traefik 日志里看不到请求。原因通常是 nginx 的 proxy_set_header Authorization 没写对，或者 Key 过期。排查方法是在 nginx pod 里 curl 后端，带上和不带 Authorization 各试一次。如果带 Key 通、不带不通，说明后端确实要鉴权，检查 nginx 配置里 header 有没有被覆盖。TaoToken 的 Key 可以在 API Keys 页面重新生成，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

local proxy failed：这个报错通常出现在本地调试工具或者 Cline MCP 场景。意思是本地代理进程连不上目标地址。在 k8s 场景下，等价于 nginx 连不上 traefik。检查三件事：traefik 的 Service 是否存在、ClusterIP 是否和 nginx 里配的一致、网络策略 NetworkPolicy 是否放行了 nginx pod 到 traefik pod 的流量。如果用了固定 ClusterIP，确认这个 IP 没被其他 Service 抢走。

reading choices 相关报错：这类报错一般出现在调用大模型接口时，响应体解析失败。在 nginx→traefik 链路里，如果后端是一个模型服务，nginx 的 proxy_read_timeout 太短会导致连接被切断，客户端读到半截响应就报解析错误。把 proxy_read_timeout 调到 60s 以上，并且确认 proxy_buffering 设置合理。如果响应是流式的，还要加proxy_set_header Connection ""和proxy_http_version 1.1。

OAuth 相关报错：如果 traefik 前面挂了 OAuth middleware，nginx 转发时可能会丢掉 cookie 或者 state 参数。检查 nginx 是否透传了 Cookie 头，traefik 的 OAuth middleware 配置里 redirect 地址是否和 nginx 暴露的地址一致。OAuth 回调地址不匹配会直接 400 或者 403。

404 但后端明明有服务：检查 traefik IngressRoute 的 match 规则。PathPrefix 是区分大小写的，/a1app和/A1App不一样。另外如果 nginx 的 location 是/a1app/，proxy_pass 后面没有斜杠，路径拼接会多一层或者少一层。用curl -v看实际请求的 path 是什么。

502 且 nginx error.log 显示 no resolver defined：说明 proxy_pass 用了变量但没配 resolver。加上resolver kube-dns.kube-system.svc.cluster.local valid=10s;即可。

Service 更新后必须 reload nginx 才恢复：这就是 DNS 缓存问题。确认 proxy_pass 用的是变量，且 resolver 的 valid 时间不要太长。如果还是不行，检查 nginx 版本，老版本对变量式 proxy_pass 的 resolver 支持有差异。

排查顺序建议：先看 nginx error.log 的 upstream 地址，再看 traefik 的 access log，最后看后端 pod 的日志。三层日志对时间戳，很快能定位断点在哪。

6. 稳定透传后的接入方式与长期使用建议

链路调通之后，日常使用就顺了。nginx pod 负责统一入口，traefik 负责动态路由，后端 pod 滚动更新不影响入口。固定 ClusterIP 这个做法比 nodePort 优雅的地方在于，nodePort 会占用每个节点的端口，端口范围有限，而且节点 IP 变化后客户端要改配置。ClusterIP 固定在集群内部，外部通过 nginx 的 LoadBalancer 或者 nodePort 进来，内部链路稳定。

如果你要把这套结构用到模型服务上，TaoToken 的接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有 Base URL、Key、Model ID 的完整说明。模型对话调试可以用 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。长期跑编码或者 Agent 任务，Coding Plan 在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。

最后给几个实用技巧。第一，nginx 的 resolver valid 时间设 10s 到 30s 之间，太短会增加 CoreDNS 压力，太长会导致 Service 变更后恢复慢。第二，固定 ClusterIP 要记录在案，避免和后续创建的 Service 冲突。第三，traefik 的 IngressRoute 用 PathPrefix 时，注意和 nginx location 的路径拼接，最好在 nginx 里用 rewrite 把前缀去掉再转发。第四，所有鉴权头统一用 TaoToken 的 Key，这样排查时只需要核对一个凭证，不用在多个 Key 之间切换。

这套配置我在多个集群里跑过，稳定运行的关键就是 resolver + 变量式 proxy_pass + 固定 ClusterIP 这三件套。少任何一个，Service 变更后都可能要手动 reload。把这三样配齐，nginx pod 到 traefik 后端的透传就不会再断。