Python Web服务器远程调试无法监听调试端口问题排查

环境配置 #

• FastAPI运行于Docker容器内，基于python3.12镜像
• 通过VSCode远程附加调试器进行连接

正常运行场景 #

当使用以下命令启动应用时可正常运行：

python -m debugpy --listen 0.0.0.0:5680 --wait-for-client main.py

对应的Docker启动命令：

docker run --mount type=bind,source=$(pwd),target=/home/app -p 5680:5680 -p 8080:8080 my_image

异常场景及报错 #

如果在main.py中添加以下代码：

debugpy.listen(("0.0.0.0", 5680))
debugpy.wait_for_client()

并通过python main.py启动服务（Dockerfile的CMD字段为CMD ["python", "main.py"]），会出现debugpy无法监听5680端口的报错，提示地址已被占用：

debugpy.listen(("0.0.0.0", 5680))
  File "/usr/local/lib/python3.12/site-packages/debugpy/public_api.py", line 31, in wrapper
    return wrapped(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/site-packages/debugpy/server/api.py", line 133, in debug
    log.reraise_exception("{0}() failed:", func.__name__, level="info")
  File "/usr/local/lib/python3.12/site-packages/debugpy/server/api.py", line 131, in debug
    return func(address, settrace_kwargs, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/site-packages/debugpy/server/api.py", line 260, in listen
    raise RuntimeError(str(endpoints["error"]))
RuntimeError: Can't listen for client connections: [Errno 98] Address already in use

希望采用内嵌代码的方式启动以适配多场景、减少开发环境代码改动，请问问题出在哪里？

排查及解决办法 #

1. 检查端口占用情况
   进入容器内部执行以下命令，确认5680端口是否被其他进程占用：

   netstat -tulpn | grep 5680
   # 或使用ss命令（部分容器镜像默认安装）
   ss -tulpn | grep 5680
   

   如果有其他进程占用，可更换debugpy监听端口（比如改为5681），同时更新Docker映射命令为-p 5681:5681。

2. 避免重复监听
   确认代码中是否存在重复调用debugpy.listen()的情况，可在调用前增加判断逻辑，避免重复初始化：

   import debugpy
   
   if not debugpy.is_client_connected() and not debugpy.is_listening():
       debugpy.listen(("0.0.0.0", 5680))
       debugpy.wait_for_client()
   

3. 检查Docker启动指令
   核实Dockerfile是否存在ENTRYPOINT与CMD组合导致main.py被重复执行的情况，确保启动指令仅执行一次python main.py。

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