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

MiroFish 部署指南Docker Compose 一键部署群体智能预测引擎【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFishMiroFish 是一款简洁通用的群体智能预测引擎上传一份文档它会自动构建关系图谱、模拟社交媒体群体行为并生成预测报告。本文给出 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 .envcp .env.example .env编辑.env只需填 4 个关键行不用的LLM_BOOST_*三行要删掉否则可能干扰配置LLM_API_KEY你的密钥 LLM_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 LLM_MODEL_NAMEqwen-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.mdNode.js ≥ 18Python ≥ 3.11 且 ≤ 3.12uvPython 包管理器最新版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_DEBUGtrue开启 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 allocated3000 或 5001 端口被占用Docker 路径改 docker-compose.yml 映射如3001:3000源码路径停掉占用进程或改FLASK_PORT3000 页面能开但上传后无反应后端未启动或代理失效确认http://localhost:5001有响应源码路径确认npm run dev两端都在跑上传文件被拒文件类型或大小超限仅支持pdf/md/txt/markdown单文件 ≤ 50MBdocker compose pull长时间卡住ghcr.io网络不通换用 compose 文件注释中的加速镜像地址uv sync报 Python 版本错误Python 不在 3.11–3.12 区间python --version核对改用 uv 管理的解释器或安装对应版本 日志是排障第一现场Docker 路径看docker compose logs -f mirofish源码路径直接看终端里 concurrently 分出的backend/frontend两列输出。七、最终验收确认 MiroFish 真正跑通无论走哪条路径都按同一份清单走一遍完整链路打开 localhost:3000 首页正常上传一份 .md 或 .txt 文档图谱构建任务创建成功模拟任务可启动并推进生成预测报告并可查看停止服务docker compose down 或 CtrlC无残留进程八、部署挑战计时开始从git clone到在页面上成功上传第一份报告你的 MiroFish 部署花了多久哪一步最耗时——拉镜像、装依赖还是填.env到评论区分享你的耗时、系统环境和踩过的坑我们一起把这份部署指南补得更顺。【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考