arm64v8/php 镜像文档

镜像概述

关于PHP

PHP是一种服务器端脚本语言，主要设计用于Web开发，同时也可作为通用编程语言使用。PHP代码可嵌入HTML中，或与多种模板引擎和Web框架配合使用，通常由Web服务器的原生模块或CGI解释器处理。

镜像定位

本镜像为PHP官方镜像的arm64v8架构构建版本，专门用于ARM64架构环境中PHP应用的容器化部署。更多关于多架构镜像的信息，请参见官方镜像文档中的“非amd64架构”部分。

核心功能与特性

• 多架构支持：官方PHP镜像支持多种架构，本镜像专注于arm64v8架构
• 多样化变体：提供cli、apache、fpm、alpine等变体，满足不同部署场景需求
• 扩展安装工具：内置docker-php-ext-configure、docker-php-ext-install、docker-php-ext-enable等脚本，简化PHP扩展安装流程
• 灵活配置体系：包含php.ini-development和php.ini-production默认配置文件，支持通过$PHP_INI_DIR/conf.d/目录自定义配置
• 轻量级选项：提供基于Alpine Linux的变体，显著减小镜像体积，适合资源受限环境

使用场景

• 命令行应用：通过cli变体运行PHP脚本、后台任务或开发工具
• 独立Web服务：使用apache变体直接部署PHP Web应用，集成Apache服务器
• 高性能Web部署：fpm变体配合Nginx等反向代理，适用于生产环境的高并发场景
• 轻量级环境：alpine变体适合对镜像体积和资源占用有严格要求的场景

快速参考

维护与支持

• 维护者：Docker社区
• 获取帮助：Docker社区Slack、Server Fault、Unix & Linux、Stack Overflow

镜像信息

• 支持的标签及Dockerfile链接：完整列表参见GitHub文档（因Hub长度限制已截断）
• 提交issue：php镜像GitHub仓库
• 支持的架构：amd64、arm32v5、arm32v6、arm32v7、arm64v8、i386、mips64le、ppc64le、riscv64、s390x（更多信息）
• 镜像元数据：repo-info仓库的php目录（包含镜像元数据、传输大小等）
• 镜像更新：official-images仓库的library/php标签、official-images仓库的library/php文件
• 文档来源：docs仓库的php目录

使用方法

创建PHP项目的Dockerfile

在PHP项目根目录创建Dockerfile：

FROM arm64v8/php:8.2-cli
COPY . /usr/src/myapp
WORKDIR /usr/src/myapp
CMD ["php", "./your-script.php"]

构建并运行镜像：

$ docker build -t my-php-app .
$ docker run -it --rm --name my-running-app my-php-app

运行单个PHP脚本

对于简单的单文件项目，可直接使用镜像运行脚本，无需编写Dockerfile：

$ docker run -it --rm --name my-running-script -v "$PWD":/usr/src/myapp -w /usr/src/myapp arm64v8/php:8.2-cli php your-script.php

安装PHP扩展

检查已安装扩展

首先通过以下命令检查镜像中预安装的扩展，避免重复安装：

$ docker run --rm arm64v8/php:8.2-cli php -m

扩展安装工具

镜像提供以下工具简化扩展管理：

• docker-php-ext-configure：配置扩展编译选项
• docker-php-ext-install：编译安装PHP核心扩展并自动启用
• docker-php-ext-enable：手动启用已安装的扩展
• docker-php-source：提取PHP源代码（用于扩展编译，需在同一镜像层删除以减小体积）

PHP核心扩展安装示例

以安装gd扩展（适用于FPM变体）为例：

FROM arm64v8/php:8.2-fpm
RUN apt-get update && apt-get install -y \
        libfreetype-dev \
        libjpeg62-turbo-dev \
        libpng-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd

注意：需手动安装扩展依赖的系统库。若需简化依赖管理，可参考社区工具install-php-extensions。

PECL扩展安装示例

通过pecl install安装PECL扩展，再用docker-php-ext-enable启用：

FROM arm64v8/php:8.2-cli
RUN pecl install redis-5.3.7 \
    && pecl install xdebug-3.2.1 \
    && docker-php-ext-enable redis xdebug

建议指定扩展版本以确保兼容性。PECL扩展需逐个安装（避免安装失败被忽略），但可一次性启用多个。

其他扩展（非核心/非PECL）安装示例

对于未包含在PHP核心或PECL中的扩展，可通过源码编译安装：

