# 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 바인딩 설정 변경 (서버 작업)

```bash
# /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단계: 방화벽 규칙 추가 (서버 작업)

```bash
# 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 추가 (실패)
```yaml
# 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 사용 (성공)
```yaml
# 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 비밀번호 설정 (서버 작업)

```bash
# 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 환경변수 설정 (로컬 작업)

```yaml
# 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 구성
```yaml
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}
```

## 검증 결과

```python
# 테스트 코드
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}]
```

## 교훈 및 권장사항

1. **Linux Docker 환경 고려**
   - Linux에서는 `host.docker.internal`이 기본 제공되지 않음
   - Windows/Mac과 다른 접근 방식 필요

2. **UFW와 Docker 네트워크**
   - UFW는 Docker의 iptables 규칙과 복잡하게 상호작용
   - DOCKER-USER 체인을 통한 설정이 필요하나 복잡함
   - 개발 환경에서는 `network_mode: host`가 가장 간단

3. **Neo4j 초기 설정**
   - 첫 설치 시 반드시 기본 비밀번호 변경
   - 외부 접근이 필요한 경우 0.0.0.0 바인딩 설정
   - 프로덕션 환경에서는 적절한 네트워크 보안 설정 필수

4. **환경변수 관리**
   - 민감한 정보는 .env 파일로 관리
   - docker-compose.yml에서는 기본값과 함께 환경변수 참조
   - 서버와 로컬 환경의 설정 동기화 중요

## 관련 파일
- `/home/happybell/projects/ivada/rb10508_test/docker-compose.yml`
- `/home/happybell/projects/ivada/rb10508_test/app/services/neo4j_service.py`
- `/etc/neo4j/neo4j.conf` (서버)
- `/home/admin/rb10508_test/.env` (서버)