MiroFish Docker 部署完全指南 2026：Compose、.env 与远程访问

本 MiroFish Docker 部署指南 从零讲解官方 666ghj/MiroFish 的 Compose 流程，映射端口 3000 / 5001。若界面能开但远程 API 失败，请看 MiroFish 网络错误与 VITE_API_BASE_URL 修复；本文侧重安装、.env 与首次项目验证。相关：SSH 远程接入、短期租用节点、OpenClaw 部署指南。

披露说明：可选云 Mac 租用由 VpsGona 提供。步骤以 GitHub 官方仓库为准。

大陆服务器拉取镜像较慢时，可使用仓库 docker-compose.yml 注释中的国内镜像地址；同时注意云厂商安全组与国内入站策略。

Docker 里跑的是什么

可引用结论： 单服务镜像 ghcr.io/666ghj/mirofish:latest，通过 env_file: .env 加载配置，暴露 3000 与 5001，数据目录 ./backend/uploads。

前置条件

• Docker 24+ 与 Compose v2
• 建议 4GB+ 内存
• LLM API 与 Zep Cloud 可访问（轻量测试可用免费额度）

步骤 1 — 克隆与配置 .env

git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env

按示例填写 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL_NAME、ZEP_API_KEY 等必填项。

步骤 2 — 启动 Compose

docker compose up -d
docker compose logs -f --tail=80

浏览器访问 http://服务器IP:3000。

步骤 3 — 远程访问必配 VITE_API_BASE_URL

VITE_API_BASE_URL=http://你的公网IP:5001

写入 .env 后执行 docker compose up --build -d。排错详见 MiroFish 网络错误与 VITE_API_BASE_URL 修复。

步骤 4 — 防火墙与健康检查

1. 安全组放行 3000、5001
2. 本机 curl http://公网IP:5001/ 测连通
3. 开发者工具确认请求主机为公网 IP

步骤 5 — 首个项目烟测

1. 上传小型 UTF-8 文本
2. 创建项目并生成 ontology
3. 若 UI 正常但报网络错误 → 先查 MiroFish 网络错误与 VITE_API_BASE_URL 修复

可选：VpsGona 云 Mac

短期试验可按 $20.7/天 租用 Mac mini M4，参考 SSH 与 VNC、节点选址（香港节点常利于大陆延迟）。

常见问题

Docker 和 npm run dev 选哪个？

VPS 生产-like 环境用 Docker；本机开发可用 npm dev，远程访问仍需 VITE_API_BASE_URL。

支持哪些 LLM？

兼容 OpenAI 格式的 API，按 .env.example 填写 LLM_BASE_URL 与模型名。

改 .env 后要重建吗？

VITE_ 变量需 docker compose up --build -d。

必须 Zep 吗？

官方示例要求 ZEP_API_KEY，轻量测试可用 Zep 免费额度。

界面正常但 ontology 失败？

多为 API 地址错误，先看网络错误文，再查 LLM 额度。