auto-trade/common-docs/features/autotrade-worker-pm2.md

# 자동매매 워커 운영 가이드 (실행/배포 구조 이해용)

이 문서는 "앱을 실행하면 뭐가 어디서 도는지"를 먼저 설명하고, 그다음 실행 방법을 설명합니다.

## 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)