diff --git a/docs/plans/2026-05-27-mac-mini-primary-ops-migration.md b/docs/plans/2026-05-27-mac-mini-primary-ops-migration.md new file mode 100644 index 0000000..c5f3e81 --- /dev/null +++ b/docs/plans/2026-05-27-mac-mini-primary-ops-migration.md @@ -0,0 +1,140 @@ +# Mac mini 주 운영 전환 및 oraclea 데이터 마이그레이션 계획 + +## 목적 + +Galaxis-Po 운영 기준을 oraclea 배포 서버에서 Mac mini로 전환한다. +갤포가 로컬 워크스페이스, Docker, DB, 스케줄러를 직접 확인하고 통제할 수 있게 하며, +oraclea는 외부 진입점 또는 보조 배포지로 축소한다. + +## 현재 확인된 상태 + +- oraclea + - `galaxis-po-backend`, `galaxis-po-frontend`, `galaxis-po-db`가 약 23시간째 healthy 상태 + - 2026-05-27 KJB daily signal 실행 결과: BUY 신호 0개 + - 2026-05-27 morning screening 실행 결과: 후보 0개 + - 일부 과거 `job_logs`에 stale `running` 상태가 남아 있음 +- Mac mini + - 로컬 Docker Desktop 기준 별도 DB와 컨테이너가 존재 + - 갤포가 직접 파일, 로그, DB, 컨테이너를 제어 가능 + - oraclea와 DB 상태가 달라 운영 판단 기준 혼선 발생 + +## 목표 운영 구조 + +```text +갤포 / Mac mini + ├─ galaxis-po backend + ├─ galaxis-po frontend + ├─ PostgreSQL primary DB + ├─ APScheduler jobs + └─ KJB screening / signal / collection jobs + +oraclea + ├─ 외부 접근용 proxy 또는 터널 종단점 + ├─ 필요 시 읽기 전용 백업/복구 대상 + └─ Gitea runner는 Galaxis-Po 자동 배포에서 제외 +``` + +## 전환 원칙 + +1. 운영 DB는 하나만 primary로 지정한다. +2. KJB, screening, collection, 자동매매 판단은 Mac mini DB 기준으로 고정한다. +3. oraclea의 Gitea Actions 기반 자동 배포는 중지한다. +4. 마이그레이션 전후 row count와 최신 업무일 데이터를 대조한다. +5. `.env`, `.env.prod`, `docker-compose.prod.yml`은 이번 작업에서 수정하지 않는다. + +## 마이그레이션 절차 + +### 1. 변경 동결 + +- oraclea의 Galaxis-Po 자동 배포 workflow 제거 +- oraclea에서 Galaxis-Po backend scheduler 중복 실행 여부 확인 +- 데이터 덤프 시작 전 수집/스크리닝/시그널 잡이 실행 중이 아닌 시간대 선택 + +### 2. oraclea DB 백업 + +oraclea에서 실행: + +```bash +docker exec galaxis-po-db pg_dump -U "$DB_USER" "$DB_NAME" \ + --format=custom \ + --file=/tmp/galaxis-po-oraclea-$(date +%Y%m%d_%H%M%S).dump +``` + +DB 환경변수를 컨테이너 밖에서 알 수 없으면 컨테이너 내부 환경을 확인한 뒤 같은 값으로 실행한다. + +```bash +docker exec galaxis-po-db printenv | grep -E 'POSTGRES_USER|POSTGRES_DB' +``` + +### 3. Mac mini로 덤프 전송 + +Mac mini에서 실행: + +```bash +scp oraclea:/tmp/galaxis-po-oraclea-YYYYMMDD_HHMMSS.dump ./backups/ +``` + +`backups/`는 git에 커밋하지 않는다. + +### 4. Mac mini DB 복원 + +기존 Mac mini DB를 보존해야 하면 먼저 로컬 백업을 만든다. + +```bash +docker exec galaxis-po-db pg_dump -U "$DB_USER" "$DB_NAME" \ + --format=custom \ + --file=/tmp/galaxis-po-macmini-before-restore.dump +``` + +복원은 빈 DB 또는 새 볼륨에 수행하는 방식을 우선한다. +기존 DB에 덮어써야 하면 사전 백업 확인 후 진행한다. + +```bash +docker exec -i galaxis-po-db pg_restore -U "$DB_USER" -d "$DB_NAME" \ + --clean --if-exists --no-owner \ + < ./backups/galaxis-po-oraclea-YYYYMMDD_HHMMSS.dump +``` + +### 5. 검증 + +Mac mini DB에서 다음을 비교한다. + +```sql +select max(date), count(*) from prices; +select max(date), count(*) from etf_prices; +select max(date), count(*) from signals; +select max(screen_date), count(*) from screening_signals; +select job_name, status, started_at, finished_at +from job_logs +order by started_at desc +limit 20; +``` + +필수 확인: + +- 최신 가격 데이터 기준일 +- KJB signal 최신 날짜와 개수 +- screening 최신 날짜와 개수 +- stale `running` job log 정리 필요 여부 +- backend `/health` 정상 응답 +- frontend 접속 정상 + +### 6. Mac mini를 primary로 고정 + +- Mac mini Docker compose를 주 운영 프로세스로 유지 +- Mac mini backend scheduler가 유일한 Galaxis-Po 스케줄러인지 확인 +- oraclea Galaxis-Po backend를 중지하거나 scheduler 비활성화 상태로 전환 +- 외부 접근이 필요하면 oraclea proxy 또는 터널만 Mac mini frontend/backend로 연결 + +## 롤백 계획 + +- Mac mini 복원 실패 시 기존 Mac mini 백업 덤프로 복원 +- 외부 접근 장애 시 oraclea 기존 컨테이너를 임시 운영 기준으로 되돌림 +- DB 기준이 다시 갈라지지 않도록 롤백 중에도 한쪽 scheduler만 활성화 + +## 후속 작업 + +- stale `running` job log 정리 절차 추가 +- Mac mini 운영 healthcheck 스크립트 추가 +- oraclea proxy 전용 구성 여부 결정 +- 운영 기준 DB를 README 또는 운영 문서에 명시