287 lines
6.8 KiB
Markdown
287 lines
6.8 KiB
Markdown
# 원격 설정 (Remote Config) 스키마 문서
|
|
|
|
## 개요
|
|
|
|
이 문서는 `https://jwt.wrmc.cc/config`에서 호스팅되는 원격 설정 파일의 스키마와 운영 가이드를 설명합니다.
|
|
|
|
클라이언트 애플리케이션은 시작 시 이 설정을 가져와 Supabase 연결 정보, 기능 플래그, 점검 모드 등을 동적으로 적용합니다.
|
|
|
|
---
|
|
|
|
## JSON 스키마
|
|
|
|
```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` 섹션을 수정합니다:
|
|
|
|
```json
|
|
{
|
|
"maintenance": {
|
|
"enabled": true,
|
|
"message": "서버 점검 중입니다. 오후 2시에 재개 예정입니다.",
|
|
"estimatedEndTime": "2025-11-30T14:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
**클라이언트 동작**:
|
|
- 앱 시작 시 점검 모드 메시지가 표시되고 앱이 종료됩니다.
|
|
|
|
**점검 완료 후**:
|
|
```json
|
|
{
|
|
"maintenance": {
|
|
"enabled": false,
|
|
"message": "",
|
|
"estimatedEndTime": null
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 2. 운영 서버 장애 시 (미러 서버 전환)
|
|
|
|
기본 운영 서버에 문제가 생겼을 때 미러 서버로 전환:
|
|
|
|
```json
|
|
{
|
|
"environments": {
|
|
"main": {
|
|
"enabled": false,
|
|
...
|
|
},
|
|
"mirror": {
|
|
"enabled": true,
|
|
...
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**클라이언트 동작**:
|
|
- `main`이 비활성화되면 자동으로 `priority`가 가장 높은 활성화된 환경(mirror)을 선택합니다.
|
|
|
|
**복구 후**:
|
|
```json
|
|
{
|
|
"environments": {
|
|
"main": {
|
|
"enabled": true,
|
|
...
|
|
},
|
|
"mirror": {
|
|
"enabled": false,
|
|
...
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3. 개발 환경 사용
|
|
|
|
개발자가 개발 서버를 사용하려면 코드에서 환경을 지정합니다:
|
|
|
|
```python
|
|
# 특정 환경 지정
|
|
supabase_manager = SupabaseManager(logger, environment="development")
|
|
```
|
|
|
|
또는 서버 설정에서 `defaultEnvironment`를 변경:
|
|
|
|
```json
|
|
{
|
|
"defaultEnvironment": "development"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 4. 기능 플래그 활용
|
|
|
|
특정 기능을 서버에서 제어하려면:
|
|
|
|
```json
|
|
{
|
|
"features": {
|
|
"debugMode": true,
|
|
"newFeatureX": false
|
|
}
|
|
}
|
|
```
|
|
|
|
클라이언트 코드에서:
|
|
```python
|
|
if supabase_manager.is_feature_enabled("debugMode"):
|
|
# 디버그 모드 동작
|
|
pass
|
|
```
|
|
|
|
---
|
|
|
|
### 5. 설정 버전 관리
|
|
|
|
설정을 변경할 때마다 `configVersion`과 `lastUpdated`를 업데이트합니다:
|
|
|
|
```json
|
|
{
|
|
"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` | 점검 모드 설정 |
|
|
|
|
---
|
|
|
|
## 폴백 동작
|
|
|
|
원격 설정 서버에 접속할 수 없는 경우, 클라이언트는 하드코딩된 기본값을 사용합니다:
|
|
|
|
```python
|
|
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` |
|
|
|
|
---
|
|
|
|
## 보안 고려사항
|
|
|
|
1. **HTTPS 필수**: 설정 파일은 반드시 HTTPS로 제공해야 합니다.
|
|
2. **anon key만 노출**: 서비스 키는 절대 노출하지 마세요.
|
|
3. **CDN 캐싱**: 설정 변경 시 CDN 캐시 무효화를 확인하세요.
|