2026년 OpenClaw 게이트웨이 그레이스풀 셧다운: readiness 프로브, 기한 있는 드레인, 도구 완료, 로드밸런서 정렬, LaunchAgent SIGTERM 창, 클라우드 Mac mini에서의 macOS 리허설

블루/그린 배포와 주간 의존성 업데이트가 지루한 운영으로 남으려면 OpenClaw 게이트웨이가 사라질 때 진행 중인 도구 호출을 반쯤 자르지 않아야 합니다. 2026년 운영자는 클라우드 네이티브와 같은 그레이스풀 셧다운 경로를 전제합니다. readiness를 내려 로드밸런서가 새 트래픽을 붙이지 않게 하고, accept 루프를 멈추며, HTTP와 스트리밍 도구 호출을 명시적 기한 안에서 드레인한 뒤, 메트릭과 로그를 비운 후 종료 코드 0으로 나갑니다. 이 글에서는 readiness와 liveness의 의미, 긴 CRM 내보내기를 굶기지 않는 드레인 창, 서킷 브레이커·데드레터 큐와의 조합, 읽기 타임아웃·행 진단, 헬스 모니터링이 드레인 상태를 합성 프로브에 어떻게 드러내야 하는지를 정리합니다.

가격 기준으로, MacHTML 전용 Mac mini를 하루 약 16.9달러에 빌려 SIGTERM 연출을 리허설하는 비용은, launchd가 30초 안팎에서 SIGKILL로 올라가는 현장에서 도구 호출이 DB 락을 쥔 채 쓰러지는 배포 사고보다 싸다는 비교가 됩니다.

시그널, launchd ExitTimeout, OS 기본값

macOS에서 launchctl bootout이나 의존성 갱신으로 작업이 다시 뜰 때 launchd는 게이트웨이에 SIGTERM을 보냅니다. ExitTimeout을 올리지 않으면 일정 유예 뒤 SIGKILL로 갑니다. 많은 템플릿이 30초 전후를 말하지만 launchctl print gui/$UID/당신의.plist로 확인하십시오. Linux 컨테이너는 다른 기본을 가지며, 섞인 함대에서 리허설 없이 초만 맞추면 깨집니다.

게이트웨이는 시그널 핸들러에서 원자적 shutting_down 플래그를 세우고 유휴 keep-alive를 닫으며 스레드 안전하게 드레인 타이머를 돌려야 합니다. 핸들러 안에서 무거운 일은 피하고 메인 루프로 이벤트를 넘겨 TLS 상태를 지킵니다.

외부 예산(밸런서가 믿는 유예)과 내부 예산(워커가 실제로 필요한 시간)을 문서화하십시오. 내부가 외부를 넘으면 밸런서 등록 해제 지연을 늘리거나 도구 타임아웃을 먼저 줄입니다.

드레인 중 readiness와 liveness

liveness는 아직 진행 가능한지, readiness는 새 작업을 받아도 되는지입니다. 편의상 뒤바꾸면 연쇄 장애가 납니다. readiness를 내리지 않고 503만 주면 프런트가 계속 새 세션을 붙이고 재시도가 폭증합니다.

/readyz에서 503과 JSON {"draining":true,"in_flight":14,"deadline_ms":12000}을 내보내 합성 모니터가 드레인 곡선을 그리게 하십시오. 게이트웨이 헬스 모니터링 가이드와 짝을 이룹니다.

accept 중단과 RST 폭풍 회피

리스닝 소켓을 즉시 닫으면 진행 중인 TLS 핸드셰이크가 RST로 갈 수 있습니다. 애플리케이션 게이트로 503과 Retry-After: 5를 주면서 기존 연결의 현재 요청은 끝내는 편이 안전합니다. HTTP/2에서는 GOAWAY 순서가 중요합니다. 최대 스트림 0을 알린 뒤 열린 스트림을 기다리고 닫습니다.

웹소켓 도구 브리지는 소켓을 닫기 전 애플리케이션 server_shutdown과 클라이언트 백오프 힌트를 보내 다음 파드로 떼 몰림을 막습니다.

워커 풀, 도구별 기한, 스트리밍

드레인 예산을 쪼개면 표준 REST 도구에 벽시계 60%, 롱폴·모델 스트림에 30%, 메트릭 스크랩 같은 관리 훅에 10%를 두는 식이 설명하기 쉽습니다. 단일 테넌트가 워커를 독점하면 드레인 중에도 테넌트별 동시 실행 상한을 유지해 다른 테넌트의 완료 기회를 남깁니다.

모델 스트리밍 중에는 새 턴은 막되 현재 SSE 청크 펌프는 바이트 완료나 하한(예: 20초) 중 먼저 오는 쪽까지 허용합니다. 중간 절단은 구조화 로그 SHUTDOWN_TRUNCATED_STREAM로 남깁니다.

