kevin/tdc114plus

Fork 0

Files

T

Codex 5d3eee7a16 Stabilize auth flow and profile images

2026-07-20 13:38:39 +09:00

15 KiB

Raw Blame History

출근 후 기동 확인 및 복구 체크리스트

작성일: 2026-07-03
최종 업데이트: 2026-07-19
버전: 2.5 (개발용 로컬 Baron worktree와 최종 배포 목표 구조 구분 반영)

목적

전날 퇴근하면서 VS Code, 터미널, Android target을 모두 종료한 뒤, 다음 출근 시 tdc114plus 작업을 빠르게 재개할 수 있도록 기동 확인과 복구 절차를 고정한다.

핵심 정책: 소스코드 변경을 요하지 않는 자동 복구(컨테이너 재시작, 충돌 컨테이너 정리, 권한 수정, 디렉터리 정리 등)는 사용자 승인 없이 자동으로 진행한다.

1. 적용 대상

앱 저장소: /home/ubuntu/workspace/tdc114plus
Baron SSO API worktree: /home/ubuntu/workspace/baron-sso-tdc114plus-api
auth 중계서버 저장소: /home/ubuntu/workspace/tdc114plus-auth
Windows ADB 서버 공유 기반 Android target + WSL/Docker Flutter 조합

주의:

이 체크리스트는 현재 개발/검증용 업무시작 기동 기준이다.
최종 배포 목표 구조에서는 로컬 baron-sso-tdc114plus-api 기동이 없어지는 방향을 목표로 한다.
다만 2026-07-19 현재는 아직 일부 로그인/조직 연동 검증이 로컬 Baron worktree에 의존하므로, 업무 시작 기동 대상에서 바로 제거하지 않는다.

2. 출근 후 기본 순서

아래 순서를 기본값으로 사용한다.

VS Code를 연다.
작업 기준 문서를 먼저 연다.
- docs/00_guide_tdc114plus_work_progress_timetable_2026-07-02.md
- docs/daily-issues/YYYY-MM-DD.md
Android target 선행 확인
Baron SSO runtime 초기화 (아래 섹션 참고)
tdc114plus-auth broker 기동 및 health 확인
1차 상태 확인 명령 실행
Integration test 실행

현재 해석:

tdc114plus와 tdc114plus-auth는 최종 배포 직접 대상이다.
baron-sso-tdc114plus-api는 현재 개발 중 연동 검증용 보조 worktree다.
Baron SSO 원본 staging/production 연동으로 완전히 전환되기 전까지는 이 보조 worktree 기동 여부가 앱 개발 중 동작에 직접 영향을 줄 수 있다.

3. 런타임 초기화 및 1차 확인

3.0 Android target 선행 확인

startup.sh는 이제 가장 먼저 Android target 상태를 확인한다. 실기기 또는 emulator가 offline, unauthorized, connection refused 중 하나면 Baron runtime 기동 전에 멈추고, Windows에서 무엇을 해야 하는지 단계별로 출력한다.

기본 정책:

기본 타깃은 실기기 1대다. emulator는 fallback일 때만 1대만 켠다.
Windows adb.exe devices에서 대상 Android target이 device 상태인지 먼저 확인한다.
표준 연결 방식은 Windows ADB server 공유 방식인 ADB_SERVER_SOCKET=tcp:172.21.128.1:5037을 사용한다.
직접 emulator port 연결인 TDC114_ADB_CONNECT_ADDRESS=<host>:<port>는 Docker local ADB가 꼭 필요한 예외 상황에만 사용한다.
Windows 단독 device 상태가 확인되기 전에는 WSL/Docker Android 스크립트를 실행하지 않는다.

권장 실행:

# Android preflight + startup 계획 확인
ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/startup.sh --dry-run --wait=40

# 실제 기동
ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/startup.sh --auto --wait=40

Android target preflight 실패 시 사용자가 로컬 PC에서 최소한으로 해야 하는 일:

