Windows下Docker化Flask应用后API无法访问且调试模式未生效

一、API请求超时问题排查与修复 #

问题原因分析 #

当前配置中，Dockerfile的CMD已经指定flask run --host 0.0.0.0，确保容器内服务监听所有网络接口，理论上可以通过主机映射端口访问。超时可能由网络连通性、端口占用或环境配置错误导致。

修复步骤 #

1. 验证容器内服务可用性
   先进入容器内部测试服务是否正常运行：

   docker-compose exec api curl localhost:8080/hello -X POST
   

   如果返回ok，说明服务本身没问题，问题出在主机到容器的网络连通性。

2. 确认主机访问地址

   • 若使用Docker Desktop for Windows（WSL2/Hyper-V后端）：直接用localhost:8080访问，192.168.99.100通常是Docker Toolbox环境的默认IP，不适用于当前主流Docker Desktop配置。
   • 若为Docker Toolbox环境：检查VirtualBox虚拟机的网络配置，确认192.168.99.100是虚拟机的正确IP。

3. 检查端口与防火墙

   • 确认主机8080端口未被占用：执行netstat -ano | findstr ":8080"查看占用情况，若被占用则修改docker-compose的端口映射（如"8081:8080"）。
   • 临时关闭Windows防火墙测试，若能访问则添加Docker Desktop的入站规则。

二、调试模式不生效问题修复 #

问题原因 #

当前通过flask run启动服务时，main.py中if __name__ == "__main__"块的代码不会执行（因为flask run是通过FLASK_APP模块加载应用，而非直接运行main.py），因此该块内的debug=True不生效。同时，默认的flask run命令未开启调试模式。

修复方案（二选一） #

方案1：修改CMD命令添加调试参数

在Dockerfile中修改CMD，添加--debug参数：

CMD ["flask", "run", "--host", "0.0.0.0", "--debug"]

方案2：添加FLASK_DEBUG环境变量

在docker-compose.yaml的environment中添加FLASK_DEBUG=1：

environment:
    - FLASK_APP=main.py
    - GOOGLE_APPLICATION_CREDENTIALS=cred.json
    - FLASK_DEBUG=1

或在Dockerfile中添加：

ENV FLASK_DEBUG=1

备选方案：直接运行main.py（不推荐）

若要让main.py中的debug=True生效，可修改CMD为直接运行python脚本，但需将main.py中的host='127.0.0.1'改为host='0.0.0.0'，否则容器外部无法访问：

if __name__ == "__main__":
    app.run(host='0.0.0.0', port=8080, debug=True)

修改Dockerfile的CMD：

CMD ["python", "main.py"]

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