数据库探针连接失败的排查步骤与解决方法

数据库探针连接失败，表面上看是“应用连不上数据库”，实际可能发生在不同阶段：主机名解析失败、TCP 连接超时、端口拒绝、TLS 握手失败、账号认证失败，或者连接成功后执行探测 SQL 超时。若不先区分失败阶段，盲目改超时、重启数据库或增加连接数，往往会掩盖真正问题。

本文适用于应用程序中的数据库健康检查、容器编排平台中的探针，以及运维人员从客户端验证数据库连通性的场景。排查时应先从探针运行的同一台主机或容器出发，逐层验证网络、协议、认证和查询；同时要区分“进程是否存活”与“实例是否适合接收流量”，避免探针本身放大故障。

一、先弄清楚探针检查的是什么

常见探针大致分为三类，检查深度和用途不同：

• 端口探测：尝试建立 TCP 连接。它能说明目标地址的端口是否可达，但不验证数据库协议、账号密码、TLS 或 SQL 查询。
• 数据库客户端探测：使用数据库驱动完成协议握手，通常也会验证认证和 TLS。是否执行 SQL，取决于工具或程序的实现。
• 应用层探测：应用建立数据库连接并执行轻量查询，例如 SELECT 1。它更接近应用实际使用路径，但也会消耗数据库连接和资源。

因此，单纯的 TCP 探针成功，并不等于应用一定能正常访问数据库。反过来，如果探针实际执行查询，失败也不一定代表数据库进程已经停止：可能是连接池耗尽、账号权限变化、查询被阻塞，或者应用到数据库的网络路径异常。

先确认以下信息：探针运行位置、数据库类型与地址、端口、是否使用 TLS、实际使用的账号、连接超时和查询超时、探针执行频率，以及探针失败后平台会采取什么动作。不要仅凭一条“connection failed”日志下结论。

二、按连接阶段逐层排查

1. 检查配置来源与目标地址

确认探针拿到的配置与应用实际配置一致。容器环境中常见问题包括环境变量没有注入、密钥引用错误、配置文件挂载路径不对、部署更新后仍使用旧副本，以及连接串中的特殊字符没有正确编码。

把连接目标拆开检查：数据库主机名、端口、数据库名、用户名、TLS 参数和超时设置。连接串包含密码时，不要将完整连接串直接打印到日志、工单或命令历史中；排查时可打印脱敏后的主机名和端口，并确认相关配置的来源与版本。

注意服务发现地址的含义。容器内的 localhost 通常指当前容器，不是数据库容器或宿主机。Kubernetes Pod 中使用 Service DNS 时，Service 端口也可能与数据库容器实际监听端口不同。应以探针所在网络命名空间内可见的地址为准。

2. 检查 DNS 解析

若连接使用主机名，先在探针所在环境中查询解析结果。不要只在个人电脑上验证，因为本机 DNS、容器 DNS 和集群 DNS 可能完全不同。

getent hosts db.example.internal
nslookup db.example.internal

如果没有这些工具，可以在 Python 中检查解析：

python -c "import socket; print(socket.getaddrinfo('db.example.internal', 5432, type=socket.SOCK_STREAM))"

解析失败时，检查 DNS 服务状态、搜索域、Service 名称与命名空间、记录是否更新，以及容器是否使用了预期的 DNS 配置。若解析到了多个 IP，逐个验证连接结果；某个后端异常时，表现可能是间歇性失败，而不是始终失败。

3. 检查 TCP 路径和端口监听

解析成功后，验证从探针位置到数据库端口的 TCP 连接。以下命令在安装了 nc 的环境中可用：

nc -vz -w 3 db.example.internal 5432

-w 3 是该版本 nc 的等待时间参数，具体选项可能因实现而异。若命令不支持，可查看 nc -h，或使用 Python 的标准库完成一次有超时的连接测试：

import socket

host = "db.example.internal"
port = 5432
timeout_seconds = 3

try:
    with socket.create_connection((host, port), timeout=timeout_seconds):
        print("TCP connection succeeded")
