전체적인 리팩토링
This commit is contained in:
269
common-docs/features/autotrade-worker-pm2.md
Normal file
269
common-docs/features/autotrade-worker-pm2.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# 자동매매 워커 운영 가이드 (실행/배포 구조 이해용)
|
||||
|
||||
이 문서는 "앱을 실행하면 뭐가 어디서 도는지"를 먼저 설명하고, 그다음 실행 방법을 설명합니다.
|
||||
|
||||
## 0) 먼저 용어 정리
|
||||
|
||||
1. React 앱: 브라우저에서 보이는 UI (`/trade` 화면)
|
||||
2. Next.js 서버: React 화면 제공 + API(`/api/*`) 처리
|
||||
3. 워커(Node): 백그라운드에서 `/api/autotrade/worker/tick` 호출하는 별도 프로세스
|
||||
|
||||
중요:
|
||||
|
||||
1. React와 API는 보통 같은 Next 프로세스에서 동작합니다.
|
||||
2. 워커는 Next와 별도 프로세스입니다.
|
||||
|
||||
---
|
||||
|
||||
## 1) 개발(local)에서 실제로 어디서 도는가
|
||||
|
||||
```text
|
||||
내 PC
|
||||
┌──────────────────────────────────────────────────────────────────────────┐
|
||||
│ 브라우저(Chrome) │
|
||||
│ - /trade 화면 렌더링 │
|
||||
│ - heartbeat 전송 (/sessions/heartbeat) │
|
||||
└──────────────────────────────────────────────────────────────────────────┘
|
||||
│ http://127.0.0.1:3001
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────────────┐
|
||||
│ 터미널 A: Next 개발 서버 (`npm run dev`) │
|
||||
│ - React 페이지 제공 │
|
||||
│ - /api/autotrade/* API 처리 │
|
||||
└──────────────────────────────────────────────────────────────────────────┘
|
||||
▲
|
||||
│ x-autotrade-worker-token
|
||||
│
|
||||
┌──────────────────────────────────────────────────────────────────────────┐
|
||||
│ 터미널 B: 워커 (`node scripts/autotrade-worker.mjs`) │
|
||||
│ - /api/autotrade/worker/tick 주기 호출 │
|
||||
└──────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
외부 클라우드 서비스
|
||||
- Supabase(Auth/DB)
|
||||
- KIS API
|
||||
- OpenAI API(선택)
|
||||
```
|
||||
|
||||
핵심:
|
||||
|
||||
1. 개발에서는 보통 프로세스 2개를 띄웁니다.
|
||||
2. Next 1개 + Worker 1개
|
||||
|
||||
---
|
||||
|
||||
## 2) 운영(prod)에서 실제로 어디서 도는가
|
||||
|
||||
## 2-1) 패턴 A: 같은 Linux 서버에 Next + Worker
|
||||
|
||||
```text
|
||||
사용자 브라우저
|
||||
│ HTTPS
|
||||
▼
|
||||
[Linux 서버]
|
||||
- Next 앱 프로세스 (웹 + API)
|
||||
- Worker 프로세스 (PM2)
|
||||
└─ 내부에서 /api/autotrade/worker/tick 호출
|
||||
```
|
||||
|
||||
장점:
|
||||
|
||||
1. 구성 단순
|
||||
2. 네트워크 경로 짧음
|
||||
|
||||
## 2-2) 패턴 B: Next는 플랫폼(Vercel 등), Worker는 별도 Linux
|
||||
|
||||
```text
|
||||
사용자 브라우저 ──HTTPS──> Next 배포 플랫폼(웹+API)
|
||||
▲
|
||||
│ HTTPS + x-autotrade-worker-token
|
||||
│
|
||||
Linux Worker 서버(PM2)
|
||||
```
|
||||
|
||||
장점:
|
||||
|
||||
1. 앱/워커 분리 운영 가능
|
||||
2. 워커 자원 독립 관리 가능
|
||||
|
||||
주의:
|
||||
|
||||
1. 워커 서버에서 Next 도메인으로 접근 가능해야 함
|
||||
2. 토큰/URL 설정을 양쪽에 정확히 맞춰야 함
|
||||
|
||||
---
|
||||
|
||||
## 3) 서버에서 "무엇이 돌아가는지" 체크표
|
||||
|
||||
| 구성요소 | 실제 실행 위치 | 프로세스 | 시작 명령 예시 | 역할 |
|
||||
|---|---|---|---|---|
|
||||
| React UI | 사용자 브라우저 | Browser Tab | URL 접속 | 화면 렌더링, 사용자 입력 |
|
||||
| Next 서버 | Linux/플랫폼 | Node(Next) | `npm run dev` 또는 `npm run start` | 웹 + `/api/autotrade/*` 처리 |
|
||||
| Worker | Linux/Worker 서버 | Node Script(PM2) | `pm2 start scripts/pm2.autotrade-worker.config.cjs` | 만료 세션 정리 |
|
||||
|
||||
---
|
||||
|
||||
## 4) heartbeat와 worker/tick 차이
|
||||
|
||||
1. heartbeat
|
||||
브라우저 -> Next 서버
|
||||
세션 살아있음 알림
|
||||
|
||||
2. worker/tick
|
||||
워커 -> Next 서버
|
||||
heartbeat 끊긴 세션 정리 요청
|
||||
|
||||
즉:
|
||||
|
||||
1. heartbeat는 "상태 보고"
|
||||
2. tick은 "청소 작업"
|
||||
|
||||
---
|
||||
|
||||
## 5) 토큰/URL: 뭘 어떻게 넣어야 하나
|
||||
|
||||
## 5-1) `AUTOTRADE_WORKER_TOKEN`
|
||||
|
||||
뜻:
|
||||
|
||||
1. 사용자용 토큰 아님
|
||||
2. 앱 서버와 워커 간 내부 인증 시크릿
|
||||
3. 환경별(dev/staging/prod)로 1개 사용
|
||||
|
||||
생성 예시:
|
||||
|
||||
```bash
|
||||
openssl rand -hex 32
|
||||
```
|
||||
|
||||
## 5-2) `AUTOTRADE_APP_URL`
|
||||
|
||||
뜻:
|
||||
|
||||
1. 워커가 호출할 Next 서버 주소
|
||||
|
||||
예시:
|
||||
|
||||
1. 로컬: `http://127.0.0.1:3001`
|
||||
2. 운영: `https://your-domain.com`
|
||||
|
||||
---
|
||||
|
||||
## 6) 어디 파일/어디 시스템에 넣나
|
||||
|
||||
## 6-1) 앱(Next 서버)
|
||||
|
||||
위치:
|
||||
|
||||
1. 로컬: `.env.local`
|
||||
2. 운영: 배포 환경변수
|
||||
|
||||
필수:
|
||||
|
||||
```env
|
||||
AUTOTRADE_WORKER_TOKEN=<랜덤시크릿>
|
||||
```
|
||||
|
||||
## 6-2) 워커(Node/PM2)
|
||||
|
||||
위치:
|
||||
|
||||
1. PM2 실행 셸 환경변수
|
||||
2. 서버 시스템 환경변수
|
||||
|
||||
필수:
|
||||
|
||||
```env
|
||||
AUTOTRADE_WORKER_TOKEN=<앱과동일값>
|
||||
AUTOTRADE_APP_URL=<Next서버URL>
|
||||
AUTOTRADE_WORKER_POLL_MS=5000
|
||||
```
|
||||
|
||||
중요:
|
||||
|
||||
1. 앱/워커 토큰 값은 완전히 같아야 합니다.
|
||||
2. 다르면 `/worker/tick`가 401로 실패합니다.
|
||||
|
||||
---
|
||||
|
||||
## 7) 실행 방법
|
||||
|
||||
## 7-1) 로컬 개발
|
||||
|
||||
터미널 A (Next):
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
터미널 B (Worker):
|
||||
|
||||
```bash
|
||||
AUTOTRADE_WORKER_TOKEN="<앱과같은값>" \
|
||||
AUTOTRADE_APP_URL="http://127.0.0.1:3001" \
|
||||
AUTOTRADE_WORKER_POLL_MS="5000" \
|
||||
node scripts/autotrade-worker.mjs
|
||||
```
|
||||
|
||||
## 7-1-a) 로컬 개발 (Windows PowerShell)
|
||||
|
||||
터미널 A (Next):
|
||||
|
||||
```powershell
|
||||
npm run dev
|
||||
```
|
||||
|
||||
터미널 B (Worker):
|
||||
|
||||
```powershell
|
||||
$env:AUTOTRADE_WORKER_TOKEN="<앱과같은값>"
|
||||
$env:AUTOTRADE_APP_URL="http://127.0.0.1:3001"
|
||||
$env:AUTOTRADE_WORKER_POLL_MS="5000"
|
||||
npm run worker:autotrade
|
||||
```
|
||||
|
||||
`.env.local` 값을 바로 쓰고 싶으면:
|
||||
|
||||
```powershell
|
||||
npm run worker:autotrade:dev
|
||||
```
|
||||
|
||||
## 7-2) 운영 서버 (PM2)
|
||||
|
||||
```bash
|
||||
npm i -g pm2
|
||||
export AUTOTRADE_WORKER_TOKEN="<앱과같은값>"
|
||||
export AUTOTRADE_APP_URL="https://your-domain.com"
|
||||
export AUTOTRADE_WORKER_POLL_MS="5000"
|
||||
pm2 start scripts/pm2.autotrade-worker.config.cjs
|
||||
pm2 status
|
||||
pm2 logs autotrade-worker
|
||||
pm2 save
|
||||
pm2 startup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8) 장애 시 빠른 점검
|
||||
|
||||
1. 워커 401
|
||||
원인: 앱/워커 토큰 불일치
|
||||
조치: `AUTOTRADE_WORKER_TOKEN` 동일화
|
||||
|
||||
2. fetch failed
|
||||
원인: `AUTOTRADE_APP_URL` 오타, Next 미기동
|
||||
조치: URL/앱 프로세스 확인
|
||||
|
||||
3. 세션이 안 정리됨
|
||||
원인: heartbeat 정상 수신 중일 수 있음
|
||||
조치: 브라우저 종료 후 TTL 경과 뒤 확인
|
||||
|
||||
---
|
||||
|
||||
## 9) 관련 소스
|
||||
|
||||
1. 워커: [`scripts/autotrade-worker.mjs`](../../scripts/autotrade-worker.mjs)
|
||||
2. PM2 설정: [`scripts/pm2.autotrade-worker.config.cjs`](../../scripts/pm2.autotrade-worker.config.cjs)
|
||||
3. 워커 API: [`app/api/autotrade/worker/tick/route.ts`](../../app/api/autotrade/worker/tick/route.ts)
|
||||
4. heartbeat API: [`app/api/autotrade/sessions/heartbeat/route.ts`](../../app/api/autotrade/sessions/heartbeat/route.ts)
|
||||
5. 세션 만료 정리: [`app/api/autotrade/_shared.ts`](../../app/api/autotrade/_shared.ts#L147)
|
||||
Reference in New Issue
Block a user