gRPC PHP 扩展 Docker 测试镜像全指南:构建、运行与多环境覆盖

原创2026-09-09 16:38:351,459 阅读
文章标签:RPC框架网络/通信微服务

gRPC PHP 扩展 Docker 测试镜像全指南:构建、运行与多环境覆盖

本指南以 gRPC 仓库 src/php/docker/README.md 为核心,系统讲解 gRPC PHP(PECL 扩展)官方测试 Docker 镜像的构建、运行原理与每个镜像的适用场景。读者将掌握如何用一条脚本构建/运行全部测试镜像、如何单独构建指定镜像、以及每个镜像背后对应的 PHP 环境与编译策略,为在不同 PHP 版本与操作系统上验证 gRPC 扩展提供可复用的实战方案。

为什么需要 Docker 测试镜像

gRPC 的 PHP 语言绑定以 PECL 扩展 形式分发,其测试需要覆盖多种差异极大的 PHP 运行时环境:不同 PHP 主版本、是否启用 ZTS(线程安全)、不同操作系统与编译器(Alpine 的 musl libc、CentOS 7 的 GCC 4.8.5)、甚至需要从零编译 PHP 源码以开启 debug 模式。直接在开发机上逐一搭建这些环境成本高且互相污染,因此仓库在 src/php/docker 目录下维护了一批可复现的 Docker 镜像,专门用于对 gRPC PHP 扩展做回归测试与兼容性验证。

从目录结构看,当前仓库实际包含以下镜像定义目录(每个目录内是一个独立的 Dockerfile):

src/php/docker/
├── alpine/       # Alpine Linux 基础镜像
├── centos7/      # CentOS 7 + devtoolset-7
├── fork-support/ # pcntl_fork() 支持验证
├── grpc-ext/     # 完整 PECL 扩展构建
├── grpc-src/     # 瘦身构建、动态链接 C Core
├── i386/         # 32 位架构镜像
├── php-src/      # 从源码编译 PHP
├── php-zts/      # ZTS 线程安全构建
├── php8.2/       # PHP 8.2 环境
└── README.md

快速上手:一键构建与运行全部镜像

构建全部镜像:build_all_docker_images.sh

进入仓库根目录后,可用官方脚本 src/php/bin/build_all_docker_images.sh 一键构建全部镜像:

$ cd grpc
$ ./src/php/bin/build_all_docker_images.sh

该脚本内部维护了镜像清单:

ALL_IMAGES=( grpc-ext grpc-src alpine centos7 php-src php-zts
             fork-support i386 php8.2 )

随后对每个镜像执行:

docker build -t grpc-php/"$arg" -f ./src/php/docker/"$arg"/Dockerfile .

可以看到,脚本为每个镜像统一使用 grpc-php/<镜像名> 的命名约定,-f 指定各自的 Dockerfile,构建上下文(最后的 .)是仓库根目录——这正是各个 Dockerfile 中 COPY . . 能拿到整个 gRPC 源码的前提。

只构建部分镜像也很简单,把镜像名作为参数传入即可:

$ ./src/php/bin/build_all_docker_images.sh grpc-ext php-src

只想查看将要执行的 docker build 命令而不实际构建,则加 --cmds 参数:

$ ./src/php/bin/build_all_docker_images.sh --cmds

脚本对 --cmds 的处理逻辑是遍历 ALL_IMAGES 逐个打印命令后直接 exit 0(见 build_all_docker_images.sh)。

运行全部镜像:run_all_docker_images.sh

构建完成后,用 src/php/bin/run_all_docker_images.sh 运行全部镜像(逐个前台执行,使用 -it --rm):

$ ./src/php/bin/run_all_docker_images.sh

同样支持指定子集与打印命令两种用法:

$ ./src/php/bin/run_all_docker_images.sh grpc-ext php-src
$ ./src/php/bin/run_all_docker_images.sh --cmds

--cmds 模式会打印出形如 docker run -it --rm grpc-php/<镜像名> 的原始命令(见 run_all_docker_images.sh)。注意 -it 意味着这些容器设计为可交互运行,容器启动后的默认行为(CMD)才是执行测试。

分镜像详解:每个镜像解决什么问题

grpc-ext:完整 PECL 扩展 + 单元测试

grpc-ext 构建完整的 grpc PECL 扩展(相当于当前发布候选版本),安装到当前 PHP 版本中并运行单元测试。其 Dockerfile 关键步骤:

FROM php:8.1-buster

RUN apt-get -qq update && apt-get -qq -y upgrade && apt-get -qq install -y \
  autoconf automake git libtool pkg-config \
  valgrind wget zlib1g-dev

ARG MAKEFLAGS=-j8

WORKDIR /github/grpc
COPY . .

