Ubuntu下PyCharm调试Docker应用连接被拒问题求助

问题详情 #

在全新安装的Ubuntu 22.04.3 LTS上使用PyCharm 2023.3.2专业版配置Django应用的docker-compose远程Python解释器时，出现以下异常：

• 项目运行正常，但调试时容器无法连接PyCharm的调试端口（172.17.0.1:xxxx），抛出ConnectionRefusedError: [Errno 111] Connection refused
• Python Console同样无法建立连接，错误原因一致
• 已排除防火墙、Docker运行异常问题，无法使用host网络模式（需访问其他容器端口），尝试过docker.sock TCP连接、修改/etc/hosts均无效
• 核心原因：Linux下PyCharm默认非root权限无法正常监听调试端口，sudo启动PyCharm会引发Docker权限等衍生问题

调试错误日志 #

/usr/local/bin/python3 /opt/.pycharm_helpers/pydev/pydevd.py --multiprocess --qt-support=auto --client 172.17.0.1 --port 41781 --file /opt/project/kamsa_api/manage.py runserver 0.0.0.0:8000 

Container redis  Running
Container es  Running
Container django_web  Recreate
Attaching to django_web
Container django_web  Recreated

django_web  | warning: PYDEVD_USE_CYTHON environment variable is set to 'NO'. Frame evaluator will be also disabled because it requires Cython extensions to be enabled in order to operate correctly.

django_web  | Could not connect to 172.17.0.1: 41781
django_web  | Traceback (most recent call last):
django_web  |   File "/opt/.pycharm_helpers/pydev/_pydevd_bundle/pydevd_comm.py", line 463, in start_client
django_web  |     s.connect((host, port))
django_web  | ConnectionRefusedError: [Errno 111] Connection refused
django_web  | Could not connect to 172.17.0.1: 41781
django_web  | Traceback (most recent call last):
django_web  |   File "/opt/.pycharm_helpers/pydev/pydevd.py", line 2206, in main
django_web  |     debugger.connect(host, port)
django_web  |   File "/opt/.pycharm_helpers/pydev/pydevd.py", line 670, in connect
django_web  |     s = start_client(host, port)
django_web  |   File "/opt/.pycharm_helpers/pydev/_pydevd_bundle/pydevd_comm.py", line 463, in start_client
django_web  |     s.connect((host, port))
django_web  | ConnectionRefusedError: [Errno 111] Connection refused

Aborting on container exit...
Container django_web  Stopping
Container django_web  Stopped

django_web exited with code 1

Python Console错误日志 #

/usr/local/bin/python3 /opt/.pycharm_helpers/pydev/pydevconsole.py --mode=client --host=172.17.0.1 --port=39883 
Traceback (most recent call last):
  File "/opt/.pycharm_helpers/pydev/pydevconsole.py", line 570, in <module>
    pydevconsole.start_client(host, port)
  File "/opt/.pycharm_helpers/pydev/pydevconsole.py", line 482, in start_client
    client, server_transport = make_rpc_client(client_service, host, port)
  File "/opt/.pycharm_helpers/pydev/_pydev_comm/pydev_rpc.py", line 11, in make_rpc_client
    client_transport, server_transport = open_transports_as_client((host, port))
  File "/opt/.pycharm_helpers/pydev/_pydev_comm/pydev_transport.py", line 231, in open_transports_as_client
    client_socket.connect(addr)
ConnectionRefusedError: [Errno 111] Connection refused
Couldn't connect to console process.
Process finished with exit code 1

无需全局sudo的解决方案 #

方案1：给PyCharm进程添加端口绑定权限 #

通过setcap命令赋予PyCharm的Java进程绑定任意端口的权限，无需root身份启动：

1. 找到PyCharm的Java二进制文件路径，通常为/opt/pycharm-2023.3.2/jbr/bin/java（根据实际安装路径调整）
2. 执行命令：

sudo setcap 'cap_net_bind_service=+ep' /opt/pycharm-2023.3.2/jbr/bin/java

方案2：配置PyCharm调试监听所有网卡 #

让PyCharm监听所有网卡地址，确保能接收来自Docker容器的连接：

1. 打开PyCharm设置：Settings → Build, Execution, Deployment → Debugger
2. 在Built-in server区域，将Host设置为0.0.0.0
3. 保存设置后重启PyCharm

方案3：允许Docker子网访问PyCharm调试端口 #

添加Docker桥接子网到PyCharm的连接白名单：

1. 打开PyCharm设置：Settings → Build, Execution, Deployment → Debugger → Allow incoming connections
2. 点击Allow from，添加Docker桥接网络的子网（默认是172.17.0.0/16）
3. 保存设置后重新启动调试

方案4：通过extra_hosts映射宿主机地址 #

利用Docker-compose的extra_hosts配置宿主机映射，同时让PyCharm使用该映射地址调试：

1. 修改docker-compose.yml中的django_web服务：

services:
  django_web:
    ...
    extra_hosts:
      - "host.docker.internal:host-gateway"

2. 打开PyCharm的Python解释器配置：Settings → Project → Python Interpreter → Show All
3. 选中对应的docker-compose解释器，点击Edit
4. 在Docker Compose页面的Environment variables中添加：
   • 变量名：PYDEVD_HOST，变量值：host.docker.internal
5. 保存配置后重启调试

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