docs:ops-manual 누락 항목 보강 — DB 동기화, PM2, MySQL 업그레이드

- 10-backup-recovery: 개발→운영 DB 동기화 절차 추가 - 05-deployment: Jenkins env-files에 APP_ENV 컬럼 및 접두사 설명 추가 - 11-server-setup: 개발서버 PM2 설정, MySQL 8.0→8.4 업그레이드 절차 추가 - 11-server-setup: 개발서버 MySQL 버전 8.0.45→8.4.8 반영 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-25 04:33:12 +09:00
parent cba43034ef
commit 7922745bea
3 changed files with 125 additions and 6 deletions
--- a/deploys/ops-manual/05-deployment.md
+++ b/deploys/ops-manual/05-deployment.md
@@ -183,11 +183,13 @@ CI/CD Gitea push -> Webhook -> Jenkins

 **환경변수 파일 (CI/CD 서버):** /var/lib/jenkins/env-files/react/

-| 파일 | API URL | Frontend URL |
-|------|---------|-------------|
-| .env.develop | https://api.codebridge-x.com | https://dev.codebridge-x.com |
-| .env.stage | https://stage-api.sam.it.kr | https://stage.sam.it.kr |
-| .env.main | https://api.sam.it.kr | https://sam.it.kr |
+| 파일 | API URL | Frontend URL | APP_ENV |
+|------|---------|-------------|---------|
+| .env.develop | https://api.codebridge-x.com | https://dev.codebridge-x.com | development |
+| .env.stage | https://stage-api.sam.it.kr | https://stage.sam.it.kr | staging |
+| .env.main | https://api.sam.it.kr | https://sam.it.kr | production |
+
+> `NEXT_PUBLIC_APP_ENV` 값으로 타이틀 접두사 결정: `development` → `[D]`, `local` → `[L]`, 그 외 → 없음

 **rsync 주의:** trailing slash 사용 금지: `.next` (O), `.next/` (X)

--- a/deploys/ops-manual/10-backup-recovery.md
+++ b/deploys/ops-manual/10-backup-recovery.md
@@ -322,6 +322,48 @@ cd /home/webservice/api-stage/current && php artisan config:cache && php artisan

 ---

+## [개발→운영] DB 동기화
+
+개발서버(sam-dev)의 sam DB를 운영서버(sam-prod)의 sam DB로 복원하는 절차입니다.
+
+> ⚠️ **운영 데이터가 덮어쓰기됩니다.** 반드시 운영 백업 후 진행하세요.
+
+### 절차
+
+```bash
+# 1. 운영 DB 백업 (안전용, 운영 서버)
+ssh sam-prod "DB_PASS=\$(grep DB_PASSWORD /home/webservice/mng/shared/.env | head -1 | cut -d= -f2) && \
+  mysqldump -ucodebridge -p\$DB_PASS --no-tablespaces --skip-triggers --skip-routines sam | gzip > /home/webservice/backups/sam_prod_before_sync.sql.gz"
+
+# 2. 개발 DB 덤프 (개발 서버)
+ssh sam-dev "DB_PASS=\$(grep DB_PASSWORD /home/webservice/mng/.env | head -1 | cut -d= -f2) && \
+  mysqldump -ucodebridge -p\$DB_PASS --no-tablespaces --skip-triggers --skip-routines sam | gzip > /tmp/sam_dev.sql.gz"
+
+# 3. 로컬 경유 전송 (dev→local→prod)
+scp sam-dev:/tmp/sam_dev.sql.gz /tmp/sam_dev.sql.gz
+scp /tmp/sam_dev.sql.gz sam-prod:/tmp/sam_dev.sql.gz
+
+# 4. 운영 DB 복원
+ssh sam-prod "DB_PASS=\$(grep DB_PASSWORD /home/webservice/mng/shared/.env | head -1 | cut -d= -f2) && \
+  gunzip -c /tmp/sam_dev.sql.gz | mysql -ucodebridge -p\$DB_PASS sam"
+
+# 5. 검증
+ssh sam-prod "DB_PASS=\$(grep DB_PASSWORD /home/webservice/mng/shared/.env | head -1 | cut -d= -f2) && \
+  mysql -ucodebridge -p\$DB_PASS -e \"SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='sam';\""
+
+# 6. 임시 파일 정리
+ssh sam-dev "rm -f /tmp/sam_dev.sql.gz"
+ssh sam-prod "rm -f /tmp/sam_dev.sql.gz"
+rm -f /tmp/sam_dev.sql.gz
+```
+
+### 주의사항
+- 개발↔운영 서버 간 직접 SCP 불가 → 로컬 경유 전송
+- `codebridge` 유저 권한 제한으로 `--no-tablespaces --skip-triggers --skip-routines` 필수
+- 롤백: `/home/webservice/backups/sam_prod_before_sync.sql.gz` 사용
+
+---
+
 ## 전체 서버 복구 절차

 ### [운영] 복구 순서
