From 15f5dcf4eabb188111c81c25fc9af84e281c2776 Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Tue, 30 Jun 2026 22:13:25 +0900 Subject: [PATCH] docs: update CLAUDE.md guidelines for TCP proxy Green-Blue deployment --- CLAUDE.md | 37 ++++++++++++++----------------------- 1 file changed, 14 insertions(+), 23 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2ca21ae..c558bfa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -564,33 +564,24 @@ ssh kjh2064@178.104.200.7 배포는 수동 실행이 아니라 **Gitea Actions CI/CD**만 사용한다. -**표준 배포 (현재)**: -1. `master` 브랜치에 push -2. Gitea Actions가 `TaxBaik.Web`을 build/publish -3. CI가 서버의 `taxbaik` 서비스와 `~/taxbaik_active`를 갱신 -4. CI가 서비스 재시작 후 `/taxbaik/admin/login`으로 헬스 체크 - -**API 클라이언트 설정 (Green-Blue 대비)**: -- API 클라이언트 Base URL이 이제 동적 설정됨: `appsettings.json` > `ApiClient:BaseUrl` -- 기본값: `http://localhost:5001/taxbaik/api/` -- 배포 시 환경변수로 오버라이드 가능: - ```bash - export ApiClient__BaseUrl="http://localhost:5002/taxbaik/api/" - systemctl start taxbaik # 새 포트에 배포 - ``` -- Nginx가 `/taxbaik` → active 포트로 라우팅하면 자동 전환됨 +**무중단 Green-Blue 배포 아키텍처 (2026-06-30 적용 완료)**: +1. **프록시 레이어**: 포트 `5001`에서 영구 가동되는 초경량 .NET TCP 프록시([TaxBaik.Proxy])가 수신 대기합니다. Nginx는 `/taxbaik` 트래픽을 기존과 같이 `5001`로 중계합니다. +2. **동적 포트 스위칭**: 프록시는 요청이 들어올 때마다 `/home/kjh2064/taxbaik_port` 파일을 읽어 active 포트(5003 또는 5004)를 판단하고 트래픽을 포워딩합니다. +3. **배포 흐름 (`deploy_gb.sh`)**: + - Gitea Actions가 코드를 build/publish 후 압축하여 서버에 업로드합니다. + - 서버의 배포 스크립트([deploy_gb.sh])가 실행되어 현재 미사용 중인 예비 포트(Target Port: 5003 또는 5004)를 파악합니다. + - 예비 포트에서 새 .NET 웹 앱을 실행하고 `http://127.0.0.1:$target_port/taxbaik/healthz` 헬스 체크를 통과할 때까지 폴링(최대 60초)합니다. + - 헬스 체크 성공 시 `/home/kjh2064/taxbaik_port` 파일에 새 포트 번호를 기입하여 **트래픽을 즉시 무중단 전환**합니다. + - 기존 포트에서 동작하던 구버전 .NET 프로세스를 종료(`kill -15`)합니다. + - 만약 헬스 체크 실패 시 새 프로세스만 강제 종료하고 배포를 롤백하여 실서비스 다운타임을 방지합니다. **운영 규칙**: -- 로컬 또는 서버에서 수동 `dotnet publish`로 운영 배포하지 않는다 -- `rsync`로 직접 아티팩트를 올리지 않는다 -- 배포 실패 시 CI 로그를 먼저 본다 -- 배포된 아티팩트는 CI가 만든 것만 신뢰한다 -- 배포 후 검증은 홈, 관리자 로그인 페이지, 로그인 API를 모두 포함한다 +- 로컬 또는 서버에서 수동 `dotnet publish`로 운영 배포하지 않는다. +- 배포 실패 시 Gitea Actions CI/CD 로그 및 `~/deployments/taxbaik_timestamp/web_*.log`를 먼저 확인한다. +- 배포 후 최종 검증은 프록시 포트를 경유하는 메인 홈페이지, 관리자 로그인 페이지, 로그인 API를 모두 포함한다. **롤백**: -- 이전 정상 커밋을 `master`에 revert 또는 hotfix로 되돌린다 -- 서버 파일을 수동으로 복구하지 않는다 -- 롤백은 커밋 단위로 추적 가능해야 한다 +- 이전 정상 커밋을 `master`에 revert 또는 hotfix로 되돌려 다시 배포를 수행하거나, 비상시 서버의 `taxbaik_port` 파일의 포트 번호를 수동 수정하여 이전 버전 포트로 즉시 원상복구한다. ### 3.4 서비스 파일 위치 ```