RUN pear package && \
  find . -name grpc-*.tgz | xargs -I{} pecl install {}

CMD ["/github/grpc/src/php/bin/run_tests.sh", "--skip-persistent-channel-tests", \
     "--ignore-valgrind-undef-errors"]

要点解读:

  • 基础镜像是官方 php:8.1-buster;安装的 autoconf/automake/libtool/pkg-config 是 PECL 扩展编译链的必需品,valgrind 用于内存错误检测,zlib1g-dev 是 gRPC 依赖的 zlib 开发头文件。
  • ARG MAKEFLAGS=-j8 为 make 指定 8 路并行编译。
  • pear package 在仓库根目录生成 grpc-*.tgz 包,pecl install 再安装它,完整走一遍 PECL 打包→安装的真实流程。
  • 容器默认命令直接执行测试脚本 src/php/bin/run_tests.sh,并跳过 persistent channel 测试、忽略 valgrind 的未定义值错误(后者是因为 PHP 扩展常见的初始化模式会触发这类误报)。

手动构建与运行:

$ docker build -t grpc-php/grpc-ext -f ./src/php/docker/grpc-ext/Dockerfile .
$ docker run -it --rm grpc-php/grpc-ext

grpc-src:瘦身构建 + 动态链接 + --enable-tests

grpc-src 以"瘦身"方式构建扩展:镜像内只包含 gRPC 扩展自身的源码文件,gRPC C Core 库需要单独安装并动态链接。这种拆分方式允许在 configure 阶段追加额外选项,例如 --enable-tests 开启更多单元测试。其 Dockerfile 关键差异:

RUN make shared_c static_c

WORKDIR /github/grpc/src/php/ext/grpc

RUN phpize && \
  GRPC_LIB_SUBDIR=libs/opt ./configure --enable-grpc=/github/grpc --enable-tests && \
  make && \
  make install

要点解读:

  • 先在仓库根目录执行 make shared_c static_c,编译出 gRPC C Core 的共享库与静态库(输出到 libs/opt)。
  • 然后进入扩展源码目录 src/php/ext/grpc,phpize 生成 configure 脚本;--enable-grpc=/github/grpc 指定 C Core 源码位置,GRPC_LIB_SUBDIR=libs/opt 指向刚编译出的库目录,--enable-tests 开启扩展内部测试。
  • 相比 grpc-ext,这里扩展与 C Core 是分离编译、动态链接的,这也更接近真实生产环境"系统已有 gRPC 库、只装 PHP 扩展"的部署形态。
$ docker build -t grpc-php/grpc-src -f ./src/php/docker/grpc-src/Dockerfile .
$ docker run -it --rm grpc-php/grpc-src

alpine:Alpine Linux 环境验证

alpine 镜像在 Alpine Linux 基础镜像上构建扩展,用于验证 gRPC 在 musl libc 生态下的可用性。其 Dockerfile 使用 php:8.1-alpine3.18 基础镜像,并通过 apk add 安装编译依赖:

FROM php:8.1-alpine3.18
RUN apk add autoconf g++ make zlib-dev git bash wget linux-headers

其余流程与 grpc-ext 一致(pear package + pecl install),同样在启动时运行单元测试。

$ docker build -t grpc-php/alpine -f ./src/php/docker/alpine/Dockerfile .
$ docker run -it --rm grpc-php/alpine

centos7:老牌 GCC 与 SCL 工具链兼容性

centos7 镜像用于验证 gRPC 扩展在 CentOS 7 自带 GCC(默认 4.8.5)环境下的兼容性。其 Dockerfile 通过安装 Software Collections(SCL)升级编译器:

FROM centos:centos7

RUN yum update -y && \
  yum install -y centos-release-scl && \
  yum install -y devtoolset-7-gcc*

SHELL [ "/usr/bin/scl", "enable", "devtoolset-7"]

RUN yum install epel-release -y && \
  yum install http://rpms.remirepo.net/enterprise/remi-release-7.rpm -y && \
  yum --enablerepo=remi-php81 install php -y && \
  ...

要点解读:

  • SHELL [ "/usr/bin/scl", "enable", "devtoolset-7"] 让后续所有 RUN 指令默认在 devtoolset-7 环境中执行,从而启用 GCC 7.3.1(CentOS 7 默认 GCC 为 4.8.5,见 README.md)。容器内如需手动切换,可运行 scl enable devtoolset-7 bash。
  • PHP 通过 Remi 仓库的 remi-php81 源安装到 CentOS 7 上,验证"老系统 + 新 PHP + gRPC 扩展"的组合。
  • 注意该镜像的 tag 是 grpc-gcc7/centos(而非 grpc-php/centos7),与脚本中的统一前缀不同,是文档中明确给出的构建方式:
