尝试理解 Ray 的远程服务器调试功能

Ray 是 Laravel 专业户 Spatie 开发的一款辅助调试工具。一开始，可能会觉得使用一个 GUI 应用来显示调试输出似乎没有必要，但实际体验后，会发现它确实大大简化了调试过程。它不仅方便了代码的理解和 bug 的排查，还增强了我对代码的信心。

Ray 不仅适用于本地调试，还支持远程服务器调试。我对如何使用它，以及它的工作原理感到好奇。

全局安装 Ray 是如何工作的？

对于使用 Composer 管理的项目，可以在本地安装 Ray，例如针对 Laravel 项目的 spatie/laravel-ray 包。然而，我们一些运行在 ThinkPHP 3.2/PHP 7.4 上的旧网站，这些网站并没有使用 Composer，此时可以采用全局安装方案：

➜  ~ touch x
➜  ~ global-ray install --ini x
...
➜  ~ cat x
auto_prepend_file = /Users/xcy/.composer/vendor/spatie/global-ray/src/scripts/global-ray-loader.php

起初我并不了解这种安装方式。后来在调查中，我想起了曾遇到的一个网站被黑的情况，当时找不到任何恶意代码。最终发现是 user.ini 文件被添加了 auto_prepend_file 配置。

Ray 是如何工作的？

Ray 是一个使用 Electron 开发的 GUI 应用，它默认在 23517 端口运行一个 HTTP 服务，用于收集调试输出。为了观察这一过程，我将 GUI Ray 的监听端口更改为 9999，并使用 socat 作为 TCP 中继，监听原先的 23517 端口，然后将数据转发到 9999 端口：

➜  ~ socat -v TCP-LISTEN:23517,fork TCP:localhost:9999
> 2023/12/14 22:53:09.000883950  length=477 from=0 to=476
POST / HTTP/1.1\r
{"uuid":"9d8b72ce-0a63-45a5-916b-95446b70d9b8","payloads":[{"type":"log","content":{"values":[42]},"origin":{"file":"php shell code","line_number":1,"hostname":"173-10-15-162-BusName-stockton.hfc.comcastbusiness.net"}}],"meta":{"php_version":"8.2.12","php_version_id":80212,"project_name":""}}
...
< 2023/12/14 22:53:09.000896145  length=260 from=0 to=259
HTTP/1.1 200 OK\r
X-Powered-By: Express\r

从中我们可以看出：

• 调试输出被封装在 JSON 格式中
• Ray 使用 Express 作为其服务器端

如果没有启动 Ray App，代码中使用了 ray() 会怎样？

即使你忘记删除 ray() 调试代码，代码也能正常运行。这是因为 Ray 会检查服务是否在线。而且，本地的网络请求速度非常快，我这里的响应时间只有几毫秒，几乎不会影响性能。

➜  ~ curl -s -w '%{json}' localhost:7123 | jq .time_total
0.00564

Ray 如何实现对远程服务器的调试？

在添加并连接到服务器后，Ray 就能接收到远程的调试输出：

这是通过 SSH 端口转发实现的。本地的 Ray GUI App 包含了一个 Express 网络服务，默认监听着 23517 端口。将这个端口通过 SSH 转发到服务器上，服务器就可以通过它自己的 localhost:23517 访问 Ray GUI App 的服务：

ssh -R 23517:127.0.0.1:23517 root@example.com

这样，即使不在 Ray GUI App 中添加服务器配置，也能接收到调试输出。