OxPHP 文档

OxPHP 是一款高性能 PHP 应用服务器，用单个二进制文件取代 nginx + PHP-FPM——内置 TLS、Brotli 压缩、限流、健康检查、Prometheus 指标、SSE 流式传输以及常驻工作进程模式。

为什么选择 OxPHP

生产环境中一个典型的 PHP 应用往往由多个容器组成：nginx、PHP-FPM，有时还有独立的 TLS 代理和指标导出器。配置分散在各处，要让一切协同工作，就得让 socket 设置、超时和路径保持同步。OxPHP 用一个容器取代整个技术栈。容器内只有一个进程，负责接受 HTTP 连接、执行 PHP 并提供静态文件。

服务器开箱即用，默认配置十分合理。精细调优通过环境变量完成：TLS 用两个变量（TLS_CERT、TLS_KEY）即可启用，限流只需一个变量（RATE_LIMIT），而 Brotli 压缩默认开启。无需编辑 nginx 配置，也不用构建独立的模块。

在专用的内部端口上，提供了健康检查（/health）、Prometheus 指标（/metrics）以及配置快照（/config）。这足以支撑 Kubernetes 的 liveness/readiness 探针，并接入 Grafana，无需额外的 sidecar 容器。

日志是结构化的 JSON：每一行都包含方法、路径、状态、响应时间和请求 ID。它们易于在 Loki、Elasticsearch 或任何其他工具中解析，无需额外的 grok 模式。

想试试工作进程模式吗？在这种模式下，PHP 进程不会在每次请求时重建，只需设置 WORKER_MODE_ENABLED=true 和 ENTRY_FILE=worker.php。框架只初始化一次，随后可处理成千上万次请求而无需重新加载。想切回经典模式，删除该变量即可。

OxPHP 还包含一些通常需要独立工具或第三方库才能实现的能力：

快速上手

  • 快速开始 — 在 5 分钟内构建并运行你的第一个 OxPHP 应用
  • 安装 — 系统要求与安装选项
  • Docker 指南 — Dockerfile、Compose 配置、卷以及部署模式
  • 命令行界面 — oxphp 命令语法：serve、run 单个 PHP 脚本、config 以及 --user 权限降级

运维

  • 配置参考 — 完整的环境变量列表，附默认值和说明
  • 健康检查 — 内部服务器的 /health、/metrics 和 /config 端点
  • 指标 — Prometheus 兼容的指标参考
  • 优雅关闭 — 连接排空行为、超时和关闭顺序

特性

  • 路由 — 三种路由模式：传统文件映射、框架前端控制器和 SPA 回退。工作进程模式是一个正交的执行模型开关，可叠加在任意路由模式之上
  • 静态文件 — 文件缓存、MIME 探测、ETag/Last-Modified 头部以及流式传输
  • 工作进程模式 — 常驻 PHP 进程，请求之间自动软重置
  • 纤程多路复用 — 通过协作式多任务，让每个工作进程线程处理数百个并发请求
  • 压缩 — 针对文本类响应的 Brotli 压缩
  • TLS — 内置 TLS 终结，支持证书和密钥配置
  • 限流 — 按 IP 限流，窗口和限额均可配置
  • 超时 — 头部读取超时和请求超时
  • 访问日志 — 结构化 JSON 访问日志，包含请求 ID、方法、路径、状态和耗时
  • 请求 ID — 自动生成并透传 X-Request-ID
  • 错误页面 — 为任意 HTTP 状态码提供自定义 HTML 错误页面
  • SSE — 从 PHP 实时推送 Server-Sent Events
  • 提前响应 — 立即发送响应并继续后台处理
  • 异步 promise — 在后台线程运行 PHP 闭包并等待结果
  • 装饰器 — 用 PHP 8 属性拦截函数和方法调用
  • 分布式追踪与 APM — W3C Trace Context、OpenTelemetry、自动埋点以及 PHP 追踪 SDK
  • 内部服务器 — 专用端口，用于健康检查、Prometheus 指标和实时配置

安全

  • 点路径拦截 — 自动拦截隐藏文件和目录（.env、.git/、.htaccess）
  • 可信代理 — 从 Forwarded（RFC 7239）和 X-Forwarded-* 头部提取真实客户端 IP，基于 CIDR 建立信任
  • PHP 执行拒绝列表 — 在可写的公共路径（如 /uploads/**，或特定的遗留脚本）阻止 .php 执行，以挫败针对遗留应用的上传 shell 攻击
  • 符号链接允许路径 — 为 DOCUMENT_ROOT 之外的符号链接目标提供可选的允许列表；在不削弱默认符号链接逃逸保护的前提下，支持 Laravel 风格的 storage:link 和共享资源卷

PHP

  • HTTP 请求 API — 通过 oxphp_http_request() 进行面向对象的请求访问：查询参数、已解析的请求体、头部、cookie、文件上传等
  • 函数 — OxPHP 提供的内置 PHP 函数（oxphp_worker()、oxphp_request_id()、oxphp_server_info() 等）
  • 超全局变量 — $_SERVER、$_GET、$_POST、$_COOKIE、$_FILES 和 php://input 是如何填充的
  • OPcache 和 JIT — OPcache 配置和 JIT 编译设置

共享状态

进程级并发原语，让工作进程无需 Redis、Memcached 或 APCu 即可协调可变状态——一切都在进程内，因此单次操作的开销是微秒级，而非网络往返。

  • 概述 — 注册表模型、句柄生命周期，以及何时应当使用共享状态
  • 注册表 — 进程级注册表、条目生命周期和内省
  • Counter — 原子 int64 累加器（get、set、add、compareAndSet）
  • Atomic — 原子 int64，可显式控制内存排序
  • Flag — 用于一次性状态转换的原子布尔值
  • Once — 只运行一次的容器，工厂函数具备可重入安全性
  • Mutex — 覆盖存储值的中毒互斥锁，带死锁检测
  • Channel — 有界、感知纤程的 MPMC 队列
  • Map — 以字符串为键的并发存储，支持批量访问
  • Pool — 有界对象池，具备每线程亲和性
  • 命名约定 — 整个 Shared\* 家族的方法命名速查表
  • 可观测性 — Prometheus 计数器和 JSON 内省端点
  • 迁移到外部存储 — 何时以及如何迁移到 Redis 或 APCu

架构

  • 架构概述 — OxPHP 的工作原理：异步 HTTP 处理、PHP 工作进程池、请求流程以及安全保证

示例

在 OxPHP 上运行主流 PHP 应用的端到端方案——每个都是完整的 Docker Compose 项目，包含 Dockerfile、docker-compose.yml、安装步骤，以及原版（nginx + PHP-FPM）文档未涵盖的 OxPHP 专属说明。

发现错误？报告问题 →