Docker化Django应用用debugpy调试：连接后立即断开求助

核心问题排查与解决步骤 #

1. 确认debugpy是否真正启动 #

你的manage.py中debugpy的初始化逻辑仅在通过python manage.py runserver启动时执行，但当前服务是通过gunicorn启动的（见start_gunicorn.sh）。gunicorn直接加载WSGI模块，不会触发manage.py的main()函数，导致debugpy根本没在监听端口。

解决方法：

• 调试场景下切换用runserver启动：修改entrypoint.sh的development命令，改为执行python manage.py runserver 0.0.0.0:8000，同时确保DEBUG_ATTACH=true环境变量已设置。
• 若坚持用gunicorn，在WSGI入口文件（uplifty/wsgi.py）中添加debugpy初始化代码：

  import os
  import debugpy
  
  if os.environ.get("DEBUG_ATTACH") == "true":
      debugpy.listen(("0.0.0.0", 5678))
      print("Debugger listening on 0.0.0.0:5678")
      # 可选：需要等待调试器连接后再启动服务，取消下方注释
      # debugpy.wait_for_client()
      # print("Debugger attached!")
  
  import os
  from django.core.wsgi import get_wsgi_application
  
  os.environ.setdefault("DJANGO_SETTINGS_MODULE", "uplifty.settings")
  application = get_wsgi_application()
  

2. 验证DEBUG_ATTACH环境变量是否生效 #

检查.env文件中是否添加了DEBUG_ATTACH=true，docker-compose通过env_file加载环境变量，若该变量未设置，debugpy逻辑不会执行。

进入容器验证：

docker exec -it uplifty printenv DEBUG_ATTACH

若输出不是true，在.env中添加该变量后重启容器。

3. 确认debugpy已安装到容器 #

检查server/pyproject.toml是否将debugpy列为开发依赖，因为你用poetry export --dev生成requirements.txt。若未添加，执行：

poetry add --dev debugpy

然后重新构建镜像：

docker-compose -f docker-compose.backend.yml build uplifty

4. 规避gunicorn多worker进程干扰 #

你设置了NUM_WORKERS=2，gunicorn会启动多个worker进程，每个进程都会尝试监听5678端口，导致冲突或调试混乱。

解决方法：
调试时将NUM_WORKERS改为1，或在start_gunicorn.sh中添加条件判断：

NUM_WORKERS=1
if [ "${DEBUG_ATTACH}" != "true" ]; then
    NUM_WORKERS=2
fi

5. 检查端口监听状态 #

进入容器验证5678端口是否被监听：

docker exec -it uplifty netstat -tulpn | grep 5678

若无输出，说明debugpy未启动，回到步骤1-3排查。

6. 优化VSCode调试配置 #

在launch.json中添加redirectOutput选项，方便查看容器调试日志：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Django",
      "type": "python",
      "request": "attach",
      "connect": {
        "port": 5678,
        "host": "localhost"
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}/server",
          "remoteRoot": "/code/server"
        }
      ],
      "justMyCode": false,
      "redirectOutput": true
    }
  ]
}

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