Add DEPLOYMENT.md guide for deployment and DB migration
- Document server structure and deployment flow - Add DB schema change checklist (SQLite ALTER TABLE) - Include common troubleshooting and rollback commands - Reference in CLAUDE.md for new sessions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
AutonetSellCar Deploy
@@ -2,6 +2,10 @@
|
||||
|
||||
이 문서는 Claude Code 세션에서 반드시 읽고 참고해야 하는 중요한 정보입니다.
|
||||
|
||||
> **배포 시 반드시 [DEPLOYMENT.md](./DEPLOYMENT.md)도 함께 확인하세요!**
|
||||
> - DB 스키마 변경 시 수동으로 ALTER TABLE 필요
|
||||
> - 배포 명령어 및 롤백 방법 안내
|
||||
|
||||
---
|
||||
|
||||
## 1. 프로젝트 구조
|
||||
|
||||
191
DEPLOYMENT.md
Normal file
191
DEPLOYMENT.md
Normal file
@@ -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와 함께 반드시 읽어주세요!**
|
||||
Reference in New Issue
Block a user