--- a/deploys/ops-manual/11-server-setup.md
+++ b/deploys/ops-manual/11-server-setup.md
@@ -1188,7 +1188,7 @@ done
 | OS | Ubuntu 24.04.2 | Ubuntu 24.04 (kernel 6.8.0-100) |
 | CPU/RAM | 2C / 3.8GB (스왑 없음) | 2C / 8GB + 스왑 4GB |
 | PHP | 8.4.15 (+ 5.6, 7.3) | 8.4.18 |
-| MySQL | **8.0.45** | **8.4.8** |
+| MySQL | **8.4.8** | **8.4.8** |
 | Node.js | 22.17.1 | 22.17.1 |
 | Nginx | 1.24.0 | 1.24.0 |
 | Redis | - | 7.0.15 (512mb) |
@@ -1197,3 +1197,78 @@ done
 | Supervisor | - | queue worker ×2 |
 | UFW | **비활성** | 활성 |
 | fail2ban | - | ✅ |
+
+---
+
+## [개발] PM2 설정
+
+개발서버는 ecosystem.config.js 없이 PM2 CLI로 직접 관리합니다.
+
+```bash
+# 실행 (포트 3001, Gitea가 3000 사용)
+cd /home/webservice/react && pm2 start npm --name sam-react -- start -- -p 3001
+
+# 재부팅 자동 시작 등록
+pm2 save
+sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u hskwon --hp /home/hskwon
+```
+
+| 이름 | 모드 | 포트 | 비고 |
+|------|------|------|------|
+| sam-react | fork | 3001 | Gitea가 3000 사용, Jenkins 배포 시 자동 restart |
+
+---
+
+## [개발] MySQL 8.0 → 8.4 업그레이드 절차
+
+Ubuntu 24.04 APT 기본은 MySQL 8.0입니다. 8.4로 업그레이드하는 절차:
+
+### 사전 준비
+
+```bash
+# 1. DB 백업
+DB_PASS=$(grep DB_PASSWORD /home/webservice/mng/.env | head -1 | cut -d= -f2)
+for db in sam chandj sam_stat; do
+  mysqldump -ucodebridge -p$DB_PASS --no-tablespaces --skip-triggers --skip-routines $db | gzip > /tmp/${db}_backup.sql.gz
+done
+
+# 2. 인증 방식 변환 (mysql_native_password → caching_sha2_password)
+# 8.4에서 mysql_native_password가 deprecated
+mysql -u debian-sys-maint -p'<debian-sys-maint_비밀번호>' -e "
+  ALTER USER 'codebridge'@'localhost' IDENTIFIED WITH caching_sha2_password BY '<비밀번호>';
+  ALTER USER 'chandj'@'localhost' IDENTIFIED WITH caching_sha2_password BY '<비밀번호>';
+  FLUSH PRIVILEGES;"
+```
+
+> debian-sys-maint 비밀번호: `/etc/mysql/debian.cnf` 참조
+
+### 업그레이드 실행
+
+```bash
+# 3. MySQL 중지
+sudo systemctl stop mysql
+
+# 4. MySQL APT 레포 추가
+wget -q https://dev.mysql.com/get/mysql-apt-config_0.8.33-1_all.deb -O /tmp/mysql-apt-config.deb
+sudo DEBIAN_FRONTEND=noninteractive dpkg -i /tmp/mysql-apt-config.deb
+
+# 5. 레포를 8.4-lts로 변경
+sudo sed -i 's/mysql-8.0/mysql-8.4-lts/g' /etc/apt/sources.list.d/mysql.list
+sudo apt-get update
+
+# 6. 업그레이드 (기존 설정 유지)
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -o Dpkg::Options::="--force-confold" mysql-server mysql-client
+
+# 7. 시작 및 확인
+sudo systemctl start mysql
+mysql --version   # → 8.4.x 확인
+```
+
+### GPG 키 만료 시
+
+MySQL APT 레포의 GPG 키가 만료된 경우:
+
+```bash
+sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys B7B3B788A8D3785C
+# 또는 allow-insecure 임시 허용 후 설치
+```