2026년 OpenClaw Gateway 내장 헬스 프로브(/health, /ready)와 부하 분산: 원격 물리 Mac 베어메탈, Docker Compose와 Kubernetes의 검수 정렬—경로 섀도잉과 오탐 NotReady 재현 Runbook(설정 조각 + FAQ)

1. 통증 포인트: 섀도잉, 드리프트, 로드밸런서의 거짓말

1. 경로 섀도잉. 정적 location /, SPA 폴백, 공격적인 try_files가 OpenClaw 업스트림에 닿기 전에 /ready에 200 OK HTML을 돌려줄 수 있습니다. 풀은 따뜻해 보이는데 게이트웨이는 프로브를 받지 못합니다.
2. 플랫폼 간 의미 드리프트. Compose는 엔진 관점 검사가 통과하면 healthy입니다. Kubernetes는 셀렉터가 겹친 다른 리비전 뒤로 트래픽이 가거나, Ingress가 의도하지 않은 카나리 백엔드로 프로브를 보낼 수 있습니다.
3. 숨은 감사·안정성 비용. liveness에 /ready를 재사용하면 의존성 장애가 Pod 재시작으로 연결됩니다. 원격 Mac 플릿에서는 스크린 공유 세션 끊김, 에이전트 상태 반쯤 기록, 시끄러운 온콜로 나타납니다.

2. 의사결정 매트릭스: 어디서 어떤 프로브를 볼 것인가

설계 리뷰용 표입니다. "누가 무엇을 반드시 관측해야 하는가?"가 전부입니다.

3. 7단계 정렬 런북

1. 호출자 열거. 클라우드 LB, nginx server_name 블록, Compose, Helm 값, 임시 모니터링에서 헬스 URL을 모읍니다. 빈 칸이 곧 사각지대입니다.
2. 섀도잉 입증. 프록시 호스트에서 curl -svH 'Host: your.api' https://127.0.0.1/ready와 루프백 게이트웨이 포트 직행 curl 본문을 diff합니다.
3. catch-all 앞에 위치 고정. location = /health·location = /ready로 업스트림 proxy_pass, proxy_buffering off;, Cache-Control no-store를 둡니다.
4. Compose: LB 타임아웃과 정렬. interval·timeout·retries를 외부 LB의 약 80% 이내로 맞춰 먼저 초록이 뜨는 낙관적 오류를 막습니다.
5. Kubernetes: 프로브 분리. liveness는 /health, readiness는 /ready, 모델 라우터 워밍업에는 startupProbe로 긴 failureThreshold를 둡니다.
6. 롤아웃 리허설. 블루/그린 또는 롤링: kubectl get endpoints와 게이트웨이 로그를 같이 보며 새 리비전의 /ready 전환 후에만 트래픽이 이동하는지 확인합니다.
7. diff 보관. 가린 nginx -T, Compose YAML, kubectl describe pod 발췌를 타임스탬프와 함께 저장합니다.

4. 설정 조각

4.1 nginx: 명시적 프로브 위치(섀도잉 방지)

location = /health { proxy_pass http://openclaw_gateway; proxy_http_version 1.1;
  proxy_set_header Host $host; proxy_buffering off; add_header Cache-Control "no-store"; }
location = /ready  { proxy_pass http://openclaw_gateway; proxy_http_version 1.1;
  proxy_set_header Host $host; proxy_buffering off; add_header Cache-Control "no-store"; }

4.2 Docker Compose: healthcheck + 의존 게이트

services:
  openclaw-gateway:
    image: your.registry/openclaw-gateway@sha256:…
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:18789/health"]
      interval: 15s
      timeout: 3s
      retries: 5
      start_period: 120s
  edge-proxy:
    depends_on:
      openclaw-gateway:
        condition: service_healthy

4.3 Kubernetes: startup + readiness + liveness

startupProbe:
  httpGet: { path: /ready, port: http }
  periodSeconds: 5
  failureThreshold: 30
readinessProbe:
  httpGet: { path: /ready, port: http }
  periodSeconds: 10
  timeoutSeconds: 3
livenessProbe:
  httpGet: { path: /health, port: http }
  periodSeconds: 20
  timeoutSeconds: 2

port: http는 containerPort 이름과 맞춥니다. Ingress에서 TLS를 끝내면 사이드카 TLS가 없는 한 컨테이너 평문 포트에 프로브를 둡니다.

5. 인용 가능한 파라미터

• 18789 — Mac 노드에서 흔한 OpenClaw 게이트웨이 HTTP 포트; openclaw.json·릴리스 노트로 항상 확인 후 LB 템플릿에 박습니다.
• 120초 start_period — 원격 Mac에서 모델 캐시·Secret 마운트 지연을 흡수하는 첫 추정치; 2주 메트릭 P95로 다듬습니다.
• readiness 타임아웃 3초 — 느린 업스트림과 kubelet 공격성 사이; 한계를 늘리기보다 failureThreshold와 로그로 근거를 쌓습니다.

6. FAQ: 재현 가능한 오탐

7. 이 복잡도를 Mac mini에서 끝내야 하는 이유

헬스 의미는 호스트가 계속 살아 있을 때만 가치가 있습니다. Apple Silicon Mac mini는 유휴 전력이 낮고(대개 수 와트대), 랙·데스크에 두기 좋은 무소음에 가깝고, curl·launchctl·Docker Desktop/Colima·SSH 같은 Unix 우선 도구를 드라이버 싸움 없이 씁니다.

Gatekeeper·SIP·FileVault는 장수 토큰을 게이트웨이 옆에 둘 때 변조 리스크를 낮춥니다. /ready가 인터넷 자동화를 여는 신호라면 이 보안 자세가 곧 운영 자세입니다.

방금 문서화한 acceptance curl을 그대로 쓸 수 있는 물리 노드를 원한다면 Mac mini M4는 2026년에도 균형 잡힌 출발점입니다. 아래 CTA에서 ZoneMac의 게이트웨이 친화 원격 Mac 옵션을 비교해 보세요.