docs: add rb8001 PostgreSQL connection troubleshooting guide

- Document Docker network isolation issue and resolution - Include network_mode: host configuration steps - Add PostgreSQL user creation and permission setup - Compare different connection methods and trade-offs - Include verification steps and testing procedures
2025-07-16 12:40:14 +09:00 · 2025-07-16 12:40:14 +09:00 · 7e1e9f621a
commit 7e1e9f621a
parent c02f34b713
1 changed files with 176 additions and 0 deletions
--- a/docs/troubleshooting/20250716_rb8001_postgresql_connection.md
+++ b/docs/troubleshooting/20250716_rb8001_postgresql_connection.md
@ -0,0 +1,176 @@
+# rb8001 PostgreSQL 연결 문제 해결
+
+**날짜**: 2025-07-16  
+**작업자**: Claude & happybell
+
+## 개요
+
+rb8001 컨테이너에서 호스트의 PostgreSQL 서버에 연결할 수 없는 문제를 해결하는 과정
+
+## 문제 상황
+
+### 초기 증상
+- Health check 성공 (`{"status":"healthy"}`)
+- 컨테이너 정상 실행 중
+- PostgreSQL 서버는 정상 작동
+- **문제**: 컨테이너에서 `localhost:5432`로 PostgreSQL 접근 불가
+
+### 에러 메시지
+```bash
+# 컨테이너 내부에서
+psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: No such file or directory
+# 또는
+psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed: Connection refused
+```
+
+## 원인 분석
+
+### Docker 네트워크 격리
+- Docker 컨테이너는 기본적으로 격리된 네트워크에서 실행
+- 컨테이너 내부의 `localhost`는 컨테이너 자체를 의미
+- 호스트의 `localhost`와 다름
+
+### 기존 설정
+```yaml
+# docker-compose.yml (문제 있던 버전)
+services:
+  rb8001:
+    build: .
+    ports:
+      - "8001:8001"  # 포트 매핑만 있음
+    # network_mode 없음
+```
+
+## 해결 과정
+
+### 1. 로컬 코드 수정
+
+#### docker-compose.yml 수정
+```yaml
+services:
+  rb8001:
+    build: .
+    container_name: rb8001
+    network_mode: host  # 추가
+    env_file:
+      - .env
+    # ports 설정 제거 (host 모드와 충돌)
+```
+
+### 2. 서버 인프라 설정
+
+#### PostgreSQL 사용자 생성
+```bash
+sudo -u postgres psql
+CREATE USER robeings WITH PASSWORD 'robeing2025!';
+GRANT ALL PRIVILEGES ON DATABASE rb8001_db TO robeings;
+GRANT ALL PRIVILEGES ON DATABASE rb10508_test_db TO robeings;
+\q
+```
+
+#### .env 파일 업데이트
+```bash
+# 기존
+DATABASE_URL=postgresql://user:password@localhost/ivada_db
+
+# 수정
+DATABASE_URL=postgresql://robeings:robeing2025!@localhost/rb8001_db
+```
+
+### 3. 불필요한 파일 정리
+```bash
+# ivada.db 디렉토리 삭제
+rm -rf /home/admin/rb8001/ivada.db
+```
+
+## 해결 방법 비교
+
+### 방법 1: network_mode: host (채택)
+```yaml
+network_mode: host
+```
+**장점:**
+- 설정 간단
+- 호스트 네트워크 직접 사용
+- localhost로 바로 접근 가능
+
+**단점:**
+- 포트 충돌 가능성
+- 네트워크 격리 해제
+
+### 방법 2: host.docker.internal 사용
+```yaml
+environment:
+  - DATABASE_URL=postgresql://user:pass@host.docker.internal/rb8001_db
+```
+**장점:**
+- 네트워크 격리 유지
+- 크로스 플랫폼 호환성
+
+**단점:**
+- Linux에서 기본 지원 안됨
+- 추가 설정 필요
+
+### 방법 3: 별도 PostgreSQL 컨테이너
+```yaml
+services:
+  postgres:
+    image: postgres:14
+    environment:
+      POSTGRES_DB: rb8001_db
+```
+**장점:**
+- 완전한 격리
+- 개발환경 일관성
+
+**단점:**
+- 리소스 중복
+- 기존 DB 활용 불가
+
+## 검증 결과
+
+### 연결 테스트
+```bash
+# 컨테이너 내부에서
+psql -h localhost -U robeings -d rb8001_db -c "SELECT version();"
+# 성공: PostgreSQL 15.x 정보 출력
+```
+
+### 애플리케이션 테스트
+```bash
+curl http://localhost:8001/health
+# 응답: {"status":"healthy"}
+
+# 데이터베이스 작업 테스트
+curl -X POST http://localhost:8001/api/test/db
+# 성공적으로 DB 연결 및 쿼리 실행
+```
+
+## 교훈
+
+### 1. Docker 네트워크 이해
+- 컨테이너의 localhost ≠ 호스트의 localhost
+- network_mode: host는 간단하지만 격리 해제
+- 환경에 따른 네트워크 전략 필요
+
+### 2. 데이터베이스 사용자 관리
+- 개발/운영 환경별 사용자 분리
+- 최소 권한 원칙 적용
+- 비밀번호 정책 수립
+
+### 3. 컨테이너 설정 일관성
+- ports와 network_mode: host 충돌 주의
+- 환경변수와 기본값 우선순위 이해
+- 설정 변경 시 전체적 영향도 고려
+
+## 관련 파일
+
+- `/home/happybell/projects/ivada/rb8001/docker-compose.yml`
+- `/home/admin/rb8001/.env`
+- PostgreSQL 설정: `/etc/postgresql/15/main/postgresql.conf`
+
+## 다음 단계
+
+1. rb10508_test도 동일한 방식으로 설정
+2. 운영 환경에서의 네트워크 보안 검토
+3. 로그 모니터링을 통한 연결 안정성 확인