PHP Serverless Runtime Docker镜像文档

一、镜像概述

PHP Serverless Runtime 是一个轻量级 Docker 镜像，专为在无服务器（Serverless）环境中运行 PHP 应用设计。该镜像提供了 PHP 运行时环境、Serverless 事件处理逻辑及基础依赖，支持主流无服务器平台（如 AWS Lambda、Azure Functions、Google Cloud Functions），可简化 PHP 应用的 Serverless 部署流程，降低冷启动时间，提升资源利用率。

二、核心功能与特性

2.1 核心功能

• 内置 PHP 运行时环境，支持 PHP 7.4+ 版本
• 集成 Serverless 事件驱动模型，适配 HTTP 请求、消息队列等触发场景
• 提供标准输入/输出（STDIN/STDOUT）通信接口，兼容无服务器平台调用协议
• 内置日志收集与格式化工具，支持结构化日志输出

2.2 关键特性

• 轻量级设计：基于 Alpine Linux，镜像体积小于 100MB，减少部署耗时
• 多平台支持：兼容 x86_64/arm64 架构，适配云厂商Serverless容器服务
• 冷启动优化：预加载常用 PHP 扩展，降低首次请求响应延迟（平均冷启动 < 300ms）
• 配置灵活：支持通过环境变量或自定义 PHP 配置文件调整运行参数
• 扩展兼容性：内置 curl、json、mbstring 等核心扩展，支持动态安装额外扩展

三、使用场景与适用范围

3.1 典型使用场景

• 无服务器 API 开发：构建基于 PHP 的 RESTful API，通过 API Gateway 触发执行
• 事件驱动型应用：响应云服务事件（如对象存储文件上传、消息队列消息到达）
• 定时任务处理：通过 CloudWatch Events、Cron 等触发定时 PHP 脚本执行
• 微服务后端：作为微服务架构中的轻量级 PHP 运行节点，处理特定业务逻辑
• 低成本原型验证：无需管理服务器，快速部署 PHP 应用原型并验证功能

3.2 适用范围

• PHP 版本需求：7.4 ~ 8.3
• 应用规模：轻量级业务逻辑（单函数代码量 < 500KB 最佳）
• 并发需求：中小流量场景（日均请求 < 10万次）
• 平台兼容性：AWS Lambda、Azure Functions、阿里云函数计算、腾讯云 SCF

四、使用方法与配置说明

4.1 镜像获取

通过 Docker Hub 拉取最新版本镜像：

bash
docker pull php-serverless-runtime:latest

如需指定 PHP 版本（如 8.2），可使用标签：

bash
docker pull php-serverless-runtime:8.2

4.2 基本运行示例

4.2.1 本地测试运行

将 PHP 代码挂载至容器并执行（模拟 Serverless 函数调用）：

bash
# 假设本地代码目录为 ./app，入口文件为 index.php
docker run --rm \
  -v $(pwd)/app:/var/task \  # 挂载代码目录至运行时工作目录
  -e HANDLER=index.handler \  # 指定处理函数（文件.函数名）
  php-serverless-runtime:latest

4.2.2 模拟 HTTP 请求触发

启动容器并暴露 HTTP 端口，模拟 API Gateway 触发：

bash
docker run -d \
  -p 8080:8080 \  # 映射容器 8080 端口至本地
  -v $(pwd)/app:/var/task \
  -e HANDLER=api.handleRequest \
  -e RUNTIME_MODE=http \  # 启用 HTTP 模式
  --name php-serverless-demo \
  php-serverless-runtime:latest

发送测试请求：

bash
curl http://localhost:8080 -d '{"name": "Serverless"}'

4.3 自定义配置

4.3.1 PHP 配置调整

通过挂载自定义 php.ini 文件覆盖默认配置：

bash
docker run --rm \
  -v $(pwd)/app:/var/task \
  -v $(pwd)/custom-php.ini:/usr/local/etc/php/conf.d/custom.ini \  # 挂载自定义 PHP 配置
  php-serverless-runtime:latest

4.3.2 环境变量配置

支持通过环境变量调整运行时参数，常用变量说明如下：

4.4 与 Serverless 框架集成

在 serverless.yml 中配置使用该镜像（以 AWS Lambda 为例）：

yaml
service: php-serverless-demo

provider:
  name: aws
  runtime: docker
  ecr:
    images:
      phpRuntime:
        path: .  # 指向包含 Dockerfile 的目录，或直接引用镜像

functions:
  api:
    image:
      name: phpRuntime
    events:
      - httpApi:
          path: /
          method: post
    environment:
      HANDLER: api.handleRequest
      LOG_LEVEL: debug

五、Docker Compose 部署示例

适用于本地开发与多容器联动场景（如集成数据库）：

yaml
# docker-compose.yml
version: '3.8'

services:
  php-serverless:
    image: php-serverless-runtime:8.2
    container_name: php-serverless-dev
    restart: unless-stopped
    volumes:
      - ./app:/var/task:ro  # 只读挂载代码目录
      - ./logs:/var/log/php  # 挂载日志目录
    ports:
      - "8080:8080"  # HTTP 模式端口
    environment:
      - HANDLER=index.handler
      - RUNTIME_MODE=http
      - MEMORY_LIMIT=256M
      - MAX_EXECUTION_TIME=60
      - DB_HOST=mysql
      - DB_USER=root
      - DB_PASSWORD=devpass
    depends_on:
      - mysql

  mysql:
    image: mysql:8.0
    container_name: php-serverless-mysql
    environment:
      - MYSQL_ROOT_PASSWORD=devpass
      - MYSQL_DATABASE=appdb
    ports:
      - "3306:3306"

启动服务：

bash
docker-compose up -d

六、注意事项

1. 代码目录结构：建议将 PHP 代码集中放置于 src/ 或根目录，入口文件需包含可被调用的处理函数（如 function handler($event) { ... }）。
2. 冷启动优化：避免在处理函数外执行耗时操作（如大文件加载），建议使用懒加载模式初始化资源。
3. 资源限制：根据实际业务需求调整 MEMORY_LIMIT 和 MAX_EXECUTION_TIME，避免因资源不足导致函数执行失败。
4. 日志输出：所有日志需通过 stdout/stderr 输出，以便 Serverless 平台收集（如 AWS CloudWatch Logs）。
5. 扩展安装：如需额外 PHP 扩展，可通过 CUSTOM_PHP_INI 环境变量指定，或基于该镜像构建自定义镜像（如 RUN docker-php-ext-install pdo_mysql）。