企业官网建设流程全解析

1. 从一次 502 说起：nginx-ingress 的坑和 AI 工具接入有什么关系

Kubernetes 里用 nginx-ingress 暴露服务，几乎是每个集群的标配动作。Ingress 本身只是一个抽象对象，它定义的是「流量从哪进来、往哪走」的规则，真正干活、把规则翻译成 nginx 配置并热加载的，是 Ingress Controller。官方维护的 Nginx Ingress Controller 用得最多，Traefik、Kong 也各有拥趸，但绝大多数人第一次踩坑，都踩在 nginx 这一版上。

我遇到最多的问题不是「配不出来」，而是「配出来了但行为跟想的不一样」：path 写/service/结果请求打到了后端根目录、rewrite 没生效导致 404、host 不写以为能通结果只能走 IP、TLS 配了但证书没挂上、注解写错一个字母整个 Ingress 静默失效。这些坑的共同点是——报错信息很少，排查全靠经验和kubectl describe。

而另一条线是：现在集群里跑的 AI 工具越来越多，Claude Code、Cursor、各种 Agent 都要调模型 API。如果每个工具各配一套 Key、各写一份 base_url，密钥散落在十几个 settings.json 和 config.toml 里，改一次要翻半天。所以这篇把两件事放一起讲：一边把 nginx-ingress 的常见坑逐个填平，一边用 TaoToken 的统一 Key 把 AI 工具的调用链路收敛到一个入口。你排查 ingress 的同时，顺手把 AI 工具的接入也理顺。

适合谁看：正在被 nginx-ingress 的 path/rewrite/TLS 折磨的后端或运维同学；以及想在 K8s 环境里统一管理 AI 工具 Key、不想每个工具单独配一遍的开发者。下面所有配置都可以直接复制改。

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

TaoToken 在这里扮演的角色，是给所有 AI 工具提供一个统一的 API 入口和一把 Key。你不需要在每个工具里填不同的厂商地址和密钥，只要把 base_url 指向同一个通道，Key 用同一把，后面换模型、加工具都只改一处。

官网入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （这个地址不加 UTM 参数，直接用于配置）。先去控制台把 Key 建出来，路径是 console 页面，然后在 API Keys 里生成一把。

具体动作分三步。第一步，打开控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，登录后进 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，点新建，复制那串以sk-开头的 Key，先存到本地环境变量里，别直接写进 YAML。

export TAOTOKEN_API_KEY="sk-你的key" echo $TAOTOKEN_API_KEY | head -c 8

第二步，确认通道地址。所有工具的 base_url 统一填https://taotoken.net/api，注意结尾不要多加/v1，具体路径由各工具自己拼。第三步，如果你要长期在集群里跑编码类 Agent，建议直接看 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，它比按量调用更适合持续性的编码场景。接入细节和参数说明在文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 里，遇到字段不确定就翻这里。

注意：Key 属于敏感信息，在 K8s 里请用 Secret 挂载，不要硬编码进 Ingress 注解或 ConfigMap 明文里。后面第 3 节会给 Secret 的写法。

3. 可复制配置：ingress 注解 + 工具 settings 骨架

先解决 nginx-ingress 的坑，再给 AI 工具的配置骨架。这两块可以并行做，互不干扰。

3.1 nginx-ingress 的 path 与 rewrite 正确写法

最常见的坑是 path 只能转到后端根目录。比如你写path: /service/，生成的规则是example.com/service/ -> app1:8080/，请求里的/service/被吃掉了。如果后端实际路由在/s1/，就必须 rewrite。正确写法是用configuration-snippet注解：

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: example-ingress annotations: nginx.ingress.kubernetes.io/configuration-snippet: | rewrite /service/(.*) /s1/$1 break; nginx.ingress.kubernetes.io/use-regex: "true" spec: ingressClassName: nginx rules: - host: example.com http: paths: - path: /service/ pathType: Prefix backend: service: name: app1 port: number: 8080

这里有两个容易忽略的点。一是pathType必须显式写，Prefix和Exact行为不同，不写在某些版本会报错或按默认处理。二是use-regex注解，如果你 path 里用了正则，必须打开它，否则 nginx 不认。老版本用的extensions/v1beta1和serviceName/servicePort字段在新集群已经废弃，换成上面networking.k8s.io/v1的写法，否则 apply 会直接失败。

3.2 host 不写会怎样

host 不指定时，任何能转发到节点 80 端口的请求都能进来，包括直接用 IP 访问。指定了 host，就只有匹配该域名的请求才路由。生产环境建议显式写 host，避免被扫到。如果你确实需要 IP 直连调试，可以临时不写，但别带到线上。

3.3 TLS 配置与 Secret

证书用 Secret 存，别写进 Ingress。创建命令：

