happybell80 ae9598f8ab refactor: 트러블슈팅 폴더를 docs 밖으로 이동

- docs/troubleshooting/ → troubleshooting/
- DOCS 루트 레벨에 위치하도록 변경
- README.md 링크 경로도 함께 수정

2025-07-29 00:13:42 +09:00

2.8 KiB

Raw Blame History

Docker 네트워크 격리로 인한 test-api unreachable 문제 해결

개요

날짜: 2025-07-14
문제: 관리자 대시보드에서 test-api (10508) 서비스가 unreachable 상태
원인: Docker 네트워크 격리 (DOCKER-ISOLATION iptables 체인)

문제 상황

증상

관리자 대시보드에서 test-api 서비스가 지속적으로 unreachable 표시
호스트에서는 curl http://localhost:10508/health 정상 동작
컨테이너 내부에서는 연결 불가

네트워크 구성

frontend_default (172.18.0.0/16)
├── frontend-backend-1 (172.18.0.2)
└── frontend-frontend-1 (172.18.0.3)

appnet (172.21.0.0/16)
└── rb10508_test (172.21.0.2)

원인 분석

Docker의 기본 bridge 네트워크 드라이버는 네트워크끼리 완전히 격리하도록 iptables 체인(DOCKER-ISOLATION, DOCKER-USER)을 자동으로 생성합니다.

결과: 같은 호스트라도 서로 다른 bridge 네트워크에 있는 컨테이너는 호스트 포트(-p 10508:10508)로도 통신이 차단됨

해결 방법

선택한 해결책: 같은 사용자 정의 네트워크에 연결

appnet 네트워크 확인

docker network ls
docker network inspect appnet

frontend 컨테이너들을 appnet에 연결

docker network connect appnet frontend-backend-1
docker network connect appnet frontend-frontend-1

연결 확인

docker network inspect appnet
# 모든 컨테이너가 나타나는지 확인

테스트

docker exec frontend-backend-1 curl -s -o /dev/null -w "%{http_code}" http://rb10508_test:10508/health
# 200 응답 확인

다른 가능한 해결 방법들

docker-compose.yml에서 네트워크 설정

services:
  backend:
    networks:
      - appnet
networks:
  appnet:
    external: true

host 네트워크 사용 (보안상 비추천)

network_mode: "host"

iptables 예외 규칙 (관리 복잡)

iptables -I DOCKER-USER -i br0 -o br1 -j ACCEPT

주의사항

영구 설정: 컨테이너 재시작 시 네트워크 연결이 유지되려면 docker-compose.yml 수정 필요
DNS 해결: 같은 네트워크에 있으면 컨테이너 이름으로 통신 가능
보안: 필요한 컨테이너만 같은 네트워크에 연결

검증 방법

# 네트워크 연결 상태 확인
docker network inspect appnet | grep -A 5 "Containers"

# 관리자 대시보드에서 서비스 상태 확인
curl http://localhost:8000/admin/services/status

참고사항

Docker 네트워크 격리는 보안을 위한 의도된 동작
같은 네트워크에 있는 컨테이너끼리만 직접 통신 가능
서로 다른 네트워크 간 통신은 명시적인 설정 필요

2.8 KiB Raw Blame History