1. 为什么集群里需要一个 Ingress 控制器Kubernetes 集群跑起来之后最先遇到的现实问题不是 Pod 起不来而是「外面怎么进来」。Service 的 NodePort 能暴露服务但每暴露一个服务就占一个 30000-32767 的端口服务一多端口就乱而且没有基于域名和路径的转发能力。LoadBalancer 类型在自建集群里又通常没有云厂商的 LB 支持直接卡住。Ingress 就是解决这件事的它把「外部流量怎么进集群、按什么规则分发到哪个 Service」抽成一层独立的 L7 网关。Ingress 本身只是一组路由规则的声明YAML真正干活的是 Ingress Controller比如 Traefik、Nginx Ingress、HAProxy Ingress。Traefik 的优势是配置动态生效、原生支持 CRDIngressRoute、自带 Dashboard对中小集群和自建环境很友好。这篇聚焦 k8s 集群中 Ingress 控制器的选型与落地以 Traefik 为例从部署、路由规则配置到验证请求走一遍完整链路。同时说明如何通过 TaoToken 统一 Key/API 通道接入 AI 工具让集群里跑的 AI 应用、编码助手、Agent 服务共用一套接入配置不用每个服务单独维护一堆 Key。适合已经有一个能用的 k8s 集群、想补上入口网关这一层的同学。2. 部署前的准备与 TaoToken 统一接入2.1 集群与网络前提你需要一个可用的 k8s 集群单节点或高可用都行。Traefik 以 DaemonSet 或 Deployment 方式跑在集群里对外暴露 8000HTTP、8443HTTPS、9000Dashboard/管理三个端口。如果前面还有一层四层负载均衡Nginx、LVS、云 LB 都可以把 80 转到 node 的 8000、443 转到 node 的 8443 即可。我试过的机器规划大致是这样你可以按自己的网段替换角色示例 IP说明master10.0.1.176执行 kubectl 的节点node10.0.1.177 / 10.0.1.178跑 Traefik Pod负载均衡10.0.1.179四层转发到 node 的 8000/84432.2 为什么要在这一步引入 TaoToken集群里一旦开始跑 AI 相关服务——比如内部的知识库问答、代码补全服务、Agent 调度器——每个服务都要配模型 API 的 Key 和 Base URL。Key 散落在各个 Deployment 的 Secret 里轮换一次要改一堆地方还容易漏。TaoToken 提供的是统一的 Key/API 通道你申请一个 Key所有 AI 工具和服务都指向同一个 API 地址模型切换、额度管理、调用统计都在一处。对 k8s 场景来说这意味着你只需要在集群里维护一个 Secret其他服务通过环境变量引用它就行。先拿到接入信息官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api申请 Key 的页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite拿到 Key 之后在集群里建一个 Secret后面所有 AI 服务都引用它kubectl create secret generic taotoken-secret \ --from-literalTAOTOKEN_API_KEY你的Key \ -n default这样做的价值在于Traefik 负责把外部流量路由到你的 AI 服务TaoToken 负责这些服务到模型侧的通道两层各管一段职责清晰。后面配置 IngressRoute 时你的 AI 服务只需要暴露一个普通 Service入口交给 Traefik。3. 部署 Traefik 与可复制的路由配置3.1 安装 RBAC 与 Traefik 本体先在 master 节点准备两个 YAML一个是 RBACServiceAccount、ClusterRole、ClusterRoleBinding一个是 Traefik 的 Deployment/DaemonSet 加 Service。RBAC 的作用是让 Traefik 有权限监听集群里的 Ingress/Service 变化否则它拿不到路由规则。kubectl apply -f traefik-rbac.yaml kubectl apply -f traefik.yaml确认 Pod 起来了kubectl get pod -n kube-system | grep traefik正常应该看到类似traefik-xxxxx 1/1 Running。如果一直 Pending先看节点资源如果 CrashLoopBackOff多半是 RBAC 没生效或端口被占。3.2 四层负载均衡转发在负载均衡节点上把 80/443 转到 node 的 8000/8443。用 Nginx stream 模块的话配置片段如下stream { upstream traefikhttp { server 10.0.1.177:8000; server 10.0.1.178:8000; } upstream traefikhttps { server 10.0.1.177:8443; server 10.0.1.178:8443; } server { listen 80; proxy_pass traefikhttp; } server { listen 443; proxy_pass traefikhttps; } }改完nginx -t检查语法再nginx -s reload。这一步做完外部访问负载均衡 IP 的 80 端口流量就会进到 Traefik。3.3 用 IngressRoute 配置路由规则Traefik 2.x 之后推荐用 CRD 的 IngressRoute比原生 Ingress 注解更直观。假设你在test命名空间有两个服务app1-svc:9001和app2-svc:9002想让test.ingress.com/走 app1、test.ingress.com/app2/走 app2apiVersion: traefik.containo.us/v1alpha1 kind: IngressRoute metadata: name: test-ingressroute namespace: test spec: entryPoints: - web routes: - match: Host(test.ingress.com) PathPrefix(/app2) kind: Rule services: - name: app2-svc port: 9002 - match: Host(test.ingress.com) PathPrefix(/) kind: Rule services: - name: app1-svc port: 9001注意顺序更具体的/app2规则要放在/前面否则/app2会被/先匹配走。这是很多人第一次配 Traefik 会踩的坑。如果你更习惯原生 Ingress也可以保留kubernetes.io/ingress.class: traefik注解的方式Traefik 同样能识别。两种方式不要混用同一个域名容易规则冲突。3.4 配置 TLS准备好域名证书的 key 和 pem创建 Secretkubectl create secret tls testssl \ --key test.ingress.com.key \ --cert test.ingress.com.pem \ -n test然后在 IngressRoute 里加 tls 段spec: entryPoints: - websecure tls: secretName: testssl routes: - match: Host(test.ingress.com) PathPrefix(/) kind: Rule services: - name: app1-svc port: 9001websecure对应 8443 入口web对应 8000。证书 Secret 必须和 IngressRoute 在同一个命名空间跨命名空间引用会失败。4. 验证请求与成功结果4.1 绑定 hosts 并 curl内网域名先在测试机上绑 hosts指向负载均衡 IPecho 10.0.1.179 test.ingress.com /etc/hosts然后分别请求两个路径curl http://test.ingress.com/ curl http://test.ingress.com/app2/预期结果是第一个返回 app1 的内容第二个返回 app2 的内容。如果配了 TLS用curl -k https://test.ingress.com/验证-k是跳过自签证书校验正式环境换成受信任证书后可以去掉。4.2 查看 Ingress 与 Dashboard确认规则被 Traefik 识别kubectl get ingressroute -n test kubectl get ingress -n testTraefik 的 Dashboard 默认在 9000 端口可以通过端口转发本地查看kubectl port-forward -n kube-system svc/traefik 9000:9000浏览器打开http://localhost:9000在 HTTP Routers 里应该能看到你刚配的test-ingressroute状态是 enabled。这一步能直观确认规则有没有生效比只看 YAML 靠谱。4.3 验证 AI 服务走 TaoToken 通道假设你在集群里跑了一个调用模型的 AI 服务它的 Deployment 里这样引用 Secretenv: - name: TAOTOKEN_API_KEY valueFrom: secretKeyRef: name: taotoken-secret key: TAOTOKEN_API_KEY - name: TAOTOKEN_BASE_URL value: https://taotoken.net/api服务起来后在 Pod 里验证通道是否通kubectl exec -it deploy/ai-service -- sh curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head能返回模型列表就说明 Key 和通道都正常。之后这个服务再通过 Traefik 暴露出去外部访问走 Ingress模型调用走 TaoToken两条链路互不干扰。5. 本篇常见错误排查5.1 404 或路由不生效最常见的原因是规则顺序或 match 写法。Traefik 按规则顺序匹配PathPrefix(/)放前面会吃掉所有请求。另外Host里的域名必须和请求的 Host 头完全一致带端口的话要写成Host(test.ingress.com:8000)。还有一种情况是 IngressRoute 的entryPoints写错比如只写了websecure却用 http 访问自然 404。检查 Dashboard 里 Router 的状态如果是disabled或没出现基本就是 entryPoint 或 CRD 版本问题。5.2 TLS 证书不生效先确认 Secret 类型是kubernetes.io/tls用kubectl describe secret testssl -n test看有没有tls.crt和tls.key两个字段。如果 Secret 建对了但浏览器还是报证书错误检查 IngressRoute 的tls.secretName拼写以及是否和 IngressRoute 同命名空间。5.3 Traefik Pod 起不来看日志最快kubectl logs -n kube-system deploy/traefik如果是权限报错说明 RBAC 没 apply 成功如果是端口占用检查 node 上 8000/8443 是不是被别的进程占了。DaemonSet 模式下每个 node 都要能起某个 node 起不来通常是该节点有端口冲突。5.4 AI 服务调用返回 401如果 Pod 里 curl TaoToken 返回 401先确认环境变量有没有正确注入kubectl exec -it deploy/ai-service -- env | grep TAOTOKENKey 前后有没有多余空格、Secret 是不是建在了正确的命名空间这两个是最容易出问题的地方。轮换 Key 之后记得重启引用它的 Deployment环境变量不会自动刷新。6. 把入口和 AI 通道分开管理Traefik 这层解决的是「流量怎么进集群」TaoToken 这层解决的是「AI 服务怎么调模型」。两者分开之后你的 Ingress 配置不用关心模型 KeyAI 服务的 Deployment 也不用关心外部域名怎么路由。如果你还在选型阶段想先验证模型通道是否通可以直接用模型对话页面试一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite如果是要长期跑编码类服务或 Agent建议用 Coding Plan 统一管理额度和 Keyhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite集群里所有 AI 服务的 Key 都从同一个 Secret 引用轮换时只改一处。接入文档里有各语言 SDK 的 Base URL 配置示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite最后提醒一个实操细节Traefik 的 IngressRoute 规则改动后是秒级生效的不需要重启 Pod。但如果你改的是 Secret 里的 Key引用的 Pod 不会自动感知得手动 rollout restart。这两类变更的生效机制不一样排查时别搞混。
1. 为什么集群里需要一个 Ingress 控制器Kubernetes 集群跑起来之后最先遇到的现实问题不是 Pod 起不来而是「外面怎么进来」。Service 的 NodePort 能暴露服务但每暴露一个服务就占一个 30000-32767 的端口服务一多端口就乱而且没有基于域名和路径的转发能力。LoadBalancer 类型在自建集群里又通常没有云厂商的 LB 支持直接卡住。Ingress 就是解决这件事的它把「外部流量怎么进集群、按什么规则分发到哪个 Service」抽成一层独立的 L7 网关。Ingress 本身只是一组路由规则的声明YAML真正干活的是 Ingress Controller比如 Traefik、Nginx Ingress、HAProxy Ingress。Traefik 的优势是配置动态生效、原生支持 CRDIngressRoute、自带 Dashboard对中小集群和自建环境很友好。这篇聚焦 k8s 集群中 Ingress 控制器的选型与落地以 Traefik 为例从部署、路由规则配置到验证请求走一遍完整链路。同时说明如何通过 TaoToken 统一 Key/API 通道接入 AI 工具让集群里跑的 AI 应用、编码助手、Agent 服务共用一套接入配置不用每个服务单独维护一堆 Key。适合已经有一个能用的 k8s 集群、想补上入口网关这一层的同学。2. 部署前的准备与 TaoToken 统一接入2.1 集群与网络前提你需要一个可用的 k8s 集群单节点或高可用都行。Traefik 以 DaemonSet 或 Deployment 方式跑在集群里对外暴露 8000HTTP、8443HTTPS、9000Dashboard/管理三个端口。如果前面还有一层四层负载均衡Nginx、LVS、云 LB 都可以把 80 转到 node 的 8000、443 转到 node 的 8443 即可。我试过的机器规划大致是这样你可以按自己的网段替换角色示例 IP说明master10.0.1.176执行 kubectl 的节点node10.0.1.177 / 10.0.1.178跑 Traefik Pod负载均衡10.0.1.179四层转发到 node 的 8000/84432.2 为什么要在这一步引入 TaoToken集群里一旦开始跑 AI 相关服务——比如内部的知识库问答、代码补全服务、Agent 调度器——每个服务都要配模型 API 的 Key 和 Base URL。Key 散落在各个 Deployment 的 Secret 里轮换一次要改一堆地方还容易漏。TaoToken 提供的是统一的 Key/API 通道你申请一个 Key所有 AI 工具和服务都指向同一个 API 地址模型切换、额度管理、调用统计都在一处。对 k8s 场景来说这意味着你只需要在集群里维护一个 Secret其他服务通过环境变量引用它就行。先拿到接入信息官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api申请 Key 的页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite拿到 Key 之后在集群里建一个 Secret后面所有 AI 服务都引用它kubectl create secret generic taotoken-secret \ --from-literalTAOTOKEN_API_KEY你的Key \ -n default这样做的价值在于Traefik 负责把外部流量路由到你的 AI 服务TaoToken 负责这些服务到模型侧的通道两层各管一段职责清晰。后面配置 IngressRoute 时你的 AI 服务只需要暴露一个普通 Service入口交给 Traefik。3. 部署 Traefik 与可复制的路由配置3.1 安装 RBAC 与 Traefik 本体先在 master 节点准备两个 YAML一个是 RBACServiceAccount、ClusterRole、ClusterRoleBinding一个是 Traefik 的 Deployment/DaemonSet 加 Service。RBAC 的作用是让 Traefik 有权限监听集群里的 Ingress/Service 变化否则它拿不到路由规则。kubectl apply -f traefik-rbac.yaml kubectl apply -f traefik.yaml确认 Pod 起来了kubectl get pod -n kube-system | grep traefik正常应该看到类似traefik-xxxxx 1/1 Running。如果一直 Pending先看节点资源如果 CrashLoopBackOff多半是 RBAC 没生效或端口被占。3.2 四层负载均衡转发在负载均衡节点上把 80/443 转到 node 的 8000/8443。用 Nginx stream 模块的话配置片段如下stream { upstream traefikhttp { server 10.0.1.177:8000; server 10.0.1.178:8000; } upstream traefikhttps { server 10.0.1.177:8443; server 10.0.1.178:8443; } server { listen 80; proxy_pass traefikhttp; } server { listen 443; proxy_pass traefikhttps; } }改完nginx -t检查语法再nginx -s reload。这一步做完外部访问负载均衡 IP 的 80 端口流量就会进到 Traefik。3.3 用 IngressRoute 配置路由规则Traefik 2.x 之后推荐用 CRD 的 IngressRoute比原生 Ingress 注解更直观。假设你在test命名空间有两个服务app1-svc:9001和app2-svc:9002想让test.ingress.com/走 app1、test.ingress.com/app2/走 app2apiVersion: traefik.containo.us/v1alpha1 kind: IngressRoute metadata: name: test-ingressroute namespace: test spec: entryPoints: - web routes: - match: Host(test.ingress.com) PathPrefix(/app2) kind: Rule services: - name: app2-svc port: 9002 - match: Host(test.ingress.com) PathPrefix(/) kind: Rule services: - name: app1-svc port: 9001注意顺序更具体的/app2规则要放在/前面否则/app2会被/先匹配走。这是很多人第一次配 Traefik 会踩的坑。如果你更习惯原生 Ingress也可以保留kubernetes.io/ingress.class: traefik注解的方式Traefik 同样能识别。两种方式不要混用同一个域名容易规则冲突。3.4 配置 TLS准备好域名证书的 key 和 pem创建 Secretkubectl create secret tls testssl \ --key test.ingress.com.key \ --cert test.ingress.com.pem \ -n test然后在 IngressRoute 里加 tls 段spec: entryPoints: - websecure tls: secretName: testssl routes: - match: Host(test.ingress.com) PathPrefix(/) kind: Rule services: - name: app1-svc port: 9001websecure对应 8443 入口web对应 8000。证书 Secret 必须和 IngressRoute 在同一个命名空间跨命名空间引用会失败。4. 验证请求与成功结果4.1 绑定 hosts 并 curl内网域名先在测试机上绑 hosts指向负载均衡 IPecho 10.0.1.179 test.ingress.com /etc/hosts然后分别请求两个路径curl http://test.ingress.com/ curl http://test.ingress.com/app2/预期结果是第一个返回 app1 的内容第二个返回 app2 的内容。如果配了 TLS用curl -k https://test.ingress.com/验证-k是跳过自签证书校验正式环境换成受信任证书后可以去掉。4.2 查看 Ingress 与 Dashboard确认规则被 Traefik 识别kubectl get ingressroute -n test kubectl get ingress -n testTraefik 的 Dashboard 默认在 9000 端口可以通过端口转发本地查看kubectl port-forward -n kube-system svc/traefik 9000:9000浏览器打开http://localhost:9000在 HTTP Routers 里应该能看到你刚配的test-ingressroute状态是 enabled。这一步能直观确认规则有没有生效比只看 YAML 靠谱。4.3 验证 AI 服务走 TaoToken 通道假设你在集群里跑了一个调用模型的 AI 服务它的 Deployment 里这样引用 Secretenv: - name: TAOTOKEN_API_KEY valueFrom: secretKeyRef: name: taotoken-secret key: TAOTOKEN_API_KEY - name: TAOTOKEN_BASE_URL value: https://taotoken.net/api服务起来后在 Pod 里验证通道是否通kubectl exec -it deploy/ai-service -- sh curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head能返回模型列表就说明 Key 和通道都正常。之后这个服务再通过 Traefik 暴露出去外部访问走 Ingress模型调用走 TaoToken两条链路互不干扰。5. 本篇常见错误排查5.1 404 或路由不生效最常见的原因是规则顺序或 match 写法。Traefik 按规则顺序匹配PathPrefix(/)放前面会吃掉所有请求。另外Host里的域名必须和请求的 Host 头完全一致带端口的话要写成Host(test.ingress.com:8000)。还有一种情况是 IngressRoute 的entryPoints写错比如只写了websecure却用 http 访问自然 404。检查 Dashboard 里 Router 的状态如果是disabled或没出现基本就是 entryPoint 或 CRD 版本问题。5.2 TLS 证书不生效先确认 Secret 类型是kubernetes.io/tls用kubectl describe secret testssl -n test看有没有tls.crt和tls.key两个字段。如果 Secret 建对了但浏览器还是报证书错误检查 IngressRoute 的tls.secretName拼写以及是否和 IngressRoute 同命名空间。5.3 Traefik Pod 起不来看日志最快kubectl logs -n kube-system deploy/traefik如果是权限报错说明 RBAC 没 apply 成功如果是端口占用检查 node 上 8000/8443 是不是被别的进程占了。DaemonSet 模式下每个 node 都要能起某个 node 起不来通常是该节点有端口冲突。5.4 AI 服务调用返回 401如果 Pod 里 curl TaoToken 返回 401先确认环境变量有没有正确注入kubectl exec -it deploy/ai-service -- env | grep TAOTOKENKey 前后有没有多余空格、Secret 是不是建在了正确的命名空间这两个是最容易出问题的地方。轮换 Key 之后记得重启引用它的 Deployment环境变量不会自动刷新。6. 把入口和 AI 通道分开管理Traefik 这层解决的是「流量怎么进集群」TaoToken 这层解决的是「AI 服务怎么调模型」。两者分开之后你的 Ingress 配置不用关心模型 KeyAI 服务的 Deployment 也不用关心外部域名怎么路由。如果你还在选型阶段想先验证模型通道是否通可以直接用模型对话页面试一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite如果是要长期跑编码类服务或 Agent建议用 Coding Plan 统一管理额度和 Keyhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite集群里所有 AI 服务的 Key 都从同一个 Secret 引用轮换时只改一处。接入文档里有各语言 SDK 的 Base URL 配置示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite最后提醒一个实操细节Traefik 的 IngressRoute 规则改动后是秒级生效的不需要重启 Pod。但如果你改的是 Secret 里的 Key引用的 Pod 不会自动感知得手动 rollout restart。这两类变更的生效机制不一样排查时别搞混。
发布！程序员进阶指南：TaoToken统一Key配置与settings.json骨架)
