Docker部署FastAPI接收UploadFile的POST请求始终无法完成

以下是针对本地运行正常、Docker部署后请求无响应的排查步骤：

1. 确认端口映射与容器网络配置 #

• 启动容器时必须显式映射端口：执行 docker run -p 3000:3000 your-image-name，确保宿主机的3000端口映射到容器内的3000端口。
• 验证容器内服务监听地址：你的代码中已设置 host="0.0.0.0"，确保服务接受所有网卡的请求，而非仅本地回环。
• 测试容器内连通性：进入容器执行 docker exec -it <容器ID> bash，然后用 curl localhost:3000/echo -F "file=@/etc/hosts" 测试接口。如果容器内请求正常，说明问题出在宿主机到容器的网络；如果容器内也卡住，排查服务本身或容器配置。

2. 检查临时目录权限 #

FastAPI处理UploadFile时会将文件写入临时目录（默认/tmp），若容器内该目录无读写权限，会导致请求阻塞：

• 在Dockerfile中添加目录创建与权限设置：

RUN mkdir -p /tmp && chmod 777 /tmp
# 或自定义临时目录
RUN mkdir -p /app/temp && chmod 777 /app/temp

• 若自定义临时目录，可在代码中指定：

import os
from fastapi import FastAPI

app = FastAPI()

# 启动前创建并配置临时目录
temp_dir = "/app/temp"
os.makedirs(temp_dir, exist_ok=True)
os.chmod(temp_dir, 0o777)
# 覆盖Starlette的临时目录配置
app.state.temp_dir = temp_dir

3. 验证服务启动与日志输出 #

• 查看容器日志：执行 docker logs <容器ID>，确认是否有服务启动的日志（比如你代码中的Starting the application...）。如果没有启动日志，说明服务未正常启动，检查Dockerfile的启动命令是否正确。
• 若服务已启动但无请求日志，说明请求未到达容器，排查端口映射、宿主机防火墙/安全组是否开放3000端口。

4. 调整Uvicorn运行参数 #

默认单线程的Uvicorn在处理大文件上传时可能出现阻塞，尝试增加工作进程数：

if __name__ == "__main__":
    logger.info("Starting the application...")
    uvicorn.run(app, host="0.0.0.0", port=3000, log_level="debug", workers=2)

5. 检查Docker资源限制 #

若容器被设置了内存/CPU限制，可能因资源不足导致文件上传处理停滞。启动容器时可移除限制或调整资源配额：

docker run -p 3000:3000 --memory=2g --cpus=1 your-image-name

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