Workerman如何与Nginx配合？Workerman反向代理配置？

煙雲

发布时间：2025-08-31 08:06:02

636人浏览过

来源于php中文网

原创

nginx反向代理workerman时，需配置proxy_pass指向workerman端口，传递host、x-real-ip等头部以确保客户端信息正确，websocket场景下必须设置proxy_http_version 1.1及upgrade、connection头以支持协议升级，同时调整proxy_connect_timeout、proxy_send_timeout、proxy_read_timeout避免长连接中断，建议关闭proxy_buffering减少延迟，并通过upstream实现负载均衡；ssl终止由nginx处理，配置证书并强制http跳转https，静态资源由nginx直接服务以提升性能，workerman专注业务逻辑，实现高效分工。

workerman如何与nginx配合？workerman反向代理配置？

Workerman与Nginx的配合，本质上就是Nginx充当一个智能的门卫，将外部的请求精准地引导到Workerman服务的内部端口。这不仅让Workerman应用能够通过标准HTTP/HTTPS端口对外提供服务，还赋予了它强大的负载均衡、SSL加密和静态资源处理能力，是生产环境中几乎不可或缺的部署模式。

解决方案

要让Workerman与Nginx配合，核心在于Nginx的反向代理配置。Workerman通常会监听一个非标准端口（例如，HTTP应用可能在8080，WebSocket应用可能在2346），而Nginx则负责监听标准的HTTP（80）或HTTPS（443）端口，并将接收到的请求转发到Workerman监听的端口。

基本的HTTP反向代理配置示例：

假设你的Workerman HTTP应用运行在

127.0.0.1:8080

。

