Проверки работоспособности

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 узлам за его пределами, тогда как пробы работоспособности остаются доступными); loopback не подразумевается неявно, поэтому укажите 127.0.0.1/32, чтобы сохранить доступ с localhost. При запуске сервер предупреждает, если слушатель открыт наружу без заданного списка разрешений.

Пробы Kubernetes

OxPHP предоставляет отдельные эндпоинты для каждого типа проб Kubernetes. Каждый эндпоинт также доступен под коротким псевдонимом (/healthz, /readyz, /startupz).

Эндпоинт Псевдоним Проверки 200 503
/health/liveness /healthz Нет (жив, если отвечает) Всегда Никогда
/health/readiness /readyz Не завершается, исполнитель исправен, нет сбойных плагинов Готов Не готов
/health/startup /startupz Исполнитель исправен Готов Не готов

Liveness всегда возвращает 200 OK. Если процесс способен ответить на HTTP-запрос, он считается живым. Проверки исполнителя или плагинов не выполняются — это не даёт Kubernetes перезапускать поды из-за временных проблем с пулом воркеров.

Readiness возвращает 503 Service Unavailable, когда:

  • Сервер завершает работу (идёт корректное завершение работы)
  • Пул PHP-воркеров неисправен
  • Любой плагин сообщает о сбое

Во время корректного завершения работы readiness сразу возвращает 503, из-за чего Kubernetes удаляет под из эндпоинтов Service ещё до завершения слива соединений.

Startup возвращает 503 Service Unavailable, пока исполнитель ещё не готов. Используйте эту пробу, чтобы предотвратить преждевременный перезапуск пода по liveness-пробе при медленной инициализации.

Все эндпоинты проб возвращают 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
Проба Эффект при сбое
Startup Kubernetes ждёт — не убивает под во время инициализации
Liveness Kubernetes перезапускает под
Readiness Kubernetes удаляет под из эндпоинтов 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 после того, как заданное число повторных попыток завершится неудачей, что может запустить политики перезапуска или удаление из балансировщика нагрузки.

См. также

Нашли ошибку? Сообщите →