SOKUREE/smart_ims

Fork 0

choibk bc16a84db5 릴리즈 v0.4.0: 프리미엄 랜딩 페이지 및 사용자 환경 설정 기능 도입

2026-01-25 00:27:40 +09:00

6.1 KiB

Raw Blame History

🏷️ Git 운영 및 통합 업데이트 관리 규칙

이 문서는 Smart IMS 플랫폼의 Git 운영 정책, 태그 작성 규칙, 그리고 운영 서버 수동 업데이트 방법을 설명합니다.

1. 태그 메시지 작성 규칙 (Changelog 자동 생성)

플랫폼의 업데이트 엔진은 태그 메시지의 **머리말(Prefix)**과 **리스트 기호(-, *)**를 분석하여 관리 페이지의 업데이트 히스토리를 생성합니다.

📋 메시지 구조

[TYPE] 업데이트 제목 (한 줄 요약)
- 상세 변경 내용 1
- 상세 변경 내용 2
* 상세 변경 내용 3

🏷️ 업데이트 타입 (TYPE) 정의

키워드	업데이트 유형	시각적 표시	비고
`[URGENT]`	긴급/보안	빨간색 배너	최우선 업데이트 권장
`[HOTFIX]`	긴급 수정	빨간색 배너	버그 즉시 수정 건
`[FEATURE]`	기능 추가	남색(Indigo)	새로운 기능 도입
`[FIX]`	일반 수정	회색(Slate)	일반적인 버그 수정
`[PATCH]`	패치/보정	회색(Slate)	마이너 품질 개선

2. 개발 및 배포 절차 (개발 PC)

개발 작업 및 태그 생성은 아래 경로에서 진행합니다.

작업 경로: d:\antigravity\smartims (윈도우 개발 환경 기반)

STEP 1: 코드 변경 사항 커밋 및 푸시

# [위치: d:\antigravity\smartims (루트)]
git add .
git commit -m "릴리즈 준비: v0.4.0 패치"
git push origin main

STEP 2: 어노테이티드 태그(Annotated Tag) 생성

# [위치: d:\antigravity\smartims (루트)]
git tag -a v0.4.0 -m "[PATCH] 시스템 안정화 패치
- 원격 태그 동기화 로직 강화
- API 캐시 방지 타임스탬프 도입"

STEP 3: 원격 저장소에 태그 푸시

# [위치: d:\antigravity\smartims (루트)]
git push origin v0.4.0

3. 운영 서버 수동 업데이트 통합 공정 [작업 전 필수 확인]

운영 환경에서 작업을 수행할 때는 반드시 아래 순서를 1번부터 차례대로 수행하십시오. 단계를 건너뛸 경우 데이터 유실 시 복구가 불가능합니다.

🚨 [STEP 1] 데이터 백업 (무조건 수행 - 예외 없음)

업데이트 명령을 입력하기 전, 현재의 이미지 파일과 데이터베이스를 안전 경로(/volume1/backup/smart_ims)로 격리합니다.

1-1. 업로드 파일(이미지/매뉴얼) 백업

# [실행 위치: /volume1/web/smartims]
# 이 명령은 등록된 모든 자산 이미지를 압축하여 보관합니다.
tar -czvf /volume1/backup/smart_ims/backup_images_$(date +%Y%m%d).tar.gz server/uploads/

1-2. 데이터베이스(DB) 전체 백업

# [실행 위치: /volume1/web/smartims]
# DB명: sokuree_platform_prod, 포트: 3307 사용
/usr/local/mariadb10/bin/mysqldump -u choibk -p --port 3307 sokuree_platform_prod > /volume1/backup/smart_ims/backup_db_$(date +%Y%m%d).sql

주의: 비밀번호 요청 시 .env 파일의 DB_PASSWORD(^Ocean...)를 입력하세요.

🚀 [STEP 2] 버전 동기화 및 코드 반영

백업이 완료된 것이 확인된 경우에만 아래 명령어를 실행하여 소스를 업데이트합니다.

# [실행 위치: /volume1/web/smartims]

# 1. 원격 저장소의 태그 목록 확인 (배포된 최신 버전이 무엇인지 체크)
git ls-remote --tags origin

# 2. 로컬 태그 정보를 원격과 완벽히 일치 (강제 동기화)
git fetch origin +refs/tags/*:refs/tags/* --force --prune --prune-tags

# 3. 목표 버전으로 소스 코드 강제 전환 (예: v0.4.0)
# [주의] 이 명령 실행 시 추적되지 않은 소스 수정사항은 사라집니다.
git checkout -f v0.4.0

🏗️ [STEP 3] 시스템 빌드 및 서비스 재시작

코드가 반영되었다면 변경된 내용을 적용하기 위해 빌드와 프로세스를 갱신합니다.

3-1. 프론트엔드 빌드

# [실행 위치: /volume1/web/smartims]
npm install && npm run build

3-2. 백엔드 반영 및 PM2 재시작

# [실행 위치: /volume1/web/smartims/server]
cd server
npm install
pm2 reload smartims-api

🆘 [STEP 4] 비상시 복구 절차 (Emergency Restore)

만약 업데이트 후 시스템이 작동하지 않거나 데이터가 보이지 않을 경우에만 수행합니다.

4-1. 이미지 파일 복원

# [실행 위치: /volume1/web/smartims]
# 작업 당일 생성한 압축파일 이름을 확인하여 입력하세요.
tar -xzvf /volume1/backup/smart_ims/backup_images_[날짜].tar.gz -C ./

4-2. 데이터베이스(DB) 복원

# [실행 위치: /volume1/web/smartims]
/usr/local/mariadb10/bin/mysql -u choibk -p --port 3307 sokuree_platform_prod < /volume1/backup/smart_ims/backup_db_[날짜].sql

4. 유용한 Git 명령어 레퍼런스

태그 목록 확인: git tag -l (모든 환경의 루트 폴더)
최신 태그 정보 확인: git describe --tags --abbrev=0

원격 태그 강제 덮어쓰기 (메시지 수정 시):

# [위치: 개발 PC 루트]
git tag -a v0.4.0 -f -m "수정된 메시지..."
git push origin v0.4.0 -f

💡 최종 주의사항 (Must Read)

DB 계정 확인: -u choibk 계정은 본 시스템 전용 계정입니다. 운영 서버 접속 시 root 권한이더라도 DB 작업은 choibk로 수행해야 권한 꼬임이 없습니다.
경로 이동 주의: cd server 이동 후 빌드가 끝나면 cd ..를 통해 반드시 루트로 돌아오십시오.
수동 설치 주의: git clone을 새로 받아 설치할 때는 기존 uploads 폴더가 포함되어 있지 않으므로 반드시 위 STEP 4-1 복구 절차를 통해 이미지를 채워넣어야 합니다.
자동 업데이트 정책: 시스템 관리 메뉴의 **[자동 업데이트]**는 내부적으로 소스 코드만 갱신하며 uploads 폴더는 건드리지 않습니다. 따라서 자동 업데이트 시에는 별도의 이미지 복구가 필요 없습니다.

6.1 KiB Raw Blame History