Azure Kubernetes集群中Uvicorn多worker启动时子进程退出问题

以下是导致子进程异常退出的常见原因及排查方向：

1. 容器PID 1信号处理异常 #

在Kubernetes容器中，主进程默认是PID 1，而Uvicorn父进程作为PID 1时，Linux系统默认的信号处理机制会失效——PID 1不会自动将信号转发给子进程，导致Uvicorn无法正确管理worker子进程，进而引发子进程启动后异常退出。

解决思路：使用tini作为容器的init进程，接管PID 1的信号处理，确保Uvicorn父进程能正常转发信号、管理worker。可以在Dockerfile中添加tini，或者在Kubernetes部署的command字段中指定tini启动Uvicorn。

2. 容器资源配额不足 #

AKS容器的CPU/内存资源限制可能过低，启动3个worker时，总资源需求超过容器配额，导致子进程被OOM Killer强制终止，或因无法分配足够资源启动失败。

排查方法：

• 执行kubectl describe pod <你的Pod名称>，查看事件日志中是否有OOMKilled记录；
• 检查Pod的resources.requests和resources.limits配置，确认资源配额是否满足多worker的运行需求。

3. 文件描述符限制过低 #

Linux系统默认文件描述符限制较低，多个worker进程同时运行时，需要打开的套接字、日志文件等资源会占用大量文件描述符，若容器内限制不足，会导致子进程启动失败。

排查方法：

• 进入容器执行ulimit -n，查看当前文件描述符限制；
• 在Dockerfile中添加RUN ulimit -n 65535，或在Kubernetes部署的securityContext中配置文件描述符限制。

4. Uvicorn与容器环境的兼容性问题 #

FastAPI 0.111.0搭配的Uvicorn版本可能在Linux容器环境下存在多worker模式的兼容性bug，比如依赖的uvloop事件循环在容器中无法正常初始化，导致子进程启动失败。

排查方法：

• 升级Uvicorn到最新稳定版本；
• 启动Uvicorn时指定使用asyncio事件循环：uvicorn.run(..., loop="asyncio")，绕过uvloop的兼容性问题。

实用排查步骤 #

1. 查看详细错误日志：执行kubectl logs <你的Pod名称>，或进入容器手动启动Uvicorn多worker模式（uvicorn main:app --host 0.0.0.0 --port 8080 --workers 3），获取更具体的报错信息；
2. 检查进程状态：进入容器执行ps aux，确认Uvicorn父进程是否为PID 1，以及子进程退出前的状态；
3. 验证资源使用：用kubectl top pod <你的Pod名称>查看Pod的实时资源占用，判断是否存在资源瓶颈。

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