Add detailed Railway PostgreSQL setup guide

RAILWAY_POSTGRESQL_SETUP.md

@@ -0,0 +1,261 @@
+# 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. **브라우저에서 다음 URL 접속**:
+   ```
+   https://wiizm-soyailabs.hf.space/api/admin/database/status
+   ```
+
+2. **응답 확인**:
+   ```json
+   {
+       "connected": true,
+       "type": "PostgreSQL",  // ✅ PostgreSQL 확인
+       "uri_masked": "postgresql://***@hostname:port/railway",
+       "version": "PostgreSQL 15.x...",
+       "test_query": "현재 시간: 2025-12-08 17:30:00",
+       "table_count": 11,
+       "user_count": 1,
+       "config_count": 1
+   }
+   ```
+
+3. **성공 확인 사항**:
+   - ✅ `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`가 유지되는지 확인
+
+## 문제 해결
+
+### 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 설정이 완료된 것입니다! 🎉
+