15d776d888
- 모든 트러블슈팅 파일명을 yymmdd 형식으로 통일 - 오늘 작업 내용 추가 (서버 구조 변경, auth-server 설정) - Git 작업 실수 관련 교훈 기록
196 lines
5.6 KiB
Markdown
196 lines
5.6 KiB
Markdown
# 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` (서버) |