系統端點

端點總覽

Server / all mode

Endpoint	用途	Auth
GET /healthz	liveness probe	無
GET /readyz	readiness probe	無
GET /metrics	主 HTTP process 的 Prometheus metrics	無

Worker-only mode

Endpoint	用途	Auth
GET :WORKER_METRICS_PORT/healthz	worker-only process 的 liveness	無
GET :WORKER_METRICS_PORT/metrics	worker-only process 的 Prometheus metrics	無

WORKER_METRICS_PORT 的預設值與驗證規則，請見 設定。

GET /healthz

只要 process 活著就回：

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok"}

worker-only listener 上的 GET :WORKER_METRICS_PORT/healthz 也使用同樣的 JSON 格式。

適合用於 liveness probe，不代表下游依賴已就緒。

/healthz 與 /readyz 本來就代表不同意義

/healthz 只表示 process 還活著。這裡回 200，不代表 PostgreSQL、Redis 或 buckets 一定可連。

GET /readyz

/readyz 會在 2 秒 timeout 內依序檢查：

• PostgreSQL
• Redis
• source bucket
• media bucket

curl 範例

curl -i http://localhost:3000/readyz

成功：

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok"}

失敗時會回 503 Service Unavailable，並提供結構化 JSON 摘要與各檢查項結果。Vylux 不會在第一個失敗依賴就停止，而是會回報這次請求中實際跑過的所有 readiness checks。

{
	"status": "not_ready",
	"error": "readiness checks failed",
	"checks": [
		{"name": "postgres", "status": "ok"},
		{
			"name": "redis",
			"status": "failed",
			"error": "dial tcp 127.0.0.1:6381: connect: connection refused"
		},
		{
			"name": "source bucket",
			"status": "failed",
			"error": "source storage is not configured"
		},
		{
			"name": "media bucket",
			"status": "failed",
			"error": "media storage is not configured"
		}
	]
}

失敗 body 欄位

欄位	代表什麼
status	整體 readiness 狀態；目前失敗時為 not_ready
error	這次 readiness 評估的摘要錯誤訊息
checks[].name	依賴名稱，例如 postgres、redis、source bucket、media bucket
checks[].status	ok 或 failed
checks[].error	只有該檢查失敗時才會出現

/readyz 是依賴探針

如果 /healthz 成功但 /readyz 失敗，優先把它當成基礎設施或設定問題，而不是 HTTP 路由問題。

GET /metrics

主 HTTP process 的 metrics 由 /metrics 暴露。典型 metric families 包括：

• vylux_http_requests_total
• vylux_http_request_duration_seconds
• vylux_image_cache_events_total
• vylux_image_results_total
• vylux_image_errors_total
• vylux_worker_tasks_total
• vylux_worker_task_duration_seconds
• vylux_readiness_failures_total
• vylux_queue_tasks
• vylux_queue_metrics_sync_failures_total

curl 範例

curl -s http://localhost:3000/metrics | rg '^vylux_'

worker-only metrics listener

當你以 --mode=worker 啟動 Vylux，worker 會另外開一個輕量 listener：

• port：WORKER_METRICS_PORT，預設 3001
• endpoints：/healthz、/metrics
• WORKER_METRICS_PORT=0 時停用

這讓 K8s 或其他平台可以把 worker 跟 HTTP server 分開探測與抓取 metrics。

worker-only mode 不會暴露 /readyz

當 Vylux 以 --mode=worker 運行時，請用 :WORKER_METRICS_PORT/healthz 做 liveness，較深層的 readiness 則交給外部依賴監控。

追蹤 header

除了 metrics 外，HTTP request 與 webhook/callback 也會攜帶 tracing 資訊：

• traceparent
• tracestate
• X-Trace-ID

X-Trace-ID 適合人工除錯與日誌關聯；真正的 trace context 仍以 W3C Trace Context headers 為主。