From ceed34063244f27db945840bc04bf597c6be71d0 Mon Sep 17 00:00:00 2001 From: htlee Date: Sat, 14 Feb 2026 20:46:56 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20CI/CD=20=EA=B0=80=EC=9D=B4=EB=93=9C?= =?UTF-8?q?=EC=97=90=20=EB=B0=B1=EC=97=94=EB=93=9C=20=EB=B0=B0=ED=8F=AC=20?= =?UTF-8?q?=EC=9B=8C=ED=81=AC=ED=94=8C=EB=A1=9C=EC=9A=B0=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 배포 흐름도에 프론트엔드/백엔드 경로 분리 - gc-guide-api 워크플로우: Maven 빌드 + systemd 자동 재시작 - Maven 컨테이너에서 git clone 사용 (actions/checkout 대체) - NEXUS_USERNAME/PASSWORD 시크릿 항목 추가 - 트러블슈팅: Maven 빌드 실패, API 서비스 재시작 미동작 Co-Authored-By: Claude Opus 4.6 --- src/content/CiCdGuide.tsx | 116 +++++++++++++++++++++++++++++++++----- 1 file changed, 102 insertions(+), 14 deletions(-) diff --git a/src/content/CiCdGuide.tsx b/src/content/CiCdGuide.tsx index 0cb9c25..512b216 100644 --- a/src/content/CiCdGuide.tsx +++ b/src/content/CiCdGuide.tsx @@ -44,10 +44,13 @@ export default function CiCdGuide() { Gitea Actions 트리거 → act_runner (Docker 컨테이너)

↓

-

npm ci → npm run build → dist/ 생성

-

↓

- 배포 경로에 복사 → Nginx 서빙 + 프론트엔드: npm ci → npm run build → dist/ →{' '} + Nginx 서빙 +

+

+ 백엔드: mvn package → app.jar → .deploy-trigger →{' '} + systemd 자동 재시작

@@ -189,6 +192,16 @@ jobs: # 실행할 작업 목록 Nexus npm 레지스트리 인증 (Base64) gc-guide + + NEXUS_USERNAME + Nexus Maven 레포지토리 사용자명 + gc-guide-api + + + NEXUS_PASSWORD + Nexus Maven 레포지토리 비밀번호 + gc-guide-api + @@ -246,14 +259,23 @@ jobs: 마운트되어 있습니다. 빌드 결과물을 복사하면 Nginx가 즉시 서빙합니다. - {/* gc-guide-api 워크플로우 예시 (향후) */} -

gc-guide-api 워크플로우 (Spring Boot, 예정)

+ {/* gc-guide-api 워크플로우 예시 */} +

gc-guide-api 워크플로우 (Spring Boot)

- Java/Spring Boot 프로젝트의 워크플로우 예시입니다. 향후 gc-guide-api에 적용 예정입니다. + gc-guide-api 프로젝트의 실제 배포 워크플로우입니다. + Maven 컨테이너 이미지에서 빌드하고, JAR 파일을 배포 경로에 복사합니다. + 배포 트리거 파일이 갱신되면 systemd가 자동으로 서비스를 재시작합니다.

+ + + Maven 이미지(maven:3.9-eclipse-temurin-17)에는 Node.js가 없어서{' '} + actions/checkout@v4를 사용할 수 없습니다. + 대신 git clone으로 소스를 가져옵니다. + + ~/.m2/settings.xml << 'EOF' + cat > ~/.m2/settings.xml << 'SETTINGS' @@ -290,17 +314,54 @@ jobs: - EOF + SETTINGS - name: Build - run: mvn clean package -DskipTests + run: mvn clean package -DskipTests -B - name: Deploy run: | - cp target/*.jar /deploy/api/app.jar - # 서비스 재시작은 별도 스크립트로 처리`} + cp target/gc-guide-api-*.jar /deploy/api/app.jar + date '+%Y-%m-%d %H:%M:%S' > /deploy/api/.deploy-trigger + echo "Deployed at $(date '+%Y-%m-%d %H:%M:%S')" + ls -la /deploy/api/`} /> + + /deploy/api/는 act_runner 컨테이너 설정에서 + 호스트의 /devdata/services/guide/api/에 + 마운트되어 있습니다. .deploy-trigger 파일이 + 갱신되면 systemd path watcher가 감지하여 서비스를 자동 재시작합니다. + + +

자동 재시작 흐름

+
+
+

main 머지 → Gitea Actions 트리거 → Maven 빌드

+

↓

+

+ app.jar 복사 + .deploy-trigger 갱신 +

+

↓

+

+ systemd path watcher 감지 →{' '} + gc-guide-api.service 재시작 +

+

↓

+

+ Spring Boot 앱 자동 기동 (포트 8082, prod 프로필) +

+
+
+ +

Checkout 시 주의사항

+

+ Java 빌드에 container 옵션으로 Maven 이미지를 직접 지정하면, + job 컨테이너에 Node.js가 설치되어 있지 않아 actions/checkout@v4가 + 실패합니다. 이 경우 git clone으로 대체하고, + Gitea 내부 네트워크 주소(http://gitea:3000)를 사용합니다. +

+ {/* Actions 확인 */}

빌드 결과 확인

+
+

Maven 빌드 실패

+
    +
  • NEXUS_USERNAME, NEXUS_PASSWORD 시크릿이 올바르게 설정되어 있는지 확인
    • +
  • + container 옵션 사용 시{' '} + actions/checkout@v4 대신{' '} + git clone 사용 필수 (Node.js 없음) +
    • +
  • + Checkout URL은 http://gitea:3000 사용 + (GITHUB_SERVER_URL은 github.com으로 고정됨) +
    • +
  • Nexus Maven 미러가 접근 가능한지 확인 (devnet 네트워크)
    • +
+
+ +
+

API 서비스가 재시작되지 않음

+
    +
  • systemd path watcher 상태: systemctl status gc-guide-api-watcher.path
    • +
  • 서비스 상태: systemctl status gc-guide-api
    • +
  • .deploy-trigger 파일 확인: cat /devdata/services/guide/api/.deploy-trigger
    • +
  • 서비스 로그: journalctl -u gc-guide-api -n 50
    • +
+
+

배포 후 변경 사항이 안 보임