旧 Docker 环境下 Python 线程创建失败的排障实录

简介

一次看似普通的 Python 服务部署，最终暴露出一个很容易被误判的问题：应用日志报出 RuntimeError: can't start new thread，服务端口连接被重置，容器反复重启。直觉会把问题指向内存不足、线程池配置过大或 Docker PID 限制；然而这些方向都不是根因。

最终的答案是旧版本 Docker 的默认 seccomp 规则与 Python 3.11 / Debian Bookworm 运行时的兼容性问题。本文完整复盘排查路径，重点分享如何构建证据链、如何用最小实验验证假设，以及如何在“快速恢复”和“长期治理”之间做工程取舍。

一、问题背景

在不少生产环境中，服务器并不是一台可以随时重装、随时升级的“空白机器”。它们往往承载着长期运行的核心业务：不同年代上线的 Java 服务、数据库、中间件、定时任务和运维脚本会逐步堆积。升级 Docker Engine 这类底层运行时，可能影响既有容器、镜像构建链路、网络规则和发布流程，因此即使应用代码持续迭代，宿主机 Docker 版本也可能停留在较早的版本。

这类环境有三个典型特征：

• 业务密度高。 同一台服务器运行多个服务，资源余量有限，任何运行时变更都需要谨慎评估。
• 升级窗口稀缺。 基础设施升级需要跨团队协调、回归验证和回滚预案，优先级通常低于直接面向业务的需求。
• 构建与运行分离。 Jenkins 或构建机率先使用新的基础镜像、语言运行时和依赖版本，而生产服务器仍保留旧 Docker，二者因此形成兼容性断层。

因此，这次故障并非“机器性能不足”或“开发环境不规范”这样简单。它本质上是一个典型的生产运行时版本债务：新的用户态软件被部署到了旧的容器运行时上，默认安全策略没有跟上基础镜像的演进。

服务由两个容器组成：

• browser：提供远程浏览器能力，供采集任务通过 CDP 连接。
• app：Python Web 服务，负责管理接口、任务调度和爬取编排。

构建节点使用较新的 Docker 和 Python 3.11 基础镜像；目标服务器运行着较旧的 Docker，且与多个既有服务共用资源。由于目标机器不具备可靠的 Compose 构建能力，部署改为“构建机产出镜像，目标机只拉取或导入镜像，再通过 docker run 启动”。

浏览器容器率先报错：

chrome_crashpad_handler: Operation not permitted

为浏览器增加 seccomp=unconfined 后，Chrome 能够正常启动。但 Python 应用仍无法稳定运行，问题进入第二阶段。

二、故障现象：服务看似启动，随后又消失

应用容器的表现具有迷惑性：

1. docker ps 中容器短暂显示 Up，健康状态为 starting。
2. 访问 http://127.0.0.1:<port>/health 返回 Recv failure: Connection reset by peer。
3. 日志显示 Web 服务已完成启动，但很快又出现下一轮进程启动日志。
4. 应用日志多次出现 can't start new thread。

其中一个容易忽略的事实是：应用启动阶段会执行数据库结构初始化。这个过程可能持续几十秒，因此刚创建容器后立刻探测端口，得到连接重置并不能直接证明服务崩溃。

这带来两个不同的问题：

• 启动慢导致健康检查可能过早失败。
• 线程创建失败导致服务即使完成启动，也无法承载依赖线程的后台任务和同步请求处理。

排障的第一原则是将两者拆开：先确认进程是否真正退出，再判断健康检查是否只是“看到了尚未就绪的服务”。

三、先排除最符合直觉的假设

1. 是否发生 OOM？

先检查容器状态：

docker inspect app-container | grep -E '"OOMKilled"|"RestartCount"|"PidsLimit"|"ExitCode"'

如果 OOMKilled=true，应优先处理内存；本次现场 OOMKilled=false，可以先排除最直接的内存杀进程路径。

需要强调：free -h 中的 free 很低并不等于系统没有可用内存，Linux 的页缓存会占用大量空闲内存。应以 available 为主要参考，并结合容器 cgroup 限额判断。

2. 是否触碰了 PID 或线程上限？

继续检查：

ps -eLf | wc -l
ulimit -u
cat /proc/sys/kernel/threads-max
cat /proc/sys/kernel/pid_max

本次结果显示：当前线程数远低于 threads-max，用户级进程限制和系统 PID 上限也有明显余量，Docker 的 PidsLimit 为 0。这意味着“线程数量耗尽”缺少证据支撑。

3. 是否是线程栈太大？

线程创建失败还可能来自默认线程栈无法分配。一个常见验证思路是降低 Python 线程栈：

python -c '
import threading
threading.stack_size(512 * 1024)
t = threading.Thread(target=lambda: None)
t.start()
t.join()
print("thread-ok")
'

如果默认栈失败、降低栈后成功，才值得考虑调整线程栈大小。本次实验在降低栈后仍失败，因此排除该方向。

四、关键转折：从业务服务缩小为最小线程实验

复杂服务的日志里混杂了数据库初始化、HTTP 框架、调度器和浏览器连接。继续在业务代码中猜测，只会扩大排查面。

我们将问题缩小到最小容器实验：

docker run --rm \
  --entrypoint python \
  example/app:stable \
  -c 'import threading; t=threading.Thread(target=lambda: None); t.start(); t.join(); print("thread-ok")'

结果仍然是：

RuntimeError: can't start new thread

这一步非常关键。它证明故障与业务代码、数据库连接、线程池大小都无关，而发生在“容器运行时 + 基础镜像”的边界。

