cointrader/docs/plans/2026-03-01-train-on-mac-deploy-to-lxc.md

맥미니 로컬 학습 후 LXC 배포 구현 계획

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: 맥미니에서 LightGBM 모델을 학습하고, 학습된 모델 파일(lgbm_filter.pkl)을 Proxmox LXC 컨테이너로 자동 전송하여 봇이 즉시 사용할 수 있도록 한다.

Architecture:

• 맥미니에서 scripts/train_model.py를 직접 실행하여 모델 학습 (M 시리즈 칩 병렬 처리 활용)
• 학습 완료 후 scp 또는 rsync로 LXC 호스트에 모델 파일 전송
• LXC 컨테이너 내 models/ 볼륨 마운트 경로에 파일이 도달하면 봇이 자동으로 핫 리로드

Tech Stack: Python 3.12, LightGBM, joblib, scp/rsync, SSH, docker-compose volume mount

---

전제 조건 확인

• 맥미니에 Python 3.12 + 의존성 설치 가능
• LXC 호스트 IP: 10.1.10.24
• SSH 키 인증 등록 완료 (ssh root@10.1.10.24 비밀번호 없이 접속 가능)
• LXC 컨테이너에서 ./models가 /app/models로 볼륨 마운트 중

---

Task 1: 맥미니 환경 준비

Files:

• Read: requirements.txt

Step 1: 의존성 설치 확인

# 맥미니 터미널에서 실행
cd /Users/gihyeon/github/cointrader
pip install -r requirements.txt

Expected: 모든 패키지 설치 완료 (lightgbm, pandas, joblib 등)

Step 2: 데이터 수집

python scripts/fetch_history.py --symbol XRPUSDT --interval 1m --days 90 --output data/xrpusdt_1m.parquet

Expected: 저장 완료: data/xrpusdt_1m.parquet (약 130,000행)

Step 3: 학습 실행 (맥미니 전체 코어 활용)

# M 시리즈 맥미니는 cpu_count()가 올바르게 반환되므로 --jobs 생략 가능
python scripts/train_model.py --data data/xrpusdt_1m.parquet

Expected 출력:

캔들 수: 130000
병렬 처리: N코어 사용 (총 129940개 인덱스)
...
검증 AUC: 0.XXXX
모델 저장: models/lgbm_filter.pkl

Step 4: 학습 결과 확인

ls -lh models/lgbm_filter.pkl
python -c "import joblib; m = joblib.load('models/lgbm_filter.pkl'); print('모델 로드 OK:', type(m))"

Expected: 파일 존재, 로드 성공

---

Task 2: LXC 전송 스크립트 작성

Files:

• Create: scripts/deploy_model.sh

Step 1: 전송 스크립트 작성

scripts/deploy_model.sh 파일을 생성한다:

#!/usr/bin/env bash
# 맥미니에서 학습한 모델을 LXC 컨테이너 볼륨 경로로 전송한다.
# 사용법: bash scripts/deploy_model.sh [LXC_HOST] [LXC_MODELS_PATH]
#
# 예시:
#   bash scripts/deploy_model.sh 10.1.10.28 /path/to/cointrader/models
#   bash scripts/deploy_model.sh root@10.1.10.28 /root/cointrader/models

set -euo pipefail

LXC_HOST="${1:-root@10.1.10.24}"
LXC_MODELS_PATH="${2:-/root/cointrader/models}"
LOCAL_MODEL="models/lgbm_filter.pkl"
LOCAL_LOG="models/training_log.json"

if [[ ! -f "$LOCAL_MODEL" ]]; then
  echo "[오류] 모델 파일 없음: $LOCAL_MODEL"
  echo "먼저 python scripts/train_model.py 를 실행하세요."
  exit 1
fi

echo "=== 모델 전송 시작 ==="
echo "  대상: ${LXC_HOST}:${LXC_MODELS_PATH}"
echo "  파일: $LOCAL_MODEL"

# 기존 모델을 prev로 백업 (원격)
ssh "${LXC_HOST}" "
  if [ -f '${LXC_MODELS_PATH}/lgbm_filter.pkl' ]; then
    cp '${LXC_MODELS_PATH}/lgbm_filter.pkl' '${LXC_MODELS_PATH}/lgbm_filter_prev.pkl'
    echo '  기존 모델 백업 완료'
  fi
  mkdir -p '${LXC_MODELS_PATH}'
"

# 모델 파일 전송
rsync -avz --progress \
  "$LOCAL_MODEL" \
  "${LXC_HOST}:${LXC_MODELS_PATH}/lgbm_filter.pkl"

# 학습 로그도 함께 전송 (있을 경우)
if [[ -f "$LOCAL_LOG" ]]; then
  rsync -avz "$LOCAL_LOG" "${LXC_HOST}:${LXC_MODELS_PATH}/training_log.json"
  echo "  학습 로그 전송 완료"
fi

echo "=== 전송 완료 ==="
echo ""
echo "봇이 실행 중이라면 아래 명령으로 모델을 즉시 리로드할 수 있습니다:"
echo "  docker exec cointrader python -c \\"
echo "    \"from src.ml_filter import MLFilter; f=MLFilter(); f.reload_model(); print('리로드 완료')\""

Step 2: 실행 권한 부여

chmod +x scripts/deploy_model.sh

Step 3: 커밋

