07 Demo Deployment

데모 배포 가이드

원칙

데모도 배포입니다.

시연자 PC에서 LM Studio를 켜두는 방식은 최종 구조가 아닙니다. 팀과 심사자가 접근 가능한 HTTPS 환경에서 PostgreSQL과 외부 LLM API/Cloud Endpoint를 사용합니다.

목표 구조

flowchart LR
  U["React Client / Worker Link"] -->|HTTPS| B["Spring Boot Demo"]
  B --> P["PostgreSQL"]
  B --> E["Durable Event Publication"]
  E --> B
  B --> A["AI Adapter"]
  A --> L["External LLM / Cloud Endpoint"]
  B -.-> O["Health · Logs · Metrics · Traces"]

Loading

배포 단위

한 Agent release를 다음 조합으로 식별합니다.

• backend_version
• agent_version
• model_provider, model_name, model_version
• prompt_version
• context_pack_version
• workflow_catalog_version

각 AI Run에는 실제 사용값과 request_id, trace_id를 저장합니다.

설정 범주

범주	예시	관리
Spring/DB	profile, JDBC URL, username/password	설정 + Secret
Auth	JWT secret, Access/Refresh TTL	Secret + 안전한 설정
AI Provider	base URL, API key, model	설정 + Secret
Resilience	connect/read timeout, retry max, concurrency	version 관리 설정
Agent	agent/prompt/context/workflow version	release 설정
Worker Link	TTL, rotation, rate limit	사업장/서버 정책
Observability	exporter, sampling, service version	배포 설정

정확한 환경변수 이름은 .env.example과 Spring configuration metadata를 기준으로 합니다. 실제 값은 Wiki·Issue·PR·Docker image에 기록하지 않습니다.

Liveness·Readiness·Degraded

• Liveness: Spring process가 정상적으로 동작하는지 봅니다.
• Readiness: PostgreSQL처럼 핵심 요청에 필요한 의존성을 확인합니다.
• AI degraded: 외부 Provider 장애를 별도로 표시합니다.

AI Provider가 잠시 실패한다고 전체 서버를 restart loop에 넣지 않습니다. HR이 기존 Task를 조회·수동 처리할 수 있다면 서버는 살아 있고 AI 기능만 degraded일 수 있습니다.

배포 전 체크리스트

Code·DB

• main CI 성공, Java 17 image 기동
• prod에서 H2와 ddl-auto: update 미사용
• Flyway migration 순서·checksum·이전 version 호환 검토
• domain 상태와 event publication table이 함께 준비됨
• seed·backup·snapshot에 실제 개인정보 없음

Security

• HTTPS와 최소 CORS origin
• JWT·DB·AI Secret은 배포 환경에만 저장
• prod Swagger 공개 범위 결정
• Authorization·Worker token·URL·PII log redaction
• 공개 link 만료·rotation·폐기·rate limit
• upload size·MIME·격리 정책

AI·Reliability

• 외부 Provider/model/version 확인, LM Studio 종료
• timeout·제한적 retry·circuit breaker·bulkhead 확인
• POST /ai-runs가 202를 반환하고 상태 조회 가능
• JSON Schema·핵심값·PII 실패가 자동 성공이 아님
• 같은 idempotency key와 confirm이 중복 생성하지 않음
• 미완료 Run/event의 재시작 복구 확인
• 영구 실패에서 수동 처리·재처리 절차 확인

관측·Rollback

• request_id/trace_id로 API→event→Provider→audit 추적
• queue 지연·AI 실패·event retry 최소 metric 확인
• 직전 image와 Agent 배포 단위 식별
• backward-compatible migration과 application rollback 범위 확인
• 관측 exporter 장애가 business transaction을 막지 않음

배포 후 Smoke Test

1. /health, liveness, DB readiness 확인
2. HR 로그인과 tenant 확인
3. 테스트 근로자 조회/등록
4. POST /ai-runs로 복합 요청 제출, 202/runId 확인
5. Run 상태 poll 후 후보 2개와 version·validation 확인
6. 선택 후보 confirm, 승인 전 link 발급 차단 확인
7. HR 승인 후 Worker Link 생성·조회
8. 근로자 응답 또는 문서 제출
9. 증빙·완료와 activities/audit 확인
10. application restart 뒤 미완료 Run/event 복구 확인

정확한 payload는 배포 Swagger와 #10 E2E의 runbook을 기준으로 합니다.

데모 당일

시작 30분 전

• 배포 version·DB readiness·AI degraded 상태 확인
• 외부 LLM 상태·비용/Rate Limit 확인
• 데모 account·seed 날짜 확인
• 이전 test Worker Link/token 폐기
• Golden Scenario와 한 번의 실패 시나리오 실행
• trace와 audit를 찾을 수 있는지 확인

시연 중 강조할 내용

1. 단순 번역이 아니라 여러 업무카드 후보로 구조화
2. 202 비동기 Run으로 지연·재시작에 안전
3. 민감정보를 제거하고 Structured Output·핵심값을 검증
4. AI 원본과 HR 수정·승인을 분리
5. 근로자는 만료 link에서 제한된 행동만 수행
6. 장애·재시도·전체 업무 흐름과 Agent version 추적

장애 시 안전한 대응

증상	확인	안전한 다음 행동
Provider timeout/429	Run error_code, circuit, Provider status	retry budget 후 수동 입력·나중 재시도
JSON/Schema 실패	validation 상태, 원문 log 금지	NEEDS_REVIEW 또는 명시적 실패 설명
DB 연결 실패	readiness, Flyway, DB status	application 반복 restart 전에 DB 확인
Run이 멈춤	상태 시각, 미완료 publication	recovery procedure 실행·중복 여부 확인
Worker Link 만료	expiry/revoked reference	HR rotation 절차 사용
권한/tenant 오류	Role·token claims·safe audit	개인정보 출력 없이 test account 확인

Fake 결과를 실제 AI 결과처럼 보여주거나 DB 상태를 수동으로 조작해 성공을 위장하지 않습니다. 사전 녹화나 test fixture를 사용하면 그 사실을 명확히 밝힙니다.

MVP 이후

Agent Router를 도입할 때 Green을 staging smoke evaluation 후 0% → 10% → 50% → 100%로 전환합니다. 문제 시 Blue로 되돌리되 backend/DB contract 호환과 Agent 배포 단위를 함께 확인합니다. M3에서는 version 기록·rollback 가능한 image·migration 규칙까지만 준비합니다.

관련 이슈

• #9 데모 배포
• #10 E2E·runbook
• #25 Event 재처리
• #26 관측성