如何用PyCharm调试Docker中Gunicorn运行的Django应用

以下是完成调试的具体步骤：

1. 调整Docker镜像与docker-compose配置 #

1.1 安装PyCharm调试依赖 #

在你的Dockerfile中添加安装pydevd-pycharm的命令（版本需与你的PyCharm Professional版本匹配，比如PyCharm 2023.2对应pydevd-pycharm~=2023.2）：

RUN pip install pydevd-pycharm~=2023.2

1.2 修改docker-compose.yml配置 #

更新web服务的命令与环境变量，确保Gunicorn以单worker、预加载模式运行，并指定自定义Worker类：

web:
    build:
      context: .
    command:
      - gunicorn
      - --workers=1  # 调试时用单worker，避免多进程干扰断点触发
      - --worker-class=my_app.custom_worker.MyCustomWorker  # 替换为你的自定义Worker路径
      - --preload  # 预加载代码，确保调试器附着到worker进程
      - my_app.wsgi:application
    ports:
      - "8000:8000"
    environment:
      - DEBUG_MODE=1  # 用于触发调试器初始化逻辑

2. 在WSGI入口添加调试器连接代码 #

修改my_app/wsgi.py，添加调试器初始化逻辑，仅在调试模式下触发：

import os
from django.core.wsgi import get_wsgi_application

# 调试器初始化（仅DEBUG_MODE开启时生效）
if os.environ.get('DEBUG_MODE') == '1':
    import pydevd_pycharm
    # host.docker.internal用于Docker容器访问宿主机的PyCharm，端口可自定义
    pydevd_pycharm.settrace(
        'host.docker.internal',
        port=51234,
        stdoutToServer=True,
        stderrToServer=True
    )

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'my_app.settings')
application = get_wsgi_application()

3. 配置PyCharm Debug Server #

• 打开PyCharm，进入Run > Edit Configurations
• 点击左上角的+，选择Python Debug Server
• 配置参数：
  • Name：自定义名称（比如Docker Gunicorn Debug）
  • Host：0.0.0.0
  • Port：51234（需与wsgi.py中设置的端口一致）
• 点击Apply保存配置

4. 启动调试流程 #

1. 启动PyCharm的Debug Server：在Run菜单中选择刚才创建的Docker Gunicorn Debug配置，点击调试按钮（绿色虫子图标），此时PyCharm会等待容器的调试连接
2. 构建并启动Docker Compose服务：在PyCharm的Services窗口（或命令行执行docker-compose up --build）启动web服务
3. 验证连接：容器启动后，PyCharm会显示"Connected"提示，此时即可正常使用断点、单步执行、变量监视功能

调试自定义Worker的注意事项 #

• 直接在自定义Worker的核心逻辑中设置断点（比如run()方法、请求处理逻辑）
• 必须开启--preload参数，否则Gunicorn fork出的worker进程无法继承调试器连接
• 若调试Socket.io事件处理逻辑，在对应的事件函数中设置断点，客户端触发事件时会自动命中断点

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