Oracle Node.js 客户端环境配置工具

适用于 Ubuntu 24.04 环境下的 Node.js Oracle 客户端依赖库自动安装脚本。

项目简介

本项目提供一键安装 Oracle Instant Client 环境的脚本，解决在 Ubuntu 24.04 上配置 node-oracledb 时的依赖问题。主要解决以下痛点：

• 自动安装 Oracle Instant Client 所需的系统依赖
• 解决 Ubuntu 24.04 中 libaio 库版本兼容问题
• 配置动态链接库路径，无需手动设置 LD_LIBRARY_PATH

前置要求

• 操作系统: Ubuntu 24.04 (或其他基于 Debian 的 Linux 发行版)
• 权限: 需要 sudo 权限执行安装脚本
• 文件: 确保以下文件存在于项目根目录：
  • instantclient-basic-linux.x64-19.31.0.0.0dbru.zip
  • instantclient-sqlplus-linux.x64-19.31.0.0.0dbru.zip

提示: Oracle Instant Client 压缩包可从 Oracle 官网 下载。

快速开始

1. 一键安装

sudo bash install-oracle-client-env.sh

安装脚本会自动完成以下操作：

1. 安装系统依赖（unzip, libaio1t64, libnsl2, ca-certificates）
2. 创建 libaio.so.1 兼容软链接
3. 解压 Oracle Instant Client 到 /opt/oracle/instantclient_19_31
4. 配置动态链接器缓存

2. 验证安装

安装完成后，可以使用 SQL*Plus 验证：

/opt/oracle/instantclient_19_31/sqlplus -v

预期输出：

SQL*Plus: Release 19.31.0.0.0 - Production
Version 19.31.0.0.0

测试连接

方式一：使用 Docker 启动 Oracle 数据库

项目提供了 docker-compose.yml 用于快速启动 Oracle 11g XE 测试数据库。

启动数据库容器：

docker compose up -d

等待数据库启动（首次启动需要 1-2 分钟）：

# 查看容器状态
docker compose ps

# 查看启动日志
docker compose logs -f oracle11g

使用 SQL*Plus 测试连接：

/opt/oracle/instantclient_19_31/sqlplus system/oracle@localhost:1521/XE

成功连接后会看到 SQL> 提示符。

方式二：使用 Node.js 测试

安装 Node.js 依赖：

npm install

运行测试脚本：

node test-oracle.js

预期输出：

node-oracledb version: 7.0.0
is thin mode: false
Oracle Client version: 19.31.0.0.0
[ [ 'SYSTEM', 'Oracle Database 11g Express Edition Release 11.2.0.2.0 - 64bit Production' ] ]

项目结构

.
├── install-oracle-client-env.sh   # 一键安装脚本
├── uninstall.sh                   # 卸载脚本
├── test-oracle.js                 # Node.js 连接测试代码
├── docker-compose.yml             # Oracle 11g XE 测试容器配置
├── package.json                   # Node.js 项目配置
├── instantclient-basic-linux.x64-19.31.0.0.0dbru.zip   # Oracle Instant Client Basic
└── instantclient-sqlplus-linux.x64-19.31.0.0.0dbru.zip # Oracle Instant Client SQL*Plus

卸载

卸载 Oracle Instant Client（不会删除已安装的系统依赖）：

sudo bash uninstall.sh

卸载完成后，可以通过以下命令验证：

# 检查目录是否已删除
ls /opt/oracle

# 检查动态链接器配置是否已删除
cat /etc/ld.so.conf.d/oracle-instantclient.conf

常见问题

1. ORA-12154: TNS:could not resolve the connect identifier specified

原因：连接字符串格式不正确。

解决方案：确保使用正确的连接格式：

• Easy Connect: host:port/service_name（如 localhost:1521/XE）
• 完整描述符格式（适用于 SID）：

  (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=数据库IP)(PORT=1521))(CONNECT_DATA=(SID=ORCL)))
  

2. DPI-1047: Cannot locate a 64-bit Oracle Client library

原因：Oracle Instant Client 未正确配置或路径不可见。

解决方案：

1. 确认安装脚本已成功执行
2. 检查 /opt/oracle/instantclient_19_31 目录是否存在
3. 运行 ldconfig 刷新缓存：

   sudo ldconfig

3. libaio.so.1: cannot open shared object file

原因：libaio 库未安装或软链接未创建。

解决方案：

# 安装依赖
sudo apt-get install -y libaio1t64

# 创建软链接
sudo ln -sf /usr/lib/x86_64-linux-gnu/libaio.so.1t64 /usr/lib/x86_64-linux-gnu/libaio.so.1

# 刷新缓存
sudo ldconfig

4. Docker 容器启动后无法连接

原因：数据库还在初始化中。

解决方案：

# 等待并查看日志，直到出现 "Database ready to use"
docker compose logs -f oracle11g

技术栈

组件	版本
Oracle Instant Client	19.31
Oracle Database (Docker)	11g XE
Node.js oracledb	^7.0.0
libaio	1t64 (Ubuntu 24.04)

参考资源

• node-oracledb 官方文档
• Oracle Instant Client 下载
• Oracle 11g XE Docker 镜像

许可证

ISC