MiroFish 部署指南：Docker Compose 一键部署群体智能预测引擎-平芜编程栈

MiroFish 部署指南：Docker Compose 一键部署群体智能预测引擎

【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎，预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish

MiroFish 是一款简洁通用的群体智能预测引擎：上传一份文档，它会自动构建关系图谱、模拟社交媒体群体行为，并生成预测报告。本文给出 Docker Compose 一键部署、源码原生部署、自定义镜像构建三条互斥路径，逐步覆盖获取代码、配置 .env、启动服务与排障，帮你以最低成本把 MiroFish 部署跑通。

二、路径选择总览

三条路径最终效果一致：前端http://localhost:3000，后端http://localhost:5001。选好后直奔对应章节，不必按顺序阅读。

三、路径一：Docker Compose 一键启动

适用场景：机器已装 Docker 与 Docker Compose，只想最快看到 MiroFish 跑起来。

前置条件：

Docker Engine + Docker Compose v2
已申请LLM_API_KEY与ZEP_API_KEY（两个密钥是必填项，没有它们后端会拒绝启动）

步骤命令：

克隆仓库到本地：

git clone https://gitcode.com/GitHub_Trending/mi/MiroFish cd MiroFish

基于模板创建环境变量文件（Windows 用copy .env.example .env）：

cp .env.example .env

编辑.env，只需填 4 个关键行（不用的LLM_BOOST_*三行要删掉，否则可能干扰配置）：

LLM_API_KEY=你的密钥 LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 LLM_MODEL_NAME=qwen-plus ZEP_API_KEY=你的Zep密钥

拉取官方镜像并在后台启动：

docker compose up -d

查看运行状态与日志：

docker compose ps docker compose logs -f mirofish

常见坑：

⚠️ 拉取ghcr.io镜像慢或超时，把 docker-compose.yml 中的image换为文件内已注释好的加速镜像地址ghcr.nju.edu.cn/666ghj/mirofish:latest再启动。

原理说明：docker-compose.yml 声明了官方镜像、3000/5001端口映射和./backend/uploads数据卷，容器内由npm run dev同时拉起前后端。因为密钥通过env_file注入容器、上传文件被卷持久化，你本地无需安装任何 Python 或 Node 环境。

扩展：镜像内部结构

Dockerfile 基于python:3.11，用npm ci与uv sync --frozen按锁文件安装依赖，保证容器环境与开发机一致。数据卷挂载让重启容器不丢失已上传的文档。

自检清单：

docker compose ps显示容器 running
日志无 KeyError 或配置报错
浏览器打开 localhost:3000
后端 5001 端口有响应

四、路径二：源码原生部署

适用场景：不想装 Docker，或需要随时改 backend/app/ 与 frontend/src/ 的代码热更新调试。

前置条件（版本来自 README-ZH.md）：

Node.js ≥ 18
Python ≥ 3.11 且 ≤ 3.12
uv（Python 包管理器，最新版）

node -v && python --version && uv --version

步骤命令：

克隆并进入仓库：

git clone https://gitcode.com/GitHub_Trending/mi/MiroFish cd MiroFish

配置环境变量（同路径一，cp .env.example .env后填入 4 个关键项）。

一键安装全部依赖（根目录 + 前端 + 后端）：

npm run setup:all

也可以分步执行：

npm run setup # 仅 Node 依赖 npm run setup:backend # 仅后端, uv 自动创建虚拟环境

在项目根目录同时启动前后端：

npm run dev

单独调试某一端时使用：

npm run backend # 仅后端, 端口 5001 npm run frontend # 仅前端, 端口 3000

常见坑：

⚠️ 后端启动即退出并打印「配置错误: LLM_API_KEY 未配置」——这是 backend/app/config.py 的校验机制在拦你，检查.env是否同时配了LLM_API_KEY和ZEP_API_KEY，改完后重启即可。

原理说明：npm run dev用 concurrently 并行拉起 Flask 后端（5001）与 Vite 前端（3000）。为什么前端页面能直接调后端？Vite 开发服务器把/api前缀的请求代理到localhost:5001，同域转发绕开了浏览器跨域限制。

扩展：端口与调试

可用环境变量FLASK_HOST、FLASK_PORT覆盖后端监听地址；FLASK_DEBUG=true开启 Flask 调试模式。Vite 配置见 frontend/vite.config.js。

自检清单：

三个版本命令输出符合前置要求
npm run setup:all无报错
npm run dev两端均启动
3000 页面加载成功
5001 接口可访问

五、路径三：自定义镜像构建

适用场景：要锁定版本、把二次开发成果打包分发，或目标机无法联网装环境。

前置条件：Docker + 已按路径二完成本地依赖验证（确认你的改动能在源码方式下跑通）。

步骤命令：

在仓库根目录构建本地镜像：

docker build -t mirofish:local .

修改 docker-compose.yml 的镜像行为你构建的版本（其余配置不动）：

image: mirofish:local

启动并查看日志：

docker compose up -d docker compose logs -f mirofish

原理说明：Dockerfile 先拷贝package-lock.json、uv.lock等锁文件并安装依赖，再拷贝源码。利用 Docker 层缓存，小改源码只需重跑最后一层COPY；锁文件安装则保证依赖不漂移。

扩展：构建要点

uv sync --frozen与npm ci均严格按锁文件安装。容器EXPOSE 3000 5001，入口命令同样是npm run dev。

自检清单：

docker build全程无错误层
容器使用本地镜像启动
修改的功能点生效
3000 页面与 5001 接口正常

六、部署排障：症状、原因与解决方法

卡在这里了？先对号入座下表，再翻日志。

症状	可能原因	解决方法
后端启动即退出，提示`LLM_API_KEY 未配置`	`.env`缺必填密钥	编辑`.env`补齐`LLM_API_KEY`、`ZEP_API_KEY`，重启服务
启动报`port is already allocated`	3000 或 5001 端口被占用	Docker 路径改 docker-compose.yml 映射如`"3001:3000"`；源码路径停掉占用进程或改`FLASK_PORT`
3000 页面能开但上传后无反应	后端未启动或代理失效	确认`http://localhost:5001`有响应；源码路径确认`npm run dev`两端都在跑
上传文件被拒	文件类型或大小超限	仅支持`pdf/md/txt/markdown`，单文件 ≤ 50MB
`docker compose pull`长时间卡住	`ghcr.io`网络不通	换用 compose 文件注释中的加速镜像地址
`uv sync`报 Python 版本错误	Python 不在 3.11–3.12 区间	`python --version`核对，改用 uv 管理的解释器或安装对应版本