101 lines
3.8 KiB
Markdown
101 lines
3.8 KiB
Markdown
# 운영 서버 배포 및 관리 가이드 (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
|