DOCS/troubleshooting/250716_rb8001_postgresql_connection.md

rb8001 PostgreSQL 연결 문제 해결

날짜: 2025-07-16
작업자: Claude & happybell

개요

rb8001 컨테이너에서 호스트의 PostgreSQL 서버에 연결할 수 없는 문제를 해결하는 과정

문제 상황

초기 증상

• Health check 성공 ({"status":"healthy"})
• 컨테이너 정상 실행 중
• PostgreSQL 서버는 정상 작동
• 문제: 컨테이너에서 localhost:5432로 PostgreSQL 접근 불가

에러 메시지

# 컨테이너 내부에서
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와 다름

기존 설정

# docker-compose.yml (문제 있던 버전)
services:
  rb8001:
    build: .
    ports:
      - "8001:8001"  # 포트 매핑만 있음
    # network_mode 없음

해결 과정

1. 로컬 코드 수정

docker-compose.yml 수정

services:
  rb8001:
    build: .
    container_name: rb8001
    network_mode: host  # 추가
    env_file:
      - .env
    # ports 설정 제거 (host 모드와 충돌)

2. 서버 인프라 설정

PostgreSQL 사용자 생성

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 파일 업데이트

# 기존
DATABASE_URL=postgresql://user:password@localhost/ivada_db

# 수정
DATABASE_URL=postgresql://robeings:robeing2025!@localhost/rb8001_db

3. 불필요한 파일 정리

# ivada.db 디렉토리 삭제
rm -rf /home/admin/rb8001/ivada.db

해결 방법 비교

방법 1: network_mode: host (채택)

network_mode: host

장점:

• 설정 간단
• 호스트 네트워크 직접 사용
• localhost로 바로 접근 가능

단점:

• 포트 충돌 가능성
• 네트워크 격리 해제

방법 2: host.docker.internal 사용

environment:
  - DATABASE_URL=postgresql://user:pass@host.docker.internal/rb8001_db

장점:

• 네트워크 격리 유지
• 크로스 플랫폼 호환성

단점:

• Linux에서 기본 지원 안됨
• 추가 설정 필요

방법 3: 별도 PostgreSQL 컨테이너

services:
  postgres:
    image: postgres:14
    environment:
      POSTGRES_DB: rb8001_db

장점:

• 완전한 격리
• 개발환경 일관성

단점:

• 리소스 중복
• 기존 DB 활용 불가

검증 결과

연결 테스트

# 컨테이너 내부에서
psql -h localhost -U robeings -d rb8001_db -c "SELECT version();"
# 성공: PostgreSQL 15.x 정보 출력

애플리케이션 테스트

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. 로그 모니터링을 통한 연결 안정성 확인