happybell80 0252dd1a7f fix: 51123 서버 IP 주소 업데이트 (성수 이전)

192.168.219.45 → 192.168.0.100 일괄 변경

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-21 11:52:26 +09:00

5.6 KiB

Raw Blame History

Neo4j Docker 컨테이너 연결 문제 해결

날짜: 2025-07-16
관련 서비스: rb10508_test, Neo4j
작성자: Claude AI Assistant

문제 상황

Docker 컨테이너에서 서버에 설치된 Neo4j에 연결할 수 없는 문제가 발생했습니다.

증상

오류 메시지: Cannot resolve address host.docker.internal:7687
연결 시도 시 타임아웃 발생
Connection refused 오류

원인 분석

1. Linux Docker의 host.docker.internal 미지원

Linux Docker는 기본적으로 host.docker.internal DNS 매핑을 제공하지 않음
Windows/Mac Docker Desktop과 다른 동작
extra_hosts 설정이 추가로 필요

2. UFW 방화벽 차단

Docker 컨테이너와 호스트 간 통신이 UFW 방화벽에 의해 차단됨
Docker 네트워크(172.17.0.0/16, 172.19.0.0/16)에서 Neo4j 포트(7687) 접근 불가
Docker의 iptables 규칙과 UFW 규칙 간 충돌

3. Neo4j 바인딩 설정

초기 설정에서 Neo4j가 localhost(127.0.0.1)에만 바인딩
외부 네트워크에서 접근 불가능
0.0.0.0으로 바인딩 필요

4. Neo4j 초기 비밀번호 문제

기본 비밀번호 'neo4j' 사용 시 첫 로그인에서 변경 필요
환경변수와 실제 비밀번호 불일치
인증 실패로 연결 거부

해결 과정

1단계: Neo4j 바인딩 설정 변경 (서버 작업)

# /etc/neo4j/neo4j.conf 수정
sudo vim /etc/neo4j/neo4j.conf

# 다음 설정 추가/수정
server.default_listen_address=0.0.0.0
server.default_advertised_address=192.168.0.100
dbms.default_listen_address=0.0.0.0
dbms.default_advertised_address=192.168.0.100

# Neo4j 재시작
sudo systemctl restart neo4j

# 포트 바인딩 확인
sudo ss -tlnp | grep 7687

2단계: 방화벽 규칙 추가 (서버 작업)

# Docker 네트워크에서 Neo4j 접근 허용
sudo ufw allow from 172.17.0.0/16 to any port 7687
sudo ufw allow from 172.19.0.0/16 to any port 7687
sudo ufw allow from 192.168.219.0/24 to any port 7687

# 방화벽 규칙 재로드
sudo ufw reload

# 규칙 확인
sudo ufw status numbered

3단계: Docker 네트워크 설정 변경 (로컬 작업)

시도 1: extra_hosts 추가 (실패)

# docker-compose.yml
services:
  test-api:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - NEO4J_URI=bolt://host.docker.internal:7687

결과: DNS는 해결되었으나 UFW 방화벽에 의해 여전히 차단됨

시도 2: network_mode: host 사용 (성공)

# docker-compose.yml
services:
  test-api:
    network_mode: host  # 브리지 모드 대신 호스트 네트워크 사용
    # ports: 섹션 제거 (host 모드에서 불필요)
    # networks: 섹션 제거 (host 모드에서 불필요)
    # extra_hosts: 섹션 제거 (host 모드에서 불필요)
    environment:
      - NEO4J_URI=bolt://127.0.0.1:7687  # localhost 직접 접근

4단계: Neo4j 비밀번호 설정 (서버 작업)

# Neo4j 초기 비밀번호 변경
cypher-shell -u neo4j -p neo4j

# 프롬프트에서 실행
ALTER CURRENT USER SET PASSWORD FROM 'neo4j' TO '<비밀번호>';

# .env 파일에 추가
echo "NEO4J_PASSWORD=<비밀번호>" >> /home/admin/rb10508_test/.env

# 컨테이너 재시작
cd /home/admin/rb10508_test
docker-compose down
docker-compose up -d

5단계: docker-compose.yml 환경변수 설정 (로컬 작업)

# docker-compose.yml
environment:
  - NEO4J_URI=bolt://127.0.0.1:7687
  - NEO4J_USER=neo4j
  - NEO4J_PASSWORD=${NEO4J_PASSWORD}

최종 해결책

network_mode: host 사용으로 Docker 네트워크 복잡성을 완전히 회피하는 것이 가장 효과적이었습니다.

장점

컨테이너가 호스트 네트워크를 직접 사용
localhost:7687로 Neo4j 접근 가능
UFW 방화벽 규칙과 충돌 없음
설정이 단순하고 명확함

최종 docker-compose.yml 구성

services:
  test-api:
    build: .
    container_name: rb10508_test
    network_mode: host
    volumes:
      - ./chroma_db:/code/chroma_db
      - ./logs:/code/logs
    environment:
      - PORT=10508
      - NEO4J_URI=bolt://127.0.0.1:7687
      - NEO4J_USER=neo4j
      - NEO4J_PASSWORD=${NEO4J_PASSWORD}

검증 결과

# 테스트 코드
from app.services.neo4j_service import neo4j_service

neo4j_service.connect()
result = neo4j_service.health_check()
print(f"헬스체크: {result}")  # True

# 쿼리 테스트
result = neo4j_service.run_query("RETURN 1 as test")
print(f"쿼리 결과: {result}")  # [{'test': 1}]

교훈 및 권장사항

Linux Docker 환경 고려
- Linux에서는 host.docker.internal이 기본 제공되지 않음
- Windows/Mac과 다른 접근 방식 필요
UFW와 Docker 네트워크
- UFW는 Docker의 iptables 규칙과 복잡하게 상호작용
- DOCKER-USER 체인을 통한 설정이 필요하나 복잡함
- 개발 환경에서는 network_mode: host가 가장 간단
Neo4j 초기 설정
- 첫 설치 시 반드시 기본 비밀번호 변경
- 외부 접근이 필요한 경우 0.0.0.0 바인딩 설정
- 프로덕션 환경에서는 적절한 네트워크 보안 설정 필수
환경변수 관리
- 민감한 정보는 .env 파일로 관리
- docker-compose.yml에서는 기본값과 함께 환경변수 참조
- 서버와 로컬 환경의 설정 동기화 중요

5.6 KiB Raw Blame History