Docker容器中Pandas read_excel运行停滞无报错问题咨询

这类问题属于Python服务容器化部署的高频踩坑，并非偶发个例，所有「容器内执行卡在读Excel步骤、无错误输出、CPU占用为0、宿主机同代码正常运行」的现象，基本可以归为以下几类可复现的诱因，对应排查方向非常明确：

核心诱因列表 #

• watchdog触发时机不对，读取到未写完的半文件
  这是搭配文件监控场景的最高发原因。PHP上传文件时是分块写入磁盘的，watchdog默认监听的on_created事件会在文件刚创建、还没写完的时候就触发回调；xlsx格式本质是zip压缩包，pd.read_excel调用的解析引擎会一直等待zip包的中央目录结构，读不到就会永久阻塞，不会抛出「文件损坏」类异常。宿主机上因为本地磁盘IO延迟低，文件写入速度快，回调触发时大概率已经写完，因此不会复现；容器环境下如果用了挂载卷、overlay2存储，IO延迟更高，很容易卡在半文件读取上。
• ubuntu:focal基础镜像缺失解析引擎依赖的系统库
  基于ubuntu:focal构建的精简镜像默认不会预装常用运行库，pip安装的openpyxl、xlrd等Excel解析引擎是预编译的wheel包，运行时会动态链接系统层的libzip4、libxml2、libgomp1库；如果这些库缺失或者版本不匹配，引擎不会在import阶段抛出导入错误，会在实际解析文件的步骤触发无响应阻塞，没有Python层的错误栈输出。另外如果镜像没配置UTF-8编码，默认使用POSIX编码时，读取带中文路径、中文单元格内容的Excel也可能卡在字符集转换逻辑上挂起。
• Docker默认安全规则拦截底层系统调用
  旧版本Docker的默认seccomp安全配置，会拦截Python 3.8（ubuntu:focal默认源自带的Python版本）在openpyxl做内存映射时调用的personality系统调用，拦截后不会返回权限错误，会直接让对应进程进入不可中断的等待状态，表现就是CPU空闲、无日志。在rootless Docker、自定义安全策略的集群环境下这个问题出现概率更高。
• 容器共享内存空间不足
  Docker默认给容器分配的/dev/shm共享内存只有64MB，pandas读取体积较大的Excel时，解析引擎会把临时解压的文件写到共享内存里，当临时文件大小超过64MB时，在部分内核版本上不会抛出「空间不足」的错误，会直接阻塞等待可用空间；宿主机的/dev/shm默认是物理内存的一半大小，因此不会触发这个问题。

可直接落地的排查步骤 #

1. 先修正watchdog的触发逻辑：不要直接响应文件创建事件，改为监听Linux inotify的IN_CLOSE_WRITE事件（对应watchdog的on_closed回调），或者加简单的轮询逻辑：每隔1s尝试以独占读模式打开目标文件，能正常打开时再调用读取逻辑，确保文件已经完全写入。
2. 在Python服务的Dockerfile里补全缺失的系统依赖，配置默认编码：

   RUN apt-get update && apt-get install -y --no-install-recommends \
       tini \
       locales \
       libxml2 \
       libxslt1.1 \
       libzip4 \
       libgomp1 \
       && locale-gen C.UTF-8
   ENV LANG=C.UTF-8 LC_ALL=C.UTF-8
   

   启动容器时用tini做1号进程，避免僵尸进程导致的阻塞。
3. 临时测试时可以给启动命令加--shm-size=1g参数把共享内存调到1G，再加--security-opt seccomp=unconfined关闭seccomp限制，如果此时能正常读取文件，就对应调整运行时的共享内存配置和seccomp规则即可。
4. 显式指定pd.read_excel的解析引擎，比如pd.read_excel(file_path, engine='openpyxl')，同时把pandas、openpyxl的版本固定到和宿主机完全一致，避免版本差异导致的逻辑兼容问题。

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