MiroFish 네트워크 오류 수정 2026: VITE_API_BASE_URL 및 VPS 원격 접속
MiroFish VPS 배포 후 Network Error가 나면 브라우저가 localhost:5001를 호출하는 경우가 대부분입니다. VITE_API_BASE_URL과 포트 3000/5001를 설명하고 SSH 원격 접속, OpenClaw 배포, 단기 렌탈 노드로 연결합니다.
고지: 클라우드 Mac 렌탈은 VpsGona 제공. MiroFish는 독립 OSS입니다.
처음 설치라면 MiroFish Docker 배포 가이드에서 .env와 compose를 먼저 완료하세요.
Network Error 원인
UI는 :3000에서 열리지만 API는 실패할 수 있습니다—axios 기본값이 잘못된 호스트를 가리킵니다 (#511).
localhost 함정
원격 http://서버IP:3000 접속 시 JS의 localhost는 내 PC입니다. Vite 프록시는 로컬 개발 전용입니다.
VITE_API_BASE_URL
VITE_ 변수는 빌드 시 번들에 포함됩니다 (Vite 문서). Docker는 --build가 필요합니다.
VITE_API_BASE_URL=http://공인IP:5001수정 체크리스트
| 상황 | 값 | 재시작 | 비고 |
|---|---|---|---|
| Same machine | http://127.0.0.1:5001 | npm run dev | Default works |
| LAN browser | http://192.168.x.x:5001 | Restart Vite | Use LAN IP in env |
| VPS / cloud | http://PUBLIC_IP:5001 | docker compose up --build -d | Open ports 3000/5001 |
.env수정- 포트 3000/5001 매핑
docker compose up --build -d- 브라우저 강력 새로고침
포트·방화벽
클라우드 SG와 OS 방화벽에서 3000, 5001를 허용하세요. 서울 노드 클라우드 Mac(일 $20.7)에서도 동일 규칙이 적용됩니다.
백엔드 확인
- 노트북에서
curl http://공인IP:5001/ - DevTools에서 XHR 호스트 확인
- env 변경 후 재빌드
클라우드 Mac 옵션
단기 파일럿은 Mac mini M4 일 $20.7 렌탈 + SSH vs VNC를 참고하세요.
FAQ
http://IP:5001/ 이 404면 장애?
루트 경로 미정의일 수 있습니다. 타임아웃이면 FW/Docker를 확인하세요.
env 변경 후에도 localhost?
프론트 재빌드 필요. Docker는 --build.
HTTPS 도메인 가능?
가능. VITE_API_BASE_URL을 https://api.example.com 으로 설정.
LLM API 키 문제?
응답 전 Network Error는 호스트 오류가 많음. 네트워크 먼저.
LAN만 되고 폰은 안 됨?
폰이 접근 가능한 LAN IP를 env에 설정.