接下来使用同一个镜像，仅放宽 seccomp：

docker run --rm \
  --security-opt seccomp=unconfined \
  --entrypoint python \
  example/app:stable \
  -c 'import threading; t=threading.Thread(target=lambda: None); t.start(); t.join(); print("thread-ok")'

输出立即变为：

thread-ok

至此，证据链闭环：不是应用配置问题，而是默认 seccomp 配置导致线程创建相关系统调用受限。

五、根因：旧 seccomp 规则与新版用户态运行时的错配

seccomp 是 Linux 的系统调用过滤机制。Docker 默认使用 seccomp profile 限制容器可调用的系统调用，以降低容器逃逸和危险行为的攻击面。

问题在于，容器内的用户态组件会持续演进。Python 3.11、Debian Bookworm 及其 glibc 版本在创建线程时会使用较新的内核接口或调用路径；旧 Docker 内置的 seccomp profile 没有同步覆盖这些路径时，运行时会被内核拒绝。上层 Python 不会直接暴露“seccomp 拒绝”的细节，而是将线程创建失败包装为：

RuntimeError: can't start new thread

浏览器 crashpad 的 Operation not permitted 其实是同一环境不兼容问题的另一种表现。这也是为什么仅修复浏览器后，Python 服务仍然异常。

六、止血方案：将兼容性配置显式化

在无法立即升级 Docker 的情况下，最务实的短期方案是仅对受影响容器设置：

--security-opt seccomp=unconfined

不要将该参数散落在人工命令中。更可靠的做法是将其放入部署配置，并由部署脚本统一转换为 Docker 参数：

# 旧 Docker 下的浏览器兼容配置
BROWSER_SECCOMP_PROFILE=unconfined
 
# 旧 Docker 下的 Python 线程兼容配置
CRAWLER_SECCOMP_PROFILE=unconfined

部署脚本读取项目根目录 .env，并在启动时分别传入对应容器。这里有一个常见误解：.env 不是“打进镜像后自动读取的文件”。

• 镜像负责携带应用代码和依赖。
• 部署脚本读取宿主机项目目录的 .env，决定 Docker 启动参数。
• docker run --env-file .env 再把应用需要的环境变量传给容器。

因此，修改 .env 后必须重建容器：

bash scripts/deploy_docker_run.sh

只修改文件、不重建容器，不会改变已运行容器的 seccomp 配置。

七、验证不应只看“容器在运行”

修复后至少验证三个层次：

# 1. 应用可用性
curl -sS http://127.0.0.1:<port>/health
 
# 2. 运行时参数是否真正生效
docker inspect app-container --format '{{json .HostConfig.SecurityOpt}}'
 
# 3. 观察是否仍有重启
docker ps --filter name=app-container

预期是：

• 健康接口返回 status=ok。
• SecurityOpt 中出现 seccomp=unconfined。
• 容器不再增加重启次数。

如果 SecurityOpt 为 null，不要继续猜应用日志。优先检查部署脚本是否支持该字段，以及脚本读取的是否真的是刚修改的 .env。这一检查能快速发现“修改了配置文件，但服务器仍在跑旧脚本”这类交付问题。

八、启动慢与健康检查：另一个容易放大的问题

应用启动包含数据库结构初始化，耗时可能超过默认健康检查宽限期。若 start-period 只有十秒，健康检查会在服务尚未监听端口时连续失败，排障时会制造大量噪声。

推荐为此类服务设置更合理的启动宽限期，例如：

HEALTHCHECK --interval=30s --timeout=5s --start-period=90s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8232/health')" || exit 1

健康检查不会天然重启容器，但在某些平台、编排系统或运维守护策略中，unhealthy 状态可能触发额外的重启动作。因此应将“进程是否退出”和“健康检查是否失败”分别观察。

九、复盘：建立更高效的排障路径

这次故障的关键收获有四点：

1. 不要让直觉替代证据。 can't start new thread 不必然等于内存不足，也不必然等于线程池太大。
2. 尽早做最小复现。 用一行 Python 创建线程，比在完整服务日志中猜测更快、更可靠。
3. 分层验证配置是否生效。 配置文件存在不等于 Docker 参数已生效，docker inspect 才是事实来源。
4. 区分短期兼容与长期治理。 seccomp=unconfined 能快速恢复业务，但会扩大系统调用面，不应成为长期默认安全策略。

十、长期治理建议

短期兼容完成后，建议纳入以下改进：

• 升级 Docker Engine。 让运行时 seccomp profile 与现代基础镜像保持兼容。
• 分离构建与运行。 Jenkins 或独立构建节点负责构建和推送镜像，生产服务器只拉取或 docker load。
• 固化预检脚本。 在发布前执行最小线程测试、浏览器 CDP 探测、镜像标签校验和健康检查。
• 将资源限制配置化。 在共享服务器上为浏览器设置明确内存限制，并控制任务并发度。
• 保留运行时证据。 发布记录中保存镜像摘要、Docker 版本、SecurityOpt 和健康检查结果，缩短下一次故障定位时间。

结语

容器化并不会抹平运行时差异，反而会把“构建环境很新、生产运行时很旧”的错配放大。面对这类问题，最有效的方式不是在业务代码里反复调参数，而是快速将现象缩小到可验证的系统边界，再用单变量实验建立因果关系。

当一次故障被沉淀为可复用的检查项、部署脚本和运行手册，它就不再只是一次踩坑，而会成为团队交付体系的一部分。