健康检查

OxPHP 在一个独立端口上运行内部 HTTP 服务器，用于健康监控、指标采集和配置检查。它与应用流量相互隔离，因此监控永远不会与用户请求争抢资源。

配置

设置 INTERNAL_ADDR 以启用内部服务器：

bash

INTERNAL_ADDR=127.0.0.1:9090

当未设置 INTERNAL_ADDR 时，内部服务器不会启动，也没有任何健康检查端点可用。

Note

仅指定端口的 INTERNAL_ADDR（:9090 或 9090）会绑定到 127.0.0.1；如需将内部服务器暴露到宿主机之外，请显式使用 0.0.0.0:9090。当它可以从宿主机之外访问时，请用 INTERNAL_ALLOW_IPS（一个 CIDR/IP 允许列表）来限制访问——/metrics、/config 以及插件路径会对该列表之外的对端返回 403，而健康检查探针仍然可以访问；环回地址并不会隐式包含在内，因此需要列出 127.0.0.1/32 以保留本地访问。如果监听器已暴露却未设置允许列表，服务器会在启动时发出警告。

Kubernetes 探针

OxPHP 为每种 Kubernetes 探针类型都提供了专用端点。每个端点还提供一个简短别名（/healthz、/readyz、/startupz）。

端点	别名	检查内容	200	503
`/health/liveness`	`/healthz`	无（能响应即视为存活）	始终	永不
`/health/readiness`	`/readyz`	未在关闭、执行器健康、无失败插件	就绪	未就绪
`/health/startup`	`/startupz`	执行器健康	就绪	未就绪

存活（Liveness） 始终返回 200 OK。只要进程能够响应 HTTP 请求，它就是存活的。不执行任何执行器或插件检查——这可以防止 Kubernetes 因工作进程池的瞬时问题而重启 pod。

就绪（Readiness） 在以下情况返回 503 Service Unavailable：

服务器正在关闭（优雅关闭进行中）
PHP 工作进程池不健康
任何插件报告了失败

在优雅关闭期间，就绪检查会立即返回 503，从而使 Kubernetes 在排空完成之前就把该 pod 从 Service 端点中移除。

启动（Startup） 在执行器尚未就绪时返回 503 Service Unavailable。使用此探针可以防止在缓慢初始化期间过早触发存活检查而杀掉进程。

所有探针端点都返回 Content-Type: text/plain，其响应体为探针名称（例如 readiness）。Kubernetes 只检查 HTTP 状态码。

bash

# Quick check
curl -s -o /dev/null -w '%{http_code}' http://localhost:9090/health/readiness

GET /health

以 JSON 形式返回完整的服务器健康状态。请将其用于仪表盘和监控系统，而不是用于 Kubernetes 探针。

bash

curl http://localhost:9090/health

健康响应（200 OK）：

json

{
  "status": "ok",
  "uptime_secs": 3612,
  "total_requests": 48203,
  "active_connections": 7,
  "executor_healthy": true,
  "plugins": {}
}

降级响应（503 Service Unavailable）：

json

{
  "status": "degraded",
  "uptime_secs": 3612,
  "total_requests": 48203,
  "active_connections": 7,
  "executor_healthy": false,
  "plugins": {}
}

字段	类型	说明
`status`	string	所有子系统健康时为 `"ok"`，否则为 `"degraded"`
`uptime_secs`	integer	服务器启动以来的秒数
`total_requests`	integer	主端口上处理的 HTTP 请求总数
`active_connections`	integer	主端口上当前打开的连接数
`executor_healthy`	boolean	PHP 工作进程池是否正在接受请求
`plugins`	`object<string, string>`	各插件的健康状况：键为插件名称，值为 `"ok"`、`"degraded"` 或 `"failed"`。当没有插件报告健康状况时为空的 `{}`。`"failed"` 插件会使 HTTP 状态切换为 503；`"degraded"` 会出现在此处，但状态仍保持为 200。

GET /metrics

以文本展示格式返回与 Prometheus 兼容的指标。完整的指标参考请见 Prometheus 指标。

bash

curl http://localhost:9090/metrics

GET /config

以 JSON 形式返回当前生效的服务器配置。出于安全考虑，TLS 证书与密钥路径、internal_addr 以及 error_pages_dir 会从响应中被清除。

bash

curl -s http://localhost:9090/config | jq .

json

{
  "listen_addr": "0.0.0.0:80",
  "document_root": "/var/www/html/public",
  "entry_file": "/var/www/html/public/index.php",
  "log_level": "info",
  "executor_type": "sapi",
  "php_workers": "8",
  "tokio_workers": 4,
  "queue_capacity": 1024,
  "max_connections": 10000,
  "drain_timeout_seconds": 30,
  "header_timeout_seconds": 5,
  "rate_limit": 100,
  "rate_window_seconds": 60,
  "tls_enabled": true,
  "compression_level": 4,
  "access_log": "all",
  "max_query_body": 524288,
  "worker_mode_enabled": false,
  "worker_max_memory_mib": 0,
  "static_max_age": 2592000,
  "static_revalidate": false,
  "async_workers": 0,
  "async_queue_capacity": 0,
  "async_max_fibers": 256,
  "async_in_flight_cap": 0,
  "trace_context": false,
  "superglobals_enabled": true,
  "trusted_proxies": false,
  "plugins": {}
}

Note

TLS 证书与密钥路径永远不会被输出（tls_enabled 表示 TLS 是否处于启用状态），而 internal_addr 和 error_pages_dir 会从对外提供的响应中被清除。

Kubernetes 集成

为每种探针类型使用专用的探针端点：

yaml

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: oxphp
          image: ghcr.io/oxphp/oxphp:latest
          env:
            - name: INTERNAL_ADDR
              value: "0.0.0.0:9090"
          ports:
            - containerPort: 8080
            - containerPort: 9090
          startupProbe:
            httpGet:
              path: /health/startup
              port: 9090
            initialDelaySeconds: 1
            periodSeconds: 2
            failureThreshold: 15
          livenessProbe:
            httpGet:
              path: /health/liveness
              port: 9090
            periodSeconds: 10
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /health/readiness
              port: 9090
            periodSeconds: 5
            failureThreshold: 2

探针	失败时的影响
启动	Kubernetes 等待——在初始化期间不会杀掉 pod
存活	Kubernetes 重启 pod
就绪	Kubernetes 将 pod 从 Service 端点中移除（不重启）

简短别名（/healthz、/readyz、/startupz）与完整路径完全等价，可以用来替代它们。

Docker Compose 健康检查

compose.yaml

services:
  oxphp:
    image: ghcr.io/oxphp/oxphp:latest
    ports:
      - "8080:80"
    environment:
      INTERNAL_ADDR: "127.0.0.1:9090"
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:9090/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 5s

在配置的重试次数全部失败后，Docker 会将容器标记为 unhealthy，这可能触发重启策略或将其从负载均衡器中移除。

另见

Prometheus 指标 —— 所有已暴露指标的完整参考
优雅关闭 —— 健康检查探针如何与关闭排空相互配合
配置参考 —— 所有环境变量，包括 INTERNAL_ADDR