Windows에서 Android Studio를 연다.
실기기면 USB 디버깅 연결을 확인하고, emulator fallback이면 Device Manager에서 1대만 켠다.
Windows PowerShell에서 adb.exe devices를 실행해 device 상태를 확인한다.
여전히 offline이면 대상 기기 또는 emulator를 재시작한다.
Windows adb는 정상인데 WSL/Docker에서만 실패하면 우선 5037 -> 127.0.0.1:5037 portproxy와 방화벽 rule을 확인한다.
5037 공유 방식은 정상인데 특정 integration test에서만 막히면 그때 <EMULATOR_PORT> -> 127.0.0.1:<EMULATOR_PORT> 직접 연결 보조 경로를 검토한다.

이 단계는 Codex가 대신 할 수 없다.

Codex가 계속할 수 있는 작업:

WSL/Docker에서 Android target 재인식 확인
Baron runtime 기동
API smoke 확인
integration/manual Android 명령 실행
tdc114plus-auth broker 기동 확인 및 자동 실행 시도

3.05 앱 직접 App Link callback 제거

2026-07-15 기준 신규 앱은 Baron SSO OIDC callback을 직접 받지 않는다.

기본 정책:

앱은 https://114.hmac.kr/auth/callback App Link를 사용하지 않는다.
앱은 tdc114plus-auth의 /api/v1/auth/link/init, /api/v1/auth/link/poll만 호출한다.
Baron SSO OIDC callback은 tdc114plus-auth가 받는다.
필요한 redirect URI는 https://114-auth.hmac.kr/api/v1/auth/oidc/callback이다.
Windows 로컬 App Link 테스트 서버는 업무 시작 기동 대상이 아니다.

참조 문서:

docs/00_guide_tdc114plus_auth_broker_redirect_flow_2026-07-15.md

3.1 Baron SSO 런타임 전체 초기화

중요: Baron SSO는 인프라(PostgreSQL, Redis, ClickHouse)와 Ory 인증(Kratos, Hydra, Keto) 서비스가 모두 필수다.

단순히 docker compose up -d로는 불충분하다. 반드시 모든 compose 파일을 포함해야 한다:

cd /home/ubuntu/workspace/baron-sso-tdc114plus-api

# 모든 compose 파일 포함하여 안전 중지 후 재시작
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml down 2>/dev/null || true
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d

# compose up 실패 시(예: name conflict) 기존 관련 컨테이너 정리 후 1회 재시도
docker ps -a --format '{{.Names}}' | grep -iE "baron|ory" | xargs -r docker rm -f
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d

# 서비스 안정화 대기 (인지 마이그레이션/헬스체크 완료)
sleep 30

# tdc114plus로 돌아가기
cd /home/ubuntu/workspace/tdc114plus

3.2 1차 상태 확인 명령

cd /home/ubuntu/workspace/tdc114plus

# Baron runtime 상태 확인 (스크립트로 자동 실행 가능)
./scripts/check-baron-api-env.sh

# API smoke 테스트 (스크립트로 자동 실행 가능)
./scripts/api-smoke.sh

실행 방법 (권장):

수동: 위 명령을 복사해 실행
자동(권장): scripts/startup.sh를 사용

자동 실행 예 (dry-run 권장):

# Dry-run: Android preflight 포함, 어떤 작업을 할지 미리 확인
ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/startup.sh --dry-run

# 실제 재기동(주의)
ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/startup.sh --auto --wait=40

기대 결과:

check-baron-api-env.sh: "RESULT ready-ish: 0 failure(s), 0 warning(s)"
api-smoke.sh: 성공 코드 0
tdc114plus-auth health: {"jwks":"ok","provider":"baron","status":"ok"}
scripts/startup.sh --auto: Android preflight, Baron runtime, tdc114plus-auth, smoke 조건 중 하나라도 충족하지 못하면 비정상 종료(exit 1)

4. 자동 복구 정책 및 규칙

4.1 자동 복구 대상 (사용자 승인 불필요)

다음 사항들은 소스 변경을 요하지 않으므로 자동으로 복구한다:

컨테이너 미실행: 자동 재시작 또는 전체 재기동
컨테이너 명 충돌: 기존 컨테이너 강제 제거 후 1회 재시작
권한 문제: chmod, chown 자동 수정
설정 디렉터리 부재: 자동 생성 또는 복원
헬스체크 실패 또는 warning: 최대 6회 재시도
서비스 안정화 대기: 자동 진행 (최대 60초)