$ docker build -t grpc-gcc7/centos -f ./src/php/docker/centos7/Dockerfile .
$ docker run -it --rm grpc-gcc7/centos

php-src:从源码编译 PHP(--enable-debug)

php-src 不使用官方 PHP 基础镜像,而是直接从 php-src 源码编译 PHP 本体,以便自定义 configure 选项(如 --enable-debug),随后再构建完整 PECL 扩展并运行单元测试。其 Dockerfile 核心片段:

FROM debian:buster

RUN apt-get -qq update && apt-get -qq -y upgrade && apt-get -qq install -y \
  autoconf bison build-essential git libtool \
  libcurl4-openssl-dev libedit-dev libonig-dev libsodium-dev \
  libsqlite3-dev libssl-dev libxml2-dev \
  pkg-config re2c valgrind wget zlib1g-dev

WORKDIR /github/php-src
RUN git clone https://github.com/php/php-src .
RUN git checkout php-8.1.27 && \
  ./buildconf --force && \
  ./configure --build=x86_64-linux-gnu --enable-option-checking=fatal \
    --enable-debug --enable-pcntl \
    --enable-ftp --enable-mbstring --enable-mysqlnd \
    --with-curl --with-libedit --with-mhash --with-openssl \
    --with-pear --with-sodium=shared --with-zlib && \
  make && make install

要点解读:

  • 编译 PHP 所需的依赖一应俱全(bison/re2c 是 PHP 语法解析器生成工具,libssl-dev/libcurl4-openssl-dev 等是对应扩展的开发库)。
  • --enable-debug 开启 PHP 的 debug 构建,便于用 valgrind 排查扩展内存问题;--enable-pcntl 开启进程控制扩展,这是后续 fork-support 镜像依赖的基础。
  • 该镜像同样由 grpc-ext 的流程(pear package + pecl install)安装扩展并跑测试。
$ docker build -t grpc-php/php-src -f ./src/php/docker/php-src/Dockerfile .
$ docker run -it --rm grpc-php/php-src

php-zts:ZTS 线程安全验证

php-zts 在启用 ZTS(Zend Thread Safety)的 PHP 上构建扩展,用于验证 gRPC 扩展在线程安全构建下的正确性。其 Dockerfile 直接以 php:8.1-zts-buster 为基础镜像,后续流程与 grpc-ext 相同(pear package + pecl install + 运行测试):

$ docker build -t grpc-php/php-zts -f ./src/php/docker/php-zts/Dockerfile .
$ docker run -it --rm grpc-php/php-zts

文档记载但当前仓库已移除的镜像:php-future 与 php5

README 中还记载了两个镜像:

  • php-future:针对当前处于 alpha、beta 或 RC 阶段的未来 PHP 版本构建扩展(见 README.md)。
  • php5:针对 PHP 5.x 的镜像,但 README 明确注明 PHP 5.x 已到达生命周期终点(EOL),不再受支持(见 README.md)。

需要说明的是,从当前仓库的目录结构看,src/php/docker 下已不再包含 php-future 与 php5 两个目录,脚本 build_all_docker_images.sh 的 ALL_IMAGES 清单中也没有它们,可以推断这两个镜像已随 PHP 5 的退役与未来版本的滚动而被移除或归档。引用这两节时请以当前仓库实际内容为准。

仓库实际包含、README 未单独展开的镜像:i386 与 php8.2

除 README 逐节介绍的镜像外,当前仓库还包含两个镜像目录:src/php/docker/i386/Dockerfile 与 src/php/docker/php8.2/Dockerfile,并且都位列 ALL_IMAGES 构建/运行清单。从命名与目录结构可以推断:i386 用于在 32 位架构环境验证扩展的构建与运行,php8.2 则覆盖 PHP 8.2 版本。它们同样通过统一脚本构建与运行:

$ ./src/php/bin/build_all_docker_images.sh i386 php8.2
$ ./src/php/bin/run_all_docker_images.sh i386 php8.2

fork-support:pcntl_fork() 支持专项验证

fork-support 镜像专门验证 pcntl_fork() 场景:确保使用 pcntl_fork() 的 PHP 脚本在 gRPC 扩展加载后不会冻结或崩溃。它的 Dockerfile 以 grpc-php/php-src 为基础镜像(因此需要先构建 php-src,这也解释了脚本中它排在该镜像之后的原因),并向 php.ini 追加配置:

FROM grpc-php/php-src

WORKDIR /tmp
COPY src/php/docker/fork-support/fork.php .

RUN echo '\
extension=grpc.so\n\
grpc.enable_fork_support=1\n\
grpc.poll_strategy=epoll1\n\
' >> /usr/local/lib/php.ini

CMD ["php", "fork.php"]

