FastAPI应用Docker部署后访问报Connection refused问题求助

问题根因 #

你当前配置里最核心的问题是启动命令加了--reload热重载参数。这个参数是本地开发调试用的，会额外启动文件监听进程，在Docker的隔离环境下经常出现子进程端口绑定失效的问题——哪怕日志显示服务已经在0.0.0.0:8000启动，实际端口也可能没有正常对外监听，外部请求直接被拒绝。你之前做的端口调整、EXPOSE配置增减都没有触碰到这个核心问题。

修复操作 #

1. 调整Dockerfile配置 #

首先修改启动命令，去掉--reload参数，同时可以优化下依赖安装逻辑减小镜像体积，修改后的Dockerfile参考：

FROM python:3.7-slim

WORKDIR /app/
COPY . /app/

# 合并apt安装命令，安装完成后清理缓存减小镜像体积
RUN apt-get update && apt-get install -y --no-install-recommends \
    apt-utils \
    curl \
    libgomp1 \
    && rm -rf /var/lib/apt/lists/*

# 安装python依赖时加--no-cache-dir避免缓存占空间
RUN pip install --no-cache-dir -r requirements.txt

EXPOSE 8000

# 去掉--reload，参数用空格分隔兼容性更好，明确指定监听地址和端口
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

补充：uvicorn的参数虽然支持--host=0.0.0.0这种等号写法，但在容器环境下用空格分隔参数的写法解析更稳定，不容易出现参数不生效的问题。

2. 重新部署容器 #

先清理之前创建的异常容器，再重新构建镜像启动：

# 强制删除旧的测试容器
docker rm -f test_cont
# 重新构建镜像
docker build -t ml_app:latest .
# 启动容器，加-d参数让容器后台运行
docker run -d -p 8000:8000 --name test_cont ml_app:latest

3. 连通性验证 #

启动后不要直接在宿主机测，先在容器内部确认服务正常：

# 在容器内部调用docs接口
docker exec -it test_cont curl http://127.0.0.1:8000/docs

如果这条命令能正常返回FastAPI默认文档的HTML内容，说明容器内服务运行正常，此时再在宿主机访问http://localhost:8000即可正常连通。

其他异常排查方向 #

如果按上面步骤修改后还是连接失败，按顺序排查：

• 宿主机8000端口被其他程序占用：修改端口映射为比如-p 8001:8000，访问宿主机8001端口测试
• 云服务器部署场景：检查安全组规则、系统防火墙（firewalld/ufw）是否开放了对应映射端口
• 代码配置冲突：检查main.py里有没有手动配置uvicorn启动时绑定127.0.0.1的逻辑，避免覆盖启动参数
• 不要在启动参数里把host设为127.0.0.1，必须绑定0.0.0.0才能让容器外部的请求访问到服务

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