必须使用Workerman 4.0.41（PHP 8.1+）、四大核心扩展齐全、Gateway与BusinessWorker分离部署、显式配置lanIp、静态路由+Redis会话管理，并双进程启动验证。
要在生产环境稳定运行企业级即时通讯系统，必须基于 Workerman 4.0.41 版本构建可扩展、可监控、支持万级并发的 IM 架构，不能直接套用 demo 示例或低版本兼容写法——该版本已移除对 PHP 7.2 的支持，强制要求 PHP 8.1+，且默认禁用未签名的 WebSocket 子协议协商。
确认 PHP 环境与核心扩展
执行 php -v 确保输出为 PHP 8.1.0 或更高版本；若低于此版本，Workerman 4.0.41 将拒绝启动并报错 Fatal error: Uncaught RuntimeException: PHP version too low。
运行 php -m | grep -E '^(pcntl|posix|sockets|json)$'，必须全部列出四项——pcntl 和 posix 缺一不可，否则多进程模型无法初始化，所有 worker 进程将退化为单进程阻塞模式。
执行 curl -Ss http://www.workerman.net/check.php | php，仅当全部显示 OK 才可进入下一步；若提示 event extension not loaded，虽非强制但必须安装：CentOS 执行 yum install libevent-devel -y && pecl install event，然后在 php.ini 中追加 extension=event.so 并重启 PHP CLI。
初始化项目结构与依赖
创建空目录 im-enterprise，进入后执行：composer init -n && composer require workerman/workerman:^4.0.41。
这一步会自动拉取 精确匹配 4.0.41 的发布包（而非最新版），避免因 minor 版本升级引入不兼容变更，比如 4.0.42 新增的 Worker::$daemonize 默认值变更会导致前台调试失效。
执行 mkdir -p app/{controller,service,model} config worker public，其中 worker/ 目录专用于存放 Gateway、BusinessWorker 启动脚本，严禁与业务代码混放——Workerman 4.0+ 的 autoloader 不扫描 worker/ 目录，防止误加载导致进程崩溃。
配置 GatewayWorker 分离架构
第一步：复制 vendor/workerman/gateway-worker/Start.php 到 worker/start_gateway.php，并修改第 23 行：$gateway = new \GatewayWorker\Gateway("websocket://0.0.0.0:7272"); → 改为 "websocket://127.0.0.1:7272"。
第二步：复制 vendor/workerman/gateway-worker/Start.php 到 worker/start_business.php，修改第 32 行：\GatewayWorker\BusinessWorker::$registerAddress = '127.0.0.1:1236';，确保与 gateway 脚本中注册地址一致。
第三步：在 config/ 下新建 gateway.php，填入：return ['start' => true, 'lanIp' => '127.0.0.1', 'pingInterval' => 30, 'pingNotResponseLimit' => 2];——必须显式设置 lanIp，否则在 Docker 容器或云服务器多网卡环境下，Gateway 会绑定到错误接口导致 BusinessWorker 无法连接。
编写消息路由与会话状态管理
方法一：在 app/service/MessageRouter.php 中定义静态路由逻辑：
public static function route(string $type, array $payload): string|null { switch ($type) { case 'chat': return 'ChatService::handle'; case 'group_notice': return 'GroupService::broadcast'; default: return null; } }
方法二：使用 PHP 8.5+ 的管道操作符重构会话克隆逻辑：
$newSession = clone $oldSession with [ 'lastActiveAt' => time(), 'unreadCount' => $oldSession->unreadCount + 1 ];——这行代码必须出现在 onMessage 回调内，且 $oldSession 必须是 #[\NoDiscard] 标记的类实例，否则 PHP 8.5 编译器会静默丢弃克隆结果。
方法三：在 app/controller/ChatController.php 中注入 Redis 实例，用 $redis->setex("session:{$connection->id}", 3600, json_encode($data)) 持久化连接元数据——禁止使用 file_get_contents 写本地文件缓存，高并发下会导致 inode 耗尽和磁盘 I/O 阻塞。
启动双进程并验证连接
终端 1 执行：php worker/start_gateway.php start；终端 2 执行：php worker/start_business.php start。
观察两个终端是否均输出 [OK] 状态，且 ps aux | grep workerman 显示至少 8 个 PHP 进程（默认 gateway count=4 + business count=4）。
用浏览器打开 ws://localhost:7272，发送 JSON 消息 {"type":"ping","data":{}}，收到响应 {"type":"pong"} 即表示基础链路通达——此时不要关闭任一终端，后续所有业务逻辑都依赖这两个进程持续运行。
