smart_ims/docs/operation/ENVIRONMENT_SETUP.md

SmartIMS 환경 설정 가이드 (Environment Setup Guide)

본 문서는 SmartIMS의 개발 환경(Windows)과 운영 환경(Synology NAS) 설정을 관리하기 위한 지침을 제공합니다.

---

1. 환경별 주요 설정 (.env)

server/.env 파일은 프로젝트의 핵심 설정을 담고 있습니다. 환경에 따라 아래 주석을 참고하여 값을 변경하세요.

1.1 데이터베이스 (MariaDB)

변수명	개발 환경 (Windows)	운영 환경 (Synology)	설명
DB_HOST	localhost 또는 sokuree.com	localhost	DB 서버 주소
DB_PORT	3307 (Docker/XAMPP 등)	3306 (기본값)	MariaDB 접속 포트
DB_NAME	sokuree_platform_dev	sokuree_platform_prod	사용할 DB 이름

1.2 시스템 및 보안

• PORT: 백엔드 서버 포트 (기본값: 3005). Synology 서비스와 충돌 시 변경 가능.
• SESSION_SECRET: 세션 암호화 키. 운영 환경에서는 고유한 긴 문자열로 변경 권장.
• LICENSE_MANAGER_URL: 라이선스 서버 주소.

---

2. 개발 및 운영 환경 차이점 정리

2.1 스트리밍 전송 모드 (CCTV_TRANSPORT_OVERRIDE)

• 개발(Windows): auto 또는 udp 사용. (TCP 사용 시 권한 문제로 스트리밍이 끊길 수 있음)
• 운영(NAS): tcp 권한이 안정적이므로 tcp 설정을 권장합니다.

2.2 API 프록시 (Vite)

• 개발 시에는 vite.config.ts의 proxy 설정을 통해 프론트엔드가 백엔드(localhost:3005)와 통신합니다.
• 운영 시에는 npm run build로 생성된 dist 폴더를 Node.js(Express)가 직접 서빙하므로 프록시 설정이 필요 없으며 동일 포트에서 동작합니다.

2.3 파일 경로 (Uploads)

• 업로드된 이미지는 server/uploads 디렉토리에 저장됩니다.
• 운영 환경으로 이전 시 이 디렉토리의 쓰기 권한이 Node.js 실행 계정에 있는지 확인해야 합니다.

---

3. 체크리스트: 자산 목록이 안 보일 때

1. 서버-DB 연결 확인: 서버 로그(npm start)에서 ✅ Connected to Database 메시지가 나오는지 확인하세요.
2. 모듈 활성화 확인: [시스템 관리] > [모듈/라이선스 관리] 메뉴에서 '자산 관리' 모듈이 활성화 상태인지 확인하세요.
3. 구독자 ID 일치: 라이선스 키 등록 시 사용된 구독자 ID(SKR-2024-...)가 [기본 설정]의 구독자 ID와 일치해야 합니다.
4. 브라우저 캐시: 프론트엔드 빌드 후 변경 사항이 반영되지 않으면 강력 새로고침(Ctrl + F5)을 수행하세요.