except socket.gaierror as exc:
    print(f"DNS resolution failed: {exc}")
except TimeoutError as exc:
    print(f"TCP connection timed out: {exc}")
except OSError as exc:
    print(f"TCP connection failed: {exc}")

将代码保存为 tcp_check.py，再运行 python tcp_check.py。它只验证 TCP 建连，不会发送数据库协议数据，也不会验证账号、密码或 TLS。

结果通常有以下含义：

• Connection refused：目标主机可达，但目标端口没有接受连接，或网络设备主动拒绝。检查数据库监听端口、监听地址和端口映射。
• Timeout：可能是路由不通、防火墙丢弃、网络策略拦截、目标无响应，或网络拥塞。超时本身不能证明数据库进程已宕机。
• No route to host：检查路由、子网、安全组、网络策略和目标地址是否正确。
• TCP 成功但驱动失败：继续检查数据库协议、认证、TLS、连接数限制和服务端日志。

数据库服务器上也应确认服务是否监听预期地址与端口。只监听 127.0.0.1 的服务，通常无法接受来自其他主机或容器的连接。修改监听地址时应同时检查防火墙和访问控制，不能为了测试直接将数据库暴露到不受信任的网络。

4. 验证数据库协议、账号和权限

TCP 通了以后，用与应用相同的驱动和连接参数测试，避免把“端口可达”误当成“数据库可用”。例如 PostgreSQL 可使用 pg_isready 检查服务器是否接受连接：

pg_isready -h db.example.internal -p 5432 -d appdb -U probe_user -t 3

pg_isready 主要判断 PostgreSQL 服务的连接状态，不等同于完整的应用认证和业务查询验证。其命令行参数与超时语义应以当前安装版本的帮助信息为准。不要把密码直接写在命令行参数中；命令行可能出现在进程列表或 shell 历史中。需要认证验证时，优先使用受权限保护的凭据文件、密钥管理系统或应用既有的秘密注入方式。

常见认证相关故障包括密码轮换后探针仍使用旧密钥、用户名或数据库名拼错、账号被锁定、认证规则不匹配，以及探针连接到了与预期不同的数据库实例。查看服务端日志时，应对密码、令牌及连接串中的敏感信息做脱敏。

探针账号应尽量只拥有完成检查所需的权限。如果探针仅需连接并执行无副作用的健康查询，就不应授予建表、写业务数据或管理用户等权限。具体权限语法和最小权限范围取决于数据库类型、版本及组织策略，不能直接照搬其他数据库的授权语句。

5. 检查 TLS 与证书

端口可连通但驱动报告握手失败、证书错误或协议不匹配时，重点检查客户端与服务端是否都要求 TLS，驱动是否使用了正确的 CA 证书，证书是否过期，以及连接主机名是否与证书中的身份匹配。时钟偏差也可能导致证书有效期判断异常。

不要把关闭证书验证当作长期解决方法。它会降低对服务端身份的验证能力，使连接可能无法确认自己连到的是预期数据库。应修复 CA 配置、证书链、主机名或证书更新流程。不同数据库驱动对 TLS 参数的命名与默认行为不同，应查阅对应驱动版本的文档。

6. 检查连接数、连接池与数据库负载

如果故障间歇发生，或服务端出现“too many connections”一类错误，检查数据库最大连接数、当前连接数、应用副本数、连接池上限和探针并发量。多个应用副本同时运行时，连接池总量是各副本上限的累加；定时创建新连接的探针也会增加连接压力。

不要把提高数据库最大连接数作为第一步。连接数上升会增加内存和调度开销，具体影响取决于数据库类型、配置和工作负载。应先确认是否存在连接未释放、连接池配置不合理、连接风暴或服务端慢查询，再进行容量调整。

检查数据库是否正在启动、切换主从、执行维护、发生故障恢复，或因 CPU、内存、磁盘和 I/O 压力而响应缓慢。连接成功但 SELECT 1 超时，可能意味着服务端繁忙，也可能是连接池排队或网络延迟。应分别记录“获取连接耗时”和“执行查询耗时”，不要把它们合并成一个无法定位的总超时。

