Quarkus 应用中 JDBC 连接异常排查与解决

理解“无法获取 JDBC 连接”错误

在 quarkus 或其他 java 应用中，当使用 hibernate 等 orm 框架尝试连接数据库时，如果遇到 javax.persistence.persistenceexception: org.hibernate.exception.jdbcconnectionexception: unable to acquire jdbc connection 错误，通常意味着应用程序无法建立与数据库的物理连接。如果进一步的堆栈信息显示 java.sql.sqlrecoverableexception: erreur d'e/s: the network adapter could not establish the connection 或类似的“网络适配器无法建立连接”消息，这明确指出问题根源在于网络层面或连接配置。

此类错误通常发生在以下场景：

1. 数据库服务器地址或端口不正确：应用程序尝试连接到一个不存在或监听在错误端口的地址。
2. 防火墙阻止连接：客户端机器或数据库服务器上的防火墙阻止了应用程序与数据库端口之间的通信。
3. 数据库服务未运行或监听器故障：数据库实例或其网络监听器（如 Oracle Listener）没有正常启动。
4. 网络路由问题：客户端机器无法通过网络路径到达数据库服务器。

核心排查与解决步骤

解决这类问题需要系统性地检查配置和网络环境。

1. 验证数据库连接配置

这是最常见也是最直接的原因。应用程序的 application.properties 文件中数据库连接字符串、用户名或密码的任何微小错误都可能导致连接失败。

以 Oracle 数据库为例，请仔细检查以下配置项：

# 数据库类型，例如 Oracle
quarkus.datasource.db-kind=oracle
# JDBC 连接 URL
quarkus.datasource.jdbc.url=jdbc:oracle:thin:@<数据库主机名或IP>:<端口>:<服务名或SID>
# 数据库用户名
quarkus.datasource.username=<你的用户名>
# 数据库密码
quarkus.datasource.password=<你的密码>

# 可选：连接池配置
# quarkus.datasource.jdbc.max-size=20
# quarkus.datasource.jdbc.min-size=5

关键检查点：

百灵大模型

蚂蚁集团自研的多模态AI大模型系列

313

查看详情

• quarkus.datasource.jdbc.url：
  • <数据库主机名或IP>：确保这是数据库服务器的正确网络地址。例如，原始问题中的 bodswv092 必须是数据库服务器的有效主机名或 IP 地址。如果使用主机名，请确保 DNS 解析正确。
  • <端口>：确认数据库监听器正在此端口上运行。Oracle 默认端口通常是 1521。
  • <服务名或SID>：对于 Oracle，这可以是服务名（如 DEMO）或系统标识符 (SID)。确保它与数据库实例的配置匹配。
• quarkus.datasource.username 和 quarkus.datasource.password：虽然“网络适配器无法建立连接”通常不是认证问题，但一旦网络连接成功，错误的凭据将导致下一个阶段的错误。因此，也要确保这些是正确的。

案例分析： 原始问题中的 URL 为 jdbc:oracle:thin:@bodswv092:1521:DEMO。如果 bodswv092 主机名、1521 端口或 DEMO 服务名有任何一个与实际数据库配置不符，就会导致连接失败。最常见的情况是主机名或 IP 地址错误。

2. 检查网络连通性

即使配置看起来正确，网络本身的问题也可能阻止连接。

• Ping 数据库主机： 在运行 Quarkus 应用的服务器上，尝试 ping <数据库主机名或IP>。如果 ping 不通，说明存在基本的网络可达性问题（如主机不存在、网络不通、防火墙阻止 ICMP）。

  ping bodswv092

  登录后复制

• Telnet 或 Netcat 检查端口可达性： 这是最关键的步骤之一。它能检查特定端口是否在数据库服务器上开放并可访问。

  # 对于 Linux/macOS
  telnet <数据库主机名或IP> <端口>
  # 例如：
  telnet bodswv092 1521
  
  # 或者使用 nc (netcat)
  nc -vz <数据库主机名或IP> <端口>
  # 例如：
  nc -vz bodswv092 1521

  登录后复制

  如果 telnet 命令成功连接（通常会显示连接信息并进入空白界面），说明网络连接到该端口是成功的。如果显示“Connection refused”、“No route to host”或长时间无响应，则表明端口不可达。

3. 检查防火墙设置

• 客户端防火墙：确保运行 Quarkus 应用的服务器没有出站规则阻止其连接到数据库的端口。
• 服务器防火墙：确保数据库服务器的防火墙（如 Linux 上的 firewalld 或 iptables，Windows 上的 Windows Defender 防火墙）允许来自应用服务器 IP 的入站连接到数据库端口（例如 1521）。

4. 确认数据库服务状态

• 数据库实例是否运行？ 登录到数据库服务器，确认数据库实例是否已启动。
• 数据库监听器是否运行？ 对于 Oracle，监听器（Listener）负责接受传入的连接请求。使用数据库工具（如 lsnrctl status）检查监听器状态。

最佳实践与注意事项

• 使用环境变量管理敏感信息：对于生产环境，数据库凭据等敏感信息不应直接硬编码在 application.properties 中，而应通过环境变量、Kubernetes Secrets 或配置管理工具注入。Quarkus 支持通过 quarkus.datasource.username=${DB_USERNAME} 这种方式引用环境变量。
• 详细日志记录：确保应用程序的日志级别设置为适当的级别（如 INFO 或 DEBUG），以便在连接失败时能获取更多详细的错误信息。Quarkus 默认日志通常已经足够。
• 逐步测试：在开发过程中，可以先使用一个简单的 JDBC 客户端（如 sqlplus、DBeaver 或一个简单的 Java 程序）从应用服务器尝试连接数据库，以排除 Quarkus/Hibernate 配置之外的问题。
• DNS 解析：如果数据库主机名无法解析，尝试直接使用 IP 地址进行连接，以排除 DNS 问题。

总结

“Unable to acquire JDBC Connection”并伴随“The Network Adapter could not establish the connection”错误，几乎总是指向数据库连接配置错误或网络连通性问题。解决此问题的关键在于：首先，仔细核对 application.properties 中的数据库 URL、主机名、端口和服务名是否完全正确；其次，利用 ping 和 telnet/nc 等网络工具验证从应用服务器到数据库服务器的网络可达性和端口开放情况；最后，检查两端的防火墙设置和数据库服务及监听器的运行状态。 通过系统性的排查，通常可以迅速定位并解决这类连接故障。

以上就是Quarkus 应用中 JDBC 连接异常排查与解决的详细内容，更多请关注php中文网其它相关文章！