如何从本地连接远程服务器Docker容器内的Xdebug？

核心问题分析 #

远程云服务器的9003端口已被Docker代理（docker-prox）占用，导致无法使用该端口进行SSH反向转发；同时跨公网场景下discover_client_host=On无法正确识别本地IDE的公网IP，需要换端口配合SSH隧道实现连接。

可行解决方案 #

方案1：更换SSH反向转发端口，调整Xdebug配置 #

无需修改现有Docker端口映射，是最稳妥的方案：

1. 本地建立反向SSH隧道
   使用未被占用的端口（比如9004）替代9003，将远程服务器的9004端口转发到本地IDE监听的9003端口：

   ssh -R 9004:localhost:9003 username@cloudhost.com
   

   保持该终端窗口开启，隧道才能持续生效。

2. 修改Docker Compose的Xdebug配置
   更新环境变量，关闭自动发现主机，指定Xdebug连接到云服务器宿主机的9004端口（隧道会将该端口请求转发至本地IDE）：

   [...]环境变量：
     - XDEBUG_MODE=debug
     - XDEBUG_CONFIG=discover_client_host=Off client_host=host.docker.internal client_port=9004
   [...]
   

   注：若host.docker.internal无法访问宿主机，可替换为云服务器内网IP，或通过docker network inspect internal查看Docker bridge网络的网关IP（通常为172.17.0.1）。

3. 重启Docker Compose栈
   重新部署使配置生效：

   docker compose down && docker compose up -d
   

方案2：修改Docker端口映射，避开占用的9003端口 #

若不想使用额外转发端口，可直接调整Docker端口映射：

1. 修改docker-compose.yml的端口映射
   将容器的9003端口映射到云服务器的其他端口（比如9004）：

   [...]端口映射：
     - 9004:9003
   [...]
   

2. 本地建立反向SSH隧道
   将远程的9004端口转发到本地9003：

   ssh -R 9004:localhost:9003 username@cloudhost.com
   

3. 调整Xdebug配置
   确保Xdebug连接到宿主机的9004端口，配置同方案1的第二步。

方案3：直接暴露本地IDE端口（不推荐） #

若本地有公网IP且可开放防火墙，可直接让Xdebug连接本地公网IP：

1. 本地防火墙开放9003端口
   确保本地IDE监听的9003端口可被公网访问。

2. 修改Xdebug配置
   指定client_host为你的本地公网IP：

   - XDEBUG_CONFIG=discover_client_host=Off client_host=你的本地公网IP client_port=9003
   

   注：该方式存在安全风险，仅适合临时测试，禁止在生产环境使用。

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