2026년에도 많은 팀이 OpenClaw 스타일 스택을Docker Compose한 파일로 묶습니다. 게이트웨이, 워커, 관측용 사이드카를 한 번에 올리기 좋지만, 사후 분석에서 살아남는 장애는 흔히재현성 붕괴입니다. 떠다니는 태그가 루트 파일 시스템을 바꿨거나, 어제 실험하던 바인드 마운트가 오늘 데모를 망가뜨리거나, 게이트웨이가 얕은 TCP 점검만 통과한 채 의존 서비스는 아직 준비되지 않은 경우입니다. 이 튜토리얼은이미지 다이제스트 고정, 볼륨 설계, 게이트웨이 헬스체크,그리고티켓 순서를 그대로 따라가는 워크플로 재현에 초점을 맞춥니다.
1) Compose를 릴리스 산출물처럼 다루기
누군가 리뷰 없이docker-compose.yml을 고칠 때마다 “내 노트북에서는 된다” 클래스의 부채가 쌓입니다. OpenClaw형 배포에서는 환경마다하나의 Compose 베이스와 오버레이(예:compose.prod.yaml)를 표준으로 두고, README에 실제로 치는 명령을 그대로 적어 두십시오:docker compose -f compose.yaml -f compose.prod.yaml up -d. 호스트의 Docker Engine 패치 레벨도 CI와 맞추면 볼륨 드라이버와 cgroup 동작까지 동일한 전제를 공유합니다.
macOS CI 풀에서 입력과 캐시를 얼마나 엄격히 맞출지에 대한 실무 프레이밍은 2026년 클라우드 Mac 자원 풀에서의 Bazel·Gradle Remote Build: 원격 캐시 적중률, NVMe 디스크 수위, 기업 병렬 CI 비교 FAQ에서도 같은 맥락으로 다룹니다.
2) 이미지는 컴파일 버전처럼 고정하기
:latest나 자주 바뀌는 마이너 태그는 편리하지만, 레지스트리 프로모션 한 번에 OpenSSL 기본값이나 폐기 예정 CLI 플래그가 바뀔 수 있습니다.불변 참조를 우선하세요:image: repo/app@sha256:… 형태의 다이제스트 핀, 또는 리뷰된 머지로만 갱신되는 자재 명세(BOM)입니다. 거버넌스상 가변 태그를 써야 한다면 승격 정책을 문서화하고, 다이제스트가 매칭되는 티켓 없이 바뀌면 실패하는 스케줄 검사를 두는 편이 안전합니다.
재빌드 정책도 핀만큼 중요합니다. 데모 전에docker compose pull을 습관화했다면 지원 재현 스크립트에도 같은 단계를 넣어 영업·지원이 동일 레이어를 보게 하십시오. Apple Silicon 호스트에서는 멀티 아키텍처 이미지인지 amd64 전용인지도 기록하세요. 에뮬레이션은 타이밍을 바꿔 arm64 네이티브에서만 드러나는 경쟁 상태를 가릴 수 있습니다.
3) 볼륨: 소중한 상태와 일회성 스크래치를 분리하기
바인드 마운트는 연결은 빠르지만 여섯 달 뒤의 인과는 추적하기 어렵습니다. 세 덩어리로 나누어 생각하십시오:설정(가능하면 읽기 전용),업그레이드 후에도 남겨야 할 상태(DB, 암호화된 자격 저장소, 모델 캐시),언제든 지워도 되는 스크래치(빌드 트리, 임시 업로드, 재구축 가능한 로컬 벡터 인덱스). 스크래치는 이름 있는 볼륨이나 tmpfs에 두면docker compose down -v로 의도치 않게 DB까지 날리는 실수를 줄이거나, 반대로 디버깅 때 망가진 캐시만 확실히 비울 수 있습니다.
- 시간을 아낀다며 호스트 홈 전체를 마운트하지 마세요. SELinux/AppArmor 라벨과 dotfile 부작용이 기기마다 갈라집니다.
- 컨테이너 내부 서비스 UID가 호스트 경로 소유자와 맞는지 문서화하십시오.
- TLS를 종료하는 게이트웨이라면, 백업 스토리가 없는 한 인증서를 익명 볼륨에만 두지 마세요.
스토리지 배치, SSH/VNC로 로그를 모아 지원 티켓을 열 때의 체크리스트는 vpszap 클라우드에서 OpenClaw 실행하기: 인스턴스, 스토리지, SSH/VNC 및 관측 가능성에서 먼저 정리해 두면 이 글의 Compose 절차와 잘 맞물립니다.
4) 게이트웨이 헬스체크는 살아 있음이 아니라 준비됨을 증명하기
백엔드 에이전트 풀이 아직 인증을 못 하는데도/healthz에서HTTP 200만 돌려주는 게이트웨이는 하드 크래시보다 위험합니다. 로드밸런서는 계속 트래픽을 블랙홀에 보냅니다. 최소한의 의존 체인을 실제로 타는 점검을 쓰세요: 토큰 인트로스펙션, 설정 파일 체크섬, 워커 큐에 대한 가벼운 합성 트랜잭션 등입니다. Compose에서는healthcheck와depends_on: condition: service_healthy를 조합하되, 프로브 자체가 정직할 때만 효과가 있습니다.
5) 워크플로 재현: 티켓 번호가 있는 장애를 따라가기
지원 티켓 #4412를 가정해 봅시다:“게이트웨이 업그레이드 뒤 고객 워크플로가 타임아웃한다.”프로덕션과 같은 태그로git checkout한 뒤docker compose --profile prod config > /tmp/repro.yaml으로 병합된 프로필까지 고정합니다. 레지스트리 이미지를 그대로 쓰려면--no-build로 올린 다음docker compose ps,docker compose logs gateway --since 30m, 티켓에 적힌 실패한 curl 또는 gRPC 클라이언트 명령을 같은 순서로 실행합니다. 재현이 되지 않으면 다이제스트 핀을 이진 탐색해 단일 서비스 범프로 좁히십시오.
원인이 논리보다 환경—디스크 압박, 시각 동기 오차, 오버레이 MTU—일 때는 같은 시간 창에 호스트 신호도 모으십시오:df -h, macOS의vm_stat, 바인드 마운트 경로가 쿼터를 넘었는지 여부입니다. 최종 Compose diff와 통과하는 헬스체크 정의를 티켓에 덧붙이면 다음 담당자에게 실행 가능한 결말을 넘깁니다.
vpszap 클라우드에서 이 스택을 현실처럼 돌리기
Compose 파일의 신뢰도는 그 아래macOS 호스트의 SSD 지연, CPU 경합 없음, 실제 사용자와 비슷한 네트워크 경로에 달려 있습니다. vpszap은물리 M4 Mac mini를 제공하며 가상화로 자원을 나누지 않고 CPU·메모리·SSD를 인스턴스 전용으로 씁니다. 약5분 안에 개통되며SSH와 VNC를 함께 받을 수 있고, 청구는 일·주·월·분기 단위로장기 약정 없이 선택할 수 있습니다. 게이트웨이와 서명 인프라를 사용자에 가깝게 두려면여러 글로벌 리전에서 노드를 고를 수 있습니다.
노트북이 아니라 프로덕션에 가까운 하드웨어에서 같은 Docker Compose 배포를 리허설하고 싶다면 vpszap 클라우드 Mac mini에서 실험을 시작하는 것이 실용적입니다.
