远程Debian服务器Xdebug 3无法触发调试问题排查求助

问题背景 #

我在Debian Bookworm的LXC容器远程Web服务器上配置Xdebug，计划通过开发机到服务器的SSH隧道实现调试。网络连通性已验证正常：

# 建立到Web服务器的SSH反向隧道
dev@client:~$ ssh -R host.example.com:9003:localhost:9000 site
# 服务器端查看Xdebug基础配置
site@host:~$ php -i | grep xdebug
# 关键配置：
xdebug.client_host => localhost => localhost
xdebug.client_port => 9003 => 9003
# 客户端启动调试监听
dev@client:~$ dbgpClient -p 9000
# 测试隧道连通性
site@host:~$ telnet localhost 9003
# 客户端dbgpClient显示：Connect from [::1]:54680

但PHP无法触发调试，没有连接请求发送到客户端的dbgpClient：

# 客户端启动dbgpClient监听
dev@client:~$ dbgpClient -p 9000
# 服务器端启动交互式PHP并尝试触发调试
site@host:~$ export XDEBUG_SESSION=1
site@host:~$ php -a -dxdebug.start_with_request=yes -dxdebug.log=/tmp/xdebug.log
Interactive shell
php > echo 1;
1
php > ^C
# 查看Xdebug日志为空
site@host:~$ cat /tmp/xdebug.log
site@host:~$ 

完整的php -i | grep xdebug输出如下：

/etc/php/8.2/cli/conf.d/20-xdebug.ini,
xdebug
Support Xdebug on Patreon, GitHub, or as a business: https://xdebug.org/support
Enabled Features (through 'xdebug.mode' setting)             
'xdebug://gateway' pseudo-host support => yes
'xdebug://nameserver' pseudo-host support => yes
xdebug.auto_trace => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.cli_color => 0 => 0
xdebug.client_discovery_header => HTTP_X_FORWARDED_FOR,REMOTE_ADDR => HTTP_X_FORWARDED_FOR,REMOTE_ADDR
xdebug.client_host => localhost => localhost
xdebug.client_port => 9003 => 9003
xdebug.cloud_id => no value => no value
xdebug.collect_assignments => Off => Off
xdebug.collect_includes => (setting removed in Xdebug 3) => (setting removed in Xdebug 3)
xdebug.collect_params => (setting removed in Xdebug 3) => (setting removed in Xdebug 3)
xdebug.collect_return => Off => Off
xdebug.collect_vars => (setting removed in Xdebug 3) => (setting removed in Xdebug 3)
xdebug.connect_timeout_ms => 200 => 200
xdebug.coverage_enable => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.default_enable => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.discover_client_host => Off => Off
xdebug.dump.COOKIE => no value => no value
xdebug.dump.ENV => no value => no value
xdebug.dump.FILES => no value => no value
xdebug.dump.GET => no value => no value
xdebug.dump.POST => no value => no value
xdebug.dump.REQUEST => no value => no value
xdebug.dump.SERVER => no value => no value
xdebug.dump.SESSION => no value => no value
xdebug.dump_globals => On => On
xdebug.dump_once => On => On
xdebug.dump_undefined => Off => Off
xdebug.file_link_format => no value => no value
xdebug.filename_format => no value => no value
xdebug.force_display_errors => Off => Off
xdebug.force_error_reporting => 0 => 0
xdebug.gc_stats_enable => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.gc_stats_output_dir => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.gc_stats_output_name => gcstats.%p => gcstats.%p
xdebug.halt_level => 0 => 0
xdebug.idekey => no value => no value
xdebug.log => no value => no value
xdebug.log_level => 7 => 7
xdebug.max_nesting_level => 256 => 256
xdebug.max_stack_frames => -1 => -1
xdebug.mode => develop => develop
xdebug.output_dir => /tmp => /tmp
xdebug.overload_var_dump => (setting removed in Xdebug 3) => (setting removed in Xdebug 3)
xdebug.profiler_append => Off => Off
xdebug.profiler_enable => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.profiler_enable_trigger => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.profiler_enable_trigger_value => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.profiler_output_dir => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.profiler_output_name => cachegrind.out.%p => cachegrind.out.%p
xdebug.remote_autostart => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_connect_back => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_enable => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_host => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_log => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_log_level => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_mode => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_port => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.remote_timeout => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.scream => Off => Off
xdebug.show_error_trace => Off => Off
xdebug.show_exception_trace => Off => Off
xdebug.show_local_vars => Off => Off
xdebug.show_mem_delta => (setting removed in Xdebug 3) => (setting removed in Xdebug 3)
xdebug.start_upon_error => default => default
xdebug.start_with_request => default => default
xdebug.trace_enable_trigger => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.trace_enable_trigger_value => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.trace_format => 0 => 0
xdebug.trace_options => 0 => 0
xdebug.trace_output_dir => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.trace_output_name => trace.%c => trace.%c
xdebug.trigger_value => no value => no value
xdebug.use_compression => 0 => 0
xdebug.var_display_max_children => 128 => 128
xdebug.var_display_max_data => 512 => 512
xdebug.var_display_max_depth => 3 => 3

排查措施 #

• 修正Xdebug模式配置：当前xdebug.mode为develop，仅启用开发辅助功能，不包含调试模块。需将模式改为debug或develop,debug。可临时通过命令行指定：php -a -dxdebug.mode=debug -dxdebug.start_with_request=yes -dxdebug.log=/tmp/xdebug.log，或修改/etc/php/8.2/cli/conf.d/20-xdebug.ini中的xdebug.mode配置项。
• 强制指定IDE Key：尝试添加-dxdebug.idekey=your_ide_key参数，同时客户端启动dbgpClient时匹配该Key：dbgpClient -p 9000 -k your_ide_key，确保触发条件匹配。
• 提升日志级别：将xdebug.log_level设为10（最高级别），重新触发调试后查看/tmp/xdebug.log，获取更详细的执行日志，确认Xdebug是否尝试发起连接。
• 验证CLI生效配置：运行php -a -dxdebug.mode=debug -dxdebug.start_with_request=yes -i | grep xdebug，确认命令行参数是否覆盖了全局配置，尤其是xdebug.mode和xdebug.start_with_request的最终生效值。
• 测试非交互式脚本：创建简单测试脚本test.php：

  <?php
  echo "Testing Xdebug\n";
  $a = 1;
  $b = 2;
  $c = $a + $b;
  var_dump($c);
  ?>
  

  执行php -dxdebug.mode=debug -dxdebug.start_with_request=yes -dxdebug.log=/tmp/xdebug.log test.php，排除交互式Shell的特殊行为影响。
• 检查LXC容器网络限制：在容器内执行curl localhost:9003，确认PHP之外的进程能正常访问隧道端口；同时检查容器的SELinux/AppArmor日志，确认是否有规则限制PHP发起出站连接。
• 调整SSH隧道绑定地址：将SSH隧道改为-R 0.0.0.0:9003:localhost:9000，确保容器内所有接口都能监听该端口，再修改Xdebug的xdebug.client_host为0.0.0.0测试连接。

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