错误消息代码
<?php
/**
* 安全的 SQL Server 连接与 DNS 延迟诊断（CLI 专用）
* - 目标：在 DNS 解析偶发变慢导致驱动超时时，向管理员输出友好且可操作的诊断信息
* - 注意：不会在控制台输出连接字符串或密码等敏感信息
*/
if (PHP_SAPI !== 'cli') {
fwrite(STDERR, "This script is intended for CLI only.\n");
exit(1);
}
/*========================
可调参数（通过环境变量覆盖）
=========================*/
$cfg = [
'host' => getenv('DB_HOST') ?: '',
'port' => getenv('DB_PORT') ?: '1433',
'db' => getenv('DB_NAME') ?: '',
'user' => getenv('DB_USER') ?: '',
'pass' => getenv('DB_PASSWORD') ?: '',
'loginTimeout' => (int)(getenv('DB_LOGIN_TIMEOUT') ?: 5), // 初始登录超时秒
'maxLoginTimeout' => (int)(getenv('DB_MAX_LOGIN_TIMEOUT') ?: 12),// 重试时的上限
'dnsSlowThresholdMs' => (int)(getenv('DB_DNS_SLOW_THRESHOLD_MS') ?: 150),
'retries' => (int)(getenv('DB_CONN_RETRIES') ?: 2), // 总尝试次数（含主机名与IP回退）
'logFile' => getenv('APP_LOG') ?: '/var/log/app/db_connect.log',
'encrypt' => (getenv('DB_ENCRYPT') ?: 'yes') === 'yes', // 加密连接
'trustServerCert' => (getenv('DB_TRUST_SERVER_CERT') ?: 'no') === 'yes', // 是否信任服务器证书（生产环境建议no）
];
if (!$cfg['host'] || !$cfg['db'] || !$cfg['user']) {
fwrite(STDERR, "配置不完整：请设置 DB_HOST / DB_NAME / DB_USER（密码通过 DB_PASSWORD 提供）。\n");
exit(2);
}
/*========================
工具函数
=========================*/
function log_safe($file, $line) {
$dir = dirname($file);
if (!is_dir($dir)) {
@mkdir($dir, 0770, true);
}
$ts = date('c');
@file_put_contents($file, "[$ts] $line\n", FILE_APPEND);
}
function mask_value($value, $keepStart = 3, $keepEnd = 3) {
$len = mb_strlen($value);
if ($len <= ($keepStart + $keepEnd)) return str_repeat('*', $len);
return mb_substr($value, 0, $keepStart) . str_repeat('*', $len - $keepStart - $keepEnd) . mb_substr($value, -$keepEnd);
}
function mask_host_for_display($host) {
// 保留首段与末段顶级域名，其他以***遮蔽
$parts = explode('.', $host);
if (count($parts) <= 2) {
return mask_value($host, 2, 2);
}
$first = $parts[0];
$lastTwo = array_slice($parts, -2);
return $first . '.***.' . implode('.', $lastTwo);
}
function dns_resolve_with_metrics($host) {
$start = microtime(true);
$ips = @gethostbynamel($host);
$durationMs = (int)round((microtime(true) - $start) * 1000);
return [
'ok' => is_array($ips) && count($ips) > 0,
'ips' => $ips ?: [],
'durationMs' => $durationMs,
];
}
function sqlsrv_connect_try($server, array $cfg, &$driverName = null, &$driverErrs = []) {
$driverErrs = [];
// 优先使用 sqlsrv 扩展
if (function_exists('sqlsrv_connect')) {
$driverName = 'sqlsrv';
$connectionInfo = [
'Database' => $cfg['db'],
'UID' => $cfg['user'],
'PWD' => $cfg['pass'],
'LoginTimeout' => (int)$cfg['loginTimeout'],
'MultipleActiveResultSets' => true,
'ConnectionPooling' => true,
'Encrypt' => $cfg['encrypt'],
'TrustServerCertificate' => $cfg['trustServerCert'],
// 跨子网连接优化（AlwaysOn 场景）
'MultiSubnetFailover' => true,
];
$conn = @sqlsrv_connect($server, $connectionInfo);
if (!$conn) {
$errs = sqlsrv_errors(SQLSRV_ERR_ALL);
$driverErrs = is_array($errs) ? $errs : [];
}
return $conn;
}
// 退回 PDO_SQLSRV
if (extension_loaded('pdo_sqlsrv')) {
$driverName = 'pdo_sqlsrv';
$dsn = sprintf(
'sqlsrv:Server=%s;Database=%s;LoginTimeout=%d;Encrypt=%d;TrustServerCertificate=%d;MultiSubnetFailover=1',
$server,
$cfg['db'],
(int)$cfg['loginTimeout'],
$cfg['encrypt'] ? 1 : 0,
$cfg['trustServerCert'] ? 1 : 0
);
try {
$pdo = new PDO($dsn, $cfg['user'], $cfg['pass'], [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_TIMEOUT => (int)$cfg['loginTimeout'],
]);
return $pdo;
} catch (PDOException $e) {
$driverErrs = [[
'SQLSTATE' => $e->getCode(),
'code' => 0,
'message' => $e->getMessage(),
]];
return false;
}
}
$driverName = 'none';
$driverErrs = [[
'SQLSTATE' => null,
'code' => null,
'message' => 'Neither sqlsrv nor pdo_sqlsrv extension is available.',
]];
return false;
}
function classify_sql_errors(array $errs) {
// 简要分类：是否为超时/网络/DNS类问题
$codes = [];
$msgs = [];
foreach ($errs as $e) {
$codes[] = strtoupper((string)($e['SQLSTATE'] ?? ''));
$msgs[] = strtolower((string)($e['message'] ?? ''));
}
$all = implode(' | ', $msgs);
$isTimeout = (stripos($all, 'timeout') !== false) || in_array('HYT00', $codes, true) || in_array('S1T00', $codes, true);
$isDns = (stripos($all, 'dns') !== false) || (stripos($all, '11001') !== false) || (stripos($all, 'name or service not known') !== false);
$isNetwork = (stripos($all, '08001') !== false) || (stripos($all, '10060') !== false) || (stripos($all, '10061') !== false);
return [$isTimeout, $isDns, $isNetwork];
}
/*========================
主流程
=========================*/
$maskedHost = mask_host_for_display($cfg['host']);
$serverWithPort = "tcp:{$cfg['host']},{$cfg['port']}";
$dns = dns_resolve_with_metrics($cfg['host']);
$dnsSlow = $dns['durationMs'] >= $cfg['dnsSlowThresholdMs'];
$attempts = [];
$connected = false;
$conn = null;
$driver = null;
$driverErrs = [];
// 第一次：使用主机名连接
$attempts[] = [
'label' => 'hostname',
'server' => $serverWithPort,
'timeout' => $cfg['loginTimeout'],
];
$resolvedIp = $dns['ok'] ? $dns['ips'][0] : null;
if ($resolvedIp) {
$attempts[] = [
'label' => 'ip-fallback',
'server' => "tcp:{$resolvedIp},{$cfg['port']}",
'timeout' => min($cfg['maxLoginTimeout'], $cfg['loginTimeout'] + 4),
];
}
// 控制最大尝试次数
$attempts = array_slice($attempts, 0, max(1, $cfg['retries']));
$errorsCollected = [];
foreach ($attempts as $i => $a) {
$cfg['loginTimeout'] = (int)$a['timeout'];
$conn = sqlsrv_connect_try($a['server'], $cfg, $driver, $driverErrs);
if ($conn) {
$connected = true;
break;
}
$errorsCollected[] = [
'attempt' => $a['label'],
'server' => $a['server'], // 日志用，不在CLI输出
'timeout' => $a['timeout'],
'driver' => $driver,
'errors' => $driverErrs,
];
// 指数回退短暂等待（避免立即拥塞）
usleep(200000 * ($i + 1)); // 200ms, 400ms...
}
// 成功则输出简短通过信息（管理员可见，不含敏感）
if ($connected) {
echo "数据库连接检查通过：SQL Server 已连接。DNS解析耗时 {$dns['durationMs']} ms。驱动={$driver}。\n";
exit(0);
}
/*========================
失败：输出面向管理员的友好诊断
=========================*/
[$isTimeout, $isDns, $isNetwork] = classify_sql_errors(array_merge(...array_map(fn($e) => $e['errors'], $errorsCollected)));
$errorId = 'DB_CONN_DNS_TIMEOUT';
$lines = [];
$lines[] = "错误：登录模块无法连接数据库（SQL Server）";
$lines[] = "错误编号：{$errorId}";
$lines[] = "影响范围：用户登录验证暂时不可用";
$lines[] = "";
$lines[] = "关键信息：";
$lines[] = "- 目标主机（遮蔽）：{$maskedHost}:{$cfg['port']}";
$lines[] = "- 目标数据库：".mask_value($cfg['db'], 1, 1);
$lines[] = "- DNS 解析：".($dns['ok'] ? "成功，用时 {$dns['durationMs']} ms" : "失败");
$lines[] = "- 连接尝试：".count($attempts)." 次（含 IP 回退：".($resolvedIp ? "是" : "否")."）";
$lines[] = "- 触发类型：".(
$isDns ? "DNS 解析/路由延迟" :
($isTimeout ? "连接超时" :
($isNetwork ? "网络不可达/防火墙" : "未知"))
);
$lines[] = "";
$lines[] = "驱动返回（节选）：";
if (!empty($errorsCollected)) {
$firstErrs = $errorsCollected[0]['errors'] ?: [];
$maxShow = 2;
$count = 0;
foreach ($firstErrs as $e) {
$count++;
if ($count > $maxShow) break;
$sqlstate = $e['SQLSTATE'] ?? '';
$code = $e['code'] ?? '';
$msg = trim(preg_replace('/\s+/', ' ', (string)($e['message'] ?? '')));
$msg = mb_strimwidth($msg, 0, 220, '...');
$lines[] = "- SQLSTATE={$sqlstate}; CODE={$code}; MSG={$msg}";
}
} else {
$lines[] = "- 无可用的驱动错误详情";
}
$lines[] = "";
$lines[] = "可能原因：";
$lines[] = "- 跨区域 DNS 解析偶发变慢或缓存未命中，导致登录超时（HYT00 等）。";
$lines[] = "- 网络抖动/丢包，或防火墙对 1433 端口限速。";
$lines[] = "- 多子网/异地容灾场景中，连接路径切换导致初次建连耗时。";
$lines[] = "";
$lines[] = "建议操作：";
$lines[] = "1) 立即缓解：";
$lines[] = " - 提高登录超时至 10~15 秒（DB_LOGIN_TIMEOUT），并开启 IP 回退（本脚本已内置）。";
$lines[] = " - 在应用侧启用连接重试，或短期在本机配置 hosts 静态解析（仅应急，变更需记录）。";
$lines[] = "2) 排查验证：";
$lines[] = " - 测试 DNS 时延：nslookup {$cfg['host']} 或 dig {$cfg['host']} 并记录耗时/TTL。";
$lines[] = " - 连通性检查：telnet {$maskedHost} 1433 或 Test-NetConnection（Windows）。";
$lines[] = " - 查看防火墙与安全组是否对跨区域流量限速/丢弃。";
$lines[] = "3) 长期优化：";
$lines[] = " - 启用/确认 MultiSubnetFailover=Yes（已在连接参数中开启）。";
$lines[] = " - 引入就近 DNS/缓存（如 systemd-resolved、nscd）并监控解析时延与命中率。";
$lines[] = " - 与 DBA/网络团队确认跨区域链路与 SQL 监听端点策略，必要时提供就近只读/写入端点。";
$lines[] = "";
$lines[] = "提示：为安全起见，已隐藏连接字符串和密码。详细技术信息请查看应用日志。";
$finalMessage = implode("\n", $lines);
echo $finalMessage . "\n";
/*========================
安全日志（包含更详细上下文，但仍不记录密码）
=========================*/
$logCtx = [
'driver' => $driver,
'host' => $cfg['host'],
'port' => $cfg['port'],
'db' => $cfg['db'],
'user_masked' => mask_value($cfg['user'], 1, 1),
'dns_ok' => $dns['ok'],
'dns_ms' => $dns['durationMs'],
'attempts' => array_map(function($a){ return ['label'=>$a['label'],'timeout'=>$a['timeout']]; }, $attempts),
'errors' => $errorsCollected,
];
log_safe($cfg['logFile'], 'DB_CONNECT_FAIL '.json_encode($logCtx, JSON_UNESCAPED_UNICODE));
exit(70); // EX_SOFTWARE
错误消息预览
错误：登录模块无法连接数据库（SQL Server）
错误编号：DB_CONN_DNS_TIMEOUT
影响范围：用户登录验证暂时不可用
关键信息：
- 目标主机（遮蔽）：db-login.***.example.com:1433
- 目标数据库：p***d
- DNS 解析：成功，用时 312 ms
- 连接尝试：2 次（含 IP 回退：是）
- 触发类型：DNS 解析/路由延迟
驱动返回（节选）：
- SQLSTATE=HYT00; CODE=0; MSG=Login timeout expired
- SQLSTATE=08001; CODE=10060; MSG=A network-related or instance-specific error occurred...
可能原因：
- 跨区域 DNS 解析偶发变慢或缓存未命中，导致登录超时（HYT00 等）。
- 网络抖动/丢包，或防火墙对 1433 端口限速。
- 多子网/异地容灾场景中，连接路径切换导致初次建连耗时。
建议操作：
- 立即缓解：
- 提高登录超时至 10~15 秒（DB_LOGIN_TIMEOUT），并开启 IP 回退（本脚本已内置）。
- 在应用侧启用连接重试，或短期在本机配置 hosts 静态解析（仅应急，变更需记录）。
- 排查验证：
- 测试 DNS 时延：nslookup <真实主机名> 或 dig <真实主机名> 并记录耗时/TTL。
- 连通性检查：telnet <目标> 1433 或 Test-NetConnection（Windows）。
- 查看防火墙与安全组是否对跨区域流量限速/丢弃。
- 长期优化：
- 启用/确认 MultiSubnetFailover=Yes（已在连接参数中开启）。
- 引入就近 DNS/缓存（如 systemd-resolved、nscd）并监控解析时延与命中率。
- 与 DBA/网络团队确认跨区域链路与 SQL 监听端点策略，必要时提供就近只读/写入端点。
提示：为安全起见，已隐藏连接字符串和密码。详细技术信息请查看应用日志。
技术说明
- 错误类型：SQL Server 连接失败（DNS 解析延迟引发的驱动登录超时 HYT00/08001 等）
- 可能原因：
- 跨区域 DNS 解析延迟或缓存未命中导致初次连接耗时偏高
- 网络链路抖动、丢包或防火墙策略导致 TCP 1433 建连超时
- 多子网/异地容灾（AlwaysOn Listener）在故障转移或路径切换时连接建立变慢
- 解决建议：
- 提高 LoginTimeout 至 10~15 秒并启用有限重试，降低瞬时抖动对业务的影响
- 保持加密连接 Encrypt=Yes，必要时与证书策略一致后再考虑 TrustServerCertificate
- 在驱动参数中启用 MultiSubnetFailover=Yes（已开启）以优化多子网探测
- 部署/启用本地 DNS 缓存或边缘 DNS，加大热点记录 TTL 并监控解析时延
- 用 nslookup/dig/Resolve-DnsName 测试解析时间，配合 ping/telnet/Test-NetConnection 验证端口可达
- 与网络/DBA 校验安全组、ACL、跨区域链路质量与带宽；必要时提供就近访问的专用读/写端点
使用说明
-
集成方式：
- 确保安装 sqlsrv 或 pdo_sqlsrv（优先使用 sqlsrv）
- 设置环境变量：
- DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD
- 可选：DB_LOGIN_TIMEOUT（默认5秒）、DB_MAX_LOGIN_TIMEOUT（默认12秒）
- 可选：DB_DNS_SLOW_THRESHOLD_MS（默认150ms）、DB_CONN_RETRIES（默认2）
- 可选：DB_ENCRYPT=yes/no（默认yes）、DB_TRUST_SERVER_CERT=yes/no（默认no）
- 可选：APP_LOG（默认 /var/log/app/db_connect.log）
- 在命令行运行此脚本，失败时会输出面向管理员的诊断信息，并记录安全日志用于深入排查。
-
注意事项：
- 控制台输出不会包含连接字符串或密码；日志同样不记录密码。
- 若在生产环境短期启用 hosts 静态解析，请记录变更并在根因修复后撤销。
- 如使用加密连接且出现证书相关错误，请与安全与DBA团队确认证书链与主机名一致性，不建议长期启用 TrustServerCertificate。
- 返回码 0 表示连接成功；70 表示软件类错误（连接失败）。
