1. 一次诡异的 404nginx 日志干净得让人发毛如果你在 k3s 里部署完服务浏览器访问域名却只看到一行冷冰冰的404 page not found第一反应大概率是去翻 nginx 的 access.log 和 error.log。结果日志里干干净净连一条请求记录都没有——这时候你就该意识到请求压根没走到 nginx 这一层。我这次遇到的场景就是这样k3s 单节点集群服务用 Deployment 跑着Service 是 ClusterIPIngress 用的是 k3s 自带的 Traefik。域名解析没问题curl本地 Pod IP 能拿到正常页面但一从外部访问域名返回的就是 Traefik 默认的 404 页面。更迷惑的是kubectl get pods里 nginx 的 Pod 状态是 Runningkubectl logs里没有任何异常kubectl get ingress也显示 ADDRESS 有值。这个 404 的本质是请求到达了 Traefik但 Traefik 没有匹配到任何 IngressRoute 规则于是返回了默认的 404。问题不在 nginx也不在 Service而在 Traefik 到 Service 之间的路由匹配以及更底层的 iptables 转发链路。下面我把整条链路拆开逐层验证每一步都给可复制的命令。2. 前置准备确认 k3s 与 Traefik 的版本和入口在开始排查之前先把环境信息固定下来。k3s 不同版本自带的 Traefik 版本差异较大IngressRoute 的 API 版本和字段名会变所以第一步是确认版本。# 查看 k3s 版本 k3s --version # 查看 Traefik 相关 Pod kubectl get pods -n kube-system | grep traefik # 查看 Traefik Service kubectl get svc -n kube-system -o wide | grep traefik我这边输出大致是k3s version v1.28.2k3s1 traefik-7d9f8c6b5-xxxxx 1/1 Running 0 3d traefik LoadBalancer 10.43.0.1 192.168.1.100 80:30080/TCP,443:30443/TCP注意这里traefik这个 Service 的类型是 LoadBalancerk3s 内置的 ServiceLB也就是 klipper-lb会给它分配一个外部 IP同时把 80 和 443 映射到节点端口。如果你的节点上已经有别的进程占用了 80/443或者 iptables 里有旧的 DNAT 规则流量就会被劫持到别的地方这正是我这次踩坑的核心。提示k3s 默认会把 Traefik 的 80/443 通过 ServiceLB 暴露到节点上。如果你之前装过 nginx、apache 或者别的反向代理先确认端口占用情况。3. 可复制配置从 IngressRoute 到 Service 的完整定义排查 404 的第一步是确认你的 IngressRoute 到底有没有正确匹配。下面是一个最小可用的 IngressRoute 配置我把它拆成三块Deployment、Service、IngressRoute。apiVersion: apps/v1 kind: Deployment metadata: name: web-demo namespace: default spec: replicas: 1 selector: matchLabels: app: web-demo template: metadata: labels: app: web-demo spec: containers: - name: nginx image: nginx:1.25-alpine ports: - containerPort: 80 --- apiVersion: v1 kind: Service metadata: name: web-demo-svc namespace: default spec: selector: app: web-demo ports: - name: http port: 80 targetPort: 80 --- apiVersion: traefik.io/v1alpha1 kind: IngressRoute metadata: name: web-demo-route namespace: default spec: entryPoints: - web routes: - match: Host(demo.example.com) kind: Rule services: - name: web-demo-svc port: 80关键点有三个entryPoints必须是web对应 80或websecure对应 443match里的 Host 必须和你的访问域名完全一致services里的 name 和 port 必须和 Service 对得上。任何一处写错Traefik 都会返回 404。应用之后用下面的命令确认资源都创建成功kubectl apply -f web-demo.yaml kubectl get ingressroute -n default kubectl get svc web-demo-svc -n default kubectl get endpoints web-demo-svc -n defaultkubectl get endpoints这一步特别重要。如果 Endpoints 是空的说明 Service 的 selector 没匹配到任何 PodTraefik 即使匹配到了路由也会因为后端为空而返回 404 或 503。4. 逐层验证Service、Endpoint、IngressRoute 与 iptables4.1 验证 Service 和 Endpoint# 查看 Service 详情确认 selector 和 port kubectl describe svc web-demo-svc -n default # 查看 Endpoint必须有 Pod IP:Port kubectl get endpoints web-demo-svc -n default -o wide正常输出应该是NAME ENDPOINTS AGE web-demo-svc 10.42.0.15:80 5m如果 ENDPOINTS 显示none就去检查 Pod 的 labels 是否和 Service 的 selector 一致。这一步用kubectl get pods --show-labels对照即可。4.2 验证 IngressRoute 是否被 Traefik 识别# 查看 Traefik 的 dashboard 端口或者直接看 CRD 状态 kubectl get ingressroute web-demo-route -n default -o yaml # 查看 Traefik 日志确认有没有加载路由 kubectl logs -n kube-system -l app.kubernetes.io/nametraefik --tail100Traefik 日志里如果出现No matching route found或者rule not matched基本就是 match 写错了。我这次的问题是 Host 写成了demo.example.com但实际访问的是www.demo.example.com差一个www就 404。4.3 验证 iptables 转发链路这是最容易被忽略的一层。k3s 的 ServiceLB 会在节点上写 iptables 规则把外部流量 DNAT 到 Traefik 的 Pod。如果节点上之前有别的服务占用了 80/443iptables 里可能残留旧的 DNAT 规则导致流量被转到错误的后端。# 查看 nat 表中 80 和 443 的 DNAT 规则 sudo iptables -L -n -t nat | grep -E 80|443 # 查看具体的 DNAT 目标 sudo iptables -t nat -L PREROUTING -n -v --line-numbers我当时的输出里出现了两条 80 端口的 DNAT一条指向 Traefik 的 Pod IP另一条指向一个已经不存在的旧 Pod IP。旧规则优先级更高流量就被转到了那个已经不存在的地址表现就是 404 或者连接超时。清理旧规则的方法是先确认规则编号然后删除# 假设旧规则在 PREROUTING 链的第 3 条 sudo iptables -t nat -D PREROUTING 3注意直接操作 iptables 有风险建议先iptables-save /tmp/iptables.bak备份确认无误后再删除。k3s 重启后会自动重建 ServiceLB 的规则所以手动删掉的旧规则不会影响 k3s 自身。4.4 完整请求链路验证动作把上面几步串起来做一次端到端验证# 1. 从集群内部直接访问 Service kubectl run curl-test --rm -it --imagecurlimages/curl -- sh curl -H Host: demo.example.com http://web-demo-svc.default.svc.cluster.local # 2. 从节点上访问 Traefik 的 NodePort curl -H Host: demo.example.com http://127.0.0.1:30080 # 3. 从外部访问域名 curl -v -H Host: demo.example.com http://节点IP如果第 1 步通、第 2 步不通问题在 Traefik 到 Service 的路由如果第 2 步通、第 3 步不通问题在 iptables 或节点端口映射。我这次就是第 2 步通、第 3 步不通最终定位到 iptables 旧规则。5. 本篇常见错排查清单下面这张表是我在实际排查中整理出来的高频错误按出现概率排序现象可能原因验证命令修复方式404 page not foundIngressRoute match 写错kubectl logs -n kube-system -l app.kubernetes.io/nametraefik修正 Host 或 Path404 且 nginx 无日志请求未到达 nginxkubectl get endpoints检查 Service selector404 但 Endpoint 正常Traefik 未加载路由kubectl get ingressroute -o yaml确认 CRD 版本和 entryPoints连接被拒绝iptables 旧规则劫持iptables -L -n -t nat | grep 80删除旧 DNAT 规则证书错误用了 Traefik 默认证书kubectl get secret -n kube-system配置正确的 TLS secret间歇性 404多副本 Pod 标签不一致kubectl get pods --show-labels统一 labels其中「404 且 nginx 无日志」和「连接被拒绝」这两类最容易让人误以为是中间人攻击或者数据库被锁。我这次就一度怀疑是外部攻击甚至重置了服务结果第二天装完 k3s 又复现了才发现是 iptables 规则冲突。提示如果你在节点上跑过 Docker 或者其他容器运行时它们也会往 iptables 里写规则。k3s 的 ServiceLB 和 Docker 的端口映射经常打架排查时一定要把iptables -t nat -L完整看一遍。6. 把请求链路固定下来后续接入更省心排查完这一轮我最大的感受是k3s 的 Ingress 链路虽然组件不多但每一层都有独立的失败模式。Traefik 负责路由匹配Service 负责服务发现Endpoint 负责后端地址iptables 负责流量转发。任何一层出问题表现都可能是 404但根因完全不同。如果你后续要频繁调试模型接口或者做本地 Agent 开发建议把 API Key 和接入文档提前准备好避免在环境问题上反复消耗时间。模型对话调试可以直接在网页端验证请求格式接入文档里有完整的鉴权和请求示例Coding Plan 则适合长期跑编码类 Agent 任务省去每次手动配环境的麻烦。把上面的排查命令存成一个脚本下次再遇到 404按 Service → Endpoint → IngressRoute → iptables 的顺序跑一遍基本十分钟内就能定位到具体是哪一层的问题。
1. 一次诡异的 404nginx 日志干净得让人发毛如果你在 k3s 里部署完服务浏览器访问域名却只看到一行冷冰冰的404 page not found第一反应大概率是去翻 nginx 的 access.log 和 error.log。结果日志里干干净净连一条请求记录都没有——这时候你就该意识到请求压根没走到 nginx 这一层。我这次遇到的场景就是这样k3s 单节点集群服务用 Deployment 跑着Service 是 ClusterIPIngress 用的是 k3s 自带的 Traefik。域名解析没问题curl本地 Pod IP 能拿到正常页面但一从外部访问域名返回的就是 Traefik 默认的 404 页面。更迷惑的是kubectl get pods里 nginx 的 Pod 状态是 Runningkubectl logs里没有任何异常kubectl get ingress也显示 ADDRESS 有值。这个 404 的本质是请求到达了 Traefik但 Traefik 没有匹配到任何 IngressRoute 规则于是返回了默认的 404。问题不在 nginx也不在 Service而在 Traefik 到 Service 之间的路由匹配以及更底层的 iptables 转发链路。下面我把整条链路拆开逐层验证每一步都给可复制的命令。2. 前置准备确认 k3s 与 Traefik 的版本和入口在开始排查之前先把环境信息固定下来。k3s 不同版本自带的 Traefik 版本差异较大IngressRoute 的 API 版本和字段名会变所以第一步是确认版本。# 查看 k3s 版本 k3s --version # 查看 Traefik 相关 Pod kubectl get pods -n kube-system | grep traefik # 查看 Traefik Service kubectl get svc -n kube-system -o wide | grep traefik我这边输出大致是k3s version v1.28.2k3s1 traefik-7d9f8c6b5-xxxxx 1/1 Running 0 3d traefik LoadBalancer 10.43.0.1 192.168.1.100 80:30080/TCP,443:30443/TCP注意这里traefik这个 Service 的类型是 LoadBalancerk3s 内置的 ServiceLB也就是 klipper-lb会给它分配一个外部 IP同时把 80 和 443 映射到节点端口。如果你的节点上已经有别的进程占用了 80/443或者 iptables 里有旧的 DNAT 规则流量就会被劫持到别的地方这正是我这次踩坑的核心。提示k3s 默认会把 Traefik 的 80/443 通过 ServiceLB 暴露到节点上。如果你之前装过 nginx、apache 或者别的反向代理先确认端口占用情况。3. 可复制配置从 IngressRoute 到 Service 的完整定义排查 404 的第一步是确认你的 IngressRoute 到底有没有正确匹配。下面是一个最小可用的 IngressRoute 配置我把它拆成三块Deployment、Service、IngressRoute。apiVersion: apps/v1 kind: Deployment metadata: name: web-demo namespace: default spec: replicas: 1 selector: matchLabels: app: web-demo template: metadata: labels: app: web-demo spec: containers: - name: nginx image: nginx:1.25-alpine ports: - containerPort: 80 --- apiVersion: v1 kind: Service metadata: name: web-demo-svc namespace: default spec: selector: app: web-demo ports: - name: http port: 80 targetPort: 80 --- apiVersion: traefik.io/v1alpha1 kind: IngressRoute metadata: name: web-demo-route namespace: default spec: entryPoints: - web routes: - match: Host(demo.example.com) kind: Rule services: - name: web-demo-svc port: 80关键点有三个entryPoints必须是web对应 80或websecure对应 443match里的 Host 必须和你的访问域名完全一致services里的 name 和 port 必须和 Service 对得上。任何一处写错Traefik 都会返回 404。应用之后用下面的命令确认资源都创建成功kubectl apply -f web-demo.yaml kubectl get ingressroute -n default kubectl get svc web-demo-svc -n default kubectl get endpoints web-demo-svc -n defaultkubectl get endpoints这一步特别重要。如果 Endpoints 是空的说明 Service 的 selector 没匹配到任何 PodTraefik 即使匹配到了路由也会因为后端为空而返回 404 或 503。4. 逐层验证Service、Endpoint、IngressRoute 与 iptables4.1 验证 Service 和 Endpoint# 查看 Service 详情确认 selector 和 port kubectl describe svc web-demo-svc -n default # 查看 Endpoint必须有 Pod IP:Port kubectl get endpoints web-demo-svc -n default -o wide正常输出应该是NAME ENDPOINTS AGE web-demo-svc 10.42.0.15:80 5m如果 ENDPOINTS 显示none就去检查 Pod 的 labels 是否和 Service 的 selector 一致。这一步用kubectl get pods --show-labels对照即可。4.2 验证 IngressRoute 是否被 Traefik 识别# 查看 Traefik 的 dashboard 端口或者直接看 CRD 状态 kubectl get ingressroute web-demo-route -n default -o yaml # 查看 Traefik 日志确认有没有加载路由 kubectl logs -n kube-system -l app.kubernetes.io/nametraefik --tail100Traefik 日志里如果出现No matching route found或者rule not matched基本就是 match 写错了。我这次的问题是 Host 写成了demo.example.com但实际访问的是www.demo.example.com差一个www就 404。4.3 验证 iptables 转发链路这是最容易被忽略的一层。k3s 的 ServiceLB 会在节点上写 iptables 规则把外部流量 DNAT 到 Traefik 的 Pod。如果节点上之前有别的服务占用了 80/443iptables 里可能残留旧的 DNAT 规则导致流量被转到错误的后端。# 查看 nat 表中 80 和 443 的 DNAT 规则 sudo iptables -L -n -t nat | grep -E 80|443 # 查看具体的 DNAT 目标 sudo iptables -t nat -L PREROUTING -n -v --line-numbers我当时的输出里出现了两条 80 端口的 DNAT一条指向 Traefik 的 Pod IP另一条指向一个已经不存在的旧 Pod IP。旧规则优先级更高流量就被转到了那个已经不存在的地址表现就是 404 或者连接超时。清理旧规则的方法是先确认规则编号然后删除# 假设旧规则在 PREROUTING 链的第 3 条 sudo iptables -t nat -D PREROUTING 3注意直接操作 iptables 有风险建议先iptables-save /tmp/iptables.bak备份确认无误后再删除。k3s 重启后会自动重建 ServiceLB 的规则所以手动删掉的旧规则不会影响 k3s 自身。4.4 完整请求链路验证动作把上面几步串起来做一次端到端验证# 1. 从集群内部直接访问 Service kubectl run curl-test --rm -it --imagecurlimages/curl -- sh curl -H Host: demo.example.com http://web-demo-svc.default.svc.cluster.local # 2. 从节点上访问 Traefik 的 NodePort curl -H Host: demo.example.com http://127.0.0.1:30080 # 3. 从外部访问域名 curl -v -H Host: demo.example.com http://节点IP如果第 1 步通、第 2 步不通问题在 Traefik 到 Service 的路由如果第 2 步通、第 3 步不通问题在 iptables 或节点端口映射。我这次就是第 2 步通、第 3 步不通最终定位到 iptables 旧规则。5. 本篇常见错排查清单下面这张表是我在实际排查中整理出来的高频错误按出现概率排序现象可能原因验证命令修复方式404 page not foundIngressRoute match 写错kubectl logs -n kube-system -l app.kubernetes.io/nametraefik修正 Host 或 Path404 且 nginx 无日志请求未到达 nginxkubectl get endpoints检查 Service selector404 但 Endpoint 正常Traefik 未加载路由kubectl get ingressroute -o yaml确认 CRD 版本和 entryPoints连接被拒绝iptables 旧规则劫持iptables -L -n -t nat | grep 80删除旧 DNAT 规则证书错误用了 Traefik 默认证书kubectl get secret -n kube-system配置正确的 TLS secret间歇性 404多副本 Pod 标签不一致kubectl get pods --show-labels统一 labels其中「404 且 nginx 无日志」和「连接被拒绝」这两类最容易让人误以为是中间人攻击或者数据库被锁。我这次就一度怀疑是外部攻击甚至重置了服务结果第二天装完 k3s 又复现了才发现是 iptables 规则冲突。提示如果你在节点上跑过 Docker 或者其他容器运行时它们也会往 iptables 里写规则。k3s 的 ServiceLB 和 Docker 的端口映射经常打架排查时一定要把iptables -t nat -L完整看一遍。6. 把请求链路固定下来后续接入更省心排查完这一轮我最大的感受是k3s 的 Ingress 链路虽然组件不多但每一层都有独立的失败模式。Traefik 负责路由匹配Service 负责服务发现Endpoint 负责后端地址iptables 负责流量转发。任何一层出问题表现都可能是 404但根因完全不同。如果你后续要频繁调试模型接口或者做本地 Agent 开发建议把 API Key 和接入文档提前准备好避免在环境问题上反复消耗时间。模型对话调试可以直接在网页端验证请求格式接入文档里有完整的鉴权和请求示例Coding Plan 则适合长期跑编码类 Agent 任务省去每次手动配环境的麻烦。把上面的排查命令存成一个脚本下次再遇到 404按 Service → Endpoint → IngressRoute → iptables 的顺序跑一遍基本十分钟内就能定位到具体是哪一层的问题。
