Hibernate Reactive连接本地Oracle数据库失败求助

问题背景 #

使用Hibernate Reactive构建示例应用时，尝试连接基于oci-oracle-free部署的Oracle数据库，以下三种部署方式均失败，报错包含ORA-17868: Unknown host specified：

• 本地或GitHub Actions中使用Docker Compose部署
• GitHub Actions中使用市场的Setup Oracle DB Free Action部署
• GitHub Actions的services节点声明Oracle服务（已尝试用localhost和服务名作为连接串主机）

但同一应用中R2DBC连接正常，IDEA数据源视图通过JDBC驱动也能正常连接本地Oracle。

排查与解决方案 #

1. 修正Oracle Reactive驱动的连接串格式 #

Hibernate Reactive依赖的Oracle Reactive驱动（oracle.database.jdbc:ojdbc11-reactive）对连接串的格式要求比JDBC更严格：

• 必须带//前缀：正确格式为 jdbc:oracle:thin:@//<host>:<port>/<service_name>
• 容器环境下不能用localhost，需使用服务名称（比如Docker Compose或GitHub Actions services中定义的Oracle服务名，如oracle）
• Oracle Free镜像默认服务名为FREEPDB1，需确保连接串中指定正确

示例正确配置：

<property name="javax.persistence.jdbc.url" value="jdbc:oracle:thin:@//oracle:1521/FREEPDB1"/>
<property name="javax.persistence.jdbc.driver" value="oracle.database.jdbc.reactive.OracleReactiveDriver"/>

2. 验证容器服务的网络可达性 #

在GitHub Actions运行环境中，先确认Oracle服务的主机和端口可访问：

# 测试主机连通性
ping oracle
# 测试端口监听
nc -zv oracle 1521

若无法连通，需检查：

• Docker容器是否正常启动（查看日志确认Oracle初始化完成）
• GitHub Actions services中是否正确映射端口，或Docker Compose的端口配置是否正确

3. 核对Hibernate Reactive配置细节 #

确保persistence.xml中的配置无遗漏：

• 驱动类必须指定为Oracle Reactive驱动，而非普通JDBC驱动
• 用户名和密码需匹配Oracle Free镜像的默认配置（默认用户SYSTEM/sys，密码需在部署时指定）

4. 确认依赖版本兼容性 #

Hibernate Reactive与Oracle Reactive驱动版本需匹配：

• Hibernate Reactive 2.x 需搭配 ojdbc11-reactive 21.3.0.0 及以上版本
• 避免使用过时的驱动版本，可能存在网络连接相关的Bug

内容的提问来源于stack exchange，提问作者Hantsy