Nginx WSS 配置

KBEngine Nex — Nginx WSS 部署说明

目标

通过 Nginx 将 WebSocket（WSS）安全代理到本地或内网的 KBEngine LoginApp（例如本机 20013 端口），并在宝塔面板上完成安装与证书管理。

前置条件

• 已有一台服务器（公网 IP）并能访问域名 yourdomain.com 的 DNS 已指向该服务器。
• 宝塔面板（BT）已在服务器上安装。
• KBEngine 的 WebSocket 服务（LoginApp 等）在服务器本机或内网中可访问（示例：127.0.0.1:20013）。
• 推荐使用 Let’s Encrypt 免费证书，宝塔面板可自动申请并绑定。

宝塔面板（BT）操作流程（简洁步骤）

1. 登录宝塔面板（默认 http://server-ip:port）。
2. 在 软件管理 中确认 Nginx 已安装（若没安装可在面板安装 Nginx）。
3. 在 网站 → 添加HTML站点(仅用于代理)：

INFO

域名：yourdomain.com 目录：例如 /www/wwwroot/yourdomain（WebSocket 本身不需要网页目录，但可填写）

4. 进入网站设置 → SSL → 一键免费申请（Let’s Encrypt）：

INFO

勾选“自动续签”。成功后证书会放在 /www/server/panel/vhost/cert/yourdomain.com/（宝塔的证书路径可能不同，请以面板显示为准）。

5. 编辑该站点的 Nginx 配置（面板→网站→配置文件，或直接通过文件管理修改）：

INFO

把下面提供的 Nginx 配置段拷贝到虚拟主机配置中（替换域名、后端端口、证书路径等）。

6. 保存并重载 Nginx（宝塔面板会有“保存并检测配置/重载”按钮）。
7. 在服务器防火墙/安全组中开放 443, 444（或其他自定义端口，如果使用自定义端口也开放）；确保内网端口（如 20013）对本机可达（不一定要对公网开放）。

Nginx 完整配置示例

#loginapp 代理
server
{
    listen 801;
    listen 443 ssl;  # 替换为你端口
    http2 on;
    server_name wss.kbelab.com;  # 替换为你的域名
   
    ssl_certificate    /www/server/panel/vhost/cert/wss.kbelab.com/fullchain.pem; # 替换为你的证书
    ssl_certificate_key    /www/server/panel/vhost/cert/wss.kbelab.com/privkey.pem; # 替换为你的证书
    ssl_protocols TLSv1.1 TLSv1.2 TLSv1.3;
    ssl_ciphers EECDH+CHACHA20:EECDH+CHACHA20-draft:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_tickets on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    add_header Strict-Transport-Security "max-age=31536000";
    error_page 497  https://$host$request_uri;

     location / {
        proxy_pass http://127.0.0.1:20013;
        proxy_http_version 1.1;

        # WebSocket 专用头
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";

        # 传递真实 IP
        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_read_timeout 600s;
        proxy_send_timeout 600s;
    }
    
    access_log  /www/wwwlogs/wss.kbelab.com.log;
    error_log  /www/wwwlogs/wss.kbelab.com.error.log;
}


# baseapp 代理
server
{
    listen 802;
    listen 444 ssl; # 替换为你端口
    http2 on;
    server_name wss.kbelab.com;# 替换为你的域名

    ssl_certificate    /www/server/panel/vhost/cert/wss.kbelab.com/fullchain.pem; # 替换为你的证书
    ssl_certificate_key    /www/server/panel/vhost/cert/wss.kbelab.com/privkey.pem; # 替换为你的证书
    ssl_protocols TLSv1.1 TLSv1.2 TLSv1.3;
    ssl_ciphers EECDH+CHACHA20:EECDH+CHACHA20-draft:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_tickets on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    add_header Strict-Transport-Security "max-age=31536000";
    error_page 497  https://$host$request_uri;

     location / {
        proxy_pass http://127.0.0.1:20015;
        proxy_http_version 1.1;

        # WebSocket 专用头
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";

        # 传递真实 IP
        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_read_timeout 600s;
        proxy_send_timeout 600s;
    }
    

    access_log  /www/wwwlogs/wss.kbelab.com.log;
    error_log  /www/wwwlogs/wss.kbelab.com.error.log;
}

