2026 OpenClaw 클러스터 실전
clustervps 롤링 업그레이드 2026.4.x · peer · 카나리 롤백

고정 슬러그: 2026-openclaw-clustervps-rolling-upgrade-peer-deps-canary.html. 관련 글: 멀티 AZ 게이트웨이·웹훅, 카나리·스킬 슬라이스, 테넌트 Doctor·실패 요약, rsync 매트릭스. 목록은 블로그 홈에서 확인하세요.

롤링은 「한 노드씩·한 semver 단계씩」이 기본입니다. 카나리가 안정되기 전 동료로 퍼지면 ERESOLVE·준비 라우트 불일치가 노드 수만큼 복제됩니다. 아래는 최소 뼈대이니 lockfile·미러 정책에 맞게 패키지명·순서만 바꿉니다.

단계 체크리스트(롤백 포인트 포함)

순서대로 실행합니다. 어느 롤백 포인트라도 발동하면 롤링을 멈추고 먼저 복구한 뒤 원인 분석을 합니다.

• 0 동결: openclaw.lock, LB 가중치, 스킬 symlink 기록. 롤백 R0 — 백업 없이 패키지를 건드리지 않음.
• 1 카나리 노드: 한 대만 먼저 npm -g 시퀀스(다음 절) 적용. 매 단계 후 openclaw doctor --json. R1 — 단일 노드 doctor 비녹색이면 스냅샷 semver로 npm -g 되돌리고 브로드캐스트.
• 2 병합 프로브: 카나리에서 병합 readyz(Doctor + 큐 + webhook digest) 실행. R2 — 병합 JSON에 하드 실패가 있으면 중단.
• 3 트래픽: 신규 세션 약 5%를 카나리 게이트웨이로, 최소 두 프로브 주기 유지. 확대 전 병합 프로브 재실행. R3 — SLO 악화 시 가중치 스냅샷 복구.
• 4 동료 롤링: 나머지 노드에 1→2 반복. 「검증된 게이트웨이보다 앞서지 않는」 worker 제약은 멀티 AZ 글과 동일하게 유지.
• 5 마무리: 감사 한 줄(actor, 티켓, semver, probe_sha256).

npm -g 업그레이드 순서(패턴)

2026.4.x는 전역 설치 순서로 반쯤 업 상태를 줄이는 데 초점을 둡니다. 릴리스 노트 순서대로 CLI·코어 후 공식 플러그인. 내부 미러면 카나리에서 npm view·캐시를 먼저 확인 후 확산. 층마다 openclaw doctor --json·npm ls -g --depth=0, peer 경고는 티켓 캡처.

# 예시: 순서·패키지명은 팀 lockfile / 릴리스 노트 기준
npm install -g openclaw@2026.4.x
# 문서에 나온 순서대로 @openclaw/* 플러그인 설치, 예:
# npm install -g @openclaw/plugin-foo@^2026.4.0
openclaw doctor --json | tee /tmp/doctor-after-core.json
npm ls -g --depth=0 2>&1 | tee /tmp/npm-global.txt

플러그인 peer와 2026.4.x 변경에 대한 중립적 설명

최근 메인라인에서는 플러그인 peer 메타데이터와 문서 링크를 다수 수정했고, 이미지·아티팩트 생성 파이프라인에서 전역 패키지 해석과 맞닿은 단계도 조정된 바 있습니다. 세부는 CHANGELOG·릴리스 노트를 따르세요. 본문은 장단을 평가하지 않습니다. 롤링 전 「peer 범위·권장 설치 순서·브레이킹 체인지」를 노트와 대조하고, 사설 registry면 CLI에 맞는 플러그인 목록이 레이어에 남는지 확인합니다. ERESOLVE는 노트 권장 구간으로 맞추고 --force는 피합니다.

노드별 Doctor와 헬스 프로브 병합

트래픽을 받는 모든 Mac은 업그레이드 후 openclaw doctor를 돌립니다. 외부 LB에는 병합된 준비 라우트 하나만 노출하는 구성을 권장합니다. 게이트웨이가 로컬에서 조립합니다: 본기 doctor 요약, 큐 수위, webhook digest(실패 면 집계). 테넌트 분할 글의 「단일 준비 JSON」과 같은 선입니다. digest는 필드일 뿐 유일한 승격 근거가 되면 안 됩니다.

#!/usr/bin/env bash
set -euo pipefail
TENANT="${TENANT:-acme}"
/usr/local/bin/openclaw doctor --tenant "${TENANT}" --json >/tmp/doctor.json
/usr/bin/curl -fsS --max-time 3 "http://127.0.0.1:8088/readyz" -o /tmp/readyz.json
/usr/bin/curl -fsS --max-time 3 "http://127.0.0.1:9099/v1/webhook-digest" -o /tmp/digest.json
/usr/bin/python3 - <<'PY'
import hashlib, json, pathlib
parts = [pathlib.Path(p).read_bytes() for p in ("/tmp/doctor.json","/tmp/readyz.json","/tmp/digest.json")]
print(json.dumps({"merged_sha256": hashlib.sha256(b"".join(parts)).hexdigest()}))
PY

semver·lockfile와 디스크 해석이 어긋나면 하드 실패로 처리합니다. 허용 가능한 저하만 degraded로 명시해 LB가 잘못 녹색으로 보지 않게 합니다.

실패 브로드캐스트와 카나리 롤백의 호흡

doctor·병합 프로브 실패나 큐 백프레셔 초과 시 Notifier로 중복 제거 요약(노드 id, semver, 오류 코드, digest 발췌)을 보냅니다. LB 롤백과 병행: 트래픽 철수(R3) → 패키지 되돌리기(R1/R2) → 동료 롤백은 원인 티켓까지 중단. 웹훅·토큰은 게이트웨이 글.

자주 묻는 질문

카나리 없이 클러스터 전체에 한 번에 npm 할 수 있나요? 비권장입니다. peer 해석·이미지 레이어 문제는 첫 대에서 드러나는 경우가 많고, 전량 업그레이드는 롤백 비용을 노드 수만큼 곱합니다.

이미지 생성 기능 업데이트가 롤링에 영향을 주나요? CI가 내놓는 글로벌 패키지 목록과 런타임 기대가 어긋나면 doctor 또는 플러그인 로딩 단계에서 드러납니다. promote 전에 프로덕션과 같은 prefix로 드라이런 설치를 한 번 돌리세요.

최소 검증 대수? 카나리 1 + 게이트웨이 2가 최소 정직 토폴로지입니다.