From 88db817da20985f6247e753d95b518492f6e4f61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=AC=B8=ED=98=95=EC=84=9D?= Date: Thu, 23 Jul 2026 14:39:06 +0900 Subject: [PATCH] =?UTF-8?q?=EC=9E=A5=ED=97=8C=20=EB=A0=88=EA=B1=B0?= =?UTF-8?q?=EC=8B=9C=20=EB=A6=AC=EB=88=85=EC=8A=A4=EC=A0=84=ED=99=98=20?= =?UTF-8?q?=EA=B2=80=ED=86=A0/ITAM=20CI=5FCD=20=EC=84=A4=EC=A0=95=20?= =?UTF-8?q?=EA=B0=80=EC=9D=B4=EB=93=9C.md=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../ITAM CI_CD 설정 가이드.md | 226 ++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 장헌 레거시 리눅스전환 검토/ITAM CI_CD 설정 가이드.md diff --git a/장헌 레거시 리눅스전환 검토/ITAM CI_CD 설정 가이드.md b/장헌 레거시 리눅스전환 검토/ITAM CI_CD 설정 가이드.md new file mode 100644 index 0000000..dd66c2f --- /dev/null +++ b/장헌 레거시 리눅스전환 검토/ITAM CI_CD 설정 가이드.md @@ -0,0 +1,226 @@ +# ITAM CI/CD 설정 가이드 + +## 1. 문서 목적 + +이 문서는 현재 ITAM 저장소에 구성된 CI/CD 파일을 실제 운영에 연결하기 위해 필요한 기준을 정리한 가이드다. + +대상 범위는 아래와 같다. + +1. Gitea Actions workflow 역할 +2. Gitea Variables / Secrets 설정값 +3. 운영 서버 배포 디렉토리 기준 +4. 운영 영속 경로 기준 +5. production deploy 실행 전 확인 사항 + +--- + +## 2. 현재 CI/CD 구성 + +현재 `.gitea/workflows`에는 ITAM 관련 workflow만 남겨둔 상태다. + +1. `itam_code_check.yml` +2. `itam_docker_build_check.yml` +3. `itam_production_deploy.yml` + +각 workflow의 역할은 아래와 같다. + +1. `itam_code_check.yml`: TypeScript/Vite build와 compose 문법 검증 +2. `itam_docker_build_check.yml`: 운영용 Docker 이미지 빌드 가능 여부 검증 +3. `itam_production_deploy.yml`: 운영 서버에 SSH 접속 후 실제 배포 수행 + +현재 배포 흐름은 아래와 같다. + +```mermaid +flowchart LR + DEV["Developer Push or Manual Run"] --> CODE["ITAM Code Check"] + CODE --> BUILD["ITAM Docker Build Check"] + BUILD --> DEPLOY["ITAM Production Deploy"] + DEPLOY --> HOST["Production Host"] + HOST --> APP["docker compose up -d --build"] + linkStyle default stroke:#d32f2f,stroke-width:2px; +``` + +--- + +## 3. Gitea Variables / Secrets 기준 + +`itam_production_deploy.yml`이 정상 동작하려면 아래 값이 필요하다. + +### 3.1 Variables + +아래 항목은 Gitea repository Variables에 등록한다. + +| Key | 설명 | 예시 | +| --- | --- | --- | +| `PROD_HOST` | 운영 서버 SSH 접속 호스트 | `10.0.0.25` | +| `PROD_USER` | 운영 서버 SSH 사용자 | `deploy` | +| `PROD_DEPLOY_PATH` | 서버에서 저장소를 배포할 경로 | `/opt/itam` | +| `PROD_BACKUP_ROOT` | 배포 전 백업 저장 경로, 배포 경로 바깥이어야 함 | `/opt/itam-backups` | +| `PROD_GIT_URL` | 운영 서버에서 pull 가능한 저장소 주소 | `git@gitea.example.com:team/itam.git` | +| `PROD_DB_HOST` | 외부 MySQL 호스트 | `172.16.8.151` | +| `PROD_DB_PORT` | 외부 MySQL 포트 | `3306` | +| `PROD_DB_USER` | 운영 DB 계정 | `itam_admin` | +| `PROD_DB_NAME` | 운영 DB 이름 | `itam` | +| `PROD_LOG_LEVEL` | 애플리케이션 로그 레벨 | `info` | + +### 3.2 Secrets + +아래 항목은 Gitea repository Secrets에 등록한다. + +| Key | 설명 | +| --- | --- | +| `PROD_SSH_PRIVATE_KEY` | 운영 서버 접속용 개인키 | +| `PROD_DB_PASS` | 운영 DB 비밀번호 | + +### 3.3 운영 원칙 + +1. `PROD_DB_PASS`는 Variables가 아니라 Secrets에만 둔다. +2. `PROD_SSH_PRIVATE_KEY`는 배포 전용 계정 키를 사용한다. +3. `PROD_GIT_URL`은 운영 서버에서 직접 pull 가능한 주소여야 한다. +4. 운영 서버의 `known_hosts`는 workflow에서 자동 등록되지만, 최초 운영 전 수동 접속 검증도 함께 수행하는 것이 안전하다. +5. `PROD_BACKUP_ROOT`는 `PROD_DEPLOY_PATH` 내부가 아니라 바깥 경로를 사용해야 한다. + +--- + +## 4. 운영 서버 배포 디렉토리 기준 + +현재 `itam_production_deploy.yml`은 운영 서버에서 아래 흐름으로 배포를 수행한다. + +1. `PROD_DEPLOY_PATH` 디렉토리를 생성한다. +2. 기존 운영 상태가 있으면 배포 전 백업을 수행한다. +3. 해당 경로에 저장소를 clone 또는 fetch 한다. +4. 지정 브랜치로 checkout 한다. +5. `uploads`, `logs/nginx` 디렉토리를 생성한다. +6. `.env.deploy`를 서버의 `.env`로 복사한다. +7. `docker compose -f docker-compose.prod.yaml up -d --build`를 실행한다. + +권장 디렉토리 구조는 아래와 같다. + +```text +/opt/itam/ + .env + docker-compose.prod.yaml + Dockerfile.frontend.prod + Dockerfile.backend.prod + map_config.json + uploads/ + logs/ + nginx/ + docker/ + nginx/ + default.conf + frontend/ + default.conf + src/ + public/ + img/ + +/opt/itam-backups/ + db/ + files/ +``` + +현재 구조 기준 배포 관계는 아래와 같다. + +```mermaid +flowchart TB + subgraph HOST["Production Host"] + REPO["PROD_DEPLOY_PATH"] + ENV[".env"] + UP["uploads/"] + LOGS["logs/nginx/"] + MAP["map_config.json"] + end + + subgraph CTR["Docker Services"] + NGINX["itam-nginx"] + FRONT["itam-frontend"] + BACK["itam-backend"] + end + + DB["External MySQL"] + + REPO --> NGINX + ENV --> BACK + UP --> BACK + MAP --> BACK + LOGS --> NGINX + REPO --> BAK["PROD_BACKUP_ROOT"] + NGINX --> FRONT + NGINX --> BACK + BACK --> DB + linkStyle default stroke:#d32f2f,stroke-width:2px; +``` + +--- + +## 5. 영속 경로 기준 + +현재 `docker-compose.prod.yaml` 기준으로 운영에서 유지되어야 하는 경로는 아래와 같다. + +1. `.env` +2. `uploads/` +3. `map_config.json` +4. `logs/nginx/` +5. `PROD_BACKUP_ROOT` + +각 경로의 의미는 아래와 같다. + +1. `.env`: backend 런타임 환경변수 +2. `uploads/`: 업로드 파일 데이터 +3. `map_config.json`: 위치/맵 구성 데이터 +4. `logs/nginx/`: reverse proxy 접근 로그 및 에러 로그 +5. `PROD_BACKUP_ROOT`: 배포 전 DB dump와 운영 파일 아카이브 저장 위치 + +운영 기준으로 보면 `uploads/`와 `map_config.json`은 애플리케이션 데이터이고, `.env`는 환경 설정이며, `logs/nginx/`는 운영 추적 데이터다. + +즉 서버 운영 시 컨테이너만 다시 띄우면 되는 구조가 아니라, 이 경로들이 유지되는 것을 전제로 배포가 성립한다. + +--- + +## 6. 배포 전 체크리스트 + +`itam_production_deploy.yml` 실행 전 아래 항목을 먼저 확인한다. + +1. 운영 서버에 Docker Engine과 `docker compose`가 설치되어 있어야 한다. +2. 운영 서버의 배포 계정이 Docker 실행 권한을 가져야 한다. +3. 운영 서버에서 `PROD_GIT_URL`로 직접 `git fetch`가 가능해야 한다. +4. 외부 MySQL 접속 정보가 실제 운영망 기준으로 열려 있어야 한다. +5. 운영 서버에 `map_config.json` 초기 파일이 존재해야 한다. +6. 방화벽 또는 보안 장비에서 80 포트 접근 정책이 정리되어 있어야 한다. + +권장 확인 명령 예시는 아래와 같다. + +```bash +docker --version +docker compose version +git ls-remote +test -f map_config.json +test -d uploads +``` + +--- + +## 7. 현재 구조에서의 해석 + +현재 ITAM CI/CD는 staging 없이도 운영 배포가 가능한 최소 구조로 정리되어 있다. + +이 구조의 장점은 아래와 같다. + +1. workflow 수가 적어서 관리가 단순하다. +2. 운영 배포에 필요한 변수와 시크릿 범위가 명확하다. +3. staging이 필요해지면 production deploy workflow를 복제해 별도 환경으로 확장하기 쉽다. + +즉, 지금 단계에서는 production 기준을 먼저 고정하고, staging은 동일 패턴으로 추후 추가하는 전략이 적절하다. + +--- + +## 8. 다음 권장 작업 + +현재 문서 기준으로 바로 이어서 할 작업은 아래 순서가 적절하다. + +1. `PROD_DEPLOY_PATH` 실제 서버 경로 확정 +2. 운영 서버 배포 계정 생성 및 SSH 키 등록 +3. `map_config.json`, `uploads/` 초기 데이터 준비 +4. production deploy workflow에 smoke check 추가 +5. 로그 로테이션과 백업/복구 절차 문서화 \ No newline at end of file