docs: Neo4j Docker 컨테이너 연결 문제 트러블슈팅 문서 추가
- Linux Docker의 host.docker.internal 미지원 문제 해결 - UFW 방화벽과 Docker 네트워크 충돌 해결 - network_mode: host를 사용한 최종 해결책 문서화 - Neo4j 초기 설정 및 비밀번호 변경 과정 포함
This commit is contained in:
happybell80
parent
2165e9a8f8
commit
53e1410ca9
196
docs/troubleshooting/20250716_neo4j_docker_connection_issues.md
Normal file
196
docs/troubleshooting/20250716_neo4j_docker_connection_issues.md
Normal file
@ -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` (서버)
|
||||
Loading…
x
Reference in New Issue
Block a user