MiroFish 網路錯誤修復 2026：VITE_API_BASE_URL 與 VPS 遠端存取說明
在 VPS 或 Docker 上部署 MiroFish 时，界面能打开但 ontology 生成报 網路錯誤，多半是浏览器仍在请求 localhost:5001。本文說明 VITE_API_BASE_URL、端口 3000/5001 与重建步骤，并链向 SSH 遠端接入、OpenClaw Mac 部署指南、短期租用節點指南。
揭露說明：可選雲 Mac 租用由 VpsGona 提供。MiroFish 為獨立開源專案。
尚未部署？請先閱讀 MiroFish Docker 部署完全指南，完成 .env 與 docker compose up -d 後再排查網路錯誤。
台灣／港澳用戶透過公網 IP 存取時，除配置 VITE_API_BASE_URL 外，还需在云厂商安全组放行 3000 与 5001；若走家庭宽带，注意上游是否封锁入站端口。
为何出现「網路錯誤」
可引用结论： 前端 :3000 能加载，不代表 API 可达——handleNewProject 失败常见于 axios 仍指向本机 localhost:5001（GitHub #511）。
localhost 陷阱（浏览器 ≠ 服务器）
你在筆電浏览器打开 http://服务器IP:3000 时，JS 里的 localhost 指向你的筆電，不是 VPS。Vite 开发代理仅在「本机浏览器 + 本机 Vite」时有效。
VITE_API_BASE_URL 做什么
以 VITE_ 开头的变量在构建时写入前端包（Vite 环境变量文档）。只改 .env 不 --build，Docker 镜像里可能仍是旧的 localhost。
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 |
- 在
docker-compose.yml同级编辑.env。 - 映射
3000与5001端口。 - 执行
docker compose down && docker compose up --build -d。 - 浏览器强制刷新，排除缓存。
端口与防火墙
云安全组与 ufw 需同时放行 3000（前端）与 5001（后端 API）。在本机执行 curl http://公网IP:5001/，若连接被拒绝，先查網路而非 LLM Key。
先验证后端再查 API Key
- 筆電
curl公网:5001，确认非超时。 - 开发者工具 Network：失败请求主机应为公网 IP，而非 localhost。
- 修改 env 后必须重建前端资源。
可选：在 VpsGona 云 Mac 上运行
短期试验可按 $20.7/天 租用 Mac mini M4，配合 SSH 与 VNC 选型 与 节点选址（香港节点常利于台灣／港澳访问延迟）。
常见问题
存取 http://IP:5001/ 返回 404 是否说明后端挂了？
不一定，根路径可能未定义。应测试 TCP 连通性与真实 API 路径；超时才是防火墙或 Docker 映射问题。
已設定 VITE_API_BASE_URL，DevTools 仍显示 localhost？
前端包未重建。Docker 需 --build，或 npm run dev 重启。
能否使用 HTTPS 域名？
可以，将变量设为 https://api.example.com，并在 nginx/Caddy 终结 TLS。
是否与 LLM API Key 有关？
未收到 HTTP 响应的 Network Error 通常是地址/端口错误，先修網路再查 Key。
服务器本机可存取，手机不行？
将 VITE_API_BASE_URL 设为手机可达的局域网 IP，并放行 5001 端口。