三、使用真实数据库驱动执行轻量探测

下面示例使用 Python 的 Psycopg 3 连接 PostgreSQL，执行 SELECT 1，并通过环境变量读取连接配置。先安装依赖：

python -m pip install "psycopg[binary]"

保存为 db_probe.py：

import os
import sys
import psycopg

required = ("DB_HOST", "DB_NAME", "DB_USER", "DB_PASSWORD")
missing = [name for name in required if not os.environ.get(name)]
if missing:
    print("Missing required environment variables: " + ", ".join(missing), file=sys.stderr)
    sys.exit(2)

try:
    with psycopg.connect(
        host=os.environ["DB_HOST"],
        port=int(os.environ.get("DB_PORT", "5432")),
        dbname=os.environ["DB_NAME"],
        user=os.environ["DB_USER"],
        password=os.environ["DB_PASSWORD"],
        connect_timeout=int(os.environ.get("DB_CONNECT_TIMEOUT", "3")),
        autocommit=True,
    ) as conn:
        with conn.cursor() as cur:
            cur.execute("SELECT 1")
            row = cur.fetchone()
            if row != (1,):
                raise RuntimeError("Unexpected probe result")
    print("database probe succeeded")
except Exception as exc:
    # 生产环境应使用日志系统并避免输出凭据或敏感连接信息。
    print(f"database probe failed: {type(exc).__name__}", file=sys.stderr)
    sys.exit(1)

配置环境变量后运行：

export DB_HOST=db.example.internal
export DB_PORT=5432
export DB_NAME=appdb
export DB_USER=probe_user
export DB_PASSWORD='由安全的密钥注入机制提供'
export DB_CONNECT_TIMEOUT=3
python db_probe.py

示例中的 connect_timeout 由驱动和底层客户端实现解释，通常表示建立连接阶段的等待限制；它不应被当作所有网络操作和 SQL 执行的统一总时限。具体支持的参数、单位和默认值，应以当前 Psycopg 与 PostgreSQL 客户端库版本文档为准。若还需要限制查询执行时间，应使用驱动支持的查询超时设置，或在数据库端配置适当的语句超时，并验证其作用范围。

代码将异常类型写入错误输出，不打印异常文本，是为了降低连接信息泄露风险。实际排障时可以在受控日志中记录经过脱敏的错误类别和耗时，并结合数据库服务端日志定位；不要把密码、完整连接串、证书私钥或敏感查询内容写入日志。SELECT 1 是示例中的无业务副作用查询，但它并不能验证业务表、业务权限或整个应用的读写链路。

四、Kubernetes 中的探针配置要点

Kubernetes 提供存活（liveness）、就绪（readiness）和启动（startup）探针，三者职责不同：

• 存活探针：判断容器内的应用是否需要重启。若它直接依赖数据库，数据库短暂故障可能让所有应用容器反复重启，进一步放大故障。
• 就绪探针：判断 Pod 是否应接收流量。应用依赖数据库才能处理请求时，可以将必要的数据库可用性纳入就绪判断；探针失败通常会影响流量路由，而不是直接重启容器。
• 启动探针：为启动较慢的应用提供启动阶段保护。在启动探针成功前，存活和就绪探针不会执行。

下面是一个通过容器内 HTTP 健康检查端点执行判断的示例。端点由应用实现，并应返回明确的状态码：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: example.invalid/api:1.0
          ports:
            - name: http
              containerPort: 8080
          startupProbe:
            httpGet:
              path: /health/startup
              port: http
            periodSeconds: 5
            timeoutSeconds: 2
            failureThreshold: 24
          readinessProbe:
            httpGet:
              path: /health/ready
              port: http
            periodSeconds: 10
            timeoutSeconds: 2
            failureThreshold: 3
          livenessProbe:
            httpGet:
              path: /health/live
              port: http
            periodSeconds: 10
            timeoutSeconds: 2
            failureThreshold: 3

