应用连接数据库失败#
验证：未记录
- 适用版本
- 未记录
- 验证范围
- 尚未登记验证记录。
先区分：连不上端口、加密/认证失败、连接池等待、查询执行慢。检查必须从故障应用实际所在网络发起；笔记本能连不能证明 Pod 能连。
1. 固定测试位置与目标#
下列命令在故障应用容器已有工具时执行，或在经批准的诊断环境执行；后者须核对命名空间、网络策略、服务身份与流量代理是否一致。不要临时给应用安装软件，也不要向诊断容器复制生产密码。
示例为 PostgreSQL，所需工具：getent、ip、nc、PostgreSQL 客户端。Linux 的 nc 实现可能不同，先用 nc -h 核对选项。
export DB_HOST='db.internal.example.com'
export DB_PORT='5432'
getent ahostsv4 "$DB_HOST"
export DB_IP='REPLACE_RESOLVED_IPV4'
ip route get "$DB_IP"
nc -vz -w 3 "$DB_HOST" "$DB_PORT"数据库仅使用 IPv6 时改用 getent ahosts 和 ip -6 route get。ip route get 只显示当前网络命名空间的路由，不能证明云路由、回程或防火墙允许。
| 结果 | 判断 | 下一步 |
|---|---|---|
| 无法解析 / 地址错误 | 私有区域、解析器、端点或缓存问题 | GCP 私网、CoreDNS |
| no route / 走错接口 | 本机路由或策略路由问题 | Linux 路由排障 |
| 端口超时 | 丢包、过滤、回程或服务无响应 | 查两端网络规则、流日志和数据库状态，不能仅凭超时确定是哪层 |
| Connection refused | 当前目标主动拒绝连接 | 查实际端点、监听端口、代理状态与故障切换 |
| 端口可连接 | 仅证明传输层连接建立 | 继续验证数据库协议、TLS 与认证 |
AWS 需要核对 VPC（Virtual Private Cloud，虚拟私有云）路由、SG（Security Group，安全组）和 NACL（Network Access Control List，网络访问控制列表）：SG 有状态，NACL 无状态，需放通对应回包。隔离数据子网与应用子网同 VPC 通信不需要 NAT（Network Address Translation，网络地址转换）网关，详见 三层子网。跨 VPC 再检查对等连接、地址重叠与双向路由。
2. 区分数据库接入与实际认证#
pg_isready -h "$DB_HOST" -p "$DB_PORT" -t 3
DB_READY_RC=$?
printf 'pg_isready_exit=%s\n' "$DB_READY_RC"退出码：0 接受连接、1 拒绝连接、2 无响应、3 参数等原因未发起检查；0 不证明业务账号可以登录或访问表。见 PostgreSQL 官方说明。
使用已批准的只读诊断账号及安全注入的凭证文件验证；实际文件不得提交仓库。下面要求平台已准备好权限为 0600 的 PGPASSFILE，不要在命令行填写密码。
export PGUSER='REPLACE_DIAGNOSTIC_USER'
export PGDATABASE='REPLACE_DATABASE'
export PGSSLMODE='verify-full'
export PGSSLROOTCERT='/run/secrets/db-ca.pem'
export PGPASSFILE='/run/secrets/db.pgpass'
PGHOST="$DB_HOST" PGPORT="$DB_PORT" PGCONNECT_TIMEOUT=3 PGOPTIONS='-c statement_timeout=5000 -c default_transaction_read_only=on' psql -X -w -v ON_ERROR_STOP=1 -c 'SELECT current_database(), current_user, 1;'TLS（Transport Layer Security，传输层安全）校验失败时查主机名、证书链、有效期和客户端时间，不降级为不校验证书。账号认证失败查凭证版本、轮换和授权；若应用经数据库代理连接，应按实际代理与身份方式测试，不能把直连测试结果直接套用。
MySQL 使用既有安全登录配置执行：
mysql --login-path=diagnostic --host="$DB_HOST" --port=3306 --connect-timeout=3 --ssl-mode=VERIFY_IDENTITY --ssl-ca=/run/secrets/db-ca.pem --execute='SELECT CURRENT_USER(), 1;'diagnostic 须事先由平台安全配置；不要在工单中展示其内容。查询成功仅验证该账号，业务账号还需通过应用的受控请求验证授权。
3. 连接成功但应用仍超时#
| 应用证据 | 优先检查 | 处理方向 |
|---|---|---|
| 等待连接池超时 | 活跃/空闲/等待连接数、持有时间 | 连接泄漏、长事务、请求并发；不要直接翻倍池大小 |
| 新增副本后连接耗尽 | 各副本池上限总和、数据库连接上限 | 加上 worker、迁移任务和管理连接预算 |
| 查询执行慢 / 锁等待 | 慢查询、执行计划、锁与事务时间 | 定位阻塞源，先评估业务影响再终止会话 |
| 轮换或切换后失败 | 凭证刷新、旧连接、解析缓存 | 验证刷新和重连机制，避免全实例同时重连 |
继续：PostgreSQL 生产实践、MySQL 生产实践、Cloud SQL。
4. 恢复验收#
从原应用路径验证读取及经批准的业务写入，确认事务结果、连接池等待和数据库连接数恢复。销毁临时诊断环境及凭证文件；不要把“端口通了”作为事故关闭标准。