在 OxPHP 上运行 OpenCart

OpenCart 是一个传统模式应用，拥有两个物理前端控制器：index.php（店铺前台）和 admin/index.php（管理后台），另有位于 image/ 和 catalog/view/ 下的静态资源。它的 webroot 就是项目根目录本身。OxPHP 的传统路由模式——即不设置 ENTRY_FILE 时的默认模式——将两个入口点都作为真实文件提供，并从磁盘提供静态资源；PHP_DENY_PATHS 则阻止直接执行框架内部文件。

技术栈一览

  • OxPHP 镜像： ghcr.io/oxphp/oxphp:0.10.0-php8.4-alpine3.23（PHP 8.4）
  • 路由模式： 传统模式（不设 ENTRY_FILE；DOCUMENT_ROOT = 项目根目录，覆盖默认的 …/public）
  • 新增扩展： gd、mysqli、zip、mbstring
  • 服务： OxPHP + MySQL
  • URL： http://localhost:8095 · 管理后台 /admin/ · 内部 http://localhost:9096/health
PHP 版本

OpenCart 4 要求 PHP 8.0+，但其代码库早于 8.5；请固定使用 PHP 8.4 镜像。OpenCart 使用 mysqli 驱动，而非 PDO。（注意：OpenCart 3.x 无法在 PHP 8.4+ 上运行——请使用 OpenCart 4.x。）

项目结构

OpenCart 以发布压缩包的形式分发，而非 Composer 包。webroot 就是压缩包中 upload/ 目录的内容：

bash
mkdir -p opencart-oxphp/src curl -sL https://github.com/opencart/opencart/releases/download/4.1.0.3/opencart-4.1.0.3.zip -o /tmp/oc.zip unzip -q /tmp/oc.zip -d /tmp/oc cp -a /tmp/oc/upload/. opencart-oxphp/src/ # the installer needs these to exist and be writable: : > opencart-oxphp/src/config.php : > opencart-oxphp/src/admin/config.php

Dockerfile 与 Compose

Dockerfile 命名为 src/Dockerfile.oxphp，以免与 OpenCart 自带的 Dockerfile 冲突。

src/Dockerfile.oxphp
ARG OXPHP_VERSION=0.10.0 ARG PHP_VERSION=8.4 ARG ALPINE_VERSION=3.23 # ── PHP base: OpenCart runtime extensions ───────────────────── FROM php:${PHP_VERSION}-zts-alpine${ALPINE_VERSION} AS php-base RUN apk add --no-cache \ libpng libjpeg-turbo freetype oniguruma libzip \ && apk add --no-cache --virtual .build-deps \ libpng-dev libjpeg-turbo-dev freetype-dev oniguruma-dev libzip-dev \ && docker-php-ext-configure gd --with-jpeg --with-freetype \ && docker-php-ext-install -j"$(nproc)" gd mysqli zip mbstring \ && 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 ──────────────────── FROM php-base AS dev RUN apk add --no-cache libgcc 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=256M"; echo "upload_max_filesize=64M"; \ echo "post_max_size=64M"; echo "max_execution_time=300"; \ } > /usr/local/etc/php/conf.d/opencart.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 && 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"]

安装与首次运行

OpenCart 4 自带一个 CLI 安装器：

bash
docker compose up -d db docker compose run --rm app php install/cli_install.php install \ --username admin --password 'admin123' --email [email protected] \ --http_server 'http://localhost:8095/' --language en-gb \ --db_driver mysqli --db_hostname db --db_username opencart \ --db_password opencart --db_database opencart --db_port 3306 --db_prefix oc_ # OpenCart recommends removing the installer afterwards: rm -rf opencart-oxphp/src/install docker compose up -d app

OxPHP 注意事项

Note
  • 传统模式提供两个前端控制器。 index.php（店铺前台）和 admin/index.php（管理后台）都是物理入口点；传统模式将它们各自作为真实文件运行。而框架模式会把所有请求汇聚到单个 index.php，从而破坏管理后台。
  • PHP_DENY_PATHS 保护内部文件。 由于 webroot 位于项目根目录，system/ 和 install/ 就处于 DOCUMENT_ROOT 之内。PHP_DENY_PATHS=/system/**,/install/** 阻止直接通过 HTTP 执行这些脚本——匹配发生在磁盘 I/O 之前，因此不存在文件存在性探测的旁路。CLI 安装器通过 shell 运行，不受影响。参见 PHP 执行拒绝列表。
  • 点文件已经是安全的。 .env 之类以及包含点段的路径通过点路径拦截返回 404；无需额外规则。
  • SEO URL 默认关闭。 默认的 OpenCart 使用 index.php?route=… 查询路由，传统模式可直接处理，无需任何重写规则。

验证

bash
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8095/ # 200 storefront curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:8095/index.php?route=common/home" # 200 curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8095/admin/ # 200 admin login curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8095/system/startup.php # 404 (denied) curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9096/health # 200

另请参阅

发现错误？报告问题 →