git add scripts/deploy_model.sh
git commit -m "feat: add deploy_model.sh for mac-to-lxc model transfer"

---

Task 3: LXC 경로 확인 및 SSH 접속 테스트

Step 1: LXC 호스트 SSH 접속 확인

# 맥미니 터미널에서 (SSH 키 등록 완료 상태)
ssh root@10.1.10.24 "echo 접속 성공"

Expected: 접속 성공

Step 2: LXC 컨테이너 내 models 경로 확인

LXC 호스트에서 docker-compose.yml의 볼륨 마운트 경로를 확인한다:

ssh root@10.1.10.24 "docker inspect cointrader | grep -A5 Mounts"

Expected 출력 예시:

"Mounts": [
  {
    "Source": "/root/cointrader/models",
    "Destination": "/app/models",
    ...
  }
]

Source 경로가 LXC 호스트에서 실제로 파일을 복사해야 할 위치다.

Step 3: 경로 기록

확인된 경로를 메모해 둔다. 예:

• LXC 호스트: root@10.1.10.24
• models 볼륨 소스: /root/cointrader/models (또는 실제 확인된 경로)

---

Task 4: 모델 전송 실행

Step 1: 전송 스크립트 실행

# 맥미니 터미널에서 (cointrader 프로젝트 루트)
bash scripts/deploy_model.sh root@10.1.10.24 /root/cointrader/models

Expected:

=== 모델 전송 시작 ===
  대상: root@10.1.10.24:/root/cointrader/models
  파일: models/lgbm_filter.pkl
  기존 모델 백업 완료
lgbm_filter.pkl ... 전송 완료
  학습 로그 전송 완료
=== 전송 완료 ===

Step 2: LXC에서 파일 존재 확인

ssh root@10.1.10.24 "ls -lh /root/cointrader/models/"

Expected: lgbm_filter.pkl, lgbm_filter_prev.pkl, training_log.json 확인

---

Task 5: 봇 핫 리로드 확인

Step 1: 봇 컨테이너에서 모델 리로드

봇이 실행 중인 경우 MLFilter.reload_model()을 트리거한다.

방법 A — 컨테이너 재시작 (가장 간단):

ssh root@10.1.10.24 "cd /root/cointrader && docker compose restart cointrader"

방법 B — 핫 리로드 (재시작 없이):

ssh root@10.1.10.24 "docker exec cointrader python -c \
  \"import sys; sys.path.insert(0,'src'); \
    from src.ml_filter import MLFilter; \
    f = MLFilter(); \
    print('모델 로드:', f.is_model_loaded())\""

Step 2: 봇 로그에서 모델 로드 확인

ssh root@10.1.10.24 "docker logs cointrader --tail 20"

Expected 로그:

INFO | ML 필터 모델 로드 완료: models/lgbm_filter.pkl

---

Task 6: 자동화 스크립트 통합 (선택 사항)

Files:

• Create: scripts/train_and_deploy.sh

전체 파이프라인(수집 → 학습 → 전송)을 한 번에 실행하는 스크립트:

#!/usr/bin/env bash
# 맥미니에서 전체 학습 파이프라인을 실행하고 LXC로 배포한다.
# 사용법: bash scripts/train_and_deploy.sh [LXC_HOST] [LXC_MODELS_PATH]

set -euo pipefail

LXC_HOST="${1:-root@10.1.10.24}"
LXC_MODELS_PATH="${2:-/root/cointrader/models}"

echo "=== [1/3] 데이터 수집 ==="
python scripts/fetch_history.py --symbol XRPUSDT --interval 1m --days 90

echo ""
echo "=== [2/3] 모델 학습 ==="
python scripts/train_model.py --data data/xrpusdt_1m.parquet

echo ""
echo "=== [3/3] LXC 배포 ==="
bash scripts/deploy_model.sh "$LXC_HOST" "$LXC_MODELS_PATH"

echo ""
echo "=== 전체 파이프라인 완료 ==="

chmod +x scripts/train_and_deploy.sh
git add scripts/train_and_deploy.sh
git commit -m "feat: add train_and_deploy.sh for full pipeline on mac"

---

운영 워크플로우 요약

맥미니 (빠른 학습)                     LXC 컨테이너 (운영)
─────────────────────                  ────────────────────
1. fetch_history.py                    
2. train_model.py                      
3. deploy_model.sh ──── rsync ────→   models/lgbm_filter.pkl
                                       (볼륨 마운트로 컨테이너에 즉시 반영)
                                       
                                       docker compose restart
                                       → MLFilter.reload_model()
                                       → 새 모델로 거래 재개

---

주의사항

• models/lgbm_filter.pkl은 joblib으로 직렬화된 LightGBM 모델이다. Python 버전이 다르면 로드 실패할 수 있다. 맥미니와 LXC 컨테이너의 Python 버전을 일치시킬 것 (현재 Python 3.12 기준).
• Docker 이미지 내 Python 버전 확인: docker exec cointrader python --version
• 버전 불일치 시 맥미니에서도 동일 버전 가상환경을 사용하거나, Docker 컨테이너 안에서 학습하는 방식으로 전환해야 한다.
• retrainer.py의 자동 재학습(매일 새벽 3시)은 LXC에서 계속 동작한다. 맥미니에서 수동 학습한 모델이 자동 재학습으로 덮어쓰여질 수 있으므로, 자동 재학습 스케줄과 충돌하지 않도록 타이밍을 조율한다.