From 69dd3fa9cca539b16d6c5ba1d18ac589d3c849ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EB=AC=B8=ED=98=95=EC=84=9D?= <moon79@hanmaceng.co.kr>
Date: Mon, 20 Jul 2026 14:26:11 +0900
Subject: [PATCH] =?UTF-8?q?tdc114plus/260720=5Ftdc114plus=20=EB=AA=A8?=
 =?UTF-8?q?=EB=B0=94=EC=9D=BC=20=EB=B0=B0=ED=8F=AC=20=EA=B2=80=ED=86=A0.md?=
 =?UTF-8?q?=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../260720_tdc114plus 모바일 배포 검토.md     | 285 ++++++++++++++++++
 1 file changed, 285 insertions(+)

diff --git a/tdc114plus/260720_tdc114plus 모바일 배포 검토.md b/tdc114plus/260720_tdc114plus 모바일 배포 검토.md
index 55498c9..60f5f87 100644
--- a/tdc114plus/260720_tdc114plus 모바일 배포 검토.md	
+++ b/tdc114plus/260720_tdc114plus 모바일 배포 검토.md	
@@ -370,6 +370,291 @@ production 직행의 장점은 아래 정도다.
 
 즉 "처음부터 무조건 완전 별도 물리 서버"가 아니라, "서비스 경계는 분리하고 인프라는 현실적으로 시작"하는 방향이다.
 