这个清单只是结构示例，镜像、端口和端点需替换为实际值。不要让存活端点在每次调用时都创建大量数据库连接，也不要仅为让探针变绿而返回固定成功。就绪端点可以检查应用是否具备服务能力，但应控制检查耗时和频率，并评估数据库短暂不可用时对流量路由的影响。

另一种做法是在容器中运行数据库驱动脚本作为 exec 探针。该方式会启动进程，频繁执行可能带来进程创建和数据库连接开销；脚本、解释器和驱动也必须确实存在于镜像中。更重要的是，exec 探针应检查容器内应用实际使用的连接配置，而不是另一套测试配置。

Kubernetes 探针字段有边界，不能用任意数值配置。常用的 periodSeconds、timeoutSeconds、failureThreshold 和 successThreshold 必须符合 Kubernetes API 对应字段的约束；例如周期、超时和失败阈值至少为 1 秒或 1 次，超时不是毫秒字段。存活探针和启动探针的 successThreshold 必须为 1。具体支持字段、默认值和版本行为，应以集群 Kubernetes 版本的 API 文档为准。配置前可运行 kubectl explain pod.spec.containers.livenessProbe 查询集群支持的字段。

探针的失败阈值和间隔共同影响故障被识别的时间，不是数据库连接本身的超时设置。合理值需结合启动时长、故障恢复时间和允许的流量中断时间设置。探针过于频繁或超时过短，会把短暂抖动误判为持续故障；过于宽松则会延迟发现问题。

五、常见误区与对应处理

• 只用端口探针判断数据库可用：端口开放只能说明 TCP 建连成功。若应用需要确认认证和查询，应额外设计驱动级检查，但要控制成本。
• 把数据库检查放进存活探针：数据库故障可能引发应用容器集体重启。通常应让存活探针关注进程是否能自行恢复，把依赖检查放入就绪判断；但是否如此仍要结合应用架构与恢复机制设计。
• 盲目延长所有超时：超时变长可能让故障更晚暴露，也可能积压探针进程或请求。先分辨 DNS、建连、握手、取连接和查询各阶段耗时。
• 用管理员账号做探针：不必要地扩大凭据泄露后的影响范围。使用专用、低权限账号，并按组织流程轮换凭据。
• 通过重启“修复”连接失败：重启可能暂时清理连接池状态，却不能解决 DNS、防火墙、证书、认证和容量问题。先收集失败时间、目标地址、错误类别和服务端日志。
• 忽略探针流量：多副本、短周期和重试叠加时，健康检查可能形成额外连接负载。评估探测频率、并发与连接复用策略，必要时避免每次探测都新建连接。
• 关闭 TLS 校验或开放数据库端口：这类做法可能让测试“通过”，却降低安全性。应修正证书、路由和访问控制，只允许必要来源访问数据库。

六、建议的排查顺序

1. 确认失败发生在哪个容器、主机和时间段，检查探针使用的配置是否正确且已更新。
2. 从探针所在环境解析数据库主机名，确认得到的地址与预期一致。
3. 使用限时 TCP 测试验证目标端口；失败时排查路由、监听地址、防火墙、安全组和网络策略。
4. 使用数据库客户端或实际应用驱动连接，分辨协议、认证与 TLS 错误；不要只依据 TCP 测试结果判断数据库可用性。
5. 若连接成功但探测失败，分别检查取连接耗时、查询耗时、账号权限、服务端负载和连接数。
6. 结合数据库日志、应用日志和集群事件，在同一时间线上核对故障；先修复原因，再调整探针阈值。
7. 验证恢复后是否会形成重试风暴、容器重启循环或连接数激增，并记录探针配置和凭据更新方式。

数据库探针的目标不是“让检查结果变绿”，而是在有限开销下准确反映应用是否能安全、及时地使用数据库。端口检查适合快速定位网络边界，驱动级检查适合验证协议与认证，应用就绪检查则应表达服务能否接收请求。明确每种探针的职责、失败后的动作和安全边界，才能让探测结果真正用于诊断，而不是成为故障的一部分。