Linux服务器Docker环境Node.js连接Oracle报ORA-12154问题排查

Node.js项目基于Docker配置Oracle Instant Client连接数据库时，抛出ORA-12154: TNS:could not resolve the connect identifier specified错误，以下是原有配置、根因分析和可直接落地的修复方案。

原有配置参考 #

原Dockerfile #

FROM node:14-slim AS build-stage

COPY . /home/app

ENV APPLICATION_NAME="::apiName::"
WORKDIR /home/app

RUN apt-get update && apt-get -y upgrade && apt-get -y dist-upgrade && apt-get install -y libpq-dev zlib1g-dev libaio1 libaio-dev wget unzip
RUN wget get https://download.oracle.com/otn_software/linux/instantclient/217000/instantclient-basiclite-linux.x64-21.7.0.0.0dbru.zip
RUN alien -i --scripts oracle-instantclient*.rpm
RUN unzip instantclient-basiclite-linux.x64-21.7.0.0.0dbru.zip
RUN echo /home/app/instantclient_21_7 > /etc/ld.so.conf.d/oracle-instantclient.conf 
RUN ldconfig


RUN npm rm -rf node_modules &&\
    npm install

CMD ["npm", "run", "dev"]

原报错信息 #

(node:256) UnhandledPromiseRejectionWarning: Error: ORA-12154: TNS:could not resolve the connect identifier specified
(Use `node --trace-warnings ...` to show where the warning was created)
(node:256) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict`
(node:256) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

原数据库连接代码 #

const conn = {
  user: "user",
  password: "pass",
  connectionString:"host:port/service_name",
};

try {
  console.log("Here in DTO");
  var connection = oracledb.getConnection(conn);
  console.log("***** Connected to Oracle DB *****");
} catch (err) {
  console.log(err);
}

问题根因 #

• Dockerfile存在逻辑错误：wget命令冗余拼接了get参数，且部署流程冲突——仅下载了zip格式的Instant Client包，未下载对应RPM包，导致alien -i安装RPM的步骤实际执行失败；同时混用ZIP解压、RPM安装两种Instant Client部署方式，极易引发动态链接库加载混乱。
• 连接代码写法错误：oracledb.getConnection()是异步返回Promise的API，同步写法的try/catch无法捕获异步抛出的异常，不仅会触发未捕获Promise警告，也拿不到连接阶段的真实错误细节。
• 连接配置与网络存在不确定性：若connectionString中的主机地址在容器网络内不可达、端口不通、服务名填写错误，或是未配置TNS_ADMIN环境变量导致本地TNS配置无法加载，都会触发ORA-12154报错。

修复步骤 #

1. 重写Dockerfile，修正Instant Client部署逻辑 #

去掉冗余、冲突的安装步骤，精简镜像层，合理利用Docker构建缓存：

FROM node:14-slim
WORKDIR /home/app

# 安装系统依赖，移除未实际使用的安装包，减少镜像体积
RUN apt-get update && apt-get install -y --no-install-recommends \
    libaio1 \
    wget \
    unzip \
    && rm -rf /var/lib/apt/lists/*

# 部署Oracle Instant Client，仅保留ZIP解压部署方式，移除冲突的RPM安装步骤
# 注意修正wget命令的冗余参数，下载对应版本的Basic Lite包
RUN wget [Oracle Instant Client 21.7 Basic Lite 对应架构官方安装包] \
    && unzip instantclient-basiclite-linux.x64-21.7.0.0.0dbru.zip \
    && rm instantclient-basiclite-linux.x64-21.7.0.0.0dbru.zip \
    && echo /home/app/instantclient_21_7 > /etc/ld.so.conf.d/oracle-instantclient.conf \
    && ldconfig

# 配置应用环境
ENV APPLICATION_NAME="::apiName::"
# 如果需要使用tnsnames.ora解析连接，添加下面这行配置，把tnsnames.ora放到对应目录即可
# ENV TNS_ADMIN=/home/app/instantclient_21_7/network/admin

# 优先复制依赖清单安装npm包，代码变更时不需要重新安装依赖，提升构建速度
COPY package*.json ./
RUN npm install --production
COPY . .

CMD ["npm", "run", "dev"]

2. 修正数据库连接代码，正确处理异步逻辑 #

21版本及以上的oracledb驱动支持Thin模式，开启后可以不依赖本地Instant Client动态库，进一步降低环境问题概率，同时正确用async/await捕获异步错误：

const oracledb = require('oracledb');
// 开启Thin模式，减少本地类库依赖
oracledb.thin = true;

const connConfig = {
  user: "user",
  password: "pass",
  connectionString: "host:port/service_name",
};

async function connectOracle() {
  let connection;
  try {
    console.log("开始尝试连接Oracle数据库");
    connection = await oracledb.getConnection(connConfig);
    console.log("***** Oracle数据库连接成功 *****");
    // 后续数据库操作逻辑在此处编写
  } catch (err) {
    console.error("数据库连接异常：", err);
    process.exit(1);
  } finally {
    if (connection) {
      await connection.close();
    }
  }
}

connectOracle();

3. 容器内网络连通性校验 #

镜像构建启动后，先进入容器执行网络校验，排除网络层问题：

• 安装telnet工具，测试数据库主机+端口的连通性，如果telnet无法建立连接，优先排查容器网络、防火墙、数据库端口监听配置，这类问题和客户端配置无关。
• 核对connectionString中的服务名是否和数据库端配置一致，如果使用SID而非服务名，调整连接字符串格式匹配即可。

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