VSCode
Claude Code
PostgreSQL
SFTP
AWS Lightsail
전체 워크플로우 개요
아래 흐름을 항상 지킵니다. 프로덕션 서버에서는 코드를 직접 수정하지 않습니다.
| 단계 | 내용 |
|---|
| ① 로컬 개발 | VSCode + Claude Code로 기능 개발 및 테스트 |
| ② 로컬 DB 테스트 | 로컬 PostgreSQL에서 마이그레이션 검증 |
| ③ 로컬 백업 | 배포 전 로컬 스냅샷 저장 |
| ④ 서버 DB 백업 | 배포 전 Lightsail PostgreSQL 덤프 |
| ⑤ SFTP 업로드 | 변경된 파일만 서버로 전송 |
| ⑥ 서버 재시작 | SSH로 서비스 재시작 및 확인 |
| ⑦ 동작 확인 | 엔드포인트 테스트 후 완료 |
1. 로컬 프로젝트 구조 권장
배포 전·후를 명확히 추적하기 위해 아래 구조를 권장합니다.
my-project/
├── app/ # FastAPI 소스코드
├── migrations/ # DB 마이그레이션 SQL 파일
├── backups/ # 로컬 DB 덤프 보관
│ ├── 20260606_1430.sql
│ └── ...
├── deploy/ # 배포 관련 스크립트
│ ├── upload.sh # SFTP 업로드 스크립트
│ └── files.txt # 업로드할 파일 목록
└── .env.local # 로컬 환경변수 (서버와 분리)
2. Claude Code 사용 규칙
⚠️ 반드시 지켜야 할 Claude Code 수칙
- DB 스키마 변경(ALTER, DROP, DELETE)은 반드시 미리 보여달라고 요청 후 검토
- Claude Code에게 항상 명시: "자동으로 DB 변경 실행 금지"
- 변경사항은 수락 전 반드시 diff를 눈으로 확인
- 마이그레이션 SQL은 별도 파일로 저장 후 수동 실행
- Claude Code 세션 시작 시 현재 작업 범위를 명확히 지정
Claude Code 세션 시작 시 이렇게 명시하세요:
Claude Code 프롬프트 템플릿
- "오늘 작업: [기능명] 개발"
- "DB 스키마 변경이 필요하면 SQL을 보여주고 내가 확인한 후 진행할 것"
- "migrations/ 폴더에 변경 SQL을 파일로 저장할 것"
- "프로덕션 서버 접속 금지 — 로컬만 수정"
3. PostgreSQL 백업 절차
3-1. 배포 전 서버 DB 백업 (필수)
배포 전에 반드시 실행합니다. 문제 발생 시 이 파일로 복구합니다.
# Lightsail 서버에 SSH 접속 후 실행
$ssh ubuntu@<서버IP>
$cd /home/ubuntu/backups
$pg_dump -U <DB유저> -d <DB명> -F c -f backup_$(date +%Y%m%d_%H%M).dump
# 백업 파일 확인
$ls -lh backup_*.dump
# 로컬 터미널에서 실행
$scp ubuntu@<서버IP>:/home/ubuntu/backups/backup_*.dump ./backups/
3-2. 로컬 DB 백업
# 배포 전 로컬 DB도 백업
$pg_dump -U postgres -d <로컬DB명> -F c -f ./backups/local_$(date +%Y%m%d_%H%M).dump
3-3. 복구 방법
문제 발생 시 아래 명령어로 복구합니다.
복구 명령어
- pg_restore -U <유저> -d <DB명> --clean backup_20260606_1430.dump
- 옵션 설명: --clean = 기존 데이터 삭제 후 복구 / -F c = custom 포맷
- 주의: 복구 전 반드시 현재 상태도 백업 후 진행
3-4. 서버 자동 백업 설정 (crontab)
Lightsail 서버에서 매일 자동 백업을 설정합니다.
# SSH 접속 후 crontab 편집
$ crontab -e
# 매일 새벽 3시 자동 백업 (최근 14일 보관)
0 3 * * * pg_dump -U <유저> -d <DB명> -F c -f /home/ubuntu/backups/auto_$(date +\%Y\%m\%d).dump
# 14일 이상 된 백업 자동 삭제
0 4 * * * find /home/ubuntu/backups -name 'auto_*.dump' -mtime +14 -delete
4. SFTP 배포 절차
4-1. 배포 전 체크리스트
배포 전 반드시 확인
- 서버 DB 백업 완료 여부 확인
- 로컬에서 테스트 통과 확인
- 변경된 파일 목록 정리 (deploy/files.txt)
- 마이그레이션 SQL 파일 준비 완료
4-2. SFTP 업로드
FileZilla 또는 터미널 sftp 명령어를 사용합니다.
# 접속
$sftp ubuntu@<서버IP>
# 원격 디렉토리 이동
$cd /home/ubuntu/myapp
# 파일 업로드 (변경된 파일만)
$put app/main.py
$put app/routers/users.py
# 디렉토리 전체 업로드
$put -r app/
4-3. 마이그레이션 실행
스키마 변경이 있는 경우 업로드 후 실행합니다.
$ssh ubuntu@<서버IP>
$cd /home/ubuntu/myapp
# 마이그레이션 SQL 직접 실행 (Claude Code 아님)
$psql -U <유저> -d <DB명> -f migrations/20260606_add_column.sql
# 결과 확인
$psql -U <유저> -d <DB명> -c '\d <테이블명>'
4-4. 서비스 재시작 및 확인
# systemd 사용 시
$sudo systemctl restart myapp
$sudo systemctl status myapp
# 또는 uvicorn 직접 실행 시
$pkill -f uvicorn
$nohup uvicorn app.main:app --host 0.0.0.0 --port 8000 &
# 로그 확인
$sudo journalctl -u myapp -n 50 --no-pager
5. 문제 발생 시 롤백 절차
| 상황 | 조치 |
|---|
| 코드 오류 | SFTP로 이전 파일 재업로드 후 재시작 |
| DB 마이그레이션 오류 | pg_restore로 직전 백업 복구 |
| 서비스 다운 | 로그 확인 → 코드 롤백 → DB 복구 순 |
| 데이터 손실 | 가장 최근 덤프 파일로 pg_restore |
롤백 황금 원칙
- 당황하지 않고 먼저 백업 파일 위치 확인
- 롤백 전 현재 상태도 덤프 저장 (증거 보존)
- 코드와 DB 롤백은 같은 시점 기준으로
6. 배포 체크리스트 1페이지 요약
| 순서 | 작업 |
|---|
| □ 1 | 로컬 테스트 완료 |
| □ 2 | 서버 DB 백업: pg_dump → 로컬 보관 |
| □ 3 | SFTP로 변경 파일 업로드 |
| □ 4 | SSH 접속 → 마이그레이션 SQL 수동 실행 (있는 경우) |
| □ 5 | 서비스 재시작 |
| □ 6 | 로그 확인 (오류 없음) |
| □ 7 | 엔드포인트 테스트 |
| □ 8 | 이상 없으면 완료 / 오류 시 즉시 롤백 |
"배포는 되돌릴 수 있어야 한다 — 백업 없는 배포는 없다"