140. 如何使用 nginx /dbg

/dbg is a program included in the ingress-nginx container image that can be used to show information about the nginx environment and the resulting nginx configuration, which can be helpful when debugging ingress issues in Kubernetes.
/dbg 是包含在 ingress-nginx 容器镜像中的程序，可用于展示 nginx 环境及其生成的 nginx 配置信息，这在调试 Kubernetes 入门问题时非常有帮助。

This command needs to be run from inside one of the ingress-nginx pods, so first determine the pod to run it in.
这个命令需要在某个 ingress-nginx pod 内部运行，所以先确定要运行的 pod。

> kubectl get pods -n ingress-nginx NAME READY STATUS RESTARTS AGE default-http-backend-67cf578fc4-54jlz 1/1 Running 0 5d nginx-ingress-controller-56nss 1/1 Running 0 5d nginx-ingress-controller-hscfg 1/1 Running 0 4d21h nginx-ingress-controller-n4p22 1/1 Running 0 5d

> export NGINX_POD=nginx-ingress-controller-n4p22

If you are diagnosing specific connection issues, you can determine which controller is receiving the traffic by looking through the logs of each.
如果你在诊断具体的连接问题，可以通过查看每个控制器的日志来确定是哪个控制器接收了流量。

/dbg general will show the count of running controllers.
/dbg general 会显示运行控制器的数量。

> kubectl exec -n ingress-nginx $NGINX_POD /dbg general { "controllerPodsCount": 3 }

/dbg backends list will list the discovered backends:
/DBG 后端列表将列出已发现的后端：

> kubectl exec -n ingress-nginx $NGINX_POD /dbg backends list cattle-system-rancher-80 upstream-default-backend

/dbg backends get will show the configuration for the named backend:
/dbg 后端 get 会显示命名后端的配置：

> kubectl exec -n ingress-nginx $NGINX_POD /dbg backends get cattle-system-rancher-80

/dbg certs will dump the x509 cert and key for a certificate that nginx has discovered from k8s secrets for the given hostname:
/dbg 证书会倾倒 nginx 从 k8s 秘密中发现的 x509 证书和密钥，该证书针对给定主机名：

> kubectl exec -n ingress-nginx $NGINX_POD /dbg certs get <fqdn>

/dbg conf will dump the dynamically generated nginx configuration. To view the configuration for a specific ingress hostname, you could run /dbg conf and then grep for the server_name:
/dbg conf 会导出动态生成的 nginx 配置。要查看特定入口主机名的配置，可以运行 /dbg conf，然后用 grep 获取 server_name：

> kubectl exec -n ingress-nginx $NGINX_POD /dbg conf | grep "server_name example.com" -B2 -A20

nginx /dbg 是什么与如何使用

nginx /dbg并非标准 Nginx 核心的内置功能，而是Kubernetes ingress-nginx 控制器提供的专用调试工具，用于快速检查和诊断运行中的 Nginx Ingress 实例状态。它是一个命令行工具，通常位于 Ingress 容器的/dbg路径下，帮助运维人员排查路由配置、后端服务、证书等相关问题。

一、核心定位与适用场景

• 定位：ingress-nginx 官方调试工具，用于实时检查Nginx 配置、后端服务、upstream 状态、证书信息等
• 适用：仅适用于 Kubernetes 环境中的 ingress-nginx 控制器，不适用于独立部署的标准 Nginx
• 用途：
  • 排查路由转发异常（404/502/503 等）
  • 验证动态配置是否正确加载
  • 检查证书有效性与匹配情况
  • 查看 upstream 后端健康状态
  • 收集调试信息用于问题诊断

二、使用方法（Kubernetes 环境）

1. 进入 Ingress 容器

首先通过 kubectl 进入运行中的 ingress-nginx Pod 容器：

bash

运行

kubectl exec -it -n <命名空间> <ingress-pod-name> -- bash # 示例（默认命名空间通常为 ingress-nginx） kubectl exec -it -n ingress-nginx ingress-nginx-controller-7f98d6f5b4-2x7z9 -- bash

2. 执行 /dbg 命令

在容器内直接运行/dbg可查看所有可用子命令：

bash

运行

/dbg # 输出示例： Available Commands: backends Inspect the dynamically-loaded backends information certs Inspect certificate information config Output the full nginx configuration help Help about any command info Show information about the nginx instance server Inspect server configuration upstream Inspect upstream information

3. 常用子命令详解

表格

4. 进阶用法

• 过滤输出：结合 grep/jq 处理 JSON 结果

  bash

  运行

  /dbg backends all | jq '.items[] | {name: .name, service: .service}'

• 导出配置：将完整配置保存到本地

  bash

  运行

  /dbg config > /tmp/nginx.conf # 从容器复制到本地 kubectl cp -n ingress-nginx ingress-nginx-controller-7f98d6f5b4-2x7z9:/tmp/nginx.conf ./local-nginx.conf