COMPOSE_PROJECT_NAME · 독립 데이터 볼륨과 포트 표 · env_file과 컨테이너 env 대조
동일한 VPS에서 두 벌의 OpenClaw를 병렬로 운용할 때 흔한 사고는 포트 점유, 기본 네트워크·볼륨 이름 충돌, 그리고 호스트에는 API Key가 있는데 컨테이너 env는 비어 있는 경우입니다. 본 글은 단일 인스턴스 기준선 대비 다중 인스턴스 최소 차이 집합 대조표로 COMPOSE_PROJECT_NAME, 데이터 디렉터리, 포트 표를 정리하고, env_file과 environment 주입 경로를 설명하며, 여섯 단계 대조 목록과 단일 인스턴스로의 복귀 조건을 제시합니다. Docker Compose 운영 기준선, Exit 137 및 초기 트러블슈팅과 함께 읽으시기 바랍니다.
docker-compose.yml을 복사해 포트만 바꾼다고 해서 격리가 완성되지는 않습니다. 기본 프로젝트 이름 때문에 네트워크와 익명 볼륨 이름이 계속 겹칠 수 있고, 호스트의 export는 컨테이너로 자동 전달되지 않으며, 리버스 프록시 upstream은 여전히 이전 컨테이너 IP를 가리킬 수 있습니다. 아래 신호가 보이면 컨테이너만 늘리기보다 대조표부터 항목별로 확인하시기 바랍니다.
포트만 바꾸고 COMPOSE_PROJECT_NAME은 그대로인 경우: 기본 bridge 네트워크와 내부 DNS가 다른 스택의 컨테이너 이름으로 해석될 수 있습니다.
데이터 디렉터리 심볼릭 링크나 마운트가 겹치는 경우: 두 세트의 ~/.openclaw 또는 workspace가 실제로는 동일 디스크 접두사 아래에 있어 업그레이드 스크립트가 서로 덮어씁니다.
API Key가 셸 프로필에만 있는 경우: docker compose up 자식 프로세스가 Compose가 기대하는 env_file 경로를 읽지 못합니다.
healthcheck 간격이 지나치게 짧은 경우: 두 번째 인스턴스의 콜드 스타트가 더 길어 오케스트레이터가 재시작으로 오판하고 첫 번째 인스턴스와 락을 다툴 수 있습니다.
리버스 프록시가 여전히 127.0.0.1의 예전 포트를 가리키는 경우: 두 Gateway가 교체될 때에도 경계 계층이 중지된 인스턴스로 트래픽을 보냅니다. 정렬 방법은 리버스 프록시와 TLS 글을 참고합니다.
아래 항목은 동일 호스트에 스택을 두 벌 둘 때 가장 흔한 최소 차이 집합입니다. 단기 시험 인스턴스만 준비한다 해도 프로젝트 이름·데이터 디렉터리·호스트 포트·env_file 경로 네 가지를 먼저 확정한 뒤 자동화를 논의하는 것이 좋습니다. 자원 상한과 로그 로테이션은 운영 기준선을 계속 따릅니다.
| 항목 | 단일 인스턴스 기준선 | 다중 인스턴스에서 반드시 분리 | 흔한 함정 |
|---|---|---|---|
COMPOSE_PROJECT_NAME | 기본 디렉터리 이름 | 스택마다 짧은 고유 이름(예: oc_a / oc_b) | 폴더만 바꾸고 프로젝트 이름은 그대로여서 익명 볼륨이 재사용됨 |
| 데이터 볼륨 경로 | 단일 호스트 바인드 경로 | /srv/openclaw-a와 /srv/openclaw-b를 완전히 분리 | 하위 경로 심볼릭 링크가 동일 상위 디렉터리를 가리킴 |
| 호스트 포트 | 단일 3000:3000 매핑 | 서로 다른 호스트 포트에 매핑하고 포트 표 문서에 기록 | 두 번째 스택 기동 실패 후에도 systemd가 재시도하며 흔들림 |
| 환경 주입 | 단일 .env | 스택마다 .env.oc-a 등으로 나누고 Compose에 env_file을 명시 | 호스트 export가 Compose 해석 범위에 포함되지 않음 |
| 헬스 체크 | 단일 start_period | 콜드 스타트가 더 길면 start_period와 retries를 상향 | 두 스택이 동시에 재시작되며 CPU 스파이크 발생 |
프로젝트 이름과 데이터 디렉터리를 포트 홍보보다 먼저 고정합니다. 순서가 바뀌면 첫 업그레이드 스크립트에서 두 세트 상태가 동일 접두사에 기록될 수 있습니다.
아래는 공식 또는 팀 Compose 조각을 단일 머신에서 이미 기동할 수 있다는 가정입니다. 목표는 두 번째 스택의 구성 렌더 결과와 실행 시점 env를 감사 가능하게 맞추는 것입니다.
프로젝트 이름과 디렉터리 기록: COMPOSE_PROJECT_NAME을 설정하고, 독립 데이터 디렉터리를 만들며 중첩 심볼릭 링크가 없는지 확인합니다.
포트 표 고정: Gateway, Control UI, 부가 채널 포트에 사용 중이 아닌 호스트 포트를 배정하고 운영 표에 적습니다.
env_file 분리: 스택마다 비밀 파일 경로를 두고 .env를 공유하지 않습니다. docker compose --project-directory로 작업 디렉터리를 명확히 합니다.
렌더 검사: docker compose -f ... config를 실행해 두 스택의 networks, volumes, ports에 동일 이름 마운트가 남아 있는지 비교합니다.
런타임 검증: docker compose exec로 컨테이너에 들어가 대상 변수를 출력하고, 호스트에서 grep 등으로 마스킹한 결과와 일치하는지 확인합니다.
헬스와 로그: 기준선 글에 따라 start_period와 json-file 상한을 설정해 두 스택이 동시에 디스크를 채우지 않도록 합니다.
export COMPOSE_PROJECT_NAME=oc_b docker compose --env-file ./.env.oc-b -f docker-compose.yml config > /tmp/oc-b.rendered.yml docker compose --env-file ./.env.oc-b -f docker-compose.yml up -d docker compose --env-file ./.env.oc-b exec -T openclaw-gateway sh -lc 'env | grep -E "ANTHROPIC|OPENAI" | sed "s/=.*/=***MASK***/"'
안내: config 서브커맨드는 합성 결과만 해석하고 컨테이너를 기동하지 않습니다. 렌더 diff를 저장한 뒤 up하면 첫 번째 스택과 대조하기 쉽습니다.
아래는 당직·사후 분석의 출발점입니다. 실제 Compose 조각과 호스트 모니터링으로 구체 임계값을 바꿔 쓰시고, 대외 SLA로 단정하지는 마십시오. 간헐적으로 잘못된 인스턴스에 연결될 때는 두 스택의 렌더된 구성, 컨테이너 inspect의 네트워크 대역, 리버스 프록시 upstream 스냅샷을 함께 보존합니다.
ss -lntp 또는 동등한 명령을 실행하고 출력을 티켓 첨부로 저장합니다.json-file 쓰기를 두 배로 할 때 inode와 대역폭이 CPU보다 먼저 병목이 됩니다. 순찰 주기는 기준선 글을 따릅니다.| 증상 | 우선 의심 필드 | 권장 명령 또는 증거 |
|---|---|---|
| 컨테이너에 API Key 없음 | env_file 경로, Compose 작업 디렉터리 | docker compose config와 exec env 출력 대조 |
| 헬스 체크로 재시작이 반복됨 | start_period, CPU steal | 호스트 dmesg, cgroup 통계, 컨테이너 로그 타임라인 |
| 요청이 잘못된 인스턴스로 감 | 리버스 프록시 upstream, 남은 이전 컨테이너 | 프록시 reload 전후 docker ps -a와 upstream 파일 diff |
주의: 첫 번째 스택을 중지하지 않은 채 동일 경로의 .env를 덮어쓰면 두 스택의 키 순환 순서가 뒤섞입니다. 항상 새 파일을 복사한 뒤 참조를 바꿉니다.
소메모리 VPS 한 대에 프로덕션급 OpenClaw를 두 벌 억지로 올리면 디스크와 로그에서 먼저 지는 경우가 많습니다. 독립 데이터 디렉터리와 포트 표가 없으면 장애 대응이 어떤 Gateway에 붙었는지 추측하는 수준으로 퇴화합니다. 렌더 diff를 남기지 않고 Compose만 수동으로 고치면 이후 업그레이드에서 어떤 환경 변수를 누가 바꿨는지 설명하기 어렵습니다.
반대로 안정적인 호스트, 예측 가능한 대역폭, 분리 가능한 작업 디렉터리가 필요한 팀은 OpenClaw를 주문 가능한 클라우드 Mac 또는 전용 VPS 플랜에 두는 편이 위 체크리스트를 실행하기에 유리합니다. 다중 인스턴스 시험과 프로덕션 격리를 같은 운영 서사에 담아야 한다면 VpsMesh Mac Mini 클라우드 임대가 보통 더 나은 선택입니다. 노드 역할을 나누고 링크를 감사할 수 있어 Compose 차이 집합과 큐 정책을 같은 방식으로 검수할 수 있습니다.
본문 대조표에 따라 익명 볼륨, 기본 네트워크 이름, 호스트 포트, env_file이 첫 번째 스택과 겹치지 않는지 확인합니다. 디렉터리 이름만 바꾸고 프로젝트 이름은 그대로 둔 경우가 가장 흔합니다. healthcheck와 restart 자세한 내용은 Compose 운영 기준선을 참고합니다.
Compose가 올바른 env_file을 읽지 않았거나 작업 디렉터리가 다르거나 변수가 build 구간에만 선언된 경우가 많습니다. 본문 여섯 단계에 따라 docker compose config와 exec 출력을 맞춥니다. 초기 단계에서는 Exit 137 및 초기 트러블슈팅의 환경 변수 절을 함께 보시기 바랍니다.
먼저 docker compose down으로 보조 스택을 내리고 포트가 비었는지 확인한 뒤, 두 데이터 디렉터리를 백업합니다. 렌더된 구성을 파일로 보관하기 전에는 볼륨을 삭제하지 마십시오. 플랜 비교는 Mac Mini M4 대여 요금, 주문은 Mac Mini M4 주문, 연동 정책은 Mac Mini 고객 센터를 참고합니다.