OxPHP 文档
OxPHP 是一款高性能 PHP 应用服务器，用单个进程取代 nginx + PHP-FPM——内置 TLS、压缩、限流、健康检查、Prometheus 指标、SSE 流式传输以及常驻工作进程模式。
为什么选择 OxPHP
生产环境中一个典型的 PHP 应用往往由多个容器组成：nginx、PHP-FPM，有时还有独立的 TLS 代理和指标导出器。配置分散在各处，要让一切协同工作，就得让 socket 设置、超时和路径保持同步。OxPHP 用一个容器取代整个技术栈。容器内只有一个进程，负责接受 HTTP 连接、执行 PHP 并提供静态文件。
服务器开箱即用，默认配置十分合理。精细调优通过环境变量完成：TLS 用两个变量（TLS_CERT、TLS_KEY）即可启用，限流只需一个变量（RATE_LIMIT），而压缩默认开启。无需编辑 nginx 配置，也不用构建独立的模块。
在专用的内部端口上，提供了健康检查（/health，另有为每种 Kubernetes 探针类型提供的专用端点）、Prometheus 指标（/metrics）以及配置快照（/config）。这足以支撑 Kubernetes 的 liveness/readiness 探针，并接入 Grafana，无需额外的 sidecar 容器。
日志是结构化的 JSON：每一行都包含方法、路径、状态、响应时间和请求 ID。它们易于在 Loki、Elasticsearch 或任何其他工具中解析，无需额外的 grok 模式。
想试试工作进程模式吗？在这种模式下，PHP 状态不会在每次请求时重建，只需设置 WORKER_MODE_ENABLED=true 和 ENTRY_FILE=worker.php。框架只初始化一次，随后可处理成千上万次请求而无需重新加载。想切回经典模式，删除该变量即可。
OxPHP 还包含一些通常需要独立工具或第三方库才能实现的能力：
- 静态文件服务 — 内存缓存、ETag/Last-Modified、自动 MIME 类型
- 三种路由模式 — 基于文件、框架和 SPA，由
ENTRY_FILE选择；常驻工作进程模式会以自己的路由取而代之，把所有未作为静态文件提供的请求交给一个.php入口脚本 - 提前响应 — 立即发送响应并继续后台处理
- 工作进程模式 — 常驻 PHP 工作进程，支持纤程多路复用
- SSE 流式传输 — 从 PHP 实时推送 Server-Sent Events
- 异步 promise — 后台执行 PHP 闭包而不阻塞工作进程
- 共享状态 — 进程级并发原语（Counter、Flag、Once、Mutex、Channel、Map、Pool），让工作进程无需 Redis 或 APCu 即可协调
- 装饰器 — 通过 PHP 8 属性拦截调用
- 分布式追踪与 APM — W3C Trace Context、OpenTelemetry、对数据库/HTTP/缓存/文件调用的自动埋点，以及一个 PHP 追踪 SDK
快速上手
- 快速开始 — 在 5 分钟内构建并运行你的第一个 OxPHP 应用
- 安装 — 系统要求与安装选项
- Docker 指南 — Dockerfile、Compose 配置、卷以及部署模式
- 命令行界面 —
oxphp命令语法：serve、run单个 PHP 脚本、config以及--user权限降级 - 迁移 — 从 nginx + PHP-FPM、FrankenPHP 或 RoadRunner 迁移：路由模式、配置映射、行为差异，以及无法沿用的部分
运维
- 配置参考 — 完整的环境变量列表，附默认值和说明
- 健康检查 — 内部服务器的
/health、/metrics和/config端点 - 指标 — Prometheus 兼容的指标参考
- 优雅关闭 — 连接排空行为、超时和关闭顺序
特性
- 路由 — 三种路由模式：传统文件映射、框架前端控制器和 SPA 回退。工作进程模式本身就是一种路由模式，会取代这三种模式：它需要一个
.php的ENTRY_FILE，并接收所有未作为静态文件提供的请求 - 静态文件 — 文件缓存、MIME 探测、ETag/Last-Modified 头部以及流式传输
- 工作进程模式 — 常驻 PHP 工作进程，请求之间自动软重置
- 纤程多路复用 — 通过协作式多任务，让每个工作进程线程处理数百个并发请求
- 压缩 — 针对文本类响应的 Brotli、Zstandard 和 gzip 压缩，按客户端协商
- 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
- 性能分析 — 内置的按请求性能分析器：激活触发条件、PHP SDK 与属性、导出格式以及内部路由
- 内部服务器 — 专用端口，用于健康检查、Prometheus 指标和实时配置
安全
- 点路径拦截 — 自动拦截隐藏文件和目录（
.env、.git/、.htaccess） - 可信代理 — 从
Forwarded（RFC 7239）、X-Forwarded-*以及（位于 Cloudflare 之后时）CF-Connecting-IP头部提取真实客户端 IP，基于 CIDR 建立信任 - PHP 执行拒绝列表 — 在可写的公共路径（如
/uploads/**，或特定的遗留脚本）阻止.php执行，以挫败针对遗留应用的上传 shell 攻击 - 路径拒绝规则 — 放在
DOCUMENT_ROOT中的 gitignore 风格.oxphpdeny文件，可阻止vendor/、转储文件、备份及其他文件被提供，或把对它们的请求交给应用处理 - 符号链接允许路径 — 为
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是如何填充的 - Worker 类 —
OxPHP\Server\Worker运行时句柄：工作进程自省、工作进程入口点以及每线程指标 - 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 工作进程池、请求流程以及安全保证
集成
- MCP 服务器 — 通过 Model Context Protocol 把 OxPHP 文档连接到你的编码智能体
示例
在 OxPHP 上运行主流 PHP 应用的端到端方案——每个都是完整的 Docker Compose 项目，包含 Dockerfile、docker-compose.yml、安装步骤，以及原版（nginx + PHP-FPM）文档未涵盖的 OxPHP 专属说明。