gRPC PHP 扩展 Docker 测试镜像全指南:构建、运行与多环境覆盖
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 配套使用。
使用建议与注意事项
- 按需选择镜像:日常快速回归用
grpc-ext(完整 PECL 流程);需要验证 C Core 动态链接与--enable-tests用grpc-src;排查内存问题优先php-src(--enable-debug+ valgrind);验证线程安全用php-zts;验证 fork 场景用fork-support(注意其依赖php-src已构建)。 - 构建上下文是仓库根目录:所有镜像都以
docker build -f ./src/php/docker/<name>/Dockerfile .的方式构建,其中的.必须是仓库根目录,否则COPY . .无法获取完整源码。 - 镜像命名不统一:绝大多数镜像 tag 为
grpc-php/<name>,但centos7文档明确使用grpc-gcc7/centos,而fork-support的FROM grpc-php/php-src隐含了镜像间的依赖顺序。 - 以当前仓库为准: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 扩展的主要运行时组合,将其作为扩展开发、回归测试与发布前验证的标准工具链。