# 운영 서버 배포 및 관리 가이드 (Production Deployment Guide)

본 문서는 SmartIMS 솔루션을 운영 서버에 최초 설치하는 절차와 Git Tag를 이용한 효율적인 버전 관리 및 업데이트 방역에 대해 설명합니다.

---

## 1. 개요 (Overview)

SmartIMS 배포는 **Git Tag 기반 배포** 방식을 권장합니다. 이는 검증된 특정 시점의 소스 코드(Release)만을 운영 서버에 반영하여 시스템 안정성을 확보하고, 향후 시스템 관리 메뉴를 통해 손쉽게 업데이트할 수 있는 기반을 제공합니다.

---

## 2. 최초 설치 절차 (Initial Installation)

운영 서버(Linux/Synology 등)에 접속한 상태에서 다음 과정을 순차적으로 진행합니다.

### 2.1. 사전 요구 사항
*   **Git**: 소스 코드 동기화용
*   **Node.js**: v20 이상 환경
*   **MySQL/MariaDB**: 서비스 데이터베이스
*   **PM2**: 서비스 프로세스 관리 (`npm install -g pm2`)

### 2.2. 설치 단계
1.  **소스 클론**:
    `/volume1/web` 위치에서 아래 명령어를 실행하면 `smartims` 폴더가 생성되며 그 안에 소스가 들어갑니다.
    ```bash
    cd /volume1/web
    # 저장소 URL 뒤에 'smartims'를 붙여 폴더명을 지정합니다.
    git clone https://gitea.qideun.com/SOKUREE/smart_ims.git smartims
    cd smartims
    ```
2.  **안정 버전(Tag) 전환**:
    ```bash
    git fetch --all --tags
    # v0.2.6 버전으로 전환
    git checkout v0.2.6
    ```
3.  **환경 설정**:
    *   `server/.env` 파일을 환경에 맞게 생성(DB 정보 등 입력).
    *   `server/config/public_key.pem` 파일이 존재하는지 확인 (라이선스 검증용).
4.  **패키지 설치 및 빌드**:
    ```bash
    # 전체 의존성 설치 및 프론트엔드 빌드
    npm install
    npm run build

    # 백엔드 의존성 설치
    cd server
    npm install
    ```
5.  **데이터베이스 초기화**:
    ```bash
    # 처음 설치 시에만 수행
    node migrate_db.js
    ```
6.  **PM2 프로세스 등록**:
    ```bash
    pm2 start index.js --name "smartims-api"
    pm2 save
    pm2 startup
    ```

---

## 3. 업데이트 관리 (Update Management)

### 3.1. 기존 수동 업데이트 방법
수동으로 업데이트가 필요할 경우 다음 명령어를 조합하여 실행합니다.
```bash
git fetch --tags
git checkout [새로운_태그]
npm install
npm run build
pm2 reload smartims-api
```

### 3.2. 시스템 관리 메뉴를 통한 업데이트 (지원됨)
시스템의 **"시스템 관리 > 버전 정보"** 화면에서 신규 버전을 감지하고 원 클릭으로 업데이트할 수 있습니다.

*   참고: 이 기능을 사용하려면 **[기본 설정]** 메뉴에서 Gitea 원격 저장소 URL과 (필요 시) 계정 정보를 먼저 설정해야 합니다.

*   **동작 원리**:
    1.  서버가 설정된 원격 저장소의 최신 Tag 리스트를 확인합니다.
    2.  `package.json`의 현재 버전과 원격의 최신 Tag를 비교합니다.
    3.  업데이트 실행 시 서버가 백그라운드에서 `git checkout` -> `npm install` -> `npm run build` -> `pm2 reload` 과정을 자동으로 수행합니다.

*   **기대 효과**:
    *   터미널(SSH) 접속 없이 관리자 화면에서 즉시 최신 기능 반영 가능.
    *   운영 서버 환경에서도 편리한 버전 관리.

---

## 4. 주의 사항 (Precautions)

1.  **보안**: `tools/` 폴더 및 개인키(`private_key.pem`)는 운영 서버에 절대로 포함되지 않도록 주의하십시오.
2.  **권한**: 업데이트 자동화 스크립트 실행 시 파일 시스템 쓰기 권한 및 Git 접근 권한이 서버 프로세스에 부여되어 있어야 합니다.
3.  **백업**: 업데이트 전에 데이터베이스 백업을 반드시 수행할 것을 권장합니다.

---
마지막 업데이트: 2026-01-24