在 OxPHP 上运行 Magento

Magento 是本系列中最重的一份配方。它强制要求一个搜索引擎（OpenSearch）、一长串扩展，以及一个静态内容部署步骤。它以 OxPHP 的框架路由模式运行，并将 pub/ 作为文档根目录，但其带版本号的静态资源 URL 需要一个额外步骤，详见下文。

技术栈一览

  • OxPHP 镜像： ghcr.io/oxphp/oxphp:0.10.0-php8.4-alpine3.23（PHP 8.4）
  • 路由模式： 框架模式（ENTRY_FILE=index.php；DOCUMENT_ROOT=/var/www/html/pub 覆盖了默认的 …/public）
  • 新增扩展： bcmath、gd、intl、pdo_mysql、soap、xsl、zip、mbstring、ftp、pcntl、sockets
  • 服务： OxPHP + MySQL 8.0 + OpenSearch 2.x
  • URL： http://localhost:8093 · 后台 /admin · 内部 http://localhost:9094/health
PHP 版本

Magento 2.4.8 声明了 "php": "~8.2 || ~8.3 || ~8.4" 并拒绝 PHP 8.5，因此请锁定 PHP 8.4 镜像。ext-sockets 是一项传递依赖（php-amqplib），编译时需要 linux-headers。

项目结构

从官方分发渠道获取的 Magento Open Source 需要 Adobe Marketplace 授权密钥。若要在没有密钥的情况下安装，请克隆开源仓库（其模块通过 replace 以源码内置的方式提供，因此 composer install 只会拉取 Packagist 上的依赖）：

bash
mkdir -p magento-oxphp git clone --branch 2.4.8 --depth 1 https://github.com/magento/magento2.git magento-oxphp/src # composer install 会在稍后于 PHP 8.4 容器内运行（composer:2 是 PHP 8.5， # 而 Magento 拒绝它）： docker compose run --rm --no-deps -e COMPOSER_MEMORY_LIMIT=-1 app \ composer install --no-interaction --prefer-dist

Dockerfile 与 compose 文件

src/Dockerfile.oxphp 之所以这样命名，是为了避免与 Magento 自带的 docker 资源冲突。

src/Dockerfile.oxphp
ARG OXPHP_VERSION=0.10.0 ARG PHP_VERSION=8.4 ARG ALPINE_VERSION=3.23 # ── PHP base: Magento runtime extensions ────────────────────── FROM php:${PHP_VERSION}-zts-alpine${ALPINE_VERSION} AS php-base RUN apk add --no-cache \ icu-libs libpng libjpeg-turbo freetype oniguruma libzip libxslt \ && apk add --no-cache --virtual .build-deps \ icu-dev libpng-dev libjpeg-turbo-dev freetype-dev oniguruma-dev \ libzip-dev libxslt-dev libxml2-dev linux-headers \ && docker-php-ext-configure gd --with-jpeg --with-freetype \ && docker-php-ext-install -j"$(nproc)" \ bcmath gd intl pdo_mysql soap xsl zip mbstring ftp pcntl sockets \ && apk del .build-deps # ── Composer ────────────────────────────────────────────────── FROM composer:2 AS composer # ── OxPHP artifacts (PHP 8.4 image) ─────────────────────────── FROM ghcr.io/oxphp/oxphp:${OXPHP_VERSION}-php${PHP_VERSION}-alpine${ALPINE_VERSION} AS oxphp # ── dev: OxPHP server + PHP CLI + Composer + Magento extensions ─ FROM php-base AS dev RUN apk add --no-cache libgcc git patch COPY --from=composer /usr/bin/composer /usr/local/bin/composer COPY --from=oxphp /usr/local/bin/oxphp /usr/local/bin/oxphp COPY --from=oxphp /usr/local/lib/liboxphp_bridge.so /usr/local/lib/ COPY --from=oxphp /usr/local/lib/php/extensions/ /tmp/oxphp-ext/ RUN cp /tmp/oxphp-ext/*/oxphp_sapi.so "$(php -r 'echo ini_get("extension_dir");')/" \ && rm -rf /tmp/oxphp-ext \ && echo "extension=oxphp_sapi.so" > /usr/local/etc/php/conf.d/oxphp-ext.ini RUN { \ echo "[opcache]"; echo "opcache.enable=1"; echo "opcache.enable_cli=1"; \ echo "opcache.validate_timestamps=1"; echo "opcache.revalidate_freq=0"; \ } > /usr/local/etc/php/conf.d/opcache-dev.ini RUN { \ echo "memory_limit=4G"; echo "max_execution_time=1800"; \ echo "realpath_cache_size=10M"; echo "realpath_cache_ttl=86400"; \ echo "upload_max_filesize=64M"; echo "post_max_size=64M"; \ } > /usr/local/etc/php/conf.d/magento.ini RUN getent passwd www-data >/dev/null \ || adduser -D -H -u 82 -G www-data -s /sbin/nologin www-data RUN mkdir -p /var/www/html/pub && chown -R www-data:www-data /var/www/html ENV LD_LIBRARY_PATH=/usr/local/lib WORKDIR /var/www/html EXPOSE 80 9090 CMD ["oxphp"]

