Docker容器内FastAPI占用CPU过高，本地运行资源占用极低问题求助

1. CPU占用过高的核心原因：--reload模式在Docker中的兼容性问题 #

• uvicorn的--reload模式依赖文件系统事件监听器检测代码变化以重启服务。在Docker容器环境中，尤其是代码目录通过卷挂载到容器内时，容器内的文件系统事件可能无法被正确捕获，导致reloader进入无限循环扫描文件的状态，直接占满CPU。
• 本地运行时，系统原生文件系统事件机制可正常工作，reloader仅在文件变化时触发扫描，因此资源占用极低。

2. Docker命令出现两次的原因：CMD的shell格式导致进程嵌套 #

你的Dockerfile中使用了shell格式的CMD：

CMD ZMQ_NETWORK="ai_manager" uvicorn api_rest.main:app --reload --host 0.0.0.0 --env-file database/config/docker.env

这种写法会让Docker启动一个sh -c父进程来执行命令，uvicorn作为子进程运行，因此查看进程时会看到两次命令（父shell进程和子uvicorn进程）。正确写法应使用exec格式的CMD，避免进程嵌套：

CMD ["sh", "-c", "ZMQ_NETWORK='ai_manager' uvicorn api_rest.main:app --reload --host 0.0.0.0 --env-file database/config/docker.env"]

或者拆分环境变量设置，用ENV指令提前定义：

ENV ZMQ_NETWORK="ai_manager"
CMD ["uvicorn", "api_rest.main:app", "--reload", "--host", "0.0.0.0", "--env-file", "database/config/docker.env"]

3. 解决CPU占用过高的具体方案 #

• 禁用--reload模式：生产环境绝对不要使用--reload，这是开发模式特性。如果是开发环境需要热重载，建议使用docker-compose卷挂载配合watchfiles替代uvicorn自带reloader，或调整uvicorn的reloader配置：

  # 使用watchfiles作为reloader后端，限制监听目录
  CMD ZMQ_NETWORK="ai_manager" uvicorn api_rest.main:app --reload --reload-dir api_rest --host 0.0.0.0 --env-file database/config/docker.env
  

  加上--reload-dir指定仅监听代码目录，避免扫描整个容器文件系统。
• 检查环境文件路径：确保database/config/docker.env在容器内存在且路径正确，若文件不存在，uvicorn可能反复尝试读取，导致额外CPU消耗。
• 使用exec格式CMD：如上述示例，避免shell进程嵌套，减少不必要的资源占用。

4. 验证步骤 #

• 启动容器时去掉--reload参数，观察CPU占用是否恢复正常。
• 若需要热重载，尝试添加--reload-dir限制监听目录，或在依赖中添加watchfiles后使用其作为reloader后端。
• 检查容器内进程列表，确认是否还有进程嵌套情况。

内容的提问来源于stack exchange，提问作者J Agustin Barrachina