RAILWAY_POSTGRESQL_SETUP.md

Railway PostgreSQL 설정 가이드

Railway에서 PostgreSQL 데이터베이스를 생성하고 Hugging Face Spaces에 연결하는 방법입니다.

1. Railway에서 PostgreSQL 서비스 생성

방법 1: 새 프로젝트에서 PostgreSQL 추가 (권장)

1. Railway 대시보드 접속

   • https://railway.app 접속 및 로그인

2. 새 프로젝트 생성

   • 좌측 상단의 "+ New Project" 클릭
   • "Deploy from GitHub repo" 또는 "Empty Project" 선택
   • 프로젝트 이름 입력 (예: soy-nv-ai-db)

3. PostgreSQL 서비스 추가

   • 프로젝트 내에서 "+ New" 버튼 클릭
   • "Database" 선택
   • "Add PostgreSQL" 클릭
   • Railway가 자동으로 PostgreSQL 인스턴스를 생성합니다 (약 1-2분 소요)

방법 2: 기존 프로젝트에 PostgreSQL 추가

1. 기존 프로젝트 선택
2. "+ New" 버튼 클릭
3. "Database" > "Add PostgreSQL" 선택

2. PostgreSQL 연결 정보 확인

PostgreSQL 서비스가 생성되면:

1. PostgreSQL 서비스 클릭

   • 프로젝트 내에서 생성된 PostgreSQL 서비스를 클릭

2. Variables 탭 확인

   • 상단 메뉴에서 "Variables" 탭 클릭
   • 다음 환경 변수들이 자동으로 생성되어 있습니다:
     • PGHOST: 호스트 주소
     • PGPORT: 포트 번호 (기본값: 5432)
     • PGDATABASE: 데이터베이스 이름
     • PGUSER: 사용자 이름
     • PGPASSWORD: 비밀번호
     • DATABASE_URL: 전체 연결 문자열 ⭐ (이것을 사용합니다!)

3. DATABASE_URL 복사

   • DATABASE_URL 변수의 값을 복사합니다
   • 형식: postgresql://postgres:password@hostname:port/railway
   • 예시: postgresql://postgres:abc123@containers-us-west-123.railway.app:5432/railway

3. Hugging Face Spaces에 연결 정보 설정

3-1. Hugging Face Spaces 접속

1. https://huggingface.co/spaces 접속
2. 해당 Space 페이지로 이동 (예: wiizm/soyailabs)

3-2. 환경 변수 추가

1. Settings 탭 클릭

   • Space 페이지 상단의 "Settings" 탭 클릭

2. Repository secrets 섹션으로 이동

   • 좌측 메뉴에서 "Repository secrets" 클릭
   • 또는 페이지를 아래로 스크롤하여 "Repository secrets" 섹션 찾기

3. 새 환경 변수 추가

   • "New secret" 버튼 클릭
   • 다음 정보 입력:
     • Key: DATABASE_URL
     • Value: Railway에서 복사한 DATABASE_URL 값 붙여넣기

       postgresql://postgres:password@hostname:port/railway
       

   • "Add secret" 버튼 클릭

4. 확인

   • DATABASE_URL이 secrets 목록에 추가되었는지 확인

4. Spaces 재빌드 및 확인

4-1. 자동 재빌드

환경 변수를 추가하면 Hugging Face Spaces가 자동으로 재빌드를 시작합니다.

1. Settings 탭에서 빌드 상태 확인
   • 또는 "Logs" 탭에서 빌드 진행 상황 확인
   • 빌드 완료까지 약 2-5분 소요

4-2. 연결 확인

재빌드 완료 후:

⚠️ 중요: 관리자 계정으로 로그인한 상태에서만 접근 가능합니다.

1. 관리자 로그인:

   • 먼저 애플리케이션에 관리자 계정으로 로그인합니다
   • 로그인하지 않은 상태에서는 접근할 수 없습니다

2. 브라우저에서 다음 URL 접속 (GET 요청):

   https://wiizm-soyailabs.hf.space/api/admin/database/status
   

   • ⚠️ GET 메서드만 지원: POST나 다른 메서드로 요청하면 "Method Not Allowed" 오류가 발생합니다
   • 브라우저 주소창에 직접 입력하거나, 개발자 도구에서 fetch() 사용 시 GET 요청인지 확인하세요

3. 또는 개발자 도구에서 확인:

   • 브라우저 개발자 도구(F12) 열기
   • Console 탭에서 다음 명령 실행:

   fetch('/api/admin/database/status', {
       method: 'GET',  // GET 메서드 명시
       credentials: 'include'  // 쿠키 포함 (로그인 세션)
   })
   .then(res => res.json())
   .then(data => console.log('DB 상태:', data));
   

4. 응답 확인:

   {
       "config_count": 1,
       "connected": true,
       "error": null,
       "table_count": 11,
       "test_query": "현재 시간: 2025-12-08 17:40:35.168889+00:00",
       "type": "PostgreSQL",
       "uri_masked": "postgresql://***@hopper.proxy.rlwy.net:15569/railway",
       "user_count": 1,
       "version": "PostgreSQL 17.7 (Debian 17.7-3.pgdg13+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 14.2.0-19) "
   }
   

5. 성공 확인 사항:

   • ✅ type: "PostgreSQL" (SQLite가 아님)
   • ✅ connected: true
   • ✅ version에 PostgreSQL 버전 표시

5. 데이터베이스 테이블 자동 생성 확인

애플리케이션이 시작되면 자동으로 필요한 테이블들이 생성됩니다.

1. Logs 탭 확인:

   • [데이터베이스] PostgreSQL 연결 성공! 메시지 확인
   • [데이터베이스] 테이블 생성 완료 메시지 확인

