From 7e1e9f621a43664c111acdf1ad46dbc1a0978533 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Wed, 16 Jul 2025 12:40:14 +0900 Subject: [PATCH] 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 --- .../20250716_rb8001_postgresql_connection.md | 176 ++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 docs/troubleshooting/20250716_rb8001_postgresql_connection.md diff --git a/docs/troubleshooting/20250716_rb8001_postgresql_connection.md b/docs/troubleshooting/20250716_rb8001_postgresql_connection.md new file mode 100644 index 0000000..dacab84 --- /dev/null +++ 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. 로그 모니터링을 통한 연결 안정성 확인 \ No newline at end of file