85 lines
3.4 KiB
Markdown
85 lines
3.4 KiB
Markdown
# Settings and Env Loading
|
|
|
|
- Related REQ: N/A
|
|
|
|
## 목표
|
|
설정값 로딩 경로를 단일화하여 로컬/운영 간 동작 차이를 최소화하고, 보안 민감 값을 안전하게 주입한다.
|
|
|
|
## 설정 로딩 우선순위
|
|
1. 환경 변수
|
|
2. `.env` 파일
|
|
3. 코드 기본값
|
|
|
|
## 핵심 설정 그룹
|
|
|
|
| 그룹 | 예시 키 | 목적 |
|
|
| --- | --- | --- |
|
|
| API/CORS | `PORTFOLIOHUB_ALLOWED_ORIGINS` | 브라우저 호출 허용 오리진 제어 |
|
|
| 인증/권한 | `PORTFOLIOHUB_READ_TOKENS`, `PORTFOLIOHUB_TRADE_WRITE_TOKENS`, `PORTFOLIOHUB_ADMIN_TOKENS` | 정적 토큰 기반 접근 제어 |
|
|
| 세션/토큰 TTL | `PORTFOLIOHUB_SESSION_TOKEN_TTL_HOURS` 등 | DB 발급 토큰 만료 정책 |
|
|
| Bootstrap User | `PORTFOLIOHUB_BOOTSTRAP_USERNAME`, `PORTFOLIOHUB_BOOTSTRAP_PASSWORD` | 초기 admin 사용자 생성 |
|
|
| DB 연결 | `TIMESCALEDB_*` | Postgres/Timescale 접속 정보 |
|
|
| Observability | `LOKI_*`, `REDIS_*` | 중앙 로그/캐시 운영 확장 포인트 |
|
|
|
|
## 상세 설정 명세
|
|
|
|
핵심 설정:
|
|
|
|
- `PORTFOLIOHUB_ALLOWED_ORIGINS`: comma-separated CORS origins
|
|
- `PORTFOLIOHUB_BOOTSTRAP_USERNAME`: users 테이블이 비어 있을 때 생성할 초기 username
|
|
- `PORTFOLIOHUB_BOOTSTRAP_EMAIL`: bootstrap user의 선택적 email
|
|
- `PORTFOLIOHUB_BOOTSTRAP_PASSWORD`: 초기 admin password
|
|
- `PORTFOLIOHUB_READ_TOKENS`: comma-separated read tokens
|
|
- `PORTFOLIOHUB_TRADE_WRITE_TOKENS`: comma-separated trade-write tokens
|
|
- `PORTFOLIOHUB_ADMIN_TOKENS`: comma-separated admin tokens
|
|
- `PORTFOLIOHUB_DB_ENABLED`: `true`일 때 DB repository 활성화
|
|
- `PORTFOLIOHUB_SESSION_TOKEN_TTL_HOURS`: login session token TTL(hours)
|
|
- `PORTFOLIOHUB_CLIENT_TOKEN_DEFAULT_TTL_DAYS`: client token 기본 TTL(days)
|
|
- `PORTFOLIOHUB_BOT_TOKEN_DEFAULT_TTL_DAYS`: bot token 기본 TTL(days)
|
|
|
|
DB 활성 설정:
|
|
|
|
- `TIMESCALEDB_HOST`
|
|
- `TIMESCALEDB_PORT`
|
|
- `TIMESCALEDB_NAME`
|
|
- `TIMESCALEDB_USER`
|
|
- `TIMESCALEDB_PASSWORD`
|
|
- `TIMESCALEDB_SSLMODE`
|
|
- `TIMESCALEDB_CONNECT_TIMEOUT_SEC`
|
|
- `TIMESCALEDB_APPLICATION_NAME`
|
|
|
|
파생 설정:
|
|
|
|
- `active_database_url`은 psycopg PostgreSQL URL 포맷으로 credentials와 query options를 인코딩해 구성한다.
|
|
|
|
## CORS 정책
|
|
|
|
CORS middleware는 다음 기준으로 동작한다.
|
|
|
|
- `allow_origins`: 구성된 origins 목록 사용
|
|
- `allow_credentials = true`
|
|
- `allow_methods = ["GET", "POST", "PATCH", "DELETE", "OPTIONS"]`
|
|
- `allow_headers = ["Authorization", "Content-Type"]`
|
|
|
|
브라우저 기반 frontend가 HTTPS로 접근하면 `PORTFOLIOHUB_ALLOWED_ORIGINS`에는 정확한 HTTPS origin만 명시한다.
|
|
|
|
예시:
|
|
|
|
```bash
|
|
PORTFOLIOHUB_ALLOWED_ORIGINS=https://app.example.com,https://www.example.com
|
|
```
|
|
|
|
## 운영 규칙
|
|
- 운영 환경에서는 `.env` 대신 배포 플랫폼의 환경 변수 주입을 우선한다.
|
|
- `PORTFOLIOHUB_DB_ENABLED=true`일 때 `TIMESCALEDB_*` 필수 키 누락 여부를 시작 시 검증한다.
|
|
- 민감 값은 문서/샘플에 실제 비밀 값을 기록하지 않는다.
|
|
|
|
## Validation Notes
|
|
- 필수 키 누락 시 명확한 예외 메시지로 기동 실패해야 한다.
|
|
- CORS 오리진 파싱은 공백/쉼표 변형 입력에도 안정적으로 동작해야 한다.
|
|
- 부트스트랩 계정 자동 생성은 `users` 테이블이 비어 있을 때만 수행되어야 한다.
|
|
|
|
## Open Implementation Points
|
|
- 설정 스키마를 strict mode로 고정할지(미정의 키 거부) 여부를 확정한다.
|
|
- Redis/Loki 활성화 플래그와 실패 시 동작(무시/실패)을 명시적으로 분리할지 결정한다.
|