1. 반복되는 유형
전제 불명확, 프로세스 모델 오해(셸 종료 시 중단), 관측 부족(포트/프록시/절전) 세 가지가 대부분입니다.
2. 전제 점검
| 항목 | 권장 | 실패 시 |
|---|---|---|
| Node | 문서 권장 버전 | 네이티브 모듈 불일치 |
| 패키지 매니저 | 저장소당 하나 고정 | lockfile 드리프트 |
| 설정 경로 | 실제 읽는 파일 확인 | 잘못된 파일 편집 |
| API 키 | 최소 권한·비공개 관리 | 비용·유출 |
3. onboard 의도
키, 채널, 실행 모드, 워크스페이스를 한 번에 기록하는 과정입니다. 실패 시 스택과 단계 번호를 남깁니다.
4. 포그라운드 vs 데몬
첫 연결은 stdout/stderr가 보이는 포그라운드가 가장 빠릅니다. 데몬은 WorkingDirectory·환경 변수를 명시하고 동일 헬스 체크로 검증합니다.
5. 다섯 단계 스모크
리슨/헬스 → 최소 메시지 왕복 → 로그(인증·레이트리밋) → 리버스 프록시면 TLS/WS → 버전·성공 요청 ID 기록.
6. 포트와 로그
| 증상 | 먼저 | 조치 |
|---|---|---|
| 포트 사용 중 | lsof 등 | 좀비 종료 또는 포트 변경 |
| 데몬 즉시 종료 | 서비스 로그 | 포그라운드 재현 |
| 채널 무응답 | Webhook·방화벽 | 내/외부 curl 분리 |
| 간헐 끊김 | 절전·상한 | 절전 해제·백오프 |
lsof -iTCP:PORT -sTCP:LISTEN
운영 앵커:
- 로그는 연속 수십 줄 단위로 읽기.
- 마이너 업그레이드 전후 헬스+E2E 각 1회.
- 원격 Mac 여유 공간·로그 로테이션 점검.
7. 원격 Mac 장기 호스팅
절전 정책, OS 업데이트 후 자동 기동, 로그 로테, 서비스 계정 일관성을 Runbook으로 고정합니다.
8. 재현 가능한 부팅 경로
기능 목록보다 onboard 산출물·유닛·헬스 명령을 버전 관리하는 편이 TCO를 낮춥니다. GPU 작업과 분리하려면 전용 원격 Mac에 게이트웨이를 두는 구성이 유리합니다.
로컬이 불안정하면 MACGPU 원격 Mac으로 상시 전원과 디스크 여유를 확보하고 시간 과금으로 파일럿하세요.