三个 php.ini 配置项的语义非常明确:

  • extension=grpc.so:加载 gRPC 扩展。
  • grpc.enable_fork_support=1:开启 gRPC 的 fork 支持(对应扩展的 grpc.enable_fork_support 配置)。
  • grpc.poll_strategy=epoll1:将轮询策略固定为 epoll1(避免某些轮询引擎在 fork 后出现资源继承问题)。

被执行的测试脚本 fork.php 内容极简但切中要害:

<?php
$pid = pcntl_fork();
if ($pid == -1) {
  die("could not fork");
} else if ($pid) {
  // parent
  echo "parent waiting...\n";
  pcntl_waitpid($pid, /*&*/$pcntl_status);
} else {
  // child
  echo "child exiting...\n";
  exit(0);
}
echo "parent finishing. Done\n";

父进程 fork 出子进程后等待其退出,若脚本能完整打印 "parent finishing. Done" 而进程不卡死、不崩溃,即表明在启用 grpc.enable_fork_support 与 epoll1 轮询策略的组合下,扩展的 fork 语义正常。

$ docker build -t grpc-php/fork-support -f ./src/php/docker/fork-support/Dockerfile .
$ docker run -it --rm grpc-php/fork-support

深入:镜像内统一执行的 run_tests.sh

除 fork-support 外,几乎所有测试镜像的 CMD 都指向 src/php/bin/run_tests.sh,因此理解该脚本就能理解"镜像跑测试时到底发生了什么":

set -ex
cd $(dirname $0)/../../..
root=$(pwd)
cd src/php/bin
source ./determine_extension_dir.sh
export DYLD_LIBRARY_PATH=$root/libs/$CONFIG
$(which php) $extension_dir -d max_execution_time=300 $(which phpunit) -v --debug \
  --exclude-group persistent_list_bound_tests ../tests/unit_tests

for arg in "$@"
do
  if [[ "$arg" == "--skip-persistent-channel-tests" ]]; then
    SKIP_PERSISTENT_CHANNEL_TESTS=true
  elif [[ "$arg" == "--ignore-valgrind-undef-errors" ]]; then
    VALGRIND_UNDEF_VALUE_ERRORS="--undef-value-errors=no"
  fi
done

if [[ "$SKIP_PERSISTENT_CHANNEL_TESTS" != "true" ]]; then
   $(which php) $extension_dir -d max_execution_time=300 $(which phpunit) -v --debug \
     ../tests/unit_tests/PersistentChannelTests
fi

要点解读:

  • 脚本通过 src/php/bin/determine_extension_dir.sh 定位扩展目录,用 phpunit 运行 src/php/tests/unit_tests 下的单元测试,并设置 max_execution_time=300 防止单测超时。
  • --exclude-group persistent_list_bound_tests 先跳过 persistent channel 相关测试;只有当调用方没有传 --skip-persistent-channel-tests 时,才单独补跑 PersistentChannelTests 目录。这正是 grpc-ext 等镜像的 CMD 传 --skip-persistent-channel-tests、而 grpc-src 不传的原因——前者以非持久连接模式验证主流程,后者完整覆盖持久连接用例。
  • 该脚本同时兼容 valgrind 模式(--ignore-valgrind-undef-errors 会映射为 --undef-value-errors=no),与镜像内安装的 phpunit 9.5.9 配套使用。

使用建议与注意事项

  1. 按需选择镜像:日常快速回归用 grpc-ext(完整 PECL 流程);需要验证 C Core 动态链接与 --enable-tests 用 grpc-src;排查内存问题优先 php-src(--enable-debug + valgrind);验证线程安全用 php-zts;验证 fork 场景用 fork-support(注意其依赖 php-src 已构建)。
  2. 构建上下文是仓库根目录:所有镜像都以 docker build -f ./src/php/docker/<name>/Dockerfile . 的方式构建,其中的 . 必须是仓库根目录,否则 COPY . . 无法获取完整源码。
  3. 镜像命名不统一:绝大多数镜像 tag 为 grpc-php/<name>,但 centos7 文档明确使用 grpc-gcc7/centos,而 fork-support 的 FROM grpc-php/php-src 隐含了镜像间的依赖顺序。
  4. 以当前仓库为准:README 记载的 php-future、php5 已不在当前 src/php/docker 目录中,实际清单以脚本 ALL_IMAGES 与目录结构为准(当前为 grpc-ext grpc-src alpine centos7 php-src php-zts fork-support i386 php8.2)。

通过这套 Docker 镜像体系,可以在完全隔离的环境中快速覆盖 gRPC PHP 扩展的主要运行时组合,将其作为扩展开发、回归测试与发布前验证的标准工具链。

登录后查看全文
grpc