SOKUREE/smart_ims

Fork 0

choibk aa12234bd1 운영 가이드 수정: 시놀로지 MariaDB 10 권한 오류 해결을 위해 전용 계정(choibk) 및 포트(3307) 정보 반영

2026-01-25 00:09:29 +09:00

6.3 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.3.5 패치"
git push origin main

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

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

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

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

3. 운영 서버 수동 업데이트 방법 (Production Server)

웹 UI 업데이트가 실패하거나 SSH를 통해 직접 서버에서 제어해야 할 경우 사용합니다.

서비스 경로: /volume1/web/smartims (리눅스 운영 환경 기반)

STEP 1: 원격 정보 확인 및 체크아웃

# [위치: /volume1/web/smartims (루트)]

# 1. 원격 저장소의 최신 태그 목록 확인 (무엇이 최신인지 먼저 확인)
git ls-remote --tags origin

# 2. 태그 정보 강제 업데이트 (원격 저장소와 완벽 동기화)
git fetch origin +refs/tags/*:refs/tags/* --force --prune --prune-tags

# 3. 대상 버전으로 강제 체크아웃
git checkout -f v0.3.5

STEP 2: 프론트엔드 빌드 및 의존성 업데이트

# [위치: /volume1/web/smartims (루트)]
npm install
npm run build

STEP 3: 백엔드 반영 및 서비스 재시작

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

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

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

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

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

5. 데이터 백업 및 복구 절차 (시놀로지 전용)

자동 업데이트는 데이터를 안전하게 유지하지만, 만약의 사태나 서버 이전을 위해 현재 운영 중인 백업 폴더(/volume1/backup/smart_ims)를 활용한 절차를 안내합니다.

✅ 자동 업데이트 시 데이터 안전성

파일 안전: 시스템 관리 메뉴를 통한 [자동 업데이트] 실행 시, server/uploads 폴더는 Git 추적 제외 대상이므로 삭제되거나 초기화되지 않고 그대로 유지됩니다.
DB 안전: 업데이트 시 기존 데이터베이스의 테이블 구조만 업데이트하며, 이미 등록된 자산 데이터는 보존됩니다.

📦 데이터 백업 절차 (Backup)

운영 서버 SSH 터미널에서 실행하여 지정된 백업 폴더에 저장합니다.

1단계: 업로드 이미지 백업

# [위치: /volume1/web/smartims]
tar -czvf /volume1/backup/smart_ims/backup_images_$(date +%Y%m%d).tar.gz server/uploads/

2단계: 데이터베이스(DB) 백업

시놀로지 MariaDB 10은 보안상 root 접근보다 서비스 전용 계정 사용을 권장하며, 기본 포트가 3307인 경우가 많습니다.

# [위치: /volume1/web/smartims]
# .env에 등록된 사용자(choibk)와 포트(3307)를 명시하여 백업
/usr/local/mariadb10/bin/mysqldump -u choibk -p --port 3307 smartims > /volume1/backup/smart_ims/backup_db_$(date +%Y%m%d).sql

🔄 데이터 복구 절차 (Restore / Recovery)

서버 재설치 등으로 데이터 복구가 필요한 경우 아래 순서대로 실행합니다.

1단계: 이미지 복구 (압축 해제)

# [위치: /volume1/web/smartims]
tar -xzvf /volume1/backup/smart_ims/backup_images_[날짜].tar.gz -C ./

2단계: 데이터베이스(DB) 복원

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

💡 최종 주의사항

DB 계정 확인: 위 명령어의 -u choibk는 본 시스템의 데이터베이스 사용자명입니다. 비밀번호 요청 시 .env 파일에 기록된 DB_PASSWORD를 입력하십시오.
실행 위치 확인: 특히 pm2 명령어나 server 관련 설정은 반드시 server 폴더 내에서 실행하거나 경로를 정확히 지정해야 합니다.
경로 이동 주의: cd server를 통해 폴더를 이동하여 작업을 마친 후에는 반드시 cd ..를 통해 다시 루트 폴더로 복귀하여 다음 작업에 혼선이 없도록 합니다.
권한 관리: 운영 서버에서는 반드시 서비스 실행 권한을 가진 계정으로 명령어를 실행해야 PM2 프로세스 관리에 문제가 생기지 않습니다.
수동 설치 주의: git clone을 새로 받아 설치할 때는 기존 uploads 폴더가 포함되어 있지 않으므로 반드시 위 복구 절차를 통해 데이터를 복구해야 자산 이미지가 나타납니다.

6.3 KiB Raw Blame History