270 lines
7.5 KiB
Markdown
270 lines
7.5 KiB
Markdown
# 자동매매 워커 운영 가이드 (실행/배포 구조 이해용)
|
|
|
|
이 문서는 "앱을 실행하면 뭐가 어디서 도는지"를 먼저 설명하고, 그다음 실행 방법을 설명합니다.
|
|
|
|
## 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)
|