# tdc114plus 모바일 배포 검토 회의 정리 작성일: 2026-07-20 상태: 회의 준비 초안 목적: 신규앱 `tdc114plus`의 Android 배포 방식, 향후 iOS 추가 시 검토사항, `tdc114plus-auth` 중계서버 운영 위치, 배포 전략을 회의 전에 쉽게 검토할 수 있도록 정리한다. 관련 문서: - `docs/00_guide_tdc114plus_work_progress_timetable_2026-07-02.md` - `docs/00_guide_tdc114plus_deployment_migration_matrix_2026-07-19.md` - `docs/00_policy_tdc114plus_auth_repo_2026-07-15.md` ## 1. 이번 회의에서 결정해야 할 핵심 이번 회의의 핵심 질문은 아래 3가지다. 1. 신규앱을 어떤 절차로 배포할 것인가 2. `tdc114plus-auth` 중계서버를 어디에 둘 것인가 3. 서버 배포 전략은 블루/그린, 롤링, 카나리 중 무엇이 맞는가 현재 문서 기준으로 이미 비교적 명확한 전제는 아래와 같다. - 최종 배포 직접 대상은 `tdc114plus` 앱과 `tdc114plus-auth` 서버다. - 로컬 개발용 `baron-sso-tdc114plus-api` worktree는 최종 배포 필수 구성으로 보지 않는다. - 신규앱은 Baron SSO 원본 `staging` 연동을 먼저 안정화한 뒤 `production`으로 승격하는 흐름이 기본값이다. 즉 이번 회의는 완전히 백지상태의 논의가 아니라, 이미 정리된 방향을 실제 운영 가능한 배포 구조로 굳히는 회의에 가깝다. ## 2. 먼저 쉽게 보는 결론 현재 기준 추천안은 아래와 같다. ### 2.1 앱 배포 - 처음부터 production 직행보다는 `staging 서버 구성 -> 내부 테스트 APK 배포 -> 운영 체크 완료 후 production 배포` 순서가 안전하다. - Android 앱은 우선 `내부 배포용 APK 또는 AAB` 기준으로 시작하고, 외부 공개 앱스토어 배포는 후순위로 둔다. - 앱 코드 저장소와 서버 저장소는 분리 유지한다. ### 2.2 중계서버 배치 - `tdc114plus-auth`는 Baron SSO 본체 저장소에 흡수하지 않고 별도 서버/별도 저장소/별도 배포 단위로 유지하는 쪽이 맞다. - 다만 물리 서버를 완전히 따로 만들지, 기존 운영 서버 안에서 서브도메인 기반으로 분리할지는 인프라 사정에 따라 선택할 수 있다. - 가장 현실적인 1차안은 `114-auth.hmac.kr` 같은 별도 서브도메인으로 분리하고, 실행 주체는 독립 서비스로 유지하는 것이다. ### 2.3 배포 전략 - 신규앱의 현재 규모와 위험도를 보면 `tdc114plus-auth` 서버는 `블루/그린`이 가장 설명하기 쉽고 운영 리스크도 낮다. - 롤링은 인프라가 단순할 때 쓸 수 있지만, 인증/세션/콜백 문제가 생기면 원인 추적이 조금 더 번거롭다. - 카나리는 장기적으로 좋을 수 있으나, 현재 단계에서는 운영도와 관찰체계가 더 필요하다. 요약하면 현재 회의에서 제안하기 좋은 1차 권장안은 아래다. - 앱: `staging -> 내부 검증 -> production` - 서버 위치: `독립 서비스 + 서브도메인 분리` - 서버 배포 방식: `블루/그린` ## 3. 신규앱 배포방법 정리 ## 3.1 앱 배포에서 실제로 나눠서 봐야 할 것 안드로이드 배포는 보통 아래 3개를 따로 봐야 한다. 1. 소스코드를 어디서 관리하는가 2. 빌드 결과물 APK/AAB를 어떻게 만드는가 3. 만들어진 결과물을 누구에게 어떤 경로로 배포하는가 이번 프로젝트에서는 이 3개를 아래처럼 이해하면 쉽다. - 소스코드 관리: Gitea 저장소 - 빌드: 로컬 또는 CI에서 APK/AAB 생성 - 배포: 내부 사용자에게 설치 파일 전달 또는 관리형 배포 즉 Gitea는 "앱을 직접 설치해 주는 도구"라기보다, "소스와 버전과 변경이력을 관리하는 중심 저장소"라고 보면 된다. ## 3.2 Gitea를 이용한 배포를 아주 쉽게 설명하면 Gitea를 처음 접할 때 가장 헷갈리는 부분은 "Gitea가 곧 배포 서버인가?"라는 점인데, 보통은 그렇지 않다. Gitea의 기본 역할은 아래와 같다. - 소스코드 저장 - 브랜치 관리 - 커밋 이력 관리 - 태그와 릴리스 버전 관리 - 협업용 리뷰와 병합 관리 배포 관점에서는 Gitea를 아래처럼 사용한다. 1. 개발자가 기능 작업 브랜치에서 코드 수정 2. 테스트 후 `main` 또는 `release` 성격 브랜치로 병합 3. 특정 시점에 `v0.1.0`, `v0.2.0` 같은 태그 생성 4. 그 태그 기준으로 APK/AAB를 빌드 5. 빌드 결과물을 내부 배포 채널에 올림 6. 운영 이슈가 없으면 다음 버전으로 승격 즉 "Gitea를 이용한 배포"는 정확히 말하면 아래 뜻에 가깝다. - Gitea에서 릴리스 기준 버전을 확정하고 - 그 버전으로 APK/AAB를 빌드하고 - 결과물을 staging 또는 production 배포 절차에 따라 배포한다 ## 3.3 Gitea 기준 권장 운영 흐름 회의에서 설명하기 쉬운 흐름은 아래 순서다. 1. 개발 브랜치에서 기능 개발 2. 테스트 완료 후 `main` 병합 3. 배포 후보 버전에 태그 부여 4. 태그 기준으로 staging APK/AAB 빌드 5. staging 환경에서 실기기 로그인, 직원검색, 조직도, 프로필 사진 확인 6. 문제 없으면 같은 커밋 또는 새 릴리스 태그로 production 빌드 7. production 배포 후 장애 모니터링 이 흐름의 장점은 아래와 같다. - 어떤 코드가 배포됐는지 추적이 쉽다 - 문제가 생겼을 때 어느 버전으로 돌아가야 하는지 واضح하게 보인다 - 앱과 서버의 버전 기준을 맞추기 쉽다 ## 3.4 Gitea 기준 브랜치 예시 가장 단순하게는 아래 구조로도 충분하다. - `main`: 다음 배포 후보가 모이는 기본 브랜치 - `feature/...`: 기능 개발 브랜치 - `hotfix/...`: 운영 장애 긴급 수정 브랜치 운영이 더 커지면 아래를 추가할 수 있다. - `release/...`: 배포 직전 안정화 브랜치 하지만 현재 단계에서는 브랜치가 너무 많아지면 오히려 관리가 어려워질 수 있으므로 아래 정도가 현실적이다. - 개발은 `feature/...` - 검토 후 `main` 병합 - 배포 시 태그 생성 ## 3.5 Gitea와 staging/prod를 연결하는 이해하기 쉬운 예시 예를 들어 아래처럼 생각하면 된다. - `main`의 특정 커밋 `abc1234`가 테스트를 통과했다. - 그 커밋에 `v0.3.0-rc1` 태그를 붙인다. - 이 버전으로 staging APK를 만든다. - staging 서버와 staging 중계서버에 연결해서 실기기 검증을 한다. - 문제 없으면 같은 커밋에 `v0.3.0` 태그를 붙이거나 새 릴리스 태그를 만든다. - 그 버전으로 production APK를 만든다. 즉 Gitea는 "어떤 코드를 staging에 올렸고, 어떤 코드를 production에 올렸는지 기록하는 기준점" 역할을 한다. ## 3.6 신규앱 배포 채널 후보 안드로이드 앱 배포 채널은 크게 아래처럼 나눌 수 있다. | 방식 | 설명 | 장점 | 단점 | 현재 적합도 | | --- | --- | --- | --- | --- | | APK 직접 배포 | APK 파일을 직접 전달해 설치 | 가장 빠르고 단순 | 설치 관리, 버전 통제, 보안 통제가 약할 수 있음 | 초기 내부 테스트에 적합 | | AAB/Managed Store | 관리형 스토어 또는 사내 배포 체계 이용 | 버전 관리와 배포 통제가 좋음 | 초기 준비가 더 필요 | 운영 단계에 적합 | | 일반 공개 스토어 | Play 스토어 공개 배포 | 배포 체계가 표준적 | 내부 전용 앱이면 과할 수 있음 | 현재는 우선순위 낮음 | 현재 프로젝트 성격상 내부/협력사 중심이라면 아래 순서가 자연스럽다. 1. 내부 staging 검증용 APK 2. 제한된 운영 사용자 대상 production APK 또는 관리형 배포 3. 필요 시 나중에 관리형 스토어 체계 확장 ## 3.7 iOS를 추가할 경우 배포 경로는 어떻게 달라지는가 iOS는 Android처럼 APK를 바로 전달하는 방식으로 생각하면 안 된다. 보통 아래 경로로 본다. - 내부 테스트: `TestFlight` - 사내 관리형 배포: `Apple Business Manager` 또는 `MDM` - 일반 공개 배포: `App Store` 현재 프로젝트 성격상 iOS는 아래 순서가 가장 현실적이다. 1. 개발/QA용 실기기 테스트 2. 내부 사용자 대상 `TestFlight` 3. 운영 구조가 안정되면 `Apple Business Manager` 또는 정식 배포 검토 즉 Android는 초기 APK 직접 배포가 비교적 쉽지만, iOS는 초반부터 Apple 배포 절차를 일정에 포함해야 한다. ## 3.8 Android만 할 때와 iOS까지 같이 할 때의 차이 Android만 진행할 때는 핵심이 아래에 가깝다. - APK/AAB 빌드 - staging/production 서버 연결 - 실기기 설치 검증 반면 iOS가 추가되면 아래 준비가 더 들어간다. - Apple Developer 계정 및 권한 - Bundle ID 확정 - Provisioning Profile - 배포용 인증서/서명 - Universal Link 설정 - iPhone 실기기 테스트 - TestFlight 등록 및 검수 대기 그래서 iOS는 "코드 조금 더 만드는 일"이라기보다 "플랫폼 운영 준비를 하나 더 여는 일"에 가깝다. ## 3.9 iOS 추가 시 바로 회의에서 말해둘 핵심 아래 문장으로 정리하면 이해가 쉽다. "iOS는 Flutter 공통 코드 재사용이 가능해서 화면과 비즈니스 로직은 상당 부분 함께 가져갈 수 있지만, 실제 배포와 로그인 링크 처리 단계에서는 Apple 계정, 서명, Universal Link, TestFlight 절차가 별도로 필요하므로 Android만 할 때보다 준비 단계와 검증 기간이 더 필요합니다." ## 4. staging 서버를 먼저 둘지, 바로 production으로 갈지 ## 4.1 결론 현재는 `staging 먼저`가 맞다. 바로 production으로 가는 것은 아래 이유로 위험하다. - 로그인 승인 링크와 세션 발급 흐름이 아직 민감하다 - `tdc114plus-auth`가 앱 전용 인증 broker 역할을 한다 - 프로필 사진 프록시, org-context proxy, OIDC callback 등 외부 연동 지점이 많다 - 실기기에서만 드러나는 환경 문제를 production에서 처음 만나면 대응 비용이 커진다 ## 4.2 staging을 먼저 두는 이유 staging은 단순히 "테스트용 서버"가 아니라 운영 전 최종 예행연습 환경이라고 생각하면 된다. staging에서 확인해야 할 대표 항목은 아래와 같다. - 문자 승인 로그인 실제 동작 - App Link 또는 callback 흐름 - `tdc114plus-auth` 세션 발급 - 직원검색, 조직도, 상세 조회 - 프로필 사진 1순위, 2순위, 기본 아바타 fallback - 장애 시 로그 추적 가능 여부 - 서버 설정값과 비밀키 주입 방식 ## 4.3 production 직행의 장점도 있기는 하다 production 직행의 장점은 아래 정도다. - 환경이 하나라서 단순하다 - 서버를 두 번 만들지 않아도 된다고 느낄 수 있다 - 초기 속도는 빨라 보일 수 있다 하지만 지금 프로젝트에서는 이 장점보다 단점이 더 크다. - 장애가 나면 바로 운영 이슈가 된다 - 로그인/인증 계층 문제는 영향 범위가 넓다 - rollback 판단이 더 어려워진다 ## 4.4 회의에서 추천할 문장 아래 정도로 정리하면 전달이 쉽다. "신규앱은 인증과 조직도 연동이 포함된 구조라서, 일반 화면 앱보다 운영 리스크가 높습니다. 따라서 production 직행보다 Baron SSO 원본 staging 연동을 먼저 안정화하고, 실기기 검증이 끝난 뒤 production으로 승격하는 구조가 맞습니다." ## 5. `tdc114plus-auth` 중계서버를 어디로 둘지 ## 5.1 먼저 정리할 전제 현재 문서 기준으로 `tdc114plus-auth`는 아래 역할을 한다. - 앱의 로그인 시작 요청 수신 - Baron SSO headless/link API 호출 - 앱 세션 발급 - org-context proxy - 프로필 사진 lookup 및 네이버웍스 사진 프록시 즉 단순 정적 파일 서버가 아니라, 실제 운영 로직과 보안 설정을 가지는 독립 서비스다. 그래서 저장소도 별도이고, 운영 단위도 별도로 보는 것이 맞다. ## 5.2 배치안 1: 완전 별도 서버 설명: - `tdc114plus-auth`만 위한 별도 VM 또는 별도 컨테이너 서버를 둔다. 장점: - 장애 분리가 가장 명확하다 - 보안 경계가 분명하다 - 서버 리소스와 로그를 독립적으로 관리하기 쉽다 - 향후 scale-out이나 교체가 쉽다 단점: - 인프라 비용과 운영 포인트가 늘어난다 - 서버 provisioning, 인증서, 모니터링 구성이 추가된다 언제 적합한가: - 장기 운영 확률이 높고 - 사용자 수가 늘어날 가능성이 있고 - 인증 broker를 명확히 분리하고 싶을 때 ## 5.3 배치안 2: 기존 운영서버 안에 독립 서비스로 배치 설명: - 물리적으로는 기존 시스템 운영서버 또는 Baron SSO 관련 서버에 두되, 프로세스/컨테이너/리버스프록시 레벨에서 독립 서비스로 운영한다. - 예: `114-auth.hmac.kr` -> reverse proxy -> `tdc114plus-auth` 장점: - 인프라 준비가 빠르다 - 인증서와 네트워크 구성을 재활용하기 쉽다 - 운영팀이 익숙한 서버에 올릴 수 있다 단점: - 물리 분리는 아니므로 리소스 충돌 가능성이 있다 - 잘못 운영하면 "서버는 같고 서비스만 다름" 상태에서 경계가 흐려질 수 있다 언제 적합한가: - 초기 운영 진입 속도가 중요하고 - 완전 별도 서버까지는 아직 부담일 때 ## 5.4 배치안 3: Baron SSO 본체에 흡수 설명: - `tdc114plus-auth` 기능을 Baron SSO 본체 저장소나 서비스 안으로 넣는다. 장점: - 겉보기에는 서비스 수가 줄어든다 단점: - 저장소 경계가 무너진다 - 앱 전용 로직과 SSO 본체 로직이 섞인다 - 긴급 장애 대응 시 영향 범위가 커진다 - 배포 타이밍을 분리하기 어렵다 현재 판단: - 이 안은 비권장이다. 이미 기존 문서에서도 `tdc114plus-auth`는 별도 저장소, 별도 배포 단위로 유지하는 방향이 정리되어 있다. ## 5.5 서브도메인으로 두는 안은 어떤 의미인가 사용자가 말한 "Baron SSO쪽에 서브도메인식으로 넣는지"는 보통 아래 두 의미 중 하나다. 1. 서버 자체도 Baron 쪽 인프라 안에 둔다 2. 주소만 Baron 계열 도메인/서브도메인으로 준다 이 둘은 꼭 같은 말이 아니다. 예를 들어 아래 구조가 가능하다. - 주소: `114-auth.hmac.kr` - 실제 실행: 독립 컨테이너 또는 독립 서비스 - 네트워크/인증서: 기존 운영 인프라 활용 이 방식은 "주소는 자연스럽게 연결되지만 서비스 경계는 유지"할 수 있어서 현실성이 높다. ## 5.6 현재 회의에서 추천할 중계서버 방향 가장 현실적인 추천은 아래다. 1. `tdc114plus-auth`는 독립 서비스로 유지 2. 주소는 `114-auth.hmac.kr` 같은 전용 서브도메인 사용 3. 초기에는 기존 운영 인프라 또는 Baron 인프라 안의 독립 서비스로 올릴 수 있음 4. 사용자 증가나 운영 부담이 커지면 별도 서버로 분리 가능하게 설계 즉 "처음부터 무조건 완전 별도 물리 서버"가 아니라, "서비스 경계는 분리하고 인프라는 현실적으로 시작"하는 방향이다. ## 5.6-A 위 문장을 더 쉽게 풀면 여기서 가장 헷갈리기 쉬운 부분은 아래 3가지를 같은 뜻으로 오해하는 것이다. 1. 저장소를 따로 둔다 2. 서비스를 따로 운영한다 3. 물리 서버를 따로 둔다 이 3가지는 서로 다른 이야기다. ### 저장소 분리 이 뜻은 소스코드를 Git 저장소 단위로 따로 관리한다는 뜻이다. 예: - `tdc114plus` 앱 저장소 - `tdc114plus-auth` 저장소 - Baron SSO 저장소 ### 서비스 분리 이 뜻은 실제 실행되는 프로그램을 따로 운영한다는 뜻이다. 예: - Baron SSO 본체 프로세스 - `tdc114plus-auth` 프로세스 둘이 같은 서버 안에 있어도 실행 주체가 따로면 서비스는 분리된 것이다. ### 물리 서버 분리 이 뜻은 아예 다른 VM, 다른 컨테이너 호스트, 다른 장비에 올린다는 뜻이다. 즉 아래처럼 이해하면 된다. - 저장소는 따로일 수 있다 - 서비스도 따로일 수 있다 - 하지만 물리 서버는 처음엔 같은 것을 쓸 수도 있다 그래서 "처음부터 인프라를 너무 크게 벌리지 않아도 된다"는 말은 `저장소만 다르게 둔다`는 뜻이 아니라 아래 뜻에 가깝다. - Git 저장소는 분리한다 - 실행 서비스도 분리한다 - 다만 처음에는 같은 운영 서버 자원을 활용할 수 있다 ## 5.6-B 실제로는 어떤 모습인가 예를 들어 한 대의 서버 안에서 아래처럼 운영할 수 있다. - Baron SSO 본체 서비스는 기존 포트/기존 설정으로 실행 - `tdc114plus-auth`는 별도 포트 또는 별도 컨테이너로 실행 - 외부에서는 `114-auth.hmac.kr` 주소로 들어오고 reverse proxy가 `tdc114plus-auth`로 전달 즉 겉으로 보기에는 전용 서버처럼 보이지만, 실제 초기 운영은 기존 인프라 안의 독립 서비스로 시작할 수 있다. 이 구조의 핵심은 아래다. - 주소는 분리 - 실행 프로세스도 분리 - 설정값도 분리 - 배포도 분리 - 다만 물리 장비는 처음엔 공유 가능 ## 5.6-C `tdc114plus-auth`는 같이 둘 수 있는데, `tdc114plus` 앱은 왜 다르게 보나 이 부분도 자주 헷갈릴 수 있다. ### `tdc114plus-auth` `tdc114plus-auth`는 서버 프로그램이다. 즉 실제로 서버 위에서 계속 실행되어야 하는 대상이므로, Baron SSO 인프라 안의 독립 서비스로 두는 개념이 성립한다. ### `tdc114plus` 반면 `tdc114plus`는 모바일 앱 소스코드와 빌드 산출물이다. 즉 서버에서 계속 떠 있는 운영 프로세스가 아니라 아래 성격에 가깝다. - 개발 대상 - 빌드 대상 - 배포 대상 - 휴대폰에 설치되는 결과물 그래서 `tdc114plus-auth`를 같은 서버 인프라 안의 독립 서비스로 둔다는 개념을 그대로 앱 저장소에 적용하면 안 된다. ## 5.6-D 그럼 `tdc114plus` 앱 소스코드를 Baron SSO 쪽에 같이 두는 것은 어떤가 기술적으로 저장소를 한곳에 둘 수는 있다. 하지만 현재 프로젝트 기준으로는 권장하지 않는다. 이유는 아래와 같다. 1. 책임이 다르다 - `tdc114plus`는 모바일 앱이다 - Baron SSO는 인증 본체다 - `tdc114plus-auth`는 앱 전용 중계서버다 2. 배포 시점이 다르다 - 앱 배포 - auth 서버 배포 - Baron SSO 배포 이 셋은 서로 다른 주기로 움직일 수 있어야 한다. 3. 커밋과 리뷰 경계가 다르다 - 앱 화면 수정 - 인증 서버 수정 - SSO 본체 수정 이것이 한 저장소에 섞이면 추적과 검토가 어려워진다. 4. 보안과 권한 경계가 다르다 - 앱 개발자 - auth 운영자 - Baron SSO 운영자 각자 접근 범위가 달라질 수 있다. 그래서 현재 기준 추천 구조는 아래다. - `tdc114plus`: 별도 저장소 - `tdc114plus-auth`: 별도 저장소 - Baron SSO: 기존 저장소 유지 단, `tdc114plus-auth` 실행 위치는 초기에는 Baron SSO 운영 인프라 안의 독립 서비스일 수 있다. ## 5.6-E 한 줄로 정리하면 아래처럼 기억하면 가장 쉽다. - `tdc114plus-auth`는 같은 서버 인프라 안에 둘 수 있다 - 하지만 Baron SSO와 같은 서비스는 아니다 - `tdc114plus` 앱은 같은 저장소나 같은 관리 경계에 섞지 않는 편이 낫다 - 즉 서버 위치 공유는 가능하지만, 저장소와 서비스 경계까지 합치는 것은 권장하지 않는다 ## 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` 같은 서버 배포 전략을 중심으로 설명한다. 앱 APK 자체 배포는 서버와 달리 사용자가 설치한 버전이 남기 때문에, 아래 전략은 주로 서버 쪽에 더 직접적으로 적용된다. ## 6.1 블루/그린 배포 뜻: - 현재 운영 중인 서버 묶음이 `Blue` - 새 버전 서버 묶음이 `Green` - 새 버전 준비가 끝나면 트래픽을 한 번에 Green으로 전환 장점: - rollback이 빠르다 - 전환 전까지 새 버전을 충분히 검증할 수 있다 - 인증/콜백 계층처럼 민감한 서비스에 설명하기 쉽다 단점: - 서버 자원을 두 벌 준비해야 한다 - 환경 동기화가 안 맞으면 전환 직후 문제가 날 수 있다 신규앱 적합도: - 높음 왜 잘 맞는가: - `tdc114plus-auth`는 로그인, 세션, 프록시를 담당하므로 장애 시 즉시 되돌릴 수 있어야 한다 - 운영팀과 비개발자에게도 설명이 쉽다 ## 6.2 롤링 배포 뜻: - 여러 서버 인스턴스가 있다면 하나씩 순서대로 새 버전으로 교체하는 방식 장점: - 추가 자원이 블루/그린보다 적게 들 수 있다 - 대규모 서비스에서 일반적으로 많이 쓴다 단점: - 구버전과 신버전이 잠시 섞여 운영된다 - 세션/콜백/응답 포맷 차이가 있으면 문제 원인 추적이 어려울 수 있다 신규앱 적합도: - 중간 왜 조심해야 하는가: - 인증 broker에서 구버전/신버전이 섞이면 로그인 중 일부만 실패하는 식의 애매한 장애가 날 수 있다 ## 6.3 카나리 배포 뜻: - 전체 사용자 중 일부에게만 새 버전을 먼저 보낸 뒤, 이상이 없으면 점차 확대하는 방식 장점: - 위험을 아주 작게 시작할 수 있다 - 실제 운영 사용자 반응을 조금씩 볼 수 있다 단점: - 관찰 지표, 라우팅 제어, 사용자 분리 기준이 필요하다 - 운영 난이도가 높다 신규앱 적합도: - 장기적으로는 좋을 수 있으나 지금 당장은 중간 이하 왜 지금은 이른가: - 현재는 먼저 배포 기준 구조를 단순하게 확정하는 것이 더 중요하다 - 카나리를 잘 하려면 로그, 모니터링, 비율 제어, 빠른 롤백 체계가 먼저 안정적이어야 한다 ## 6.4 한눈에 보는 비교표 | 방식 | 설명 난이도 | 운영 난이도 | 롤백 속도 | 추가 인프라 요구 | 현재 추천도 | | --- | --- | --- | --- | --- | --- | | 블루/그린 | 쉬움 | 중간 | 매우 빠름 | 중간~높음 | 가장 추천 | | 롤링 | 중간 | 중간 | 보통 | 낮음~중간 | 차선 | | 카나리 | 어려움 | 높음 | 빠를 수도 있으나 운영 복잡 | 높음 | 후순위 | ## 6.5 회의에서 말하기 쉬운 추천 문장 "`tdc114plus-auth`는 로그인과 세션을 담당하므로 배포 후 바로 장애가 보일 수 있습니다. 그래서 신구 버전이 섞이는 롤링보다, 새 버전을 미리 준비해 두고 전환 후 문제 시 즉시 되돌리기 쉬운 블루/그린이 현재 단계에 더 적합합니다." ## 7. 이번 회의에서 제안할 권장안 ## 7.1 최종 권장안 아래 안을 1차 기본안으로 제안하는 것이 가장 무난하다. 1. 앱 배포는 `staging -> 내부 실기기 검증 -> production` 순서로 진행 2. `tdc114plus-auth`는 별도 저장소와 별도 서비스로 유지 3. 주소는 `114-auth.hmac.kr` 같은 전용 서브도메인 사용 4. 초기 인프라는 기존 운영서버 또는 Baron 인프라 안의 독립 서비스로 시작 가능 5. 서버 배포 전략은 우선 `블루/그린` 채택 6. `baron-sso-tdc114plus-api`는 배포 필수 구성에서 제외 ## 7.2 이렇게 제안하는 이유 - 현재 문서 방향과 가장 잘 맞는다 - 운영 안정성과 현실성을 같이 잡을 수 있다 - 운영 책임자가 바로 판단하기 쉬운 구조다 - 나중에 확장할 여지도 남긴다 ## 7.3 iOS 추가를 전제로 보면 어떤 판단이 필요한가 iOS까지 염두에 두면 아래 판단을 회의에서 같이 받아두는 편이 좋다. 1. 올해 범위가 `Android 우선 출시 후 iOS 확장`인지 2. 아니면 `Android/iOS 동시 준비`인지 3. Apple Developer 계정과 배포 권한을 누가 관리하는지 4. TestFlight로 내부 배포할지, Apple Business Manager 또는 MDM까지 갈지 현재 프로젝트 상태와 기존 문서 흐름을 보면, 가장 현실적인 방향은 아래다. - 1차: Android staging/production 구조 안정화 - 2차: 공통 코드 유지 전제로 iOS 확장 - 3차: iOS TestFlight 내부 검증 후 운영 판단 즉 iOS를 완전히 배제하는 것이 아니라, Android 운영 구조를 먼저 굳힌 뒤 iOS를 붙이는 순차 확장이 가장 무난하다. ## 8. iOS 추가 시 작업 단계 검토 ## 8.1 전체 관점 iOS 추가 작업은 크게 아래 4묶음으로 나눌 수 있다. 1. 사전 준비 2. 앱 코드 및 플랫폼 설정 3. 로그인/링크/배포 검증 4. 운영 준비 기존 Flutter 공통 코드가 이미 있다는 전제에서는 Android를 처음 만드는 것보다 짧을 수 있다. 하지만 Apple 배포 절차 때문에 체감 일정은 생각보다 짧지 않을 수 있다. ## 8.2 단계별 작업 정리 | 단계 | 작업 내용 | 주요 확인 포인트 | | --- | --- | --- | | 1 | iOS 범위 확정 | Android와 동일 기능 범위인지, 보류 기능이 있는지 | | 2 | Apple 계정/권한 준비 | Apple Developer 계정, 팀 권한, 인증서 관리 주체 | | 3 | iOS 프로젝트 기본 설정 정리 | Bundle ID, signing, provisioning, build config | | 4 | 로그인/링크 방식 적용 | Universal Link, callback, redirect URI, associated domains | | 5 | Flutter 공통 기능 iOS 정합성 점검 | 직원검색, 조직도, 상세, 즐겨찾기, 세션 저장 | | 6 | iOS 플랫폼 차이 보정 | 전화/문자 호출, 권한 안내, secure storage, WKWebView 동작 | | 7 | `tdc114plus-auth` 연동 검증 | staging에서 로그인, org-context, profile image 동작 | | 8 | 실기기 테스트 | iPhone에서 로그인, 앱 복귀, 세션 유지, 링크 재진입 | | 9 | 배포 준비 | TestFlight 업로드, 배포 그룹, 릴리스 노트 | | 10 | 운영 전 점검 | 장애 대응, 버전 정책, 사용자 배포 절차 | ## 8.3 단계별 설명 ### 1단계: iOS 범위 확정 가장 먼저 확인할 것은 "iOS도 Android와 기능을 완전히 같게 가져갈 것인가"다. 현재 문서 흐름상 아래 기능은 Android/iOS 공통 범위로 보기 좋다. - 로그인 - 직원검색 - 조직도 - 직원 상세 - 전화/문자 실행 - 즐겨찾기 - 프로필 사진 조회 반면 아래는 별도 검토가 필요하다. - 향후 푸시 알림 - 기기 보안 강화 - iOS 전용 운영정책 ### 2단계: Apple 계정 및 서명 준비 이 단계는 개발보다 운영 준비에 가깝다. 필요 항목 예시는 아래다. - Apple Developer Program 계정 - App ID 또는 Bundle ID - 인증서 발급 권한 - Provisioning Profile - 배포 담당자 계정 이 단계가 늦어지면 코드가 준비돼도 실제 배포 테스트를 못 하게 된다. ### 3단계: iOS 프로젝트 설정 정리 Flutter 공통 코드가 있어도 iOS 프로젝트 설정은 따로 확인해야 한다. 대표 항목: - 앱 이름 - Bundle Identifier - signing team - build configuration - URL/도메인 설정 - Info.plist 권한 문구 ### 4단계: 로그인 및 링크 처리 적용 Android의 App Link와 비슷한 개념이 iOS에서는 Universal Link다. 여기서 확인해야 하는 것은 아래다. - callback URL 또는 redirect URI - associated domains 설정 - Apple App Site Association 파일 배포 - 앱 설치 상태에서 링크 클릭 시 앱 복귀 여부 이 단계는 실제 로그인 성공과 직결되므로 일정상 중요하다. ### 5단계: 공통 기능 iOS 정합성 점검 Flutter 공통 코드라도 아래 항목은 iOS 실기기에서 다시 확인해야 한다. - 로그인 후 직원검색 진입 - 조직도 필터와 초기 선택 상태 - 상세화면 표시 - 프로필 이미지 로딩 - 즐겨찾기 유지 ### 6단계: iOS 플랫폼 차이 보정 여기서는 "Android에서는 되는데 iOS에서는 동작이 조금 다른 것"을 맞춘다. 대표 예시는 아래다. - 전화/문자 앱 호출 방식 - 권한 안내 문구 - secure storage 동작 - WKWebView 정책 차이 - 앱 백그라운드 복귀 시 세션 처리 ### 7단계: staging 연동 검증 iOS도 Android와 동일하게 production 직행보다 staging 검증이 먼저다. 확인 항목: - `tdc114plus-auth` 로그인 시작/완료 - org-context proxy - profile-image proxy - callback 이후 앱 복귀 ### 8단계: 실기기 테스트 iOS는 simulator만으로 끝내기 어렵다. 실제 iPhone에서 확인해야 한다. 특히 아래가 중요하다. - 문자 링크 또는 로그인 링크 처리 - 앱이 백그라운드에 있을 때 복귀 - 세션 저장 유지 - 배포 빌드 기준 동작 ### 9단계: TestFlight 배포 준비 내부 검증용으로는 TestFlight가 가장 현실적이다. 여기서는 아래가 필요하다. - archive/build 생성 - App Store Connect 등록 - 테스터 그룹 지정 - 배포 노트 작성 ### 10단계: 운영 전 점검 마지막으로 아래를 정리해야 한다. - iOS 버전명 규칙 - Android와 iOS의 동기 배포 여부 - 장애 시 재배포 절차 - 운영 담당자 확인 절차 ## 8.4 iOS 추가 시 예상 소요기간 검토 아래 기간은 "현재 Android 공통 코드가 어느 정도 있는 상태에서 iOS 대응을 추가한다"는 전제로 본 대략치다. 또한 아래 항목이 이미 준비되어 있다고 가정한다. - `tdc114plus-auth` staging 서버가 준비됨 - Baron SSO staging 연동이 Android 기준으로 먼저 안정화됨 - Apple 계정 발급이 장기 지연되지 않음 ## 8.5 권장 기간표 | 구분 | 예상 기간 | 설명 | | --- | --- | --- | | 사전 준비 및 계정/서명 정리 | 3~5 영업일 | Apple 계정, Bundle ID, signing, provisioning | | 로그인/링크/iOS 설정 반영 | 4~6 영업일 | Universal Link, callback, associated domains, 권한 설정 | | 공통 기능 iOS 실기기 정합성 점검 및 수정 | 5~7 영업일 | 검색, 조직도, 상세, 즐겨찾기, 프로필 이미지 | | TestFlight 배포 및 내부 검증 | 3~5 영업일 | 빌드, 업로드, 테스터 검증, 수정 반영 | | 운영 배포 준비 | 2~3 영업일 | 배포 기준, 장애 대응, 운영 체크 | 합산하면 보통 아래 정도로 보는 것이 현실적이다. - 빠른 경우: `3주 내외` - 보통 경우: `4주 내외` - 계정/서명/링크 이슈가 있으면: `5주 이상` ## 8.6 일정 시나리오별 판단 | 시나리오 | 예상 기간 | 특징 | | --- | --- | --- | | 낙관 시나리오 | 3주 | Apple 계정과 링크 설정이 빠르게 정리되고, 공통 코드 수정이 적음 | | 기본 시나리오 | 4주 | 가장 현실적인 기준. 실기기 수정과 TestFlight 재배포 1~2회 포함 | | 보수 시나리오 | 5~6주 | Universal Link, 서명, 심사/내부 승인 지연 또는 플랫폼 이슈 발생 | ## 8.7 현재 회의에서 추천할 일정 설명 회의에서는 아래 정도로 설명하는 것이 적절하다. "iOS는 Flutter 공통 코드를 활용할 수 있으므로 Android를 처음 만드는 수준의 장기 일정은 아니지만, Apple 계정, 서명, Universal Link, TestFlight 절차가 추가되므로 Android 안정화 이후 별도 3주에서 4주 정도의 확장 기간을 보는 것이 현실적입니다." ## 8.8 일정 산정 시 주의할 점 아래 항목은 일정에 큰 영향을 준다. 1. Apple Developer 계정과 권한이 이미 준비돼 있는지 2. 실제 테스트용 iPhone을 바로 확보할 수 있는지 3. Universal Link용 도메인 파일 배포를 누가 처리하는지 4. TestFlight 내부 배포 권한이 준비돼 있는지 5. Android와 서버 구조가 먼저 안정화되어 있는지 즉 iOS 일정은 단순 개발 공수보다 "운영 준비물의 선행 여부"에 많이 좌우된다. ## 9. 회의 중 확인받아야 할 질문 아래 질문은 회의에서 꼭 확인받는 것이 좋다. 1. 안드로이드 배포 대상 사용자는 사내 전용인지, 협력사까지 포함인지 2. 내부 APK 직접 배포로 시작해도 되는지, 아니면 처음부터 관리형 배포 체계를 써야 하는지 3. `tdc114plus-auth`를 올릴 수 있는 기존 운영 인프라가 있는지 4. `114-auth.hmac.kr` 같은 전용 서브도메인 사용이 가능한지 5. staging용 도메인과 production용 도메인을 별도로 줄 수 있는지 6. 서버 배포 시 블루/그린을 할 수 있을 만큼 인프라 자원이 있는지 7. 장애 시 rollback 책임자와 절차를 누가 맡는지 8. iOS를 올해 범위에 포함할지, Android 안정화 후 후속 단계로 둘지 9. Apple Developer 계정과 TestFlight 운영 권한을 누가 관리하는지 10. iOS 내부 테스트용 실기기와 담당자를 확보할 수 있는지 ## 10. 회의용 짧은 결론 문안 아래 문안은 그대로 읽어도 큰 무리가 없다. ```text 신규앱은 일반 화면 앱이 아니라 인증, 조직도, 프로필 이미지 프록시가 함께 붙는 구조이므로 production 직행보다 staging 안정화가 먼저 필요합니다. 배포 단위는 앱과 tdc114plus-auth 중계서버를 분리하는 것이 맞고, 중계서버는 별도 저장소와 별도 서비스로 유지하되 주소는 114-auth.hmac.kr 같은 전용 서브도메인으로 두는 안이 현실적입니다. 서버 배포 전략은 현재 단계에서는 카나리보다 단순하고 롤백이 빠른 블루/그린이 가장 적합합니다. iOS를 추가할 경우에는 Flutter 공통 코드 재사용이 가능하더라도 Apple 계정, 서명, Universal Link, TestFlight 절차가 별도로 필요하므로 Android 안정화 이후 약 3주에서 4주 정도의 추가 검토 및 적용 기간을 잡는 것이 현실적입니다. ``` ## 11. 회의 후 바로 이어질 실행 항목 회의에서 방향이 정해지면 바로 아래 작업으로 이어가면 된다. 1. staging 도메인, production 도메인, 인증서 담당자 확정 2. `tdc114plus-auth` 배치 위치 확정 3. 앱 빌드 버전 규칙과 Gitea 릴리스 태그 규칙 확정 4. staging APK 배포 및 실기기 점검 체크리스트 작성 5. production 승격 기준표 작성 6. rollback 절차 문서화 7. iOS 포함 시 Apple 계정/권한/도메인 담당자 확인 8. iOS 확장 일정표 초안 작성 ## 12. 현재 문서 기준 최종 판단 2026-07-20 현재 프로젝트 문서 흐름과 실제 구조를 함께 보면, 아래 판단이 가장 일관된다. - 신규앱은 staging을 먼저 두는 것이 맞다. - `tdc114plus-auth`는 Baron SSO에 흡수하지 않는 독립 서비스가 맞다. - 다만 도메인과 인프라는 Baron 계열 운영체계를 활용할 수 있다. - 서버 배포 전략은 블루/그린이 1순위, 롤링이 2순위, 카나리는 추후 검토가 적절하다. - iOS는 제외가 아니라 후속 확장 대상으로 보되, Android 구조 안정화 후 별도 3주~4주 수준의 준비/검증 기간을 추가로 보는 것이 현실적이다. 필요하면 이 문서를 바탕으로 바로 `회의자료용 1페이지 요약본`이나 `발표 순서형 문안`으로 다시 재구성한다.