6.8 KiB

Raw Blame History

원격 설정 (Remote Config) 스키마 문서

개요

이 문서는 https://jwt.wrmc.cc/config에서 호스팅되는 원격 설정 파일의 스키마와 운영 가이드를 설명합니다.

클라이언트 애플리케이션은 시작 시 이 설정을 가져와 Supabase 연결 정보, 기능 플래그, 점검 모드 등을 동적으로 적용합니다.

JSON 스키마

{
  "configVersion": "20251130.2",
  "lastUpdated": "2025-11-30T12:00:00Z",
  "environments": {
    "main": {
      "supabaseUrl": "https://kong.wrmc.cc",
      "anonKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "priority": 1,
      "enabled": true,
      "description": "기본 운영 서버"
    },
    "mirror": {
      "supabaseUrl": "https://mirror.wrmc.cc",
      "anonKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "priority": 2,
      "enabled": false,
      "description": "미러 서버 (장애 시 사용)"
    },
    "development": {
      "supabaseUrl": "https://dev.wrmc.cc",
      "anonKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "priority": 3,
      "enabled": false,
      "description": "개발 서버"
    }
  },
  "defaultEnvironment": "main",
  "features": {
    "debugMode": false
  },
  "maintenance": {
    "enabled": false,
    "message": "서버 점검 중입니다. 잠시 후 다시 시도해주세요.",
    "estimatedEndTime": "2025-11-30T14:00:00Z"
  }
}

필드 설명

최상위 필드

필드	타입	필수	설명
`configVersion`	string	✅	설정 버전 (형식: `YYYYMMDD.N`, 예: `20251130.2`)
`lastUpdated`	string	✅	최종 업데이트 시간 (ISO 8601 형식)
`environments`	object	✅	환경별 Supabase 연결 설정
`defaultEnvironment`	string	✅	기본 사용 환경
`features`	object	❌	기능 플래그 설정
`maintenance`	object	✅	점검 모드 설정

environments (환경 설정)

각 환경은 다음 필드를 포함합니다:

필드	타입	필수	설명
`supabaseUrl`	string	✅	Supabase 서버 URL
`anonKey`	string	✅	Supabase Anonymous Key
`priority`	number	✅	우선순위 (1이 가장 높음)
`enabled`	boolean	✅	환경 활성화 여부
`description`	string	❌	환경 설명 (로깅용)

환경 예시:

main: 기본 운영 서버
mirror: 미러 서버 (운영 서버 장애 시 사용)
development: 개발 서버

features (기능 플래그)

필드	타입	기본값	설명
`debugMode`	boolean	`false`	디버그 모드 활성화

💡 필요에 따라 새로운 기능 플래그를 추가할 수 있습니다.

maintenance (점검 모드)

필드	타입	설명
`enabled`	boolean	점검 모드 활성화 여부
`message`	string	사용자에게 표시할 점검 메시지
`estimatedEndTime`	string \| null	점검 종료 예정 시간 (ISO 8601)

운영 가이드

1. 서버 점검 시

서버 점검 시 maintenance 섹션을 수정합니다:

{
  "maintenance": {
    "enabled": true,
    "message": "서버 점검 중입니다. 오후 2시에 재개 예정입니다.",
    "estimatedEndTime": "2025-11-30T14:00:00Z"
  }
}

클라이언트 동작:

앱 시작 시 점검 모드 메시지가 표시되고 앱이 종료됩니다.

점검 완료 후:

{
  "maintenance": {
    "enabled": false,
    "message": "",
    "estimatedEndTime": null
  }
}

2. 운영 서버 장애 시 (미러 서버 전환)

기본 운영 서버에 문제가 생겼을 때 미러 서버로 전환:

{
  "environments": {
    "main": {
      "enabled": false,
      ...
    },
    "mirror": {
      "enabled": true,
      ...
    }
  }
}

클라이언트 동작:

main이 비활성화되면 자동으로 priority가 가장 높은 활성화된 환경(mirror)을 선택합니다.

복구 후:

{
  "environments": {
    "main": {
      "enabled": true,
      ...
    },
    "mirror": {
      "enabled": false,
      ...
    }
  }
}

3. 개발 환경 사용

개발자가 개발 서버를 사용하려면 코드에서 환경을 지정합니다:

# 특정 환경 지정
supabase_manager = SupabaseManager(logger, environment="development")

또는 서버 설정에서 defaultEnvironment를 변경:

{
  "defaultEnvironment": "development"
}

4. 기능 플래그 활용

특정 기능을 서버에서 제어하려면:

{
  "features": {
    "debugMode": true,
    "newFeatureX": false
  }
}

클라이언트 코드에서:

if supabase_manager.is_feature_enabled("debugMode"):
    # 디버그 모드 동작
    pass

5. 설정 버전 관리

설정을 변경할 때마다 configVersion과 lastUpdated를 업데이트합니다:

{
  "configVersion": "20251130.3",
  "lastUpdated": "2025-11-30T15:30:00Z",
  ...
}

버전 형식: YYYYMMDD.N

YYYYMMDD: 날짜 (예: 20251130)
N: 해당 날짜의 리비전 번호 (1, 2, 3, ...)

클라이언트 API

SupabaseManager 메서드

메서드	반환 타입	설명
`is_feature_enabled(name, default=False)`	`bool`	기능 활성화 여부
`is_maintenance_mode()`	`bool`	점검 모드 여부
`get_maintenance_message()`	`str`	점검 메시지
`get_maintenance_end_time()`	`str \| None`	점검 종료 예정 시간
`get_config_info()`	`dict`	전체 설정 정보

속성

속성	타입	설명
`config_version`	`str`	설정 버전
`last_updated`	`str`	최종 업데이트 시간
`current_environment`	`str`	현재 환경 이름
`features`	`dict`	기능 플래그
`maintenance`	`dict`	점검 모드 설정

폴백 동작

원격 설정 서버에 접속할 수 없는 경우, 클라이언트는 하드코딩된 기본값을 사용합니다:

DEFAULT_URL = "https://kong.wrmc.cc"
DEFAULT_KEY = "eyJhbGciOiJIUzI1NiIs..."
DEFAULT_ENVIRONMENT = "production"

운영 시나리오 요약

시나리오	변경 내용
서버 점검	`maintenance.enabled = true`
점검 완료	`maintenance.enabled = false`
기본 서버 장애	`main.enabled = false`, `mirror.enabled = true`
기본 서버 복구	`main.enabled = true`, `mirror.enabled = false`
개발 모드 전환	`defaultEnvironment = "development"`
디버그 모드	`features.debugMode = true`

보안 고려사항

HTTPS 필수: 설정 파일은 반드시 HTTPS로 제공해야 합니다.
anon key만 노출: 서비스 키는 절대 노출하지 마세요.
CDN 캐싱: 설정 변경 시 CDN 캐시 무효화를 확인하세요.

6.8 KiB Raw Blame History