#프로덕션 준비 체크리스트

버전: 0.33.0 최종 업데이트: 2026-03-15 적용 대상: ranvier-core, ranvier-runtime, ranvier-http, ranvier-std, ranvier-inspector 카테고리: 가이드

#1. 인증 및 인가

JWT 시크릿을 환경 변수(JWT_SECRET)에서 로드, 절대 하드코딩하지 않음
- 참조: `auth-tower-integration`, 보안 가이드
BearerAuth 가드에 타이밍 공격에 안전한 검증 구성 (subtle::ConstantTimeEq)
- 참조: `inspector-demo`
역할 기반 접근 제어를 위해 Axon::with_iam()으로 IAM 정책 정의
- 참조: `auth-jwt-role-demo`
토큰 만료 및 갱신 전략 결정
민감한 엔드포인트 보호 (관리자 라우트, 데이터 내보내기)

#2. 보안

CorsGuard에 명시적 허용 출처 구성 (프로덕션에서 * 사용 금지)
- 참조: `guard-demo`
공개 엔드포인트에 RateLimitGuard 적용
- 참조: `guard-demo`
SecurityHeadersGuard에서 HSTS, CSP, X-Frame-Options 주입
필요 시 관리자 엔드포인트에 IpFilterGuard 구성
릴리스 모드에서 오류 응답이 스택 트레이스를 노출하지 않음 (수정을 위해 Sensitive<T> 사용)
- 참조: 보안 가이드 §오류 응답
XorEncryption을 프로덕션에 사용하지 않음 (지원 중단, 피처 게이트)

#3. 관측성

트레이스 및 메트릭을 위한 OpenTelemetry exporter 구성
- 참조: `telemetry-otel-demo`, OTel 운영 플레이북
로드 밸런서 프로브를 위한 /health 및 /ready 엔드포인트 구현
- 참조: `production-config-demo`
적절한 로그 수준으로 tracing_subscriber 초기화 (RUST_LOG 환경 변수)
프로덕션에서 Inspector 대시보드 접근 제한 (BearerAuth 필수)
- 참조: `inspector-demo`
규정 준수 관련 작업에 대한 감사 로깅 활성화
- 참조: `audit-demo`

#4. 복원력

외부 서비스 호출에 적절한 정책으로 then_with_retry() 적용
- RetryPolicy::exponential_default(max_attempts, initial_ms) 권장
- 참조: `resilience-patterns-demo`
예측 불가능한 지연이 있는 작업에 then_with_timeout() 적용
- 참조: `resilience-patterns-demo`
우아한 종료 타임아웃 구성 (Tokio 시그널 핸들러)
- 참조: `production-operations-demo`
외부 서비스 호출에서 재시도 가능한 오류에는 Outcome::Fault, 클라이언트 오류에는 Outcome::Branch 사용
- 참조: `service-call-demo`

#5. 데이터 및 영속성

적절한 max_connections와 min_connections로 커넥션 풀 구성
영속성 스토어 선택:
- InMemoryPersistenceStore — 로컬 개발 전용
- PostgresPersistenceStore — 내구성 있는 프로덕션 저장소 (persistence-postgres 피처)
- RedisPersistenceStore — 임시/빠른 체크포인트 (persistence-redis 피처)
- 참조: `state-persistence-demo`
PostgresPersistenceStore에 대해 시작 시 ensure_schema() 호출
중요 워크플로우에 대한 보상 훅 정의 (CompensationHook 트레이트)
- 참조: `state-persistence-demo`
데이터베이스 테이블 이름 검증 (화이트리스트 패턴을 통한 SQL 인젝션 방지)

#6. 배포 및 빌드

--release 프로파일로 빌드 (LTO, strip, codegen-units=1)
```
cargo build --release
```
Dockerfile에 멀티 스테이지 빌드 사용 (빌더 → 런타임)
- 참조: 배포 가이드

환경 변수 문서화 및 로딩:

JWT_SECRET=...          # 인증에 필요
DATABASE_URL=...        # PostgresPersistenceStore에 필요
RUST_LOG=info           # 로그 수준
OTEL_EXPORTER_OTLP_ENDPOINT=...  # 선택사항: OTLP collector

시크릿을 버전 관리에 커밋하지 않음 (.gitignore에 .env 포함)
컨테이너 오케스트레이터에 헬스 체크 엔드포인트 구성

#7. CI/CD 파이프라인

Ranvier 프로젝트를 위한 최소 GitHub Actions 파이프라인:

name: CI
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
      - run: cargo check --workspace
      - run: cargo test --workspace
      - run: cargo clippy --workspace -- -D warnings
      - run: cargo build --release

팁:

빠른 빌드를 위해 ~/.cargo/registry와 target/ 캐시
린트 이슈를 조기에 잡기 위해 cargo clippy -- -D warnings 실행
피처 게이트 코드의 경우: cargo test --workspace --features persistence-postgres
병렬 실행을 위해 check, test, clippy를 별도 작업으로 분리 고려

#빠른 검증

# 전체 워크스페이스 확인
cargo check --workspace
cargo test --workspace
cargo clippy --workspace

# 프로덕션 유사 설정으로 실행
RUST_LOG=info JWT_SECRET=test-secret cargo run -p your-app --release

#관련 문서

보안 가이드 — 보안 강화 세부사항
OTel 운영 플레이북 — 관측성 설정
Persistence 운영 런북 — 영속성 운영
Bus 접근 패턴 — Bus 메서드 선택 가이드
API 안정성 계약 — v1.0 API 동결 범위