fix: 인증 미들웨어 활성화, lifespan 예외처리, Docker 네트워크 바인딩 수정 및 문서 전면 개선
- hydra/main.py: auth_guard 미들웨어에 실제 API 키 검증 로직 추가 - hydra/main.py: lifespan 초기화 블록 try-except 감싸기, finally에서 ohlcv_store None 체크 추가 - Dockerfile: --host 127.0.0.1 → 0.0.0.0 (컨테이너 간 통신 가능하도록) - hydra/config/settings.py: 기본 API 키 사용 시 경고 validator 추가 - README.md: 첫 사용자를 위한 상세 가이드로 전면 재작성 - docs/QUICKSTART_KO.md: 단계별 시작 가이드 개선 - docs/API_REFERENCE_KO.md: 전체 엔드포인트 응답 예시 및 파라미터 설명 추가 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
sinmb79
@@ -1,116 +1,190 @@
|
||||
# HYDRA Engine 빠른 시작 가이드
|
||||
|
||||
이 문서는 "처음 받은 사람이 10분 안에 테스트와 기본 실행까지 해보는 것"을 목표로 합니다.
|
||||
**목표:** 이 문서를 따라하면 10~15분 안에 테스트 통과 및 서버 기동까지 완료할 수 있습니다.
|
||||
|
||||
## 1. 준비물
|
||||
---
|
||||
|
||||
- Python 3.11 이상
|
||||
- Git
|
||||
- Docker / Docker Compose
|
||||
|
||||
## 2. 설치
|
||||
## 1단계: 저장소 다운로드
|
||||
|
||||
```bash
|
||||
git clone https://github.com/sinmb79/Hydra-Engine.git
|
||||
cd Hydra-Engine
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2단계: Python 가상환경 설정
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
```
|
||||
|
||||
Windows PowerShell:
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
.venv\Scripts\Activate.ps1
|
||||
```
|
||||
|
||||
패키지 설치:
|
||||
**macOS / Linux:**
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
터미널 앞에 `(.venv)` 가 표시되면 활성화 성공입니다.
|
||||
|
||||
```bash
|
||||
pip install -e .[dev]
|
||||
```
|
||||
|
||||
## 3. 환경 변수
|
||||
---
|
||||
|
||||
## 3단계: 환경 변수 설정
|
||||
|
||||
**macOS / Linux:**
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
최소 예시:
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
Copy-Item .env.example .env
|
||||
```
|
||||
|
||||
`.env` 파일을 열고 `HYDRA_API_KEY` 를 변경합니다:
|
||||
|
||||
```env
|
||||
HYDRA_API_KEY=my-local-demo-key
|
||||
HYDRA_API_KEY=my-secret-key-2024
|
||||
HYDRA_PROFILE=lite
|
||||
REDIS_URL=redis://localhost:6379
|
||||
```
|
||||
|
||||
## 4. 정상 동작 확인
|
||||
> `HYDRA_API_KEY` 는 API 호출 시 사용하는 비밀번호입니다. 아무 문자열이나 가능합니다.
|
||||
|
||||
---
|
||||
|
||||
## 4단계: 테스트 실행
|
||||
|
||||
```bash
|
||||
pytest -q
|
||||
```
|
||||
|
||||
테스트가 모두 통과하면 기본 코드 상태는 정상입니다.
|
||||
전체 테스트가 통과하면 코드 상태가 정상입니다.
|
||||
|
||||
## 5. Lite 프로필 실행
|
||||
실패하는 테스트가 있으면:
|
||||
- 가상환경이 활성화되어 있는지 확인
|
||||
- `pip install -e .[dev]` 를 다시 실행
|
||||
|
||||
---
|
||||
|
||||
## 5단계: Docker로 서버 실행
|
||||
|
||||
Docker Desktop이 실행 중인지 먼저 확인합니다.
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.lite.yml up --build
|
||||
```
|
||||
|
||||
다른 터미널에서 헬스체크:
|
||||
새 터미널 창을 열고 헬스체크:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8000/health
|
||||
```
|
||||
|
||||
## 6. 필수 API 예제
|
||||
|
||||
### 6.1 활성 시장 확인
|
||||
|
||||
```bash
|
||||
curl -H "X-HYDRA-KEY: my-local-demo-key" http://127.0.0.1:8000/markets
|
||||
```json
|
||||
{"status": "ok"}
|
||||
```
|
||||
|
||||
### 6.2 저장된 심볼 목록 확인
|
||||
이 응답이 오면 서버가 정상 실행 중입니다.
|
||||
|
||||
---
|
||||
|
||||
## 6단계: 기본 API 호출 테스트
|
||||
|
||||
이후 모든 API 호출에는 `X-HYDRA-KEY` 헤더를 붙입니다.
|
||||
|
||||
### 시장 확인
|
||||
|
||||
```bash
|
||||
curl -H "X-HYDRA-KEY: my-local-demo-key" http://127.0.0.1:8000/data/symbols
|
||||
curl -H "X-HYDRA-KEY: my-secret-key-2024" \
|
||||
http://127.0.0.1:8000/markets
|
||||
```
|
||||
|
||||
### 6.3 백테스트 실행
|
||||
### 저장된 심볼 목록
|
||||
|
||||
```bash
|
||||
curl -H "X-HYDRA-KEY: my-secret-key-2024" \
|
||||
http://127.0.0.1:8000/data/symbols
|
||||
```
|
||||
|
||||
### 캔들 데이터 조회
|
||||
|
||||
```bash
|
||||
curl -G http://127.0.0.1:8000/data/candles \
|
||||
-H "X-HYDRA-KEY: my-secret-key-2024" \
|
||||
--data-urlencode "market=binance" \
|
||||
--data-urlencode "symbol=BTC/USDT" \
|
||||
--data-urlencode "timeframe=1h" \
|
||||
--data-urlencode "limit=50"
|
||||
```
|
||||
|
||||
### 백테스트 실행
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:8000/backtest/run \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-HYDRA-KEY: my-local-demo-key" \
|
||||
-H "X-HYDRA-KEY: my-secret-key-2024" \
|
||||
-d '{
|
||||
"market": "binance",
|
||||
"symbol": "BTC/USDT",
|
||||
"timeframe": "1h",
|
||||
"since": 1704067200000,
|
||||
"until": 1706745600000
|
||||
"until": 1706745600000,
|
||||
"initial_capital": 10000,
|
||||
"trade_amount_usd": 100,
|
||||
"commission_pct": 0.001
|
||||
}'
|
||||
```
|
||||
|
||||
## 7. CLI 예제
|
||||
---
|
||||
|
||||
```bash
|
||||
python -m hydra.cli.app status
|
||||
python -m hydra.cli.app market list-markets
|
||||
python -m hydra.cli.app market enable binance --mode paper
|
||||
python -m hydra.cli.app kill
|
||||
## 7단계: 권장 사용 순서
|
||||
|
||||
```
|
||||
테스트 통과 확인
|
||||
↓
|
||||
시장 설정 확인 (GET /markets)
|
||||
↓
|
||||
데이터 수집 상태 확인 (GET /data/symbols)
|
||||
↓
|
||||
캔들 데이터 조회 (GET /data/candles)
|
||||
↓
|
||||
백테스트 실행 (POST /backtest/run)
|
||||
↓
|
||||
전략 성과 분석
|
||||
↓
|
||||
(충분한 검증 후) 실거래 연결
|
||||
```
|
||||
|
||||
## 8. 추천 사용 순서
|
||||
---
|
||||
|
||||
1. 테스트 통과 확인
|
||||
2. Lite 프로필 실행
|
||||
3. 시장 설정 확인
|
||||
4. 데이터 조회
|
||||
5. 백테스트 실행
|
||||
6. 전략/실거래 확장 여부 판단
|
||||
## CLI 빠른 참조
|
||||
|
||||
## 9. 주의사항
|
||||
```bash
|
||||
python -m hydra.cli.app --help # 전체 도움말
|
||||
python -m hydra.cli.app setup # 초기 설정 마법사
|
||||
python -m hydra.cli.app status # 현재 상태
|
||||
python -m hydra.cli.app market list-markets # 시장 목록
|
||||
python -m hydra.cli.app market enable binance --mode paper # 모의거래 활성화
|
||||
```
|
||||
|
||||
- 실거래 키를 넣기 전에 먼저 paper 모드로 확인하세요.
|
||||
- API 키, 계정번호, 개인 설정은 `.env` 또는 로컬 전용 파일에만 저장하세요.
|
||||
- FastAPI Swagger UI는 기본 비활성화 상태입니다. API 사용법은 `docs/API_REFERENCE_KO.md`를 참고하세요.
|
||||
---
|
||||
|
||||
## 문제가 생겼을 때
|
||||
|
||||
| 증상 | 확인할 것 |
|
||||
|------|----------|
|
||||
| `ModuleNotFoundError` | 가상환경 활성화 여부, `pip install -e .[dev]` 재실행 |
|
||||
| `403 Invalid API key` | `.env`의 `HYDRA_API_KEY`와 헤더 값 일치 여부 |
|
||||
| Redis 연결 오류 | Docker Desktop 실행 여부, `REDIS_URL` 설정 |
|
||||
| 포트 8000 이미 사용 중 | 다른 프로세스 확인 후 종료 |
|
||||
|
||||
더 자세한 내용은 [README.md](../README.md) 의 FAQ 섹션을 참고하세요.
|
||||
|
||||
Reference in New Issue
Block a user