Ubuntu下Oracle SQL Developer无法连接本地数据库 OCI库加载失败

安全阿岳

2026-8-26

Ubuntu环境Docker部署Oracle后SQL Developer连接故障修复

故障现象

Docker部署的Oracle实例在Windows、Intel芯片macOS上可通过SQL Developer正常连接，更换Ubuntu系统后连接localhost:1596/ORCLCDB失败
SQL*Plus可正常连接，但需提前在21.6版本Instant Client的sqlnet.ora中添加DISABLE_OOB=ON参数
数据库运行日志抛出Fatal NI connect error 12170，伴随TNS-12535操作超时、ORA-00609无法接入传入连接、ORA-12170 TNS连接超时异常
SQL Developer配置Instant Client路径/opt/oracle/instantclient_21_6时，目录校验、JDBC驱动加载、驱动版本（21.6.0.0.0）校验均通过，但native OCI库加载失败，报错提示java.library.path未包含Instant Client目录，当前路径列表为/usr/java/packages/lib:/usr/lib64:/lib64:/lib:/usr/lib

Ubuntu系统默认网络栈参数与Oracle客户端默认开启的OOB（带外数据）检测存在兼容性冲突，触发连接超时
SQL Developer启动时未继承终端配置的LD_LIBRARY_PATH环境变量，导致无法找到Instant Client下的native OCI动态库
OCI驱动加载失败后SQL Developer自动回退到纯JDBC瘦驱动，瘦驱动默认未配置OOB禁用规则，最终触发连接超时

修复动态库路径加载问题
编辑SQL Developer安装目录下的sqldeveloper/bin/sqldeveloper.conf文件，添加如下配置，强制指定Java动态库搜索路径：
```
AddVMOption -Djava.library.path=/opt/oracle/instantclient_21_6:/usr/java/packages/lib:/usr/lib64:/lib64:/lib:/usr/lib
```
也可以通过编辑/etc/profile全局配置环境变量，追加以下内容后执行source /etc/profile生效：
```
export LD_LIBRARY_PATH=/opt/oracle/instantclient_21_6:$LD_LIBRARY_PATH
```
配置客户端网络参数
进入Instant Client目录下的network/admin文件夹（不存在则手动创建），编辑sqlnet.ora文件添加以下配置，和SQL*Plus的可用配置保持一致：
```
DISABLE_OOB=ON
SQLNET.OUTBOUND_CONNECT_TIMEOUT=60
SQLNET.RECV_TIMEOUT=60
SQLNET.SEND_TIMEOUT=60
```
验证连接
重启SQL Developer，重新进入Instant Client配置页确认native OCI库加载成功，新建连接时选择OCI连接类型，填写主机localhost、端口1596、服务名ORCLCDB和对应账号密码即可连通。

如果不需要使用OCI驱动的专属特性，可直接配置瘦驱动禁用OOB，无需加载Instant Client：

编辑SQL Developer安装目录下的sqldeveloper/bin/sqldeveloper.conf文件，添加如下VM参数：
```
AddVMOption -Doracle.net.disableOob=true
```
重启SQL Developer，新建连接时选择默认的Basic连接类型，填写对应连接信息即可正常连通。

修复完成后可通过以下命令确认Docker端口映射正常，排除端口映射错误导致的连接问题：

docker ps | grep <oracle容器ID或名称>

确认输出中存在0.0.0.0:1596->1521/tcp的端口映射规则即可。

内容的提问来源于stack exchange，提问作者Jean-Philippe M