安装与首次运行

bash
docker compose up -d db opensearch # composer install（参见“项目结构”），然后： docker compose run --rm app php bin/magento setup:install \ --base-url=http://localhost:8093/ \ --db-host=db --db-name=magento --db-user=magento --db-password=magento \ --admin-firstname=Admin --admin-lastname=User \ [email protected] --admin-user=admin --admin-password='Admin123!' \ --language=en_US --currency=USD --timezone=America/New_York \ --search-engine=opensearch --opensearch-host=opensearch --opensearch-port=9200 \ --opensearch-index-prefix=magento --opensearch-enable-auth=0 # 生产模式会编译 DI 并部署静态内容 docker compose run --rm app php bin/magento deploy:mode:set production # 对 OxPHP 至关重要：让带版本号的静态 URL 能够解析（参见下方注意事项） docker compose run --rm app sh -c \ 'ln -sfn . "pub/static/version$(cat pub/static/deployed_version.txt)"' docker compose up -d app

OxPHP 注意事项

Note

  • 带版本号的静态 URL 需要一个符号链接。 Magento 会生成形如 /static/version<timestamp>/frontend/… 的资源 URL，而文件实际位于 pub/static/frontend/…。nginx 会用一条重写规则去掉 version<N>/ 片段；OxPHP 的框架模式没有这样的重写，因此每个带版本号的资源都会返回 404，店面也会以无样式的方式渲染。解决办法是建立一个自引用的符号链接，让带版本号的路径解析到真实文件：

    bash
    ln -sfn . "pub/static/version$(cat pub/static/deployed_version.txt)"

    由于该符号链接始终位于 DOCUMENT_ROOT（pub/）之内，因此无需添加任何 SYMLINK_ALLOW_PATHS 条目。

  • 运行生产模式。 OxPHP 的工作进程池是多线程的（PHP ZTS）。Magento 开发者模式会即时生成 DI 类和静态资源（通过 pub/static.php，而框架模式并不会路由到它），这可能在多个工作线程之间引发竞态。deploy:mode:set production 会预先编译 DI 并提前部署静态内容，这样工作进程就永远不会在请求期间生成代码。

  • MySQL：--log_bin_trust_function_creators=1。 Magento 在安装期间会创建触发器和存储函数；当启用二进制日志（MySQL 8.0 的默认设置）时，非 SUPER 权限的 magento 用户否则会遇到 1419 错误。

  • composer install 在 PHP 8.4 容器中运行。 官方的 composer:2 镜像是 PHP 8.5，而 Magento 拒绝它；请改用构建出来的 app 镜像来运行它。

验证

bash
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8093/ # 200 店面 curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8093/admin # 200 后台登录 curl -s http://localhost:8093/ | grep -oE '/static/version[0-9]+/[^"]+\.css' | head -1 | \ xargs -I{} curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:8093{}" # 200 curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9094/health # 200

另见

发现错误？报告问题 →