如何调试Docker容器中通过Gunicorn运行的Flask应用？

这个场景完全可以实现，不存在无法调试的情况，核心是适配Gunicorn的运行特性，打通debugpy的远程连接链路即可，具体配置步骤如下：

1. 容器内依赖与Gunicorn启动配置 #

首先在项目依赖中安装Python调试工具debugpy：

pip install debugpy

调试场景下必须调整Gunicorn启动参数，避免多进程冲突、调试超时断连：

• 强制单worker：添加启动参数--workers 1，多worker会导致debugpy端口冲突、断点随机命中无法稳定调试
• 强制单线程：添加启动参数--threads 1，避免多线程下调试时序错乱
• 拉长worker超时时间：添加启动参数--timeout 3600，默认30秒超时会导致断点停留时worker被Gunicorn主进程杀掉重启
• 其余参数和你正常启动Gunicorn的配置保持一致即可

在Flask应用入口文件（一般是app.py或者wsgi.py）的最顶部加入debugpy初始化代码：

import debugpy
# 监听容器内所有网卡的5678调试端口
debugpy.listen(("0.0.0.0", 5678))
# 按需开启下面这行：开启后容器启动会阻塞等待VSCode调试器连接后才会启动应用，适合启动阶段就要打断点的场景
# debugpy.wait_for_client()

2. Docker配置调整 #

构建镜像时确保debugpy被正常安装进容器环境即可，不需要额外修改基础镜像配置。
启动容器时需要把debugpy用的5678端口映射到宿主机：

• 直接docker run启动时追加参数：-p 5678:5678
• docker-compose启动时在服务的ports配置段追加：- "5678:5678"

3. VSCode端调试配置 #

在本地项目的.vscode/launch.json文件中添加远程附加调试配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "附加到Docker内Gunicorn Flask应用",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "/app"
                }
            ],
            "justMyCode": false
        }
    ]
}

配置项说明：

• remoteRoot需要替换为你自己容器内Flask项目代码存放的绝对路径，比如代码放在/opt/service就填对应路径，必须和容器内实际路径一致，否则断点无法命中
• justMyCode设为false时可以跟进Flask、Gunicorn框架层的代码调试，不需要可以设为true

配置完成后先启动容器，等Gunicorn服务正常运行后，打开VSCode的运行调试面板，选择刚才添加的配置点击启动，即可完成调试器连接，直接在代码中打点就能正常拦截请求、查看变量、单步执行。

常见踩坑排查 #

• 断点显示灰色无法命中：优先检查pathMappings的本地路径和容器路径是否对应，其次检查容器内代码和本地打开的代码版本是否一致
• 调试器连不上：先在宿主机执行telnet localhost 5678确认端口连通性，排查是否端口映射错误、宿主机5678端口被其他程序占用
• 调试过程中频繁断连：检查Gunicorn的timeout参数是否设置足够长，确认worker数量为1

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