숨은 이중 기록의 마찰
Docker Compose 는 선언적이지만 비밀은 단 하나의 근원이어야 합니다. 환경변수 OPENCLAW_GATEWAY_TOKEN 과 마운트된 openclaw.json 의 gateway.auth.token 이 어긋나면 RPC 는 되고 WebSocket 만 끊길 수 있습니다.
종료 코드 1006 은 전송 계층(프록시 타임아웃, TLS 중단, RST) 문제인 경우가 많고 1008 은 정책 위반(토큰 불일치, Origin)입니다. HTTP 200 헬스만으로는 부족합니다.
페어링은 로컬 중간 파일을 씁니다. 익명 볼륨은 force-recreate 로 지워져 UI 가 무한 대기처럼 보입니다.
TLS 종단 리버스 프록시의 idle 이 클라이언트 ping 보다 짧으면 프로덕션에서만 문제가 드러납니다.
새 이미지인데 오래된 JSON 을 마운트하면 split-brain 글과 증상이 섞입니다. 바이너리 드리프트와 토큰 드리프트를 분리합니다.
로그 sidecar 가 chmod 를 바꿔도 티켓에 없으면 인증 오류로 오인할 수 있습니다.
호스트에 Kubernetes 와 compose 가 같은 포트를 쓰면 WebSocket 거부가 인증처럼 보입니다.
프로젝트 이름 없는 백업은 다른 네임스페이스로 오래된 pairing 샤드를 섞습니다.
공식 문서와 같은 계층 진단
공식 순서는 프로세스→전송→인증→페어링입니다. Compose 는 증거 수집만 docker logs 로 바뀝니다.
프로세스는 리스닝과 재시작 루프를 확인합니다.
전송은 포트 publish·NAT·IPv6 를 확인합니다.
인증은 단일 진실 원천과 Vault 렌더 순서를 문서화합니다.
페어링은 명명 볼륨과 UID/GID 를 명시합니다.
거버넌스는 compose 병합 시 secrets 와 env_file 을 함께 검토합니다.
임계값과 SLA 가늠
레지스트리가 느리면 start_period 를 45~90초까지 보되 SLA 를 기록합니다.
외부 WS 합성 프로브는 분 단위, 내부 curl 은 15초 등 비대칭으로 두면 WAN 과 로컬을 분리합니다.
SSD 기준 페어링 10초 안팎이 목표, 40초 넘으면 디스크 큐를 봅니다.
토큰 로테이션은 5분 안에 끝나도록 Vault 와 compose 를 같은 파이프라인으로 묶습니다.
종료 코드 로그는 최소 14일 보관, 더 엄격하면 30일과 IP 의사명명화.
cgroup CPU throttle 은 핸드셰이크만 늘리므로 대시보드에 포함합니다.
토폴로지 × 토큰 × WS × 페어링
| 토폴로지 | 토큰 | WebSocket | 페어링 |
|---|---|---|---|
| 브리지 publish | 단일 출처 | 공개 포트와 클라이언트 URL 정렬 | 네임드 볼륨 |
| network_mode:host | JSON 우선 | NAT 없음·포트 충돌 주의 | 경로는 베어메탈에 근접 |
| 리버스 프록시 TLS | 토큰은 서버만 보관 | idle 은 ping 보다 길게 Upgrade 유지 | 필요 시 세션 스티키 |
| Sidecar secrets | 마운트 경합 회피 | 사이드카 로그 혼동 금지 | 공유 페어링 볼륨 GC 금지 |
행렬은 bridge/host/프록시/sidecar 선택과 설치 경로 글을 연결합니다.
비용 측면에서 QA 가 표류하면 단일 기준 노드보다 비쌀 수 있습니다.
compose 스니펫(값 교체)
version: "3.9"
services:
openclaw-gateway:
image: ghcr.io/example/openclaw-gateway:latest
env_file:
- .env.gateway
environment:
OPENCLAW_GATEWAY_TOKEN: "${OPENCLAW_GATEWAY_TOKEN}"
volumes:
- ./openclaw.json:/etc/openclaw/openclaw.json:ro
- gateway_pairing:/var/lib/openclaw/pairing
ports:
- "18789:18789"
healthcheck:
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:18789/health"]
interval: 30s
timeout: 5s
retries: 5
start_period: 45s
volumes:
gateway_pairing:
1： compose config 와 로그 저장.
2： 토큰 권위 결정.
3： 페어링 명명 볼륨.
4： start_period 조정.
5： 프록시 idle 과 Upgrade.
6： openclaw doctor.
7： 로테이션 기록.
8： URL 이상하면 remote matrix.
연결과 내비
원격 게이트웨이 로 gateway.remote.url 을 확인하세요.
split-brain 글로 바이너리와 설정을 분리합니다.
daemon 설치 런북이 헬스체크 환산에 도움이 됩니다.
FAQ 와 마무리
FAQ 는 운영 제약을 연결하며 개인정보 평가는 별도 티켓입니다.
bare metal 과 오케스트레이터 혼합 시 identity 소유자를 명확히 합니다.
env 와 JSON 이 왜 충돌하나요?
Compose 는 .env 를 먼저 펼치고 bind-mount 는 나중입니다. 우선순위를 문서화하세요.
1008 이 항상 비번 문제?
정책이나 Origin 인 경우가 많습니다. 서버 메시지를 확인하세요.
recreate 후 페어링이 멈추나요?
익명 볼륨이 파일을 잃습니다. 명명 볼륨으로 바꾸세요.
인시던트에 compose project 표기.
요약:토큰 단일 근원·페어링 영속화·계층형 헬스가 맞춰져야 Compose 가 안전합니다.
한계:나쁜 프록시나 Vault 순서 꼬임은 Compose 가 고칠 수 없습니다.
대비:SFTPMAC 임대 원격 Mac 은 SLA 와 감사 가능한 전송으로 24/7 게이트웨이를 보강합니다.
doctor 실행 로그를 남깁니다.