TLS 종단 · WebSocket · allowedOrigins · Docker 출시 검증
Docker VPS에서 OpenClaw를 돌리며 실제 호스트명과 HTTPS를 올리려는 엔지니어는 Gateway 수신 위치, TLS 종단 주체, 브라우저에서 Control UI가 크로스 오리진·불안정한 폴백을 보고하는 이유에서 자주 막힙니다. 글은 의사결정 표로 루프백+에지 프록시와 컨테이너 포트 공인 바인딩을 대비하고, 최소 Caddy·Nginx 리버스 프록시 스니펫, WebSocket·X-Forwarded 헤더, 사용자 입력과 맞추는 allowedOrigins 검수 순서를 줍니다. OOM·첫 WASM은 Docker VPS 장문 트러블슈팅으로. 설치 개요 v2026.4 가이드, 노출 멀티채널 강화, 이미지 롤백 고정·롤백.
Docker로 실제 배포할 때는 호스트 방화벽, 127.0.0.1에만 묶인 publish, 전체 인증서 체인, HTTPS에 맞춘 채널 콜백 URL도 함께입니다. 아래는 온콜 1차 분류용이며 세부 플래그는 사용 중 버전 문서를 따릅니다.
0.0.0.0 습관: WAF·속도 제한·감사 없이 Gateway를 공인 인터페이스에 노출하면 피해 반경이 급증합니다.
WebSocket 반쪽: 프록시가 Upgrade / Connection을 넘기지 않아 패널이 순간 502나 핸드셰이크 실패처럼 보입니다.
Host·origin 드리프트: 브라우저는 호스트명 A를 쓰는데 설정이 IP·내부 별칭에 고정되어 Control UI와 API 교차 출처 보호에 걸립니다.
인증서·DNS 순서: DNS 전파 전 발급이나 자체 서명·공개 체인 혼합은 모바일·자동화 클라이언트 불일치를 만듭니다.
디스크·로그: 프록시+컨테이너 액세스 로그를 돌리지 않으면 작은 VPS에서 inode가 바쁜 주에 가득 차 멈춘 것처럼 보입니다.
업그레이드 창: 이미지 고정 없이 프록시 뒤에서 롤링하면 스테이징·롤백 순서를 건너뛴 구·신 Gateway 행동 갈림이 납니다.
참고: OOM·Exit 137·첫 WASM 지연·Control UI allowedOrigins 장치 페어링이 막혀 있으면 대조표 글부터 보세요. 본문은 메모리 프로필을 반복하지 않습니다.
이 표는 실험용을 처음 실제 호스트명 아래로 올리는 검토용입니다. HTTPS, 채널 콜백, 관측 가능성을 한 검수 스토리에 둡니다.
| 차원 | 127.0.0.1 Gateway + 리버스 프록시 TLS | 컨테이너 포트 공인 직바인딩 |
|---|---|---|
| 최소 노출 | 인터넷은 443만, 업스트림은 루프백 | 별도 네트워크 ACL과 지속 포트 검토 필요 |
| 인증서 운영 | Caddy·Nginx·ACME 단일 파이프라인 | 앱·사이드카마다 인증서를 들고 드리프트 |
| WebSocket | 성숙한 프록시 모듈이 업그레이드·타임아웃 처리 | 헤더 누락, 직접 디버깅이 공백을 가림 |
| 관측 | 에지·업스트림 로그를 request_id로 연결 | 동등한 집계·알림을 직접 구축 |
프로덕션 1원칙: 같은 체크리스트에서 「패널 로드」와 「채널이 공표한 https 호스트로 되돌아올 수 있음」을 동시에 충족합니다.
18789)가 로컬 override와 다르면 설정·compose를 끝까지 검색하고 프록시만 바꾼 채 컨테이너 리슨을 어긋나게 두지 마세요.allowedOrigins에는 브라우저가 실제로 쓰는 https 출처를 넣고, 수정 뒤에는 트러블슈팅 글 순서로 콜드 스타트해 캐시 오판을 피합니다.순서는 compose가 Gateway를 루프백 전용 포트에서 이미 올린 경우를 가정합니다. 설치가 덜됐다면 먼저 마법사·compose 기준 글을 마무리하세요.
호스트명 동결: 인증서 발급 전 A/AAAA가 이 VPS를 가리키는지 확인하고 TTL·유지 창을 명시합니다.
Gateway 바인딩 확인: 호스트에서 ss -lntp 등으로 127.0.0.1 대상 포트만 수신하는지 검증합니다.
프록시 선택: 단일 노드 최소는 Caddy 자동 HTTPS. 기존 Nginx 자산에는 stream/location 템플릿으로 이어 붙입니다.
최소 스니펫 적용: 아래 블록 참고. 업스트림은 문서 포트·실제 호스트명으로 바꿉니다.
채널 콜백 정렬: IM·웹훅 외부 URL은 같은 공인 호스트명·경로 접두사를 씁니다.
golden path 기록: 「브라우저로 https 호스트 열기」에서 「무해한 하트비트나 doctor 한 번」까지 내부 playbook에 적어 교대를 돕습니다.
openclaw.example.com {
encode gzip
reverse_proxy 127.0.0.1:18789
}
server {
listen 443 ssl http2;
server_name openclaw.example.com;
ssl_certificate /etc/letsencrypt/live/openclaw.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/openclaw.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:18789;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 600s;
}
}
표를 교대 메모로 쓰고 각 행이 구체 로그 필드·명령 출력에 닿게 하며 「느낌상 네트워크」로 끝내지 않습니다.
| 증상 | 의심 층 | 첫 조치 |
|---|---|---|
| https만 실패·원시 http 업스트림은 정상 | 인증서 체인 또는 SNI | 신뢰 클라이언트로 체인 검증, server_name과 CN/SAN 대조 |
| 정적 페이지는 열리나 실시간 채널이 즉시 끊김 | WebSocket 프록시 타임아웃 | read timeout 상향, Upgrade가 프록시를 통과하는지 확인 |
| 콘솔에 교차 출처·blocked origin | allowedOrigins에 https 출처 없음 | 출처 목록 재작성 후 영향 프로세스 전부 재시작 |
| 외부 curl 502·로컬 curl 200 | 프록시 업스트림이 옛 포트이거나 컨테이너가 127.0.0.1에 없음 | compose·publish 맵을 홉별로 따라감 |
주의: 멀티채널 강화를 다 읽기 전에 데모용으로 대시보드·디버그 포트를 0.0.0.0에 바인딩하지 마세요.
아래 숫자는단일 VPS에서 흔한 관측 구간으로 디스크·타임아웃 추정용이며 벤더 SLA가 아닙니다.
proxy_read_timeout 또는 Caddy 상응을600초 이상으로. 짧으면 끊김처럼 보이는 위양성이 납니다.df·inode 실측.| 역할 | 프로필 | 권장 |
|---|---|---|
| 개인 샌드박스 | 낮은 트래픽·짧은 유지 허용 | 단일 Caddy+단일 compose+수동 변경 창 |
| 소규모 프로덕션 | 주간 다채널 | 이미지 고정+스테이징 compose+프록시·Gateway 단계적 롤백 |
| Mac·CI 인계 | 긴 잡·서명 공존 | Gateway는 VPS 고정, 빌드는 공유 Mac 풀로. 표는 앞선 글 참조 |
가정용 회선이나 불안정한 소형 클라우드만 출입구로 쓰면 동적 IP·포트 리스크·예고 없는 슬립이 겹칩니다. 순수 자체 DC만 고집하면 TLS·다지역 DR에 시간이 길어져 파트너에게 반복 설명 가능한 공개 진입점을 주기 어렵습니다.
지속 가능한 공개 https 전면과 장수 에이전트를 iOS CI 풀에서 분리하려면 VpsMesh 클라우드 Mac mini 대여와 상시 VPS 조합이 더 안정적인 공학적 답인 경우가 많습니다. 연산·서명은 계약 노드에, Gateway·에지 인증서는 이 런북대로 자체 운영해 「한 대가 전부」 숨은 SPOF를 피합니다.
브라우저 주소줄 전체 출처(포트 포함)가 allowedOrigins에 있는지 확인하세요. 혼합 콘텐츠·IP 직접·호스트명 혼용도 오신호입니다. 복잡한 compose는 Docker VPS 트러블슈팅, 셀프 서비스는 고객 센터입니다.
대부분 업스트림 포트와 헬스 점검이 그대로인지만 확인하면 됩니다. 경로 접두사나 WebSocket 라우팅이 바뀌면 릴리스 노트를 읽고 이미지 고정·롤백 글에 따라 이중 인스턴스로 검증하세요.