4.2 수동 개입 필요 (사용자 승인 필요)

다음 사항들은 설정 또는 소스 변경을 요하므로 명시적 승인을 받는다:

소스코드 수정
환경 변수 값 변경
설정 파일 내용 수정
데이터베이스 마이그레이션 또는 초기화
API 엔드포인트 주소 변경

5. 실패 시 복구 순서

5.1 `check-baron-api-env.sh` 실패 또는 warning 다수

Baron SSO runtime 상태 확인 및 복구:

cd /home/ubuntu/workspace/baron-sso-tdc114plus-api

자동 복구 절차 (순차 실행):

# 1단계: 안전 중지 후 전체 재시작
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml down 2>/dev/null || true
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d

# 2단계: name conflict가 보이면 관련 컨테이너 정리 후 1회 재시작
docker ps -a --format '{{.Names}}' | grep -iE "baron|ory" | xargs -r docker rm -f
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d

# 3단계: 서비스 안정화 대기
sleep 30

# 4단계: 재확인
cd /home/ubuntu/workspace/tdc114plus
./scripts/check-baron-api-env.sh

상태 확인 명령어:

docker ps --format '{{.Names}} {{.Status}}' | grep -E "baron_backend|baron_gateway|ory_kratos|ory_postgres"

정상 기대 상태:

서비스	상태	설명
`baron_backend`	Up (healthy)	메인 백엔드 서비스
`baron_gateway`	Up	리버스 프록시
`baron_postgres`	Up (healthy)	메인 데이터베이스
`baron_redis`	Up	캐시/세션 저장소
`ory_postgres`	Up (healthy)	Ory 데이터베이스
`ory_kratos`	Up	사용자 관리/인증
`ory_hydra`	Up	OAuth2/OIDC 제공자
`ory_keto`	Up	권한 관리

5.2 `api-smoke.sh` 실패 (HTTP 502/503)

원인 분석

# Ory Kratos 로그 확인 (인증 서비스)
docker logs ory_kratos 2>&1 | tail -30

# Baron backend 로그 확인
docker logs baron_backend 2>&1 | tail -30

# 전체 컨테이너 상태
docker ps | grep -iE "baron|ory"

자동 복구

Ory 또는 Baron 서비스가 준비 완료되지 않은 경우:

cd /home/ubuntu/workspace/baron-sso-tdc114plus-api

# 전체 재시작 (가장 안전한 방법)
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml down
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d
sleep 40

# 재확인
cd /home/ubuntu/workspace/tdc114plus
./scripts/api-smoke.sh

HTTP 401 (인증 오류)

cat /home/ubuntu/workspace/tdc114plus/scripts/.env.smoke.local | grep -E "PHONE|PROVIDER"

전화번호, provider 설정이 올바른지 확인. 변경 필요시 사용자 승인 후 수정.

6. Android target 확인

startup.sh가 이 단계를 먼저 수행하지만, 수동 재확인이 필요하면 아래 명령을 쓴다.

실기기 우선이면 USB 디버깅 연결을 먼저 확인하고, emulator fallback이면 Windows에서 Android Studio emulator를 켠다.

그 후 WSL/Docker 기준 확인:

cd /home/ubuntu/workspace/tdc114plus
ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/flutter-docker.sh devices

완료 기준:

emulator-<PORT> 또는 Android target이 표시된다.
직접 emulator port 연결은 표준 방식이 실패하거나 integration test 보조 경로가 필요할 때만 사용한다.

6.1 Android device가 보이지 않을 때

우선 정책 문서를 참고한다:

docs/policy_android_studio_wsl_adb_2026-07-03.md
docs/scenario_android_emulator_device_integration_test_2026-07-03.md

가장 흔한 확인 포인트:

Windows emulator가 실제로 켜져 있는가?
Windows adb.exe devices에서 대상이 device 상태인가?
당일 emulator port에 맞는 portproxy가 살아 있는가?
Docker local ADB가 device 상태를 보는가?

7. Android SDK license 관련

현재 scripts/flutter-docker.sh에는 Android SDK license 선행 승인 로직이 들어 있다.

