Docker容器内Python Flask连接Oracle时报错找不到libclntsh.so如何解决？

可行解决方案及排查方向 #

1. 优先推荐：替换Oracle驱动为python-oracledb #

这是最简单的规避方案，Oracle官方新版Python驱动python-oracledb默认支持瘦连接模式，无需安装Oracle Instant Client，完全避免动态库依赖问题：

• 替换requirements.txt中的cx_Oracle为oracledb>=1.0
• 代码中连接逻辑调整为：

import oracledb
# 无需额外配置，直接按原连接参数创建连接即可，默认走瘦模式
connection = oracledb.connect(user="用户名", password="密码", dsn="DSN串")

如果必须使用厚模式兼容旧逻辑，再按需配置Instant Client即可，不会出现依赖找不到的问题。

2. 保留cx_Oracle的修复方案 #

如果必须使用旧版cx_Oracle驱动，按优先级排查以下问题：

• 架构不匹配校验
  如果你使用ARM架构设备（如苹果M系列芯片）构建镜像，默认生成的是arm64架构容器，但你下载的Oracle Instant Client是x86_64版本，就会出现ldconfig能查到库但实际无法加载的情况。
  解决方案：构建镜像时指定架构为amd64：

  docker build --platform linux/amd64 -t 你的镜像名 .
  

  或者下载对应arm64架构的Oracle Instant Client安装包。

• 权限校验
  如果你容器内使用非root用户运行Flask应用，需要确保Instant Client目录对运行用户有读和执行权限：

  # 安装完Instant Client后加一行
  RUN chmod -R a+rx /opt/oracle
  

• 驱动安装顺序校验
  必须先完成Instant Client的安装、环境变量配置，再执行pip install cx_Oracle，否则pip安装时无法链接到动态库，会生成无法加载的驱动二进制。可以在pip命令前加--force-reinstall强制重装：

  RUN pip install --force-reinstall -r requirements.txt
  

• 补全软链接
  解压Instant Client zip包后，需要手动创建无版本号的软链接，避免驱动找不到：

  RUN cd /opt/oracle/instantclient_19_13 \
      && ln -s libclntsh.so.19.13 libclntsh.so \
      && ln -s libocci.so.19.13 libocci.so
  

• entrypoint环境变量校验
  检查你的entrypoint.sh是否会重置LD_LIBRARY_PATH环境变量，可以在entrypoint脚本启动应用前加以下调试命令确认变量生效：

  echo $LD_LIBRARY_PATH
  ldd $(find /usr/local/lib/python3.9/site-packages -name "cx_Oracle*.so")
  

  确认输出中libclntsh.so有对应的加载路径。

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