FrankenPHP的WebSocket反向代理怎么写-php教程-PHP中文网

frankenphp本身不支持websocket反向代理，必须由nginx等外部代理处理协议升级并透传tcp流量至独立运行的websocket服务（如swoole），frankenphp仅负责http请求。

frankenphp的websocket反向代理怎么写

FrankenPHP 本身不支持 WebSocket 反向代理 —— 它没有内置的 WebSocket 代理能力，不能像 Nginx 那样直接用 proxy_pass 转发 ws:// 或 wss:// 流量。 所以你不能在 frankenphp.yaml 里配个字段就让 WebSocket 过来；必须靠外部反向代理（比如 Nginx）前置处理 WebSocket 协议升级请求，再把原始 TCP 流量透传给后端 PHP 应用（如 Swoole、ReactPHP 或自研 WebSocket server）。

为什么 FrankenPHP 不能直接代理 WebSocket

FrankenPHP 是基于 Caddy 的 Go 实现封装，但当前（v1.1.x）的 frankenphp 模块仅接管 HTTP/HTTPS 请求并转发给 PHP-FPM 兼容接口。它不解析或透传 Upgrade: websocket 请求头，也不维持长连接生命周期 —— 这些都属于反向代理层的职责，而 FrankenPHP 的定位是「PHP 运行时」，不是「通用反向代理」。

常见错误现象：
• 前端 new WebSocket('wss://app.example.com') 报 WebSocket connection to 'wss://...' failed
• 浏览器 Network 面板显示 400 或 502，且响应体为空或含 Bad Request
• 后端 WebSocket server 日志无任何连接记录，说明连接根本没到达它

Nginx 作为 WebSocket 前置代理的标准配置

你需要用 Nginx（或其他支持 WebSocket 的反向代理）监听 443/80，处理 TLS 终止和协议升级，然后把原始 TCP 流量（非 HTTP）转发给本地运行的 WebSocket server（例如监听 127.0.0.1:8000 的 Swoole 服务）。FrankenPHP 在这里只负责常规 HTTP API，WebSocket 流量完全绕过它。

关键点：

proxy_http_version 1.1 必须显式设置，否则 Nginx 默认用 HTTP/1.0，无法携带 Upgrade 头
proxy_set_header Upgrade $http_upgrade 和 proxy_set_header Connection "upgrade" 缺一不可 —— 这是触发 WebSocket 协议升级的核心
proxy_pass http://backend_ws 的目标地址必须是纯 HTTP（不是 ws://），Nginx 不支持 ws:// 作为 proxy_pass 协议
不要在 location /ws/ 块里加 frankenphp 指令 —— 那会让请求进 PHP-FPM，彻底破坏 WebSocket 握手

示例 Nginx 配置片段：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

upstream backend_ws {
    server 127.0.0.1:8000;
}
<p>server {
listen 443 ssl;
server_name app.example.com;</p><pre class="brush:php;toolbar:false;">ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;

location /ws/ {
    proxy_pass http://backend_ws;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 86400; # 长连接保活
}

location / {
    # 正常 HTTP 请求交给 FrankenPHP
    frankenphp;
}

}

如何让 PHP WebSocket server 和 FrankenPHP 共存于同一域名

核心原则：路径分流 + 端口隔离。FrankenPHP 只处理它启动时监听的 HTTP 端口（如 8080），而你的 WebSocket server 必须独立运行在另一个端口（如 8000），由 Nginx 根据 location 路径决定流量去向。

使用场景：

前端通过 wss://app.example.com/ws/chat 连 WebSocket，Nginx 将其转发到 127.0.0.1:8000
前端通过 https://app.example.com/api/messages 调用 REST 接口，Nginx 将其交给 frankenphp，最终跑在 PHP 中
两者共享 session？不行 —— WebSocket server 通常不走 PHP-FPM，无法自动继承 $_SESSION。需改用 Redis 存储 session，并在两边手动读写

性能影响：Nginx 透传 WebSocket 是零拷贝级别的转发，几乎没有额外开销；但如果你误把 WebSocket 请求塞进 FrankenPHP，会导致握手失败或连接立即关闭 —— 这是最常踩的坑。

真正容易被忽略的是：FrankenPHP 的 frankenphp.yaml 文件里所有配置都只影响 HTTP 生命周期，对 WebSocket 流量完全无效。别试图在里面加 websockets: 或类似字段 —— 它不识别，也不会报错，只是静默忽略。