workerman 4.0.34 搭建高性能网关须严格区分协议：mqtt 必用 workerman/mqtt 扩展实现完整协议栈，tcp/http/websocket 可基于 workerman/workerman 构建，禁止裸 worker 监听 1883 端口手动解析；需 php ≥ 7.4、linux/macos/wsl2 环境，启用 pcntl 和 posix 扩展；安装 composer require workerman/mqtt:^2.0；mqtt 网关必须 use workerman\mqtt\server，实例化 new server('0.0.0.0', 1883) 并调用 ->listen()；tcp 网关转发禁用字符串处理，鉴权网关需在 onconnect 绑定 client_id 并 onmessage 校验授权；部署后用 mosquitto_sub 或 mqttx 验证，日志默认输出至 ./workerman.log。
用 Workerman 4.0.34 搭建高性能网关，需严格区分协议类型与组件职责：MQTT 网关必须用 workerman/mqtt 扩展实现完整协议栈，TCP/HTTP/WebSocket 网关可直接基于 workerman/workerman 构建，不可混用裸 Worker 监听 1883 端口并手动解析二进制帧。
安装与环境准备
执行 composer create-project workerman/workerman 初始化项目骨架，避免 autoload 配置遗漏；确认 PHP CLI 已启用 pcntl 和 posix 扩展：php -m | grep -E "pcntl|posix"，缺失则需在 php.ini 中取消对应 extension 行注释。
Workerman 4.0.34 要求 PHP 版本 ≥ 7.4，且仅支持 Linux/macOS/WSL2 环境；Windows 用户若强行运行，将触发 undefined function pcntl_fork() 致命错误。
安装 MQTT 服务端扩展：composer require workerman/mqtt:^2.0，该版本已适配 Workerman 4.0.x 主线，不兼容 v1.x 的旧写法。
启动标准 MQTT 网关
创建 mqtt_gateway.php，内容如下：
第一行必须引入 use Workerman\MQTT\Server;；不能写成 use Workerman\Worker; + 手动解析 CONNECT 包，否则客户端连上即断，现象为 Connection reset by peer。
实例化时传入地址和端口：$server = new Server('0.0.0.0', 1883);；注意协议前缀 mqtt:// 是非法的，Workerman 不识别该字符串，会导致监听失败。
调用 $server->listen(); 启动监听，缺此行端口不会真正打开；若需 TLS，则改用 new Server('0.0.0.0', 8883, ['ssl' => $context]) 并配置证书上下文。
构建 TCP 协议透传网关
方法一：纯转发模式（无协议解析）
创建 tcp_gateway.php，使用 Worker('tcp://0.0.0.0:9000') 实例化；onMessage 回调中禁止对 $data 做任何字符串截取或 JSON 解码，因原始字节流可能含 \x00 或非 UTF-8 字符，强行 decode 会中断连接。
转发逻辑写为：$upstream->send($data);，其中 $upstream 是预建立的上游连接对象；连接池需自行维护，Workerman 不提供内置连接池。
方法二：带设备鉴权的 TCP 网关
在 onConnect 中记录 client_id 与 IP 绑定关系；onMessage 开头先查该 connection 是否已通过 /auth 主题完成握手，未通过则 $connection->close();。
鉴权成功后，将 connection 存入全局数组：$connections[$client_id] = $connection;；后续下行指令按 client_id 查表推送，避免广播风暴。
部署与验证
执行 php mqtt_gateway.php start -d 后，用 mosquitto_sub -t '#' -v -h 127.0.0.1 -p 1883 测试订阅；若返回 Connection refused，检查是否漏掉 $server->listen() 或防火墙拦截 1883 端口。
使用 MQTTX 客户端连接时，Broker 地址填 mqtt://127.0.0.1:1883，协议版本选 3.1.1；若提示 Not authorized，说明 onConnect 回调中未调用 $connection->authorize(true) 显式放行。
日志输出默认写入 ./Workerman.log，每条记录含时间戳与连接 ID；调试阶段建议临时关闭守护模式：php mqtt_gateway.php start，实时观察控制台输出。
