diff --git a/deploy/BACKUP.md b/deploy/BACKUP.md index 4d7f49d..8ec14c0 100644 --- a/deploy/BACKUP.md +++ b/deploy/BACKUP.md @@ -1,16 +1,21 @@ -# DB 백업·복원 운영 가이드 +# 백업·복원 운영 가이드 -학습 플랫폼 DB(PostgreSQL)는 **매일 새벽 3시(KST)** 자동 백업되어 S3에 올라갑니다. +학습 플랫폼 **DB(PostgreSQL)**와 **Git 서버(Gitea)**가 **매일 새벽** 자동 백업되어 S3에 올라갑니다. ## 구성 ``` EC2 (3.36.160.246) -├── mirim-postgres 컨테이너 ← 원본 DB -├── ~/backups/*.sql.gz ← 서버 로컬 사본 (7일 보관) -└── systemd timer (매일 03:00 KST) - ↓ pg_dump | gzip | aws s3 cp -S3: awesomedev-mirim-backup-apne2/postgres/ ← 30일 보관 후 자동 삭제 +├── mirim-postgres 컨테이너 ← 원본 DB +├── mirim-gitea 컨테이너 ← 원본 Git 서버 (저장소 + SQLite + 설정) +├── ~/backups/ ← 서버 로컬 사본 (7일 보관) +└── systemd timer + ├── 03:00 KST → backup-db.sh : pg_dump | gzip | s3 cp + └── 03:10 KST → backup-gitea.sh : gitea dump | s3 cp (10분 뒤 — 겹치지 않게) + ↓ +S3: awesomedev-mirim-backup-apne2/ + ├── postgres/*.sql.gz ← 30일 보관 후 자동 삭제 + └── gitea/*.zip ← 30일 보관 후 자동 삭제 ``` **3-2-1 원칙**: 3벌(원본·로컬·S3) / 2종 매체(EC2 디스크·S3) / 1벌 원격(S3) @@ -23,27 +28,62 @@ S3: awesomedev-mirim-backup-apne2/postgres/ ← 30일 보관 후 자동 삭제 | **액세스 키 대신 IAM 역할** | 키를 파일에 적으면 유출 시 끝. 역할(`mirim-backup-role`)은 이 서버에서만, 이 버킷의 `postgres/` 에만 쓸 수 있다 (최소 권한) | | **cron 대신 systemd timer** | Amazon Linux 2023에 cron이 없기도 하고, 타이머는 실행 이력이 journalctl에 남고 `Persistent=true`로 서버가 꺼졌던 시간대 작업도 따라잡는다 | | **SQL 덤프(pg_dump)** | 파일 복사가 아니라 "다시 만드는 SQL"이라 PG 버전이 달라도 복원되고, 텍스트라 gzip이 잘 먹는다 (8.5MB → 102KB) | +| **Gitea는 볼륨 tar가 아니라 `gitea dump`** | Gitea는 저장소 파일 + SQLite DB(이슈·PR·계정) + 설정이 한 몸이다. 돌아가는 중에 tar로 묶으면 "파일은 새 것, DB는 옛 것"처럼 시점이 어긋날 수 있다. `gitea dump`는 셋을 일관된 시점으로 묶는다. → **앱이 자기 백업 도구를 제공하면 그걸 먼저 찾아본다** | ## 자주 쓰는 명령 ```bash -# 백업 목록 보기 +# 백업 목록 보기 (로컬 + S3) ~/mirim-app/deploy/restore-db.sh # 지금 즉시 백업 -sudo systemctl start mirim-backup.service +sudo systemctl start mirim-backup.service # DB +sudo systemctl start mirim-gitea-backup.service # Gitea # 백업 이력·로그 확인 sudo journalctl -u mirim-backup.service -n 30 +sudo journalctl -u mirim-gitea-backup.service -n 30 -# 다음 실행 예정 시각 -systemctl list-timers mirim-backup.timer +# 다음 실행 예정 시각 (둘 다) +systemctl list-timers 'mirim-*' -# 복원 (확인 프롬프트 있음. 복원 전 현재 상태를 자동으로 먼저 백업함) +# DB 복원 (확인 프롬프트 있음. 복원 전 현재 상태를 자동으로 먼저 백업함) ~/mirim-app/deploy/restore-db.sh mirim-2026-07-17_030000.sql.gz docker compose -f docker-compose.prod.yml restart backend # 복원 후 재시작 ``` +## Gitea 복원 방법 + +Gitea 복원은 자주 쓸 일이 아니고 단계가 많아 스크립트 대신 절차로 둔다. +(자동화하지 않는 것도 선택이다 — 드물게 쓰는 위험한 작업은 사람이 한 단계씩 확인하는 편이 안전하다.) + +```bash +# 1) 백업 받아서 풀기 +aws s3 cp s3://awesomedev-mirim-backup-apne2/gitea/gitea-2026-07-17_031000.zip /tmp/ +cd /tmp && unzip -q gitea-2026-07-17_031000.zip -d gitea-restore + +# 2) Gitea 중지 +cd ~/mirim-app/deploy && docker compose -f docker-compose.prod.yml stop gitea + +# 3) 저장소·설정·DB 되돌리기 (볼륨에 직접 씀 — sudo 필요) +V=/var/lib/docker/volumes/deploy_gitea-data/_data +sudo cp -a /tmp/gitea-restore/repos/. $V/git/repositories/ +sudo cp -a /tmp/gitea-restore/data/. $V/gitea/ +sudo cp /tmp/gitea-restore/app.ini $V/gitea/conf/app.ini +# gitea-db.sql → SQLite로 되돌리기 +sudo rm -f $V/gitea/gitea.db +docker run --rm -v deploy_gitea-data:/data -v /tmp/gitea-restore:/r alpine/sqlite \ + sh -c "sqlite3 /data/gitea/gitea.db < /r/gitea-db.sql" +sudo chown -R 1000:1000 $V + +# 4) 다시 시작 +docker compose -f docker-compose.prod.yml start gitea +``` + +> 저장소만 급히 살리면 되는 경우엔 훨씬 간단하다 — zip 안의 `repos/awesomedev/mirim-app.git`은 +> 그 자체로 완전한 bare 저장소라, `git clone repos/awesomedev/mirim-app.git` 하면 바로 소스가 나온다. +> **실제로 이 방법으로 복원 검증을 했다** (아래 참고). + ## 복원 리허설 (권장: 분기 1회) > **복원해 본 적 없는 백업은 백업이 아니다.** @@ -60,21 +100,46 @@ docker exec mirim-postgres psql -U mirim -d restore_test -c \ docker exec mirim-postgres psql -U mirim -d postgres -c 'DROP DATABASE restore_test;' ``` -**최초 검증 결과 (2026-07-17)**: 복원본과 운영 원본이 완전 일치 — -사용자 5 / 퀴즈문항 355 / 문서 17 / 체크리스트 46 / 코딩문제 20 ✅ +Gitea도 같은 방식으로 검증할 수 있다 (백업 속 저장소에서 직접 clone): + +```bash +F=$(ls -t ~/backups/gitea-*.zip | head -1) +mkdir -p ~/gtest && cd ~/gtest && unzip -qo $F 'repos/*' +docker run --rm --entrypoint sh -v ~/gtest:/w -w /w alpine/git:latest -c ' + git config --global --add safe.directory "*" + git clone -q repos/awesomedev/mirim-app.git restored && cd restored + git log --oneline -3; git rev-list --count HEAD' +sudo rm -rf ~/gtest +``` + +**최초 검증 결과 (2026-07-17)** + +| 대상 | 결과 | +|---|---| +| PostgreSQL | 임시 DB에 복원 → 운영 원본과 **완전 일치** (사용자 5 / 퀴즈 355 / 문서 17 / 체크리스트 46 / 코딩 20) ✅ | +| Gitea | 백업 속 저장소에서 clone 성공 → HEAD·커밋 20개·파일 269개가 운영과 **완전 일치** ✅ | ## 무엇이 백업되고, 무엇이 안 되나 | 대상 | 백업 | 비고 | |---|---|---| -| 학생 진도·제출물·퀴즈 성적·코딩 제출 | ✅ | **이게 진짜 자산** — 코드에 없는 유일한 데이터 | -| 사용자 계정(비밀번호 해시 포함) | ✅ | | -| 코스·문서·퀴즈 문항·체크리스트 | ✅ | (없어도 시드로 재생성 가능) | -| **Gitea 저장소** | ❌ | 별도 볼륨(`gitea-data`). 필요하면 백업 추가 검토 | -| 소스 코드 | ❌ | Gitea + 로컬에 있음 | +| 학생 진도·제출물·퀴즈 성적·코딩 제출 | ✅ postgres | **이게 진짜 자산** — 코드에 없는 유일한 데이터 | +| 플랫폼 사용자 계정(비밀번호 해시) | ✅ postgres | | +| 코스·문서·퀴즈 문항·체크리스트 | ✅ postgres | (없어도 시드로 재생성 가능) | +| Git 저장소(소스·전체 이력) | ✅ gitea | 개발자 PC에도 clone 사본이 있어 이중 안전 | +| **Gitea 이슈·PR 리뷰 코멘트** | ✅ gitea | **Gitea에만 있는 것** — 잃으면 복구 불가 | +| Gitea 계정·권한·설정 | ✅ gitea | | +| EC2 서버 설정 자체 | ❌ | 재구축은 `deploy/` + `DEPLOY` 문서로 가능 | + +> 백업 설계의 출발점은 **"무엇이 이 서버에만 있는가"**를 묻는 것이다. +> 소스 코드는 git의 분산 구조 덕에 개발자 PC마다 사본이 있지만, +> **이슈·PR 코멘트·학생 제출물**은 이 서버에만 있다 — 그래서 이 둘을 지킨다. ## 비용 -- S3 저장: 102KB × 30일 ≈ **3MB** → 사실상 $0 (월 몇 원) -- 데이터 전송: 업로드는 무료 -- **총 추가 비용 ≈ $0** +| 항목 | 크기 | 비용 | +|---|---|---| +| postgres 백업 | 102KB × 30일 ≈ 3MB | ~$0 | +| gitea 백업 | 2.8MB × 30일 ≈ 84MB | ~$0.002/월 | +| 업로드 전송 | — | 무료 | +| **합계** | ~87MB | **월 몇 원 (≈$0)** | diff --git a/deploy/backup-gitea.sh b/deploy/backup-gitea.sh new file mode 100644 index 0000000..786b4ca --- /dev/null +++ b/deploy/backup-gitea.sh @@ -0,0 +1,67 @@ +#!/bin/bash +# 이 파일이 하는 일: 사내 Git 서버(Gitea)를 통째로 백업해 S3에 올린다. +# systemd timer가 매일 새벽 3시 10분(KST)에 실행한다. (DB 백업 10분 뒤 — 겹치지 않게) +# +# 학습 포인트 ① — 왜 볼륨을 그냥 tar로 묶지 않고 `gitea dump`를 쓰나? +# Gitea는 세 가지가 한 몸이다: 저장소 파일(/data/git) + SQLite DB(이슈·PR·계정) + 설정. +# 돌아가는 중에 tar로 묶으면 "파일은 새 것, DB는 옛 것" 같은 어긋난 시점이 섞일 수 있다. +# gitea dump는 이 셋을 일관된 시점으로 묶어 zip 하나로 만들어 준다. +# → 교훈: 애플리케이션이 자기 백업 도구를 제공하면 그걸 먼저 찾아본다. +# "파일만 복사하면 되겠지"가 통하지 않는 경우가 생각보다 많다(DB, 검색엔진 등). +# +# 학습 포인트 ② — 무엇을 지키려는 백업인가? +# 소스 코드 자체는 개발자 PC마다 clone 사본이 있어 사실 덜 급하다(git의 분산 구조!). +# 진짜 잃으면 아픈 건 Gitea에만 있는 것들: 이슈, PR 리뷰 코멘트, 계정, 권한 설정. +# "무엇이 이 서버에만 있는가"를 묻는 것이 백업 설계의 출발점이다. +set -euo pipefail + +BUCKET="awesomedev-mirim-backup-apne2" +CONTAINER="mirim-gitea" +BACKUP_DIR="/home/ec2-user/backups" +LOCAL_KEEP_DAYS=7 # 로컬 사본 보관 (S3는 30일 — 수명주기 규칙이 자동 삭제) + +TIMESTAMP="$(date +%Y-%m-%d_%H%M%S)" +FILENAME="gitea-${TIMESTAMP}.zip" +LOCAL_PATH="${BACKUP_DIR}/${FILENAME}" + +mkdir -p "$BACKUP_DIR" + +echo "[$(date '+%F %T')] Gitea 백업 시작" + +# ── 1) 컨테이너 안에서 dump 생성 ── +# 학습 포인트: -u git — Gitea 프로세스를 돌리는 사용자로 실행해야 파일 권한이 꼬이지 않는다. +# --file 로 이름을 지정하고, /tmp에 만든다(컨테이너가 지워지면 같이 사라지는 임시 공간). +docker exec -u git "$CONTAINER" gitea dump --file "/tmp/${FILENAME}" --quiet --work-path /data/gitea + +# ── 2) 컨테이너 밖으로 꺼내기 ── +# 학습 포인트: docker cp 는 컨테이너 안팎으로 파일을 옮긴다. +# 컨테이너는 언제든 지워질 수 있는 존재라, 백업을 그 안에 두면 백업이 아니다. +docker cp "${CONTAINER}:/tmp/${FILENAME}" "$LOCAL_PATH" +docker exec -u git "$CONTAINER" rm -f "/tmp/${FILENAME}" # 컨테이너 안 임시본은 지운다 + +# ── 3) 결과 검증 ── +# 명령이 성공했다고 결과물이 쓸모 있는 건 아니다. 크기와 zip 무결성을 확인한다. +SIZE=$(stat -c%s "$LOCAL_PATH") +if [ "$SIZE" -lt 10000 ]; then + echo "[오류] 백업 파일이 너무 작습니다(${SIZE} bytes). 실패로 간주하고 중단합니다." + rm -f "$LOCAL_PATH" + exit 1 +fi +# unzip -t : 압축 파일이 깨지지 않았는지 검사 (풀지 않고 검증만) +if ! unzip -tq "$LOCAL_PATH" > /dev/null 2>&1; then + echo "[오류] zip 무결성 검사 실패. 손상된 백업이므로 올리지 않습니다." + rm -f "$LOCAL_PATH" + exit 1 +fi +echo " 덤프 완료: ${FILENAME} ($(numfmt --to=iec "$SIZE")) — zip 무결성 OK" + +# ── 4) S3 업로드 ── +# 액세스 키가 이 파일 어디에도 없다 — EC2에 붙인 IAM 역할이 임시 자격증명을 자동 제공한다. +aws s3 cp "$LOCAL_PATH" "s3://${BUCKET}/gitea/${FILENAME}" --only-show-errors +echo " S3 업로드 완료: s3://${BUCKET}/gitea/${FILENAME}" + +# ── 5) 오래된 로컬 사본 정리 ── +find "$BACKUP_DIR" -name "gitea-*.zip" -mtime "+${LOCAL_KEEP_DAYS}" -delete +echo " 로컬 사본 ${LOCAL_KEEP_DAYS}일 초과분 정리 완료" + +echo "[$(date '+%F %T')] Gitea 백업 성공 ✅"