2. Railway에서 확인 (선택사항):

   • Railway 프로젝트 > PostgreSQL 서비스 > "Data" 탭
   • 생성된 테이블 목록 확인

6. 설정 저장 테스트

PostgreSQL 연결이 확인되면:

1. 관리자 페이지 접속

   • https://wiizm-soyailabs.hf.space/admin/settings

2. Gemini API 키 저장

   • API 키 입력 후 저장

3. 저장 확인

   • /api/admin/database/status에서 config_count 확인
   • config_count가 1 이상이면 저장 성공

4. 영구 저장 확인

   • Spaces를 재시작하거나 업데이트해도
   • /api/admin/database/status에서 config_count가 유지되는지 확인

문제 해결

Method Not Allowed 오류

증상: /api/admin/database/status 접속 시 "Method Not Allowed" 오류 발생

원인:

• 엔드포인트는 GET 메서드만 지원합니다
• POST, PUT, DELETE 등의 다른 메서드로 요청하면 오류가 발생합니다

해결 방법:

1. 브라우저 주소창에서 직접 접속:

   • 브라우저 주소창에 URL을 직접 입력하면 자동으로 GET 요청이 됩니다
   • 예: https://wiizm-soyailabs.hf.space/api/admin/database/status

2. 개발자 도구에서 GET 메서드 명시:

   fetch('/api/admin/database/status', {
       method: 'GET',  // GET 명시
       credentials: 'include'
   })
   

3. 관리자 로그인 확인:

   • 관리자 계정으로 로그인되어 있는지 확인
   • 로그인하지 않았거나 일반 사용자 계정이면 접근할 수 없습니다

4. curl 명령어 사용 시:

   curl -X GET https://wiizm-soyailabs.hf.space/api/admin/database/status
   

   • -X GET 옵션으로 GET 메서드 명시 (기본값이지만 명시하는 것이 안전)

PostgreSQL 연결 실패

증상: /api/admin/database/status에서 connected: false 또는 type: "SQLite"

해결 방법:

1. 환경 변수 확인:

   • Hugging Face Spaces > Settings > Repository secrets
   • DATABASE_URL이 올바르게 설정되었는지 확인
   • 값에 공백이나 줄바꿈이 없는지 확인

2. 연결 문자열 형식 확인:

   • postgresql:// 또는 postgres://로 시작해야 함
   • 비밀번호에 특수문자가 있으면 URL 인코딩 필요
     • @ → %40
     • # → %23
     • % → %25
     • & → %26

3. Railway 연결 정보 재확인:

   • Railway > PostgreSQL 서비스 > Variables 탭
   • DATABASE_URL 값을 다시 복사하여 확인

4. 로그 확인:

   • Hugging Face Spaces > Logs 탭
   • [데이터베이스] PostgreSQL 연결 실패: ... 오류 메시지 확인
   • 오류 메시지를 기반으로 문제 해결

Railway 외부 연결 문제

증상: Railway에서 외부 연결이 안 되는 경우

해결 방법:

1. TCP Proxy 확인:

   • Railway는 기본적으로 TCP Proxy를 활성화합니다
   • PostgreSQL 서비스 > "Connect" 탭 확인
   • 외부 연결 정보 확인

2. 네트워크 요금 확인:

   • Railway는 외부 연결 시 네트워크 송신량에 대한 요금이 부과될 수 있습니다
   • 사용량 모니터링: Railway 대시보드 > Usage 탭

여전히 SQLite 사용 중

증상: 환경 변수를 설정했는데도 type: "SQLite"로 표시됨

해결 방법:

1. 재빌드 확인:

   • 환경 변수 변경 후 Spaces가 재빌드되었는지 확인
   • Settings > Build logs 확인

2. 환경 변수 이름 확인:

   • 정확히 DATABASE_URL인지 확인 (대소문자 구분)
   • 다른 이름으로 설정하지 않았는지 확인

3. 코드 확인:

   • app/core/config.py에서 환경 변수를 올바르게 읽는지 확인
   • (이미 구현되어 있음)

Railway 추가 기능

데이터베이스 백업

1. Railway 대시보드 > PostgreSQL 서비스
2. "Backups" 탭에서 백업 설정
3. 자동 백업 스케줄 설정 가능

데이터베이스 모니터링

1. Railway 대시보드 > PostgreSQL 서비스
2. "Metrics" 탭에서 성능 모니터링
3. 연결 수, 쿼리 성능 등 확인 가능

데이터베이스 확장 기능

Railway는 다음 PostgreSQL 확장을 지원합니다:

• PostGIS (지리 공간 데이터)
• TimescaleDB (시계열 데이터)
• 기타 PostgreSQL 확장

필요시 Railway 문서를 참고하여 추가하세요.

비용 정보

• Railway 무료 티어: $5 크레딧/월
• PostgreSQL: 무료 티어에서 사용 가능
• 외부 연결: 네트워크 송신량에 따라 요금 부과 가능
• 사용량 확인: Railway 대시보드 > Usage 탭

참고 자료

• Railway PostgreSQL 문서: https://docs.railway.com/guides/postgresql
• Railway 환경 변수: https://docs.railway.com/develop/variables
• PostgreSQL 연결 문자열: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING

확인 체크리스트

PostgreSQL 설정 완료 후:

• Railway에서 PostgreSQL 서비스 생성 완료
• DATABASE_URL 환경 변수 복사 완료
• Hugging Face Spaces에 DATABASE_URL 환경 변수 추가 완료
• Spaces 재빌드 완료
• /api/admin/database/status에서 type: "PostgreSQL" 확인
• connected: true 확인
• Gemini API 키 저장 후 config_count 증가 확인
• Spaces 재시작 후에도 데이터 유지 확인

모든 항목이 체크되면 PostgreSQL 설정이 완료된 것입니다! 🎉