feat:CI/CD Gitea 워크플로우 등 누락 파일 반영

운영구축_변경비교_보고서.md

@@ -0,0 +1,242 @@
+# ITAM 구축 방식 변경 비교 보고서
+
+## 1. 문서 목적
+
+이 문서는 ITAM 시스템의 Docker 기반 구축 방식이 초기 개발/테스트 중심 구조에서 현재 운영 배포 중심 구조로 어떻게 변경되었는지 설명하기 위한 보고용 문서다.
+
+이번 비교의 기준은 아래 두 단계다.
+
+1. 초기 구축 방식: Windows + WSL 환경에서 개발 및 테스트 재현을 목적으로 한 Docker 구조
+2. 현재 구축 방식: 정식 운영 배포를 고려하여 production 기준으로 정리한 Docker 구조
+
+즉, 이 문서는 “예전 계획안과 지금 계획안의 차이”가 아니라, “처음 구축했던 개발/테스트용 구조와 현재 운영 배포용 구조의 차이”를 설명하는 문서다.
+
+---
+
+## 2. 한눈에 보는 핵심 변화
+
+초기 구축은 아래 목적에 맞춰져 있었다.
+
+1. Windows PC에서 WSL2를 이용해 빠르게 실행할 수 있어야 한다.
+2. 현재 개발 구조를 그대로 Docker 안에서 재현해야 한다.
+3. 프런트와 백엔드가 개발용 방식으로 동작하면 된다.
+
+반면 현재 구축은 아래 목적에 맞춰 변경되었다.
+
+1. 실제 운영 배포에 사용할 수 있어야 한다.
+2. 프런트는 개발 서버가 아니라 정적 빌드 산출물로 서비스되어야 한다.
+3. reverse proxy, health check, 운영용 Dockerfile, 운영용 compose 기준이 정리되어야 한다.
+4. 운영 과정에서 경로, 정적 자산, 로그, 환경변수 사용 방식이 명확해야 한다.
+
+즉, 초기에는 “개발 재현”이 목적이었고, 현재는 “운영 배포 가능 상태로 정리”하는 것이 목적이다.
+
+---
+
+## 3. 구조 비교도
+
+### 3.1 초기 구축 구조
+
+```mermaid
+flowchart LR
+  U["User Browser"] --> FE["Frontend Container Vite Dev 8080"]
+  FE -->|api proxy| BE["Backend Container Express 3000"]
+  BE --> DB["External MySQL 3306"]
+  BE --> UP["./uploads"]
+  BE --> CFG["./map_config.json"]
+  ENV["./.env"] --> BE
+  linkStyle default stroke:#d32f2f,stroke-width:2px;
+```
+
+### 3.2 현재 구축 구조
+
+```mermaid
+flowchart LR
+  U["User Browser"] --> RP["Nginx Reverse Proxy 80"]
+  RP --> FE["Frontend Container Static Nginx 80"]
+  RP -->|api| BE["Backend Container Node 3000"]
+  RP -->|uploads| BE
+  BE --> DB["External MySQL 3306"]
+  BE --> UP["./uploads"]
+  BE --> CFG["./map_config.json"]
+  ENV["./.env"] --> BE
+  LOGS["./logs/nginx"] --> RP
+  linkStyle default stroke:#d32f2f,stroke-width:2px;
+```
+
+---
+
+## 4. 비교 요약표
+
+| 구분 | 초기 구축 방식 | 현재 구축 방식 |
+|---|---|---|
+| 구축 목적 | Windows/WSL 개발 테스트 재현 | 정식 운영 배포 기준 정리 |
+| 프런트 실행 방식 | Vite dev server | 빌드된 정적 파일 + Nginx |
+| 프런트 포트 | 8080 | 80 |
+| 백엔드 | Express API 컨테이너 | Express API 컨테이너 |
+| 프록시 구조 | frontend 내부 dev proxy | 외부 nginx reverse proxy |
+| 운영용 compose | 없음 또는 개발형 중심 | `docker-compose.prod.yaml` 별도 구성 |
+| 테스트용 compose | `docker-compose.yaml` 중심 | `docker-compose.test.yaml` 별도 구성 |
+| 정적 자산 처리 | 개발 서버가 직접 참조 | 운영 이미지에 정적 자산 포함 필요 |
+| health check | 사실상 없음 | `/health`, `/ready` 기반 포함 |
+| 운영 관점 기능 | 낮음 | 높음 |
+
+---
+
+## 5. 초기 구축 방식 설명
+
+초기 구축은 Windows + WSL 환경에서 “지금 돌아가는 개발 구조를 Docker로 그대로 재현”하는 것이 핵심이었다.
+
+주요 특징은 아래와 같다.
+
+1. 프런트는 `Dockerfile.frontend`를 통해 Vite 개발 서버를 컨테이너에서 실행했다.
+2. 백엔드는 `Dockerfile.backend`를 통해 Express API 서버를 컨테이너로 실행했다.
+3. 프런트는 `VITE_DEV_PROXY_TARGET`을 이용해 `/api` 요청을 `backend:3000`으로 전달했다.
+4. 접속 포트는 `http://localhost:8080`이었다.
+5. 목적은 운영 배포가 아니라 개발/시연/테스트 재현이었다.
+
+즉, 이 단계에서 중요한 것은 “실제 앱이 개발 환경과 최대한 비슷하게 동작하는가”였다.
+
+---
+
+## 6. 현재 구축 방식 설명
+
+현재 구축은 정식 운영 배포에 맞게 구조를 보강한 상태다.
+
+주요 특징은 아래와 같다.
+
+1. 프런트는 `Dockerfile.frontend.prod`에서 multi-stage build를 통해 정적 파일로 빌드된다.
+2. 빌드 산출물은 frontend 컨테이너 내부 Nginx가 서빙한다.
+3. 별도의 nginx reverse proxy가 외부 80 포트를 받아 frontend와 backend로 요청을 분기한다.
+4. backend는 `Dockerfile.backend.prod`를 사용하며, 비루트 사용자와 health check를 포함한다.
+5. 운영용 `docker-compose.prod.yaml`과 검증용 `docker-compose.test.yaml`이 분리되어 있다.
+6. 정적 이미지 자산과 로고 파일도 운영 이미지에 포함되도록 보완되었다.
+
+즉, 현재는 단순 개발 재현이 아니라 “운영에 투입 가능한 형태로 구조를 정리”한 상태다.
+
+---
+
+## 7. 주요 변경 포인트 상세
+
+### 7.1 프런트 실행 방식 변경
+
+초기 구축:
+
+1. Vite 개발 서버를 그대로 띄웠다.
+2. 코드 수정과 빠른 재확인에 유리했다.
+3. 운영 배포용 웹 서버 구조는 아니었다.
+
+현재 구축:
+
+1. `npm run build` 결과물을 사용한다.
+2. frontend 컨테이너 내부 Nginx가 정적 파일을 서빙한다.
+3. 운영 환경에서 더 안정적인 구조다.
+
+이 차이는 개발 중심 구조에서 운영 중심 구조로 넘어갔다는 것을 가장 잘 보여준다.
+
+### 7.2 프록시 구조 변경
+
+초기 구축:
+
+1. 프런트 컨테이너 내부에서 dev proxy가 `/api`를 backend로 우회했다.
+2. 구조가 단순했지만 운영형 reverse proxy는 아니었다.
+
+현재 구축:
+
+1. 외부 nginx가 진입점 역할을 한다.
+2. `/`는 frontend, `/api`와 `/uploads`는 backend로 분기한다.
+3. 운영형 라우팅 구조를 갖추게 되었다.
+
+### 7.3 compose 구성 분리
+
+초기 구축:
+
+1. 사실상 개발용 compose 중심이었다.
+2. 운영 목적과 검증 목적이 명확히 분리되지 않았다.
+
+현재 구축:
+
+1. `docker-compose.test.yaml`은 운영형 구조 검증용
+2. `docker-compose.prod.yaml`은 운영 모드 기동용
+3. 목적에 따라 compose 파일이 구분된다.
+
+### 7.4 백엔드 운영성 강화
+
+초기 구축:
+
+1. 백엔드는 단순 실행 중심이었다.
+2. 운영 상태 확인이나 readiness 기준이 부족했다.
+
+현재 구축:
+
+1. `/health`, `/ready` 엔드포인트 추가
+2. `dumb-init` 적용
+3. 비루트 계정 실행
+4. health check 포함
+
+즉, 장애 확인과 운영 점검이 가능한 상태로 바뀌었다.
+
+### 7.5 정적 자산 보강
+
+초기 구축:
+
+1. 개발 환경에서는 파일이 로컬에 그대로 있어 지도 이미지와 로고가 직접 보였다.
+2. 운영 이미지 기준으로는 정적 자산 누락 가능성이 드러나지 않았다.
+
+현재 구축:
+
+1. `img/location_photo/...` 경로의 지도 이미지 포함
+2. `/image 92.png` 로고 파일 포함
+3. 운영 이미지에서도 실제 화면이 깨지지 않도록 보완 완료
+
+즉, 현재 구축은 운영 화면 품질까지 고려한 상태다.
+
+---
+
+## 8. 왜 이렇게 바뀌었는가
+
+초기 단계에서는 다음이 중요했다.
+
+1. 빠르게 실행되는가
+2. 개발 PC에서 재현 가능한가
+3. 기존 코드 구조를 크게 안 건드리고 Docker 안에서 띄울 수 있는가
+
+하지만 운영 배포 기준으로는 다음이 추가로 필요했다.
+
+1. 개발 서버가 아니라 정적 배포 구조여야 함
+2. reverse proxy가 있어야 함
+3. health check와 운영 점검 기준이 있어야 함
+4. 정적 자산 누락 없이 화면이 완전하게 떠야 함
+
+따라서 초기 구축은 목적에 충실한 개발/테스트형 구조였고, 현재 구축은 그 위에 운영 요소를 보강한 형태라고 볼 수 있다.
+
+---
+
+## 9. 기대 효과
+
+현재 구축 방식으로 변경되면서 기대되는 효과는 아래와 같다.
+
+1. 운영 배포 적합성 향상
+2. 요청 라우팅 구조 명확화
+3. 장애 점검 및 상태 확인 가능
+4. test와 prod 분리로 검증 절차 명확화
+5. 화면 자산 누락 문제 해소
+
+즉, 지금 구조는 단순히 실행되는 수준을 넘어 운영 준비도가 높아진 구조다.
+
+---
+
+## 10. 최종 요약
+
+이번 변경의 본질은 아래와 같이 정리할 수 있다.
+
+“처음에는 Windows/WSL에서 개발과 테스트를 빠르게 재현하는 Docker 구조였다면, 현재는 실제 운영 배포를 염두에 둔 production 기준 구조로 발전시켰다.”
+
+요약하면 아래와 같다.
+
+1. 초기 구축은 개발 재현과 테스트 목적이었다.
+2. 현재 구축은 정식 운영 배포 목적이다.
+3. 프런트는 dev server에서 정적 배포 구조로 바뀌었다.
+4. nginx reverse proxy와 health check가 추가되었다.
+5. 운영 이미지 기준 정적 자산까지 보완되었다.
+
+현재 상태는 “개발 테스트용 Docker 재현” 단계를 넘어, “운영 배포가 가능한 Docker 구조”로 정리된 상태라고 설명할 수 있다.