webman集群部署需绕过官方docker-compose.yml陷阱：必须显式安装pcntl/posix扩展、补全restart: unless-stopped、volumes挂载runtime目录、init: true，多实例应禁用内置多进程改用横向扩容，并通过redis/nacos实现状态共享与服务发现。
Webman 在 Docker 下跑单实例容易，但要真正形成可扩缩、可发现、可运维的集群，必须绕开官方 docker-compose.yml 的“开箱即用”陷阱——它缺 restart、不挂载 runtime、没信号处理、pcntl/posix 默认失效，直接上线等于裸奔。
pcntl 和 posix 扩展必须显式安装且同时启用
Webman 启动时依赖 pcntl_fork() 和 posix_kill() 实现多进程管理与平滑重启。PHP 官方 php:8.1-fpm 镜像默认禁用这两个扩展，光靠 docker-php-ext-enable pcntl 没用，因为模块压根没编译进去。
- 必须在
Dockerfile中写RUN docker-php-ext-install pcntl posix（两个一起，缺一不可） - Alpine 镜像需提前装
gcc和make，否则编译失败 - 优先选
php:8.2-cli而非fpm镜像：Webman 是常驻 CLI 进程，fpm本质是 CGI 模式，信号收不到，热重载会静默失效 - 验证是否生效：进容器执行
php -m | grep -E "pcntl|posix"，两行都得有输出；再跑php start.php start -d，日志里得看到Workerman start success
docker-compose.yml 必须补全三项硬配置
官方生成的 docker-compose.yml 只能用于本地调试，上线前不改这三项，容器一重启就丢日志、炸缓存、连不上健康检查。
-
restart: unless-stopped：防止宿主机重启后服务消失 -
volumes: ["./runtime:/app/runtime"]：强制挂载，否则runtime/log和runtime/cache全丢，路由缓存每次重启都重建 -
init: true：启用容器 init 进程，确保SIGTERM能传给 PHP 主进程，实现优雅退出 - 端口映射写成
"8787:8787"，别写"8080:8787"后忘了改 Nginx 或 Traefik 的 upstream；Webman 默认监听0.0.0.0:8787，容器内地址不能改
多实例启动前先关掉多进程模式
容器环境不适合 Webman 默认的多 worker 进程模型（如 --process=4），既浪费资源又难监控。生产集群应让每个容器只起一个主进程，靠横向扩实例来提升吞吐。
- 启动命令统一改为
command: php start.php start -d --process=1 - 这样每个容器只占一个 CPU 核心配额，K8s HPA 或 Swarm 调度更准，OOM Killer 触发逻辑也更可控
- 若仍需多进程（比如做 CPU 密集型任务），必须确认镜像已装
pcntl+posix，且command不带-g（调试模式会绑定终端，容器一断开就死） -
APP_DEBUG=true必须设为false，否则异常堆栈直接打到 HTTP 响应体，安全风险拉满
集群通信依赖外部状态中心，别信共享文件系统
Webman 自身无内置服务发现或状态同步机制。多个容器实例之间要共享 session、锁、定时任务调度或配置变更通知，不能靠挂同一个 NFS 卷——性能差、一致性难保、还容易引发 race condition。
- Session / Cache / Lock：统一走
Redis，配置config/cache.php和config/session.php指向外部 Redis 地址 - 服务注册与发现：接入
Consul或Nacos，用 Webman 的service-discovery插件自动上报ip:port和健康状态 - 集中日志：禁用
runtime/log文件写入，改用monolog推送到ELK或Loki+Promtail - 配置中心化：把
.env和config/*.php中的敏感项抽到Nacos或Consul KV，启动时通过 HTTP 拉取并注入
真正卡住 Webman 集群落地的，从来不是“怎么起多个容器”，而是“怎么让它们互相知道对方活着、状态一致、不抢活也不漏活”。pcntl/posix 是门槛，restart/volume/init 是底线，而 Redis/Nacos 才是集群的脊椎——漏掉任何一层，扩容出来的都是孤岛。
