Skip to main content

원격 개발 환경 접속 가이드

이 문서는 로컬 개발 환경(예: 개인용 MacBook, PC)에서 AWS VPC 내부에 있는 프라이빗 리소스(Private Resource), 즉 **PostgreSQL 데이터베이스(RDS)**와 **Redis 캐시(ElastiCache)**에 안전하게 접속하는 방법을 안내합니다.

1. 왜 직접 접속할 수 없나요?​

vivid-ai 프로젝트의 데이터베이스와 캐시 서버는 보안을 위해 **프라이빗 서브넷(Private Subnet)**에 위치해 있습니다. 프라이빗 서브넷은 외부 인터넷으로부터의 직접적인 접근을 원천적으로 차단하여, 인가되지 않은 사용자가 민감한 데이터에 접근하는 것을 방지합니다.

따라서, VPC 외부 네트워크에 있는 로컬 개발 환경에서는 이 리소스들의 주소로 직접 접속을 시도하면 Connection Timeout 오류가 발생합니다.

2. 접속 방식: 배스천 호스트와 SSH 터널링​

이러한 문제를 해결하고 안전한 접속을 확보하기 위해 **배스천 호스트(Bastion Host)**를 이용한 SSH 터널링(SSH Tunneling) 방식을 사용합니다.

  • 배스천 호스트(Bastion Host): '요새'라는 의미처럼, VPC의 **퍼블릭 서브넷(Public Subnet)**에 위치하여 외부에서의 접속을 위한 유일한 관문 역할을 하는 소규모 EC2 인스턴스입니다. 이 서버는 SSH 접속만 허용하도록 보안이 강화되어 있습니다.

  • SSH 터널링(SSH Tunneling): 로컬 컴퓨터에서 배스천 호스트까지 맺어진 암호화된 SSH 연결을 '터널'처럼 사용하여, 로컬 컴퓨터의 특정 포트(예: localhost:6379)로 들어오는 요청을 VPC 내부의 최종 목적지(예: ElastiCache Redis)로 안전하게 전달(Port Forwarding)하는 기술입니다.

3. 설정 절차​

3.1. 사전 준비​

  • 배스천 호스트 정보: AWS EC2 콘솔에서 배스천 호스트의 퍼블릭 IP 주소를 확인합니다.
  • SSH 키 페어 (.pem 파일): 배스천 호스트에 접속하기 위한 개인 키 파일을 로컬 컴퓨터의 안전한 위치에 저장합니다. (예: ~/.ssh/)

3.2. SSH 키 파일 권한 설정​

개인 키 파일은 보안을 위해 소유자만 읽을 수 있는 권한을 가져야 합니다.

chmod 400 /경로/내-키페어.pem

3.3. SSH 터널링 명령어 실행​

로컬 컴퓨터의 터미널에서 아래 명령어를 실행하여 터널을 생성합니다. 이 명령어는 RDS와 Redis 접속을 위한 터널을 동시에 생성합니다.

ssh -i <키-파일-경로> -N -L <로컬-RDS-포트>:<RDS-엔드포인트>:<원격-RDS-포트> -L <로컬-Redis-포트>:<Redis-엔드포인트>:<원격-Redis-포트> <사용자>@<배스천-호스트-IP>

실행 예시 (실제 값으로 대체 필요):

ssh -i ~/.ssh/your-key.pem -N -L 5432:your-rds-endpoint.rds.amazonaws.com:5432 -L 6379:your-redis-endpoint.cache.amazonaws.com:6379 ec2-user@<bastion-ip-address>
  • -i: 사용할 SSH 개인 키 파일을 지정합니다.
  • -N: 원격 명령어를 실행하지 않고, 포트 포워딩만 활성화합니다.
  • -L: 로컬 포트 포워딩 규칙을 지정합니다. (<로컬-포트>:<목적지-주소>:<목적지-포트>)
  • 이 명령어를 실행한 터미널 창은 백엔드 개발을 하는 동안 계속 켜두어야 합니다.

3.4. 애플리케이션 설정 (.env 파일)​

SSH 터널이 활성화되면, 백엔드 애플리케이션은 더 이상 AWS의 실제 엔드포인트 주소를 알 필요가 없습니다. 모든 요청을 localhost로 보내면 터널이 알아서 전달해줍니다.

backend-vivid-ai/.env 파일을 다음과 같이 수정합니다.

# .env
DB_HOST=localhost
DB_PORT=5432

REDIS_HOST=localhost
REDIS_PORT=6379

3.5. 문제 해결 (Troubleshooting)​

  • Permissions ... are too open 또는 bad permissions 오류:

    • 원인: SSH 키 파일의 권한이 너무 개방적입니다.
    • 해결: chmod 400 <키-파일-경로> 명령어로 권한을 수정합니다.

  • Connection refused 오류:

    • 원인: SSH 터널이 활성화되지 않았거나, 로컬에서 지정한 포트(예: 6379)와 애플리케이션이 접속하려는 포트가 다릅니다.
    • 해결: SSH 터널 명령어가 실행 중인지 확인하고, .env 파일의 포트 번호를 확인합니다.

  • 명령어가 응답 없이 멈춤 (Timeout):

    • 원인: SSH 터널은 배스천 호스트까지 연결되었으나, 배스천 호스트와 최종 목적지(RDS/Redis) 간의 통신이 실패하는 경우입니다.
    • 해결: AWS 콘솔에서 RDS/Redis의 보안 그룹이 배스천 호스트의 보안 그룹으로부터 오는 트래픽(5432, 6379 포트)을 허용하는지 인바운드 규칙을 확인해야 합니다.