diff --git a/CLAUDE.md b/CLAUDE.md index d7d33f5..bde5b6e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,10 @@ 이 문서는 Claude Code 세션에서 반드시 읽고 참고해야 하는 중요한 정보입니다. +> **배포 시 반드시 [DEPLOYMENT.md](./DEPLOYMENT.md)도 함께 확인하세요!** +> - DB 스키마 변경 시 수동으로 ALTER TABLE 필요 +> - 배포 명령어 및 롤백 방법 안내 + --- ## 1. 프로젝트 구조 diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 0000000..bc1f74a --- /dev/null +++ b/DEPLOYMENT.md @@ -0,0 +1,191 @@ +# AutonetSellCar.com 배포 가이드 + +## 서버 구성 + +``` +server5 (집 Win11) + ↓ Remote Desktop +server4 (회사 Win11, 개발서버) + ↓ SSH / Git Push +server1 (192.168.0.201) - NPM (Nginx Proxy Manager) +server2 (192.168.0.202) - 운영서버 (Docker) +server3 (192.168.0.203) - grantech.kr +``` + +## 배포 흐름 + +``` +[server4 개발] + │ + ▼ git push staging main +[server2 스테이징 자동 배포] + │ + ▼ ssh server2 "/opt/autonet/scripts/deploy.sh promote" +[server2 운영 배포] +``` + +--- + +## 일반 배포 (코드만 변경) + +```bash +# 1. 커밋 +git add -A && git commit -m "변경 내용" + +# 2. 스테이징 배포 (자동) +git push staging main + +# 3. 운영 승격 +ssh damon@192.168.0.202 "/opt/autonet/scripts/deploy.sh promote" +``` + +--- + +## DB 스키마 변경 시 (중요!) + +### SQLite 특성 +- SQLAlchemy 모델에 컬럼 추가해도 **DB에 자동 반영 안 됨** +- Docker 재시작해도 DB 볼륨은 유지됨 +- **반드시 수동으로 ALTER TABLE 실행 필요!** + +### 새 컬럼 추가 시 체크리스트 + +``` +□ 1. backend/app/models/*.py - 모델에 컬럼 추가 +□ 2. backend/app/schemas/*.py - 스키마에 필드 추가 +□ 3. backend/app/api/*.py - API 기본값 설정 +□ 4. git commit & push +□ 5. 운영 배포 후 DB에 컬럼 추가 (아래 명령어) +□ 6. 테스트 +``` + +### DB 컬럼 추가 명령어 + +```bash +# 운영서버 DB에 컬럼 추가 +ssh damon@192.168.0.202 "docker exec autonet-backend python -c \" +import sqlite3 +for db in ['/app/autonet.db', '/app/autonet_data.db']: + try: + conn = sqlite3.connect(db) + conn.execute('ALTER TABLE 테이블명 ADD COLUMN 컬럼명 타입 DEFAULT 기본값') + conn.commit() + print(f'{db}: OK') + except Exception as e: + print(f'{db}: {e}') +\"" +``` + +### 예시: cc_per_banner_view 컬럼 추가 + +```bash +ssh damon@192.168.0.202 "docker exec autonet-backend python -c \" +import sqlite3 +for db in ['/app/autonet.db', '/app/autonet_data.db']: + try: + conn = sqlite3.connect(db) + conn.execute('ALTER TABLE system_settings ADD COLUMN cc_per_banner_view REAL DEFAULT 0.1') + conn.commit() + print(f'{db}: OK') + except Exception as e: + print(f'{db}: {e}') +\"" +``` + +### SQLite 타입 매핑 + +| Python/SQLAlchemy | SQLite | +|-------------------|--------| +| Integer | INTEGER | +| Float | REAL | +| String | TEXT | +| Boolean | INTEGER (0/1) | +| DateTime | TEXT | + +--- + +## 롤백 + +```bash +# 직전 버전으로 롤백 +ssh damon@192.168.0.202 "/opt/autonet/scripts/deploy.sh rollback" + +# 특정 버전으로 롤백 +ssh damon@192.168.0.202 "/opt/autonet/scripts/deploy.sh rollback-to 20260101_094303" + +# 릴리즈 목록 확인 +ssh damon@192.168.0.202 "/opt/autonet/scripts/deploy.sh status" +``` + +--- + +## 서버 상태 확인 + +```bash +# 컨테이너 상태 +ssh damon@192.168.0.202 "docker ps" + +# 백엔드 로그 +ssh damon@192.168.0.202 "docker logs autonet-backend --tail 50" + +# 프론트엔드 로그 +ssh damon@192.168.0.202 "docker logs autonet-frontend --tail 50" + +# DB 테이블 확인 +ssh damon@192.168.0.202 "docker exec autonet-backend python -c \" +import sqlite3 +conn = sqlite3.connect('/app/autonet.db') +cursor = conn.cursor() +cursor.execute('PRAGMA table_info(system_settings)') +for row in cursor.fetchall(): + print(row) +\"" +``` + +--- + +## SSH 키 설정 (server4 → server1,2,3) + +```powershell +# 공개키 확인 +cat ~/.ssh/id_ed25519.pub + +# 각 서버에 등록 +# server1,2,3 각각에서: +nano ~/.ssh/authorized_keys +# 공개키 붙여넣기 +``` + +--- + +## 자주 발생하는 문제 + +### 1. "no such column" 에러 +- **원인**: 코드에 새 컬럼 추가했지만 DB에는 없음 +- **해결**: ALTER TABLE로 컬럼 추가 (위 참고) + +### 2. "Failed to save settings" 에러 +- **원인**: 보통 DB 스키마 불일치 +- **확인**: `docker logs autonet-backend --tail 30` +- **해결**: 누락된 컬럼 추가 + +### 3. 번역 안 됨 +- **원인**: i18n.ts에 해당 단어 번역 없음 +- **해결**: CAR_TRANSLATIONS에 번역 추가 + +### 4. 배포 후 변경사항 안 보임 +- **프론트엔드**: 브라우저 캐시 클리어 (Ctrl+Shift+R) +- **백엔드**: 컨테이너 재시작 확인 + +--- + +## 변경 이력 + +| 날짜 | 변경 내용 | DB 변경 | +|------|----------|---------| +| 2026-01-01 | cc_per_banner_view 설정 추가 | system_settings.cc_per_banner_view (REAL) | +| 2026-01-01 | 마이스터 번역 추가 | - | + +--- + +**이 문서는 새 세션 시작 시 CLAUDE.md와 함께 반드시 읽어주세요!**