7.5 KiB
7.5 KiB
자동매매 워커 운영 가이드 (실행/배포 구조 이해용)
이 문서는 "앱을 실행하면 뭐가 어디서 도는지"를 먼저 설명하고, 그다음 실행 방법을 설명합니다.
0) 먼저 용어 정리
- React 앱: 브라우저에서 보이는 UI (
/trade화면) - Next.js 서버: React 화면 제공 + API(
/api/*) 처리 - 워커(Node): 백그라운드에서
/api/autotrade/worker/tick호출하는 별도 프로세스
중요:
- React와 API는 보통 같은 Next 프로세스에서 동작합니다.
- 워커는 Next와 별도 프로세스입니다.
1) 개발(local)에서 실제로 어디서 도는가
내 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(선택)
핵심:
- 개발에서는 보통 프로세스 2개를 띄웁니다.
- Next 1개 + Worker 1개
2) 운영(prod)에서 실제로 어디서 도는가
2-1) 패턴 A: 같은 Linux 서버에 Next + Worker
사용자 브라우저
│ HTTPS
▼
[Linux 서버]
- Next 앱 프로세스 (웹 + API)
- Worker 프로세스 (PM2)
└─ 내부에서 /api/autotrade/worker/tick 호출
장점:
- 구성 단순
- 네트워크 경로 짧음
2-2) 패턴 B: Next는 플랫폼(Vercel 등), Worker는 별도 Linux
사용자 브라우저 ──HTTPS──> Next 배포 플랫폼(웹+API)
▲
│ HTTPS + x-autotrade-worker-token
│
Linux Worker 서버(PM2)
장점:
- 앱/워커 분리 운영 가능
- 워커 자원 독립 관리 가능
주의:
- 워커 서버에서 Next 도메인으로 접근 가능해야 함
- 토큰/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 차이
-
heartbeat 브라우저 -> Next 서버
세션 살아있음 알림 -
worker/tick 워커 -> Next 서버
heartbeat 끊긴 세션 정리 요청
즉:
- heartbeat는 "상태 보고"
- tick은 "청소 작업"
5) 토큰/URL: 뭘 어떻게 넣어야 하나
5-1) AUTOTRADE_WORKER_TOKEN
뜻:
- 사용자용 토큰 아님
- 앱 서버와 워커 간 내부 인증 시크릿
- 환경별(dev/staging/prod)로 1개 사용
생성 예시:
openssl rand -hex 32
5-2) AUTOTRADE_APP_URL
뜻:
- 워커가 호출할 Next 서버 주소
예시:
- 로컬:
http://127.0.0.1:3001 - 운영:
https://your-domain.com
6) 어디 파일/어디 시스템에 넣나
6-1) 앱(Next 서버)
위치:
- 로컬:
.env.local - 운영: 배포 환경변수
필수:
AUTOTRADE_WORKER_TOKEN=<랜덤시크릿>
6-2) 워커(Node/PM2)
위치:
- PM2 실행 셸 환경변수
- 서버 시스템 환경변수
필수:
AUTOTRADE_WORKER_TOKEN=<앱과동일값>
AUTOTRADE_APP_URL=<Next서버URL>
AUTOTRADE_WORKER_POLL_MS=5000
중요:
- 앱/워커 토큰 값은 완전히 같아야 합니다.
- 다르면
/worker/tick가 401로 실패합니다.
7) 실행 방법
7-1) 로컬 개발
터미널 A (Next):
npm run dev
터미널 B (Worker):
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):
npm run dev
터미널 B (Worker):
$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 값을 바로 쓰고 싶으면:
npm run worker:autotrade:dev
7-2) 운영 서버 (PM2)
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) 장애 시 빠른 점검
-
워커 401 원인: 앱/워커 토큰 불일치 조치:
AUTOTRADE_WORKER_TOKEN동일화 -
fetch failed 원인:
AUTOTRADE_APP_URL오타, Next 미기동 조치: URL/앱 프로세스 확인 -
세션이 안 정리됨 원인: heartbeat 정상 수신 중일 수 있음 조치: 브라우저 종료 후 TTL 경과 뒤 확인
9) 관련 소스
- 워커:
scripts/autotrade-worker.mjs - PM2 설정:
scripts/pm2.autotrade-worker.config.cjs - 워커 API:
app/api/autotrade/worker/tick/route.ts - heartbeat API:
app/api/autotrade/sessions/heartbeat/route.ts - 세션 만료 정리:
app/api/autotrade/_shared.ts