From 53e1410ca9d9991db81cdf5acecc92090a4291ef Mon Sep 17 00:00:00 2001 From: happybell80 Date: Wed, 16 Jul 2025 19:20:54 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20Neo4j=20Docker=20=EC=BB=A8=ED=85=8C?= =?UTF-8?q?=EC=9D=B4=EB=84=88=20=EC=97=B0=EA=B2=B0=20=EB=AC=B8=EC=A0=9C=20?= =?UTF-8?q?=ED=8A=B8=EB=9F=AC=EB=B8=94=EC=8A=88=ED=8C=85=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Linux Docker의 host.docker.internal 미지원 문제 해결 - UFW 방화벽과 Docker 네트워크 충돌 해결 - network_mode: host를 사용한 최종 해결책 문서화 - Neo4j 초기 설정 및 비밀번호 변경 과정 포함 --- ...20250716_neo4j_docker_connection_issues.md | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 docs/troubleshooting/20250716_neo4j_docker_connection_issues.md diff --git a/docs/troubleshooting/20250716_neo4j_docker_connection_issues.md b/docs/troubleshooting/20250716_neo4j_docker_connection_issues.md new file mode 100644 index 0000000..a91ff03 --- /dev/null +++ b/docs/troubleshooting/20250716_neo4j_docker_connection_issues.md @@ -0,0 +1,196 @@ +# 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.219.45 +dbms.default_listen_address=0.0.0.0 +dbms.default_advertised_address=192.168.219.45 + +# 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 'robeing2025!'; + +# .env 파일에 추가 +echo "NEO4J_PASSWORD=robeing2025!" >> /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:-robeing2025!} +``` + +## 최종 해결책 + +`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:-robeing2025!} +``` + +## 검증 결과 + +```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` (서버) \ No newline at end of file