다음과 같은 오류가 나면 먼저 cache 상태를 의심한다:

ndk;28.2.13676358 license not accepted
CMake 3.22.1 license not accepted

확인 경로:

ls -la /home/ubuntu/workspace/tdc114plus/.docker-cache/flutter/android-sdk/licenses/

이 디렉터리들이 비어 있지 않으면 재사용되는 것이 정상이다.

8. 정상 기대 상태

정상 재개 기준:

✅ ./scripts/check-baron-api-env.sh 통과 (0 failures, 0 warnings)
✅ ./scripts/api-smoke.sh 통과 (성공 코드 0)
✅ Android emulator device 인식 성공
✅ integration test 통과

Integration test에서 확인할 실제 홈화면 기대값:

로그인 후 홈화면에는 문형석의 조직 slug is-3 기준 팀 직원목록이 보여야 한다:

직원검색
검색 결과
문형석
IS3

9. 다음 조치

위 순서 중 어느 단계에서 실패했는지 docs/daily-issues/YYYY-MM-DD.md에 남긴다.

기록할 최소 항목:

실패 단계 (예: 3.2, 5.1, 5.2 등)
첫 번째 에러 메시지
수행한 자동 복구 명령
복구 성공 여부
추가 수동 개입 필요 여부 및 사유

기록 예시:

## 2026-07-06 출근 재기동

### 진행 상황
- [x] 3.1 Baron SSO 초기화: 성공
- [x] 3.2 상태 확인: 초기 실패 (baron_backend not running)
- [x] 5.1 자동 복구: docker compose 재시작 → 성공
- [x] 5.2 api-smoke 재확인: 통과
- [ ] 6.0 Android emulator: 미진행 (시간 부족)

### 실패 내역
- Initial check-baron-api-env.sh: WARN baron_backend not running
- Resolved with: docker compose -f ... up -d
- No source code changes needed

부록: 명령 치트시트

빠른 전체 초기화 (추천)

# 1. Baron SSO 전체 재시작 (권장)
cd /home/ubuntu/workspace/baron-sso-tdc114plus-api
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml down 2>/dev/null || true
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d
sleep 30

# 2. tdc114plus 상태 확인
cd /home/ubuntu/workspace/tdc114plus
./scripts/check-baron-api-env.sh && ./scripts/api-smoke.sh

컨테이너 상태 모니터링

# 실시간 로그 보기
docker logs -f baron_backend      # 백엔드 로그
docker logs -f ory_kratos         # 인증 로그

# 모든 baron/ory 컨테이너 상태
docker ps | grep -iE "baron|ory"

# 전체 상태 요약
docker ps --format '{{.Names}} {{.Status}}'

긴급 초기화 (최후의 수단)

cd /home/ubuntu/workspace/baron-sso-tdc114plus-api

# 모든 관련 컨테이너 강제 제거
docker ps -a --format '{{.Names}}' | grep -iE "baron|ory|sso" | xargs -r docker rm -f

# 전체 재시작
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d

# 서비스 안정화 대기
sleep 40

# 상태 확인
docker ps | grep -iE "baron_backend|ory_kratos"

일반적인 문제 해결

# 권한 문제 수정 (config 디렉터리 쓰기 불가)
cd /home/ubuntu/workspace/baron-sso-tdc114plus-api
chmod -R u+w config/.generated/ 2>/dev/null || true

# Ory 마이그레이션 재시도
docker compose -f docker-compose.yaml -f compose.ory.yaml up kratos-migrate

# 특정 컨테이너만 재시작
docker restart baron_backend
docker restart ory_kratos

# 로그 대량 확인
docker logs baron_backend 2>&1 | grep -i error | tail -20

변경 이력

v2.0 (2026-07-06)

자동 복구 정책 섹션 추가 (섹션 4)
Ory 포함 필수 명시 (섹션 3.1)
컨테이너 정리 자동화 (섹션 5.1)
안정화 대기 시간 추가 (30~40초)
권한 문제 자동 처리 설명 추가
명령 치트시트 부록 추가
문제 기록 템플릿 추가 (섹션 9)

v1.0 (2026-07-03)

초기 버전: 기본 기동 절차 및 복구 순서

15 KiB Raw Blame History