server {
    listen 80;
    server_name your_domain.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;

        # 解决502 Bad Gateway问题，增加超时时间
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

WebSocket反向代理配置示例（Workerman最常见的用途）：

假设你的Workerman WebSocket应用运行在

127.0.0.1:2346

。

server {
    listen 80;
    server_name your_websocket_domain.com;

    location /ws { # 或直接 / 如果整个域名都用于WebSocket
        proxy_pass http://127.0.0.1:2346;
        proxy_http_version 1.1; # 升级HTTP协议到1.1
        proxy_set_header Upgrade $http_upgrade; # 传递Upgrade头，用于协议升级
        proxy_set_header Connection "Upgrade"; # 传递Connection头，告知服务器保持连接

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # WebSocket连接可能长时间不活跃，但不能断开，所以超时设置要合理
        proxy_connect_timeout 7200s; # 连接超时
        proxy_send_timeout 7200s;   # 发送超时
        proxy_read_timeout 7200s;    # 读取超时
    }
}

我个人觉得，这种分工非常清晰，Nginx做它擅长的网络层转发和优化，Workerman则专心处理应用逻辑和实时通信，各司其职，效率最高。

Nginx反向代理Workerman有哪些关键配置要点？

在Nginx反向代理Workerman时，有一些配置是相当关键的，它们直接影响着应用的稳定性和用户体验。

首先是HTTP头部信息的传递。

proxy_set_header Host $host;

、

proxy_set_header X-Real-IP $remote_addr;

和

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

这些指令非常重要。它们确保Workerman应用能够正确识别客户端的真实IP地址和请求的原始域名。如果缺少这些，Workerman可能会认为所有请求都来自Nginx服务器本身（通常是

127.0.0.1

），这在日志记录、IP限制或一些基于地理位置的功能上会造成困扰。

对于WebSocket代理，核心在于

proxy_http_version 1.1;

、

proxy_set_header Upgrade $http_upgrade;

和

proxy_set_header Connection "Upgrade";

这三行。WebSocket协议的建立需要一个HTTP协议升级的过程，这些头信息就是告诉Nginx和Workerman进行这种升级。我见过不少新手在配置WebSocket时忘记了

Upgrade

和

Connection

头，结果就是连接一直断开，调试起来非常头疼。这些看似小细节，却是确保Workerman应用稳定运行的关键。

此外，超时设置也是一个容易被忽视但至关重要的点。

proxy_connect_timeout

、

proxy_send_timeout

和

proxy_read_timeout

决定了Nginx与Workerman之间连接、发送和接收数据的最长等待时间。对于HTTP请求，默认值可能够用；但对于长连接的WebSocket应用，这些值需要根据实际情况适当调大，以避免Nginx在Workerman尚未响应或客户端长时间不活跃时过早地切断连接。

最后，别忘了错误页处理。当Workerman服务意外崩溃或重启时，Nginx可以配置

error_page 502 /502.html;

来优雅地显示一个错误页面，而不是直接抛出Nginx的502 Bad Gateway错误，这能提升用户体验。

Workerman WebSocket应用在Nginx反向代理下有哪些特殊配置和注意事项？

Workerman的WebSocket应用在Nginx反向代理下，确实有一些非常特殊的配置和需要注意的地方，因为WebSocket是一种长连接协议，与传统的短连接HTTP请求有着本质的区别。

最核心的仍然是前面提到的HTTP协议升级相关的头部：

proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade";

。这是WebSocket握手成功的基石，没有它们，WebSocket连接就无法建立。Nginx需要将客户端发来的

Upgrade

和

Connection

头转发给Workerman，Workerman再根据这些头信息进行协议升级响应。

一帧秒创

基于秒创AIGC引擎的AI内容生成平台，图文转视频，无需剪辑，一键成片，零门槛创作视频。

下载

其次是超时设置的考量。WebSocket连接是持久的，客户端和服务器之间可能长时间没有数据传输，但这不意味着连接可以断开。因此，Nginx的

proxy_read_timeout

、

proxy_send_timeout

以及

proxy_connect_timeout

需要设置得足够长，以防止Nginx因为“不活跃”而误判并关闭连接。我发现，很多时候大家会忽略Nginx的

keepalive_timeout

与Workerman内部心跳机制的协调。如果Nginx的超时设置过短，可能会在Workerman心跳发送前就断开连接，导致不必要的重连。这需要一些细致的考量，Workerman应用本身也应该实现心跳机制，定期发送ping/pong帧来维持连接活跃。

另一个值得注意的是代理缓冲（Proxy Buffering）。Nginx默认是开启代理缓冲的，这意味着Nginx会先将Workerman的响应数据缓冲起来，再一次性发送给客户端。对于WebSocket这种实时性要求高的应用，这可能会引入不必要的延迟。因此，通常建议在WebSocket的

location

块中关闭代理缓冲：

proxy_buffering off;

。这样Nginx就会直接将从Workerman接收到的数据流式传输给客户端，减少延迟。

此外，负载均衡对于高并发的WebSocket应用也至关重要。如果你的Workerman集群有多个实例，可以通过Nginx的

upstream

模块进行负载均衡，将WebSocket连接分散到不同的Workerman进程或服务器上。例如：

upstream websocket_backend {
    server 127.0.0.1:2346;
    server 127.0.0.1:2347; # 另一个Workerman实例
    # ip_hash; # 保持同一客户端连接到同一后端
}

server {
    listen 80;
    server_name your_websocket_domain.com;

    location /ws {
        proxy_pass http://websocket_backend;
        # ... 其他WebSocket配置 ...
    }
}

使用

ip_hash

可以确保同一个客户端的WebSocket连接始终被代理到同一个Workerman后端，这对于一些需要会话粘性的应用场景非常有用。

Nginx反向代理Workerman时，如何处理SSL/TLS加密和静态资源服务？

让Nginx来处理SSL/TLS加密和静态资源服务，是我个人认为在Workerman部署中一个非常明智的决策，它能极大地提升应用的安全性、性能和可维护性。

SSL/TLS加密的处理

Nginx作为反向代理，可以完美地充当SSL/TLS的“终结者”（SSL Termination）。这意味着Nginx负责处理客户端与Nginx之间的加密通信，然后将解密后的HTTP或WebSocket请求转发给Workerman。

配置Nginx来处理SSL非常直接：

server {
    listen 443 ssl;
    server_name your_domain.com;

    ssl_certificate /etc/nginx/ssl/your_domain.com.crt; # 你的SSL证书路径
    ssl_certificate_key /etc/nginx/ssl/your_domain.com.key; # 你的SSL私钥路径
    ssl_protocols TLSv1.2 TLSv1.3; # 推荐使用较新的TLS版本
    ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH"; # 推荐的加密套件
    ssl_prefer_server_ciphers on;

    location / {
        # 根据Workerman应用的类型，这里可以是HTTP或WebSocket的proxy_pass配置
        proxy_pass http://127.0.0.1:8080; # 或 ws://127.0.0.1:2346;
        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 https; # 告知Workerman原始请求是HTTPS

        # 如果是WebSocket，还需要以下配置
        # proxy_http_version 1.1;
        # proxy_set_header Upgrade $http_upgrade;
        # proxy_set_header Connection "Upgrade";
    }
}

# 强制HTTP跳转到HTTPS
server {
    listen 80;
    server_name your_domain.com;
    return 301 https://$host$request_uri;
}

这样做的好处是显而易见的：

集中管理：所有证书和SSL配置都在Nginx层面处理，Workerman不需要关心加密解密，代码更简洁。
性能优化：Nginx在处理SSL握手和加解密方面效率极高，可以有效减轻Workerman的CPU负担。
内网安全：Nginx与Workerman之间的通信通常发生在本地网络（如
```
127.0.0.1
```
），即便是不加密，风险也极低。

静态资源服务

Workerman虽然也能处理HTTP请求，但它毕竟是一个PHP应用服务器，对于静态文件的处理效率远不如Nginx这种专门为HTTP服务优化的服务器。让Nginx直接服务静态资源，可以显著提升网站的响应速度和Workerman的负载能力。

你可以在Nginx配置中，通过

location

块来区分静态资源和需要代理到Workerman的动态请求：

server {
    listen 80;
    server_name your_domain.com;

    # 静态文件通常放在一个特定的目录下，例如 /public/static/
    location ~* \.(css|js|gif|jpg|jpeg|png|ico|woff|woff2|ttf|eot|svg)$ {
        root /path/to/your/workerman/project/public; # 你的静态文件根目录
        expires 30d; # 浏览器缓存30天
        add_header Cache-Control "public, no-transform";
        access_log off; # 静态文件请求通常无需记录到access log
    }

    # 其他静态资源，例如上传的文件
    location /uploads/ {
        root /path/to/your/workerman/project;
        expires 7d;
        add_header Cache-Control "public, no-transform";
    }

    # 其他所有请求都代理到Workerman
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

在我看来，让Nginx处理SSL和静态资源是最佳实践。Workerman专注于它的实时通信和业务逻辑，而Nginx则发挥其在HTTP服务器方面的极致性能。试图让Workerman也去处理这些，不仅效率低下，还会增加不必要的复杂性。这种分层处理的架构，清晰、高效且易于维护。

游戏服务器（Game Server）的后端架构

5G时代的高并发挑战与解决方案

负载均衡（Load Balance）方案

如何在Workerman中使用HBase进行数据存储与查询

swoole和workerman开发：哪个更适合业务需求？