FROM arm64v8/php:8.2-cli
RUN curl -fsSL '[扩展源码URL]' -o module-name.tar.gz \
    && mkdir -p /tmp/module-name \
    && sha256sum -c "[校验值]  module-name.tar.gz" \
    && tar -xf module-name.tar.gz -C /tmp/module-name --strip-components=1 \
    && rm module-name.tar.gz \
    && docker-php-ext-configure /tmp/module-name --enable-module-name \
    && docker-php-ext-install /tmp/module-name \
    && rm -r /tmp/module-name

以非特权用户运行

Apache变体

• 内核版本≥4.11：添加--sysctl net.ipv4.ip_unprivileged_port_start=0，然后使用--user指定用户
• 任意内核版本：修改Apache配置使用非特权端口（>1024），再通过--user指定用户

FPM变体

直接通过docker run的--user参数指定用户（支持容器内用户名/组或UID/GID）：

$ docker run -it --rm --user 1000:1000 arm64v8/php:8.2-fpm

PHP配置

默认配置文件

镜像包含两套默认配置：

• php.ini-development：开发环境配置（默认启用详细错误信息）
• php.ini-production：生产环境配置（默认禁用调试信息，启用性能优化）

配置文件位于$PHP_INI_DIR（通常为/usr/local/etc/php）。

使用生产环境配置

FROM arm64v8/php:8.2-fpm-alpine
# 切换到生产环境配置
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"

自定义配置

通过将配置文件挂载或复制到$PHP_INI_DIR/conf.d/目录来自定义配置：

FROM arm64v8/php:8.2-cli
# 添加自定义配置
COPY custom.ini "$PHP_INI_DIR/conf.d/"

生产环境建议启用OPcache扩展提升性能，参考PHP官方OPcache文档。

镜像变体

arm64v8/php:<version>-cli

用途：命令行脚本、工具或作为基础镜像
特点：

• 包含PHP CLI工具（/usr/local/bin/php）
• 唯一包含php-cgi二进制文件（用于PPM等工具）
• 适合非Web场景的PHP应用

arm64v8/php:<version>-apache

用途：直接部署PHP Web应用
特点：

• 基于Debian，集成Apache HTTP服务器和mod_php
• 默认使用mpm_prefork模块
• 适合需要快速部署的Web场景

基础用法示例

Dockerfile部署：

FROM arm64v8/php:7.2-apache
COPY src/ /var/www/html/

构建并运行：

$ docker build -t my-php-app .
$ docker run -d -p 80:80 --name my-running-app my-php-app

直接运行（无Dockerfile）：

$ docker run -d -p 80:80 --name my-apache-php-app -v "$PWD":/var/www/html arm64v8/php:7.2-apache

自定义DocumentRoot

通过环境变量修改Apache的网站根目录：

FROM arm64v8/php:7.1-apache
ENV APACHE_DOCUMENT_ROOT /path/to/new/root
RUN sed -ri -e 's!/var/www/html!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/sites-available/*.conf
RUN sed -ri -e 's!/var/www/!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/apache2.conf /etc/apache2/conf-available/*.conf

arm64v8/php:<version>-fpm

用途：配合反向代理（如Nginx）的生产环境部署
特点：

• 包含PHP-FPM（FastCGI Process Manager）
• 需与反向代理配合使用，不建议直接暴露到公网
• 适合高并发Web应用场景

安全警告：FastCGI协议不加密，禁止将FPM端口直接暴露到公网，仅在私有容器网络中使用。

arm64v8/php:<version>-alpine

用途：资源受限环境或对镜像体积有严格要求的场景
特点：

• 基于Alpine Linux，基础镜像体积约5MB
• 使用musl libc替代glibc，可能存在兼容性限制
• 默认不包含额外工具（如git、bash），需手动安装

常见问题

安装Debian PHP包时报错“E: Package 'php-XXX' has no installation candidate”

此镜像默认阻止安装Debian的PHP包（避免冲突的PHP安装）。正确解决方法是使用docker-php-ext-install、pecl或phpize安装扩展，而非通过apt-get install php-XXX。

临时解决方法（不推荐，可能导致冲突）：

RUN rm /etc/apt/preferences.d/no-debian-php

许可证

镜像中PHP软件的许可证信息参见PHP官方许可证页面。

镜像可能包含其他软件（如基础镜像中的Bash等），其许可证需由用户自行确认合规性。更多自动检测的许可证信息可参见repo-info仓库的php目录。

作为预构建镜像的使用者，您有责任确保对镜像的使用符合所有包含软件的相关许可证。