로드밸런서와 Retry-After

readiness를 내린 뒤 밸런서 헬스 간격 최소 한 번—흔히 5초—은 기다렸다 accept를 멈춥니다. 다중 리전에서는 DNS TTL이 낡은 대상을 가리키므로 여유를 둡니다. Retry-After는 클라이언트 SDK 멱등 스토리와 맞춥니다.

레이어4 패스스루에서는 기존 TCP의 HTTP/1.1 keep-alive가 새 요청을 실을 수 있습니다. 세대 카운터로 셧다운 시작 후 옛 소켓의 신규 요청은 Connection: close로 거절하되 그 소켓의 활성 한 건은 끝냅니다.

메트릭, 로그, 사후 감사

게이지 gateway_in_flight_total과 카운터 gateway_shutdown_events_total{result}(clean·deadline_exceeded·forced_kill)를 냅니다. 히스토그램 gateway_shutdown_duration_seconds는 readiness 반전부터 프로세스 종료까지 재며 45초 예산이 주간으로 현실적인지 SLO 대시보드에서 봅니다.

구조화 로그에는 macOS에 설정한 유예 초, 관측 in_flight 피크, 가장 느린 도구 이름을 넣어 배포 티켓과 대조하기 쉽게 합니다. 7일간 clean이 99% 아래로 떨어지고 배포 빈도가 오르면 도구 타임아웃이 느슨해졌거나 벤더 SDK가 컨텍스트 취소를 무시하는지 의심합니다.

롤링 재시작과 카나리

롤링은 셧다운 빈도를 올립니다. 매시간 인스턴스가 다시 뜨고 카나리 가중 이동까지 공격적이면 정상 상태에 못 갑니다. 동시에 드레인 중인 인스턴스는 함대 20%를 넘기지 않도록 상한을 두고 합성 트래픽으로 여유를 본 뒤 완화합니다.

드레인 중 5분 5xx가 1%를 넘으면 직전 양호 가중 테이블으로 되돌리고 담당자를 호출합니다.

서킷 브레이커 조율

드레인 중에는 프로브를 늘리고 싶지 않습니다. 서킷 브레이커 half-open 간격을 늘리거나 이미 불건강한 의존성은 브레이커를 연 채로 두어 소중한 초를 헛upstream 호출에 쓰지 않게 합니다.

DLQ 생산자와 멱등 인큐

셧다운이 실패 핸들러의 DLQ 인큐와 경주하면 인큐는 멱등이거나 중복 제거가 필요합니다. TCP 재시도 뒤 이중 인큐가 운영을 오염시킵니다. 데드레터 큐 설계의 봉투 필드를 대조해 프로세스 종료 후에도 추적 가능하게 합니다.

행렬: 강제 종료 대 그레이스풀 드레인

시나리오	강제 SIGKILL	그레이스풀 드레인
진행 중 DB 트랜잭션	부분 커밋 위험	대기 또는 명시 롤백 훅
스트리밍 토큰	문장 중간 절단	유한 대기 + 절단 플래그
배포 지연	짧음	전형적으로 +5~45초
운영 신뢰	낮음	메트릭으로 증명되면 높음

번호 매긴 롤아웃 체크리스트

1. /readyz 드레인 JSON을 대시보드에 올린다.
2. ExitTimeout을 내부 드레인 수학 + 10초 안전 여유에 맞춘다.
3. SIGTERM 통합 테스트에서 합성 도구 호출을 50건 이상 붙인 상태를 재현한다.
4. h2load로 HTTP/2 GOAWAY 순서를 검증한다.
5. 사후 보고서 템플릿에 드레인 타임라인 CSV 첨부 칸을 둔다.

자주 묻는 질문

systemd KillMode가 OpenClaw에 영향을 주는가

혼합 함대에서는 mixed와 control-group이 자식 프로세스 시그널 대상을 바꾼다는 점을 문서화하십시오.

드레인을 무한히 늘려도 되는가

아니오. 무한 드레인은 멈춘 워커를 가립니다. 행 진단으로 느린 호출을 분류하십시오.

Windows 개발 노트북이 중요한가

Windows 게이트웨이를 출하한다면 의미가 있지만, 파트너 대부분이 MacBook을 쓰는 현장에서는 macOS 리허설 가치가 여전히 큽니다.

그레이스풀 셧다운은 신뢰성 문화가 측정 가능한 초와 만나는 지점입니다. MacHTML에서 빌린 Mac mini(대략 하루 16.9달러)는 네이티브 macOS 시그널 전달, Apple Silicon soak 여유, SSH/VNC로 launchd 타임라인을 보며 드레인 예산을 다듬기에 적합한 기반입니다.