文档中心知识库安全API Explorer
文档中心›KB›ZCenter 服务因数据库连接异常无法启动或接口报错，如何排查？KB
文档目录

问题说明

本文用于排查Gateway仍可访问，但Base、Portal或业务服务无法启动、接口失败或间歇性超时的数据库问题。本文聚焦数据库可用性、认证、连接池、只读状态和磁盘容量；Flyway脚本校验问题应使用独立KB排查。

现象

  • 服务启动日志出现Unable to obtain connection、Communications link failure或Application run failed。
  • 接口返回应用失败信息，日志出现HikariPool、Connection is not available, request timed out。
  • 数据库返回Access denied for user、Unknown database、Too many connections或只读错误。
  • Gateway端口正常，但目标服务未注册、返回503或业务响应失败。
  • 数据库磁盘空间不足、inode耗尽或InnoDB写入失败。

适用环境

  • 产品：ZCenter
  • 版本：5.1.0
  • 组件：MariaDB/MySQL、HikariCP、Base、Portal及各业务服务

可能原因

  • 数据库进程未运行、3306不可达或防火墙/路由异常。
  • 应用实际配置的地址、数据库名、账号、密码或主机授权不正确。
  • 多个ZCenter服务和副本连接总量超过数据库max_connections。
  • 慢查询、长事务、锁等待或数据库I/O慢导致Hikari连接池耗尽。
  • HA环境连接到只读副本，或数据库启用了read_only/super_read_only。
  • 数据库数据盘、临时目录或inode不足。

排查步骤

1. 确认影响范围和有效配置

  • 记录受影响服务、接口、时间和错误堆栈。
  • 核对服务实际Spring Profile、启动参数、环境变量和挂载配置中的数据库地址、端口、库名和用户，密码需脱敏。
  • 注意：Gateway本身不使用业务数据库，Gateway正常不代表业务服务数据库连接正常。

2. 检查端口和数据库进程

ss -lntp | grep ':3306'
nc -vz <db-host> 3306
systemctl status mariadb
df -hT
df -ih
  • 预期结果：数据库进程正常、端口可达，数据盘和inode有足够空间。
  • 异常处理：恢复数据库服务、网络或存储；不要手动删除InnoDB文件、redo日志或数据库目录。

3. 使用应用账号执行只读验证

mysql --protocol=TCP -h <db-host> -P <port> -u <application-user> -p
SELECT VERSION(), @@hostname, @@port;
SELECT USER(), CURRENT_USER(), DATABASE();
SELECT 1;
SELECT @@global.read_only, @@global.super_read_only;
SHOW VARIABLES WHERE Variable_name IN ('max_connections', 'read_only', 'super_read_only');
SHOW GLOBAL STATUS WHERE Variable_name IN ('Threads_connected', 'Threads_running', 'Max_used_connections', 'Aborted_connects');
  • 预期结果：使用与应用相同网络路径和账号认证成功，目标数据库可见且需要写入的节点为可写主节点。
  • 注意：super_read_only是否存在取决于数据库版本；字段不存在时以当前MariaDB/MySQL版本支持的只读状态变量为准。
  • 异常处理：根据返回结果修正账号授权、密码、数据库名或HA连接地址；不要盲目关闭副本的只读模式。

4. 判断连接池耗尽

  • 对比Threads_connected、Max_used_connections和max_connections。
  • 核对ZCenter服务实例数量和每实例Hikari池上限，副本数会放大总连接需求。
  • 检查数据库CPU、I/O、慢查询、长事务和锁等待，并结合应用线程堆栈。
  • 注意：Hikari超时不一定是连接泄漏，数据库变慢或磁盘已满同样会占住连接。

5. 检查应用和数据库日志

  • 应用搜索：HikariPool、Unable to acquire JDBC Connection、Too many connections、Access denied、read-only、No space left on device。
  • 数据库搜索：InnoDB、连接拒绝、认证失败、磁盘满、崩溃恢复和主从切换。
  • 同时收集容器标准输出或systemd日志；部分ERROR日志不一定写入logs/zscmp.log。

处理方式

  1. 数据库不可用时先恢复数据库服务和网络，确认SELECT 1成功后再观察ZCenter服务恢复。
  2. 凭据错误时修改实际部署的Secret或运行时配置，并验证同一网络路径下的账号权限。
  3. 连接耗尽时先处理慢查询、长事务、连接风暴和数据库容量，不要同时盲目增大所有Hikari池与max_connections。
  4. 只读错误时恢复正确的可写主节点或VIP，禁止直接在未确认角色的副本执行read_only=OFF。
  5. 磁盘已满时扩容或按数据库运维规范清理可安全删除的数据，禁止手工删除数据库核心文件。
  6. 数据库恢复后Hikari通常会重新连接；如个别服务未恢复，仅按部署规范重启受影响服务。

验证方法

  • 数据库账号认证成功，所有需要的zscmp_*数据库可见。
  • 可写节点状态正确，磁盘空间和inode充足。
  • Threads_connected稳定低于上限，不再新增Hikari连接超时。
  • 受影响服务持续运行并重新注册到Nacos。
  • 完成登录、一个只读查询和一个经批准的低风险写操作。
  • 检查响应体业务状态和服务日志，不能只根据HTTP 200判断成功。

风险与回滚

  • 扩大连接池或数据库连接上限会增加数据库内存压力，应结合实例数评估。
  • 修改HA节点角色或只读状态可能破坏复制关系，必须由数据库负责人操作。
  • 配置变更前记录原连接参数；异常时恢复原配置并仅重启受影响服务。

补充信息

上一篇添加云环境或测试云账号连接失败，如何排查？下一篇ZCenter 部署或访问因端口未放通失败，如何排查？
ZCenter 服务因数据库连接异常无法启动或接口报错，如何排查？ | 故障排查 · KB | ZStack 资源中心