kubectl create secret tls tls-secret-name \ --key your_key.key \ --cert your_cert.crt

然后在 Ingress 里引用：

spec: tls: - hosts: - example.com secretName: tls-secret-name

坑点：Secret 必须和 Ingress 在同一个 namespace，跨 namespace 引用不会报错但证书不生效。另外证书链不完整时浏览器会警告，.crt里要把中间证书一起带上。

3.4 AI 工具的 settings.json 与 config.toml 骨架

Claude Code 这类工具用 settings.json，把 base_url 和 Key 指到 TaoToken：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的key" } }

其他走 config.toml 的工具：

[api] base_url = "https://taotoken.net/api" api_key = "sk-你的key" model = "claude-sonnet"

在 K8s 里跑的话，把 Key 放进 Secret，用环境变量注入：

apiVersion: v1 kind: Secret metadata: name: taotoken-secret type: Opaque stringData: api-key: "sk-你的key"

Pod 里通过envFrom或valueFrom引用，容器内工具读环境变量即可，配置文件里不出现明文。

4. 验证请求：curl 打通 ingress 与 API 两条链路

配置写完不验证等于没写。分两步，先验 ingress，再验 TaoToken 通道。

4.1 验证 ingress 路由

先看 Ingress 有没有被 Controller 正确解析：

kubectl describe ingress example-ingress

重点看 Events 里有没有rewrite相关的报错，以及 Rules 是否和你写的一致。然后用 curl 打实际路径，带上 Host 头模拟域名访问：

curl -v -H "Host: example.com" http://<节点IP>/service/health

如果返回 200 且后端日志里看到的是/s1/health，说明 rewrite 生效。如果返回 404，先确认后端服务本身有没有/s1/这个路由，再看 rewrite 规则有没有被use-regex影响。返回 502 通常是后端 Pod 没起来或端口不对，用kubectl get endpoints app1确认 Endpoints 是否为空。

4.2 验证 TaoToken 通道连通性

用 curl 直接打 API 基址，确认 Key 和通道都正常：

curl -s -o /dev/null -w "%{http_code}\n" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ https://taotoken.net/api

返回 200 或 401 都说明网络通、地址对（401 是 Key 问题，200 是正常）。如果超时，检查集群出网策略和 DNS。想直接对话验证模型是否可用，去模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 发一条消息，能正常返回就说明整条链路通了。

提示：在 Pod 内验证时，注意容器镜像里有没有 curl。没有的话用wget --spider或临时起一个带 curl 的 debug 容器。

5. 本篇常见错排查

Ingress apply 报 unknown field "serviceName"：你用的是旧版extensions/v1beta1写法，换成networking.k8s.io/v1，backend 改成service.name和service.port.number。

rewrite 不生效，请求还是打到根目录：检查configuration-snippet注解有没有拼错，以及 Controller 是否允许 snippet（有些集群默认禁用allow-snippet-annotations，需要 ConfigMap 里打开）。

TLS 配了但走 http 不跳转 https：加注解nginx.ingress.kubernetes.io/ssl-redirect: "true"，并确认force-ssl-redirect没被全局关掉。

curl 返回 308 一直重定向：多半是 ssl-redirect 和 force-ssl-redirect 同时开着，或者后端自己又跳了一次，用curl -L跟一下最终落点。

TaoToken 返回 401：Key 复制时带了空格，或者环境变量没 export 成功。用echo $TAOTOKEN_API_KEY | wc -c看长度对不对。

Pod 里读不到 Key：Secret 的 key 名和valueFrom.secretKeyRef.key不一致，或者 Secret 和 Pod 不在同一 namespace。

模型调用超时但 curl 基址正常：检查工具里 base_url 是不是多写了/v1，路径重复会导致 404 或超时。

6. 把 Key 收敛到一处，后面少改十次

nginx-ingress 的坑，本质是「抽象层和实际 nginx 行为之间的信息差」，注解就是填这个差的工具。把 path、rewrite、TLS 这三块按上面的写法固定下来，后面加服务基本就是复制改名字。而 AI 工具的接入，核心思路是别让 Key 散落各处——统一走 TaoToken 的通道，base_url 和 Key 各工具共用一份，换模型、加工具都只动一个地方。

如果你还在逐个工具配 Key，建议先去 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 把 Key 建好，再按第 3 节的骨架把 settings.json 和 config.toml 改一遍。长期在集群里跑编码 Agent 的话，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 比按量更省心。配置过程中卡在哪个字段，文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 里都有对照说明。

最后留一个我踩过的坑：改完 Ingress 注解后，Controller 热加载有延迟，别急着下结论说没生效，等 5 到 10 秒再 curl 一次，或者看 Controller Pod 日志确认 reload 完成。