关键点回顾

• proxy_http_version 1.1 + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; 是支持 WebSocket 的核心。
• proxy_buffering off 可避免在代理 WebSocket 时出现数据延迟/卡顿。
• proxy_read_timeout 要足够长（游戏长连接常设较大值）。

客户端示例

在 clientapp 中添加对域名和端口的映射，SDK底层会自动对IP、端口进行替换，从而实现通过WSS连接服务器。

C#

using UnityEngine;
using System;
using System.Collections;
using KBEngine;

public class clientapp : UnityKBEMain 
{
    public clientapp()
    {
        KBELog.Init(new UnityLogProvider());

        domainMapping.Add("127.0.0.1","kbe.com");
        domainMapping.Add("192.168.1.3","kbe.com");
        domainMapping.Add("192.168.36.128","wss.kbelab.com");

        portMapping.Add(20013,443);
        portMapping.Add(20015,444);
    }
}

TS （COCOS 为例）

// 关键代码
@ccclass
@disallowMultiple
export class ServerNode extends Component {
    @property
    ip="127.0.0.1"
    onLoad(){
        this.initServerApp()
        director.addPersistRootNode(this.node);
    }
    initServerApp():void {
        log("init Server App")
        let args = new KBEngineArgs();
        args.address=this.ip
        args.port = 20013;
        args.useWss = true;

        args.domainMapping["192.168.36.128"] = "wss.kbelab.com";
        args.portMapping[20013] = 443;
        args.portMapping[20015] = 444;

        KBEngineApp.Destroy();
        KBEngineApp.Create(args)
    }

}

测试与排错

1. 本地能否 curl/openssl 检查证书

# 检查 HTTPS 证书链
openssl s_client -connect yourdomain.com:443 -showcerts

2. 使用 wscat / websocat 测试 WebSocket 握手 （若未安装可 npm i -g wscat）

wscat -c wss://yourdomain.com/
# 或带 header 测试
wscat -H "Origin: https://yourdomain.com" -c wss://yourdomain.com/

3. 查看 Nginx 日志（宝塔常在 /www/wwwlogs）

# 访问日志
tail -f /www/wwwlogs/yourdomain.access.log
# 错误日志
tail -f /www/wwwlogs/yourdomain.error.log

4. 常见握手失败场景
   • 客户端报 WSS connection failed / failed: Error in connection establishment：
     • 检查 Nginx 是否正确转发 Upgrade/Connection 头。
     • 看后端（LoginApp）是否有错误日志（拒绝连接/协议解析）。
     • 若 Nginx 报 400 或 502，常见是 proxy_pass 地址错误或后端未运行。
   • 客户端 readyState 3：说明已 CLOSED，排查原因见 Nginx/后端日志。
   • 中间代理移除 Upgrade/Connection：如果链路上有多个代理（CDN、负载均衡器），都必须支持 WebSocket。

常见问题（FAQ）

Q1：我的页面在 HTTP 下，但 WebSocket 用 WSS，浏览器报 Mixed Content？ A：浏览器禁止从 HTTPS 页面连接 ws://（明文）地址，请使用 wss://。同时若页面是 HTTP，建议也强制跳转到 HTTPS 。

Q2：中间有 Cloudflare / CDN，会影响 WebSocket 吗？ A：部分 CDN/代理需要显式打开 WebSocket 支持或使用专用的 WebSocket 代理。若使用 Cloudflare，请在面板启用 WebSocket（并使用“灰云”或配置支持）。

Q3：连接正常但偶发断开？ A：检查 Nginx proxy_read_timeout / 后端心跳配置 / 防火墙的空闲超时（某些云厂商 TCP 空闲 4-5 分钟会断开）。