+## 5.7 `tdc114plus-auth` 배포를 아주 쉽게 설명하면
+
+초보자 기준으로 가장 먼저 이해해야 할 점은 아래다.
+
+- 앱은 사용자의 휴대폰에 설치된다.
+- `tdc114plus-auth`는 서버에 올라간다.
+- 사용자가 로그인 버튼을 누르면 앱이 이 서버를 호출한다.
+- 이 서버가 Baron SSO와 통신해서 로그인 승인 결과를 앱에 돌려준다.
+
+즉 `tdc114plus-auth`는 "앱 뒤에서 대신 인증과 중계를 처리해주는 서버"다.
+
+그래서 이 서버 배포가 잘못되면 아래 문제가 바로 생길 수 있다.
+
+- 로그인 시작이 안 됨
+- 로그인 완료 후 앱 세션이 안 생김
+- 직원검색/조직도 API 호출이 안 됨
+- 프로필 사진이 안 보임
+
+즉 이 서버는 작은 보조 기능이 아니라, 신규앱의 핵심 연결점이다.
+
+## 5.8 왜 앱보다 서버 배포를 더 조심해서 봐야 하는가
+
+앱은 잘못 배포해도 이미 설치된 예전 버전이 남아 있을 수 있다.
+
+반면 서버는 배포 순간부터 모든 사용자가 새 서버를 바로 타게 된다.
+
+예를 들어 `tdc114plus-auth`에 문제가 생기면 아래가 동시에 깨질 수 있다.
+
+- 새 로그인 요청
+- 승인 후 poll 확인
+- 세션 발급
+- 조직도 중계
+- 프로필 이미지 프록시
+
+그래서 앱 배포보다 서버 배포가 더 즉시적이고, 장애 영향도도 더 크다.
+
+## 5.9 `tdc114plus-auth` 배포 전에 준비해야 하는 것
+
+서버 배포 전에 필요한 준비물은 아래처럼 보면 된다.
+
+### 1. 서버 프로그램 자체
+
+- `tdc114plus-auth` 실행 파일 또는 컨테이너 이미지
+- 어떤 버전을 배포할지 정한 Git 커밋 또는 태그
+
+### 2. 서버 주소
+
+- 예: `114-auth.hmac.kr`
+- staging 주소와 production 주소를 나눌지 여부
+
+예시:
+
+- staging: `114-auth-stg.hmac.kr`
+- production: `114-auth.hmac.kr`
+
+### 3. HTTPS 인증서
+
+로그인과 callback 흐름은 HTTPS가 사실상 필수다.
+
+즉 아래가 준비돼야 한다.
+
+- 도메인
+- TLS 인증서
+- 리버스프록시 또는 웹서버 설정
+
+### 4. 환경설정값
+
+서버는 코드만 올린다고 끝나지 않는다. 아래 설정이 함께 필요하다.
+
+- Baron SSO 연동 주소
+- org-context 원본 주소
+- 세션 서명키 또는 secret
+- OIDC 관련 설정
+- NAVER WORKS 연동값
+- profile image 관련 base URL 또는 정책값
+
+이 값들은 코드에 박아두는 것이 아니라 서버 환경변수나 비밀값 저장소로 주입해야 한다.
+
+### 5. 로그와 모니터링
+
+배포 후 무엇이 깨졌는지 보려면 최소한 아래는 있어야 한다.
+
+- 서버 실행 로그
+- 에러 로그 확인 경로
+- health check
+- 장애 시 재기동 방법
+
+### 6. 롤백 방법
+
+배포 전에 이미 "문제 생기면 무엇으로 되돌릴지"가 정해져 있어야 한다.
+
+초보자 관점에서는 이 한 줄로 이해하면 된다.
+
+"새 버전 배포 전에, 직전 정상 버전으로 바로 돌아가는 방법을 미리 정해둬야 한다."
+
+## 5.10 `tdc114plus-auth` 배포 절차를 순서대로 풀어 설명하면
+
+아래 순서로 보면 된다.
+
+### 1단계: 배포할 버전 확정
+
+먼저 Gitea에서 어떤 커밋 또는 태그를 배포할지 정한다.
+
+예:
+
+- `main`의 특정 커밋
+- `v0.3.0-auth-staging`
+- `v0.3.0-auth-prod`
+
+핵심은 "지금 서버에 무엇을 올리는지 버전 기준이 명확해야 한다"는 점이다.
+
+### 2단계: staging 서버에 먼저 올림
+
+바로 production에 올리지 않고 staging 서버에 먼저 배포한다.
+
+이 단계에서 확인하는 것은 아래다.
+
+- 서버가 정상 기동하는지
+- `/health`가 정상인지
+- 앱에서 `link/init` 호출이 되는지
+- `link/poll` 응답이 정상인지
+- org-context 조회가 되는지
+- profile-image가 동작하는지
+
+즉 "서버가 켜졌다"가 아니라 "앱 핵심 흐름이 끝까지 되는지"를 확인해야 한다.
+
+### 3단계: staging 실기기 검증
+
+이 단계가 중요하다.
+
+서버 단독 확인만으로는 부족하고, 실제 Android 앱 또는 나중의 iOS 앱에서 아래를 봐야 한다.
+
+- 로그인 시작
+- 승인 후 앱 복귀
+- 세션 유지
+- 직원검색
+- 조직도
+- 사진 표시
+
+이 단계까지 통과해야 production 후보로 볼 수 있다.
+
+### 4단계: production 배포 준비
+
+staging 통과 후 production에 올릴 준비를 한다.
+
+여기서 확인할 것은 아래다.
+
+- production용 환경변수 값이 맞는지
+- production 도메인과 인증서가 맞는지
+- production 원본 Baron SSO 연동값이 맞는지
+- rollback 대상 버전이 준비돼 있는지
+
+### 5단계: production 반영
+
+이제 실제 production 서버에 새 버전을 올린다.
+
+이때 중요한 것은 아래다.
+
+- 가능한 짧은 시간에 반영
+- health check 즉시 확인
+- 로그인 흐름 즉시 확인
+- 문제 시 바로 rollback
+
+### 6단계: 배포 직후 집중 확인
+
+배포가 끝났다고 끝이 아니다.
+
+최소한 아래를 바로 봐야 한다.
+
+- health 응답 정상 여부
+- 로그인 시도 성공 여부
+- org-context 오류 여부
+- 이미지 프록시 오류 여부
+- 에러 로그 급증 여부
+
+즉 초반 10분~30분이 가장 중요하다.
+
+## 5.11 staging과 production의 차이를 쉽게 이해하면
+
+둘의 차이는 단순히 "테스트냐 운영이냐"만이 아니다.
+
+### staging
+
+- 내부 검증용
+- 실수해도 운영 영향이 상대적으로 작음
+- 새 설정과 새 기능을 먼저 시험하는 곳
+
+### production
+
+- 실제 사용자 대상
+- 로그인 실패가 바로 운영 이슈가 됨
+- 배포 속도보다 안정성이 우선
+
+그래서 같은 서버라도 아래처럼 다르게 봐야 한다.
+
+- staging은 확인과 수정 중심
+- production은 안정성과 rollback 중심
+
+## 5.12 `tdc114plus-auth`에 블루/그린을 적용하면 실제로 어떻게 보이는가
+
+초보자에게 가장 어려운 부분이 여기인데, 아주 단순하게 보면 아래다.
+
+### 현재 상태
+
+- 지금 운영 서버 `Blue`가 사용자 요청을 받고 있음
+
+### 새 버전 준비
+
+- 새 버전 `Green` 서버를 옆에 따로 띄움
+- 아직 사용자는 Green으로 가지 않음
+- 내부적으로 Green 서버 health와 핵심 기능을 확인함
+
+### 전환
+
+- 리버스프록시 또는 로드밸런서가 사용자 요청을 Blue에서 Green으로 바꿈
+
+### 문제 없으면 유지
+
+- Green을 새 운영 서버로 유지
+
+### 문제 생기면 rollback
+
+- 요청 방향을 다시 Blue로 돌림
+
+즉 블루/그린의 핵심은 아래다.
+
+"기존 서버를 바로 덮어쓰지 않고, 새 서버를 옆에 준비한 뒤 전환한다."
+
+## 5.13 왜 `tdc114plus-auth`는 블루/그린이 특히 잘 맞는가
+
+이 서버는 아래 기능이 한 번에 묶여 있다.
+
+- 로그인 시작
+- 로그인 완료 확인
+- 세션 발급
+- 조직도 중계
+- 프로필 사진 프록시
+
+만약 배포 후 문제가 생기면 사용자 입장에서는 "앱이 갑자기 로그인 안 된다"로 보일 수 있다.
+
+이럴 때 가장 좋은 것은 원인 분석을 오래 하는 것이 아니라, 일단 직전 정상 서버로 빨리 되돌리는 것이다.
+
+그 점에서 블루/그린이 유리하다.
+
+## 5.14 `tdc114plus-auth` 배포에서 초보자가 특히 놓치기 쉬운 것
+
+아래 항목은 회의 전에 꼭 이해하고 가는 편이 좋다.
+
+1. 앱보다 서버가 먼저 준비돼야 한다.
+앱이 서버를 호출하므로 서버 주소와 동작이 먼저 안정적이어야 한다.
+
+2. 환경변수와 secret이 매우 중요하다.
+코드가 맞아도 설정값이 틀리면 로그인은 바로 실패할 수 있다.
+
+3. health check만 통과했다고 끝난 것이 아니다.
+실제 로그인부터 사진 표시까지 앱 시나리오가 같이 확인돼야 한다.
+
+4. staging 성공과 production 성공은 다를 수 있다.
+도메인, 인증서, 원본 연동값, 보안 설정이 다르기 때문이다.
+
+5. rollback은 나중에 생각하는 것이 아니다.
+배포 전에 이미 정해져 있어야 한다.
+
+## 5.15 회의에서 바로 물어봐야 할 `tdc114plus-auth` 배포 질문
+
+이 서버 배포와 관련해서는 아래 질문을 꼭 던지는 것이 좋다.
+
+1. `tdc114plus-auth`는 어느 서버 또는 어느 컨테이너 환경에 올릴 것인가
+2. staging 도메인과 production 도메인을 나눌 것인가
+3. HTTPS 인증서 발급과 갱신은 누가 관리하는가
+4. 서버 환경변수와 secret은 어디에 저장하고 누가 주입하는가
+5. 배포는 수동인지, 스크립트인지, CI인지
+6. health check와 로그 확인은 어디서 하는가
+7. 장애 시 직전 버전으로 몇 분 안에 rollback 가능한가
+8. 블루/그린을 할 인프라가 없으면 차선 배포 방식은 무엇인가
+
+## 5.16 현재 문서 기준 추천 정리
+
+현재 단계에서 가장 현실적인 `tdc114plus-auth` 배포 이해는 아래다.
+
+- `tdc114plus-auth`는 앱의 로그인과 데이터 연결을 담당하는 핵심 서버다.
+- 그래서 앱 배포보다 서버 배포를 더 보수적으로 봐야 한다.
+- staging에서 앱 시나리오까지 확인한 뒤 production으로 가는 것이 맞다.
+- production은 블루/그린처럼 rollback이 빠른 방식이 가장 잘 맞는다.
+
 ## 6. 블루/그린, 롤링, 카나리 비교
 
 여기서는 `tdc114plus-auth` 같은 서버 배포 전략을 중심으로 설명한다.