Webman适配Docker容器_PHP Webman构建微服务镜像并运行【工具】-php教程-PHP中文网

webman不能直接用php:8.2-apache镜像，因其依赖pcntl/posix扩展并需cli常驻模式，而apache镜像禁用pcntl且进程模型冲突；应基于php:8.2-cli自建镜像，关闭zts后安装扩展，用exec启动并配置健康检查与非root用户。

webman适配docker容器_php webman构建微服务镜像并运行【工具】

Webman 能直接跑在 Docker 容器里，但不能简单套用 php:apache 或 php:fpm 镜像 —— 它不依赖 Web 服务器进程，而是自带常驻型 HTTP 服务，必须用 CLI 模式启动，且需保留 pcntl、posix 等扩展。

为什么不能直接用 php:8.2-apache 镜像

Webman 启动命令是 php webman start，本质是 fork 子进程 + 事件循环，依赖 pcntl 和 posix 扩展。而 php:8.2-apache 镜像默认禁用 pcntl（Apache MPM 模型冲突），且启动后立即接管 stdin/stdout，导致 Webman 的守护模式失效。常见现象是容器秒退、日志只输出一行 Starting webman... 就静默退出。

官方 php:apache 镜像中 pcntl 被编译禁用，docker-php-ext-install pcntl 会报错 configure: error: pcntl extension cannot be built when ZTS is enabled
即使强行启用，Apache 的 prefork/workers 模型也会和 Webman 的多进程管理器冲突，无法正常 reload 或 stop
Webman 不需要 Apache/Nginx 做反向代理（除非你主动加一层），它自己就是 HTTP 服务器

正确基础镜像选 php:8.2-cli 还是自建？

推荐从 php:8.2-cli 构建，而非直接用 php:8.2-fpm 或第三方打包镜像。原因很实际：fpm 镜像默认不带 pcntl，且工作目录、用户权限、信号处理机制都为 FastCGI 设计，和 Webman 运行时语义不匹配。

php:8.2-cli 默认启用 ZTS（线程安全），但 pcntl 在 CLI 模式下可正常编译安装 —— 关键是构建时加 --disable-zts 参数（见下方 Dockerfile）
第三方镜像如 ghcr.io/tinywan/docker-php-webman:8.2.11 虽然可用，但版本滞后、扩展固定（比如缺 redis 或 swoole）、调试信息少，生产环境难溯源
自建镜像能精准控制 opcache.enable_cli=1、memory_limit=-1、max_execution_time=0 等常驻进程关键配置

Dockerfile 必须包含的 4 个关键动作

以下是最小可行 Dockerfile 片段，适用于 Webman 1.5+ + PHP 8.2：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

FROM php:8.2-cli
<h1>1. 关闭 ZTS，否则 pcntl 编译失败</h1><p>RUN docker-php-source extract \
&& sed -i 's/^(ZTS=)true/\1false/' /usr/src/php/Makefile.global \
&& docker-php-ext-install pcntl posix</p><h1>2. 安装业务依赖扩展（按需增减）</h1><p>RUN apt-get update && apt-get install -y libpng-dev libjpeg-dev \
&& docker-php-ext-configure gd --with-freetype --with-jpeg \
&& docker-php-ext-install gd pdo_mysql redis</p><h1>3. 复制代码并设工作目录（注意权限）</h1><p>COPY . /var/www
WORKDIR /var/www
RUN chown -R www-data:www-data /var/www \
&& chmod +x /var/www/webman</p><h1>4. 启动命令必须用 exec，保证 PID 1 是 php 进程</h1><p>CMD ["php", "webman", "start", "-d"]</p>

第 1 步不可省 —— 直接 docker-php-ext-install pcntl 在默认镜像上必报错，必须先关 ZTS
-d 参数是关键：Webman 默认前台运行，-d 才进守护模式；若漏掉，容器启动即退出
CMD 必须用 JSON 数组格式，避免 shell 层 wrapper 导致信号（如 SIGTERM）无法传给 php 进程，影响优雅停机
别用 ENTRYPOINT 包一层 bash 脚本，会干扰进程树和健康检查

docker-compose.yml 中容易被忽略的三项配置

单容器部署够用，但微服务场景下常需对接 Redis、MySQL、Prometheus 等，此时 docker-compose.yml 的写法直接影响可观测性和稳定性：

restart: unless-stopped：比 always 更合理，避免故障时无限重启掩盖问题
healthcheck 必须配，例如：curl -f http://localhost:8787/health || exit 1，否则 Swarm/K8s 无法判断实例是否真就绪
user: "www-data"：显式指定运行用户，避免 root 权限启动导致日志/缓存目录权限混乱（尤其挂载 volume 时）
端口映射建议写全："8787:8787/tcp"，明确协议类型，防止 UDP 冲突或防火墙策略误判

复杂点在于信号传递和进程生命周期管理 —— Webman 的 stop 命令依赖 pcntl_signal_dispatch()，而 Docker 默认只转发 SIGTERM 给 PID 1。如果容器内有 supervisord 或 sh wrapper，信号链就断了，docker stop 会等 10 秒超时后发 SIGKILL，造成连接强制中断。这点在压测或滚动发布时特别明显。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！