MiroFish 部署指南：Docker 一键启动与源码上手教程（含端口、依赖排错）
【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎，预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish
MiroFish 是一个多智能体群体智能引擎：上传种子材料（新闻、报告、小说），它会用成百上千个智能体在数字沙盘中推演，给你一份预测报告和一个可交互的虚拟世界。这篇文章带你走完三种部署路线，读完至少能让它在 http://localhost:3000 上跑起来。
部署路线图：三条路线，对号入座
三条路线共用同一套仓库，区别只在环境复杂度和可改动的深度。下面按路线逐条讲。
路线一：容器极速路（新手档）
这节做完，你手里有一个在后台跑着的 MiroFish 容器，浏览器打开 http://localhost:3000 就是完整界面。
前置条件：装什么、怎么确认、去哪装
| 需要装什么 | 怎么确认已装 | 没装去哪装 |
|---|---|---|
| Docker（含 Compose） | 执行docker --version和docker compose version，各输出版本号 | Docker 官网 Docker Desktop（Windows/Mac）或sudo apt install docker.io docker-compose（Linux） |
| 项目代码 | 目录里有docker-compose.yml和Dockerfile | git clone https://gitcode.com/GitHub_Trending/mi/MiroFish |
分步操作
- 克隆代码并进入项目目录：
git clone https://gitcode.com/GitHub_Trending/mi/MiroFish cd MiroFish执行成功后，ls应该看到docker-compose.yml、backend/、frontend/等目录。
- 创建环境变量文件：
cp .env.example .env执行成功后，目录里多出一个.env文件。用编辑器打开，填入两个必填项：LLM_API_KEY（任意 OpenAI SDK 格式的 LLM 服务密钥，README 推荐百炼平台的 qwen-plus）和ZEP_API_KEY（Zep Cloud 密钥，每月免费额度够轻度使用）。
⚠️ 这两个 key 不填，容器里的后端会直接报配置错误退出，启动日志里会看到LLM_API_KEY 未配置。
- 拉取镜像并启动：
docker compose up -d执行成功后输出Container mirofish Started（或状态表）。首次要拉取ghcr.io/666ghj/mirofish:latest镜像，视网络而定，约 1–5 分钟。
✅ 小贴士：docker-compose.yml 里注释了一行国内加速镜像地址，拉取慢时把它替换到image:字段即可。
自测点
- 执行
docker compose ps，mirofish容器状态为Up，而不是Restarting - 打开 http://localhost:3000，能看到 MiroFish 的首页界面
- 执行
docker compose logs --tail 50，后端日志没有 Traceback，能看到 Flask 监听 5001 端口的信息 - 浏览器访问 http://localhost:5001，后端有 HTTP 响应（不是拒绝连接）
图 1：MiroFish 部署成功后的启动界面，上传种子材料从这里开始
路线二：源码二开路（开发者档）
这节做完，你手里有一套本地开发模式运行的前后端服务，前端 3000 端口、后端 5001 端口，改 frontend/src/ 或 backend/app/ 下的代码都能生效，方便二次开发。
前置条件：装什么、怎么确认、去哪装
| 需要装什么 | 怎么确认已装 | 没装去哪装 |
|---|---|---|
| Node.js 18+（含 npm） | 执行node -v，输出v18.x或更高 | Node.js 官网装 LTS 版本 |
| Python 3.11–3.12 | 执行python --version，版本落在 3.11–3.12 区间 | python.org 下载对应版本 |
| uv（Python 包管理器） | 执行uv --version，输出版本号 | 按 uv 官方安装脚本安装 |
分步操作
- 克隆代码：
git clone https://gitcode.com/GitHub_Trending/mi/MiroFish cd MiroFish执行成功后看到根目录的package.json、backend/、frontend/。
- 配置环境变量，命令和路线一第 2 步相同：
cp .env.example .env执行成功后编辑.env，填LLM_API_KEY和ZEP_API_KEY。注意 backend/app/config.py 会校验这两项，缺一后端直接sys.exit(1)并打印"配置错误"。
- 一键安装全部依赖（根目录 + 前端 + 后端虚拟环境）：
npm run setup:all执行成功后，根目录出现node_modules/，backend/下出现 uv 创建的.venv/。过程要下载 Node 和 Python 两批包，视网络而定，约 2–5 分钟。
⚠️ 中途某个包超时失败的话，直接重跑一遍npm run setup:all即可，它是可重复执行的。
- 同时启动前后端：
npm run dev执行成功后终端分两栏滚动日志（concurrently 的backend/frontend标签），浏览器自动打开 http://localhost:3000。前端由 Vite 提供并代理/api到 5001 端口（见 vite.config.js），你不需要再手动配代理。
自测点
npm run dev的终端同时输出 backend 和 frontend 两段日志，无红色报错- http://localhost:3000 页面能打开，且能发起一次上传请求（不报 404/CORS）
- 单独停掉
npm run dev，改跑npm run backend，再访问 http://localhost:5001 有响应，说明后端独立可用 - 在 frontend/src/components/ 随便改一个文案，保存后浏览器页面自动刷新（Vite 热更新生效）
图 2：源码部署后的 MiroFish 交互界面，五步工作流的入口
路线三：共建开发路（贡献者档）
这节做完，你手里是一个带调试开关、带测试用例的开发环境，可以直接提 PR。
前置条件
环境要求与路线二完全一致（Node 18+、Python 3.11–3.12、uv），确认方式看上一节表格，不重复。额外需要一个能跑 Python 单测的终端，任何现代 bash/zsh 都行。
分步操作
环境搭建走路线二第 1–3 步（克隆、
.env、npm run setup:all），不再赘述。打开后端调试模式。
.env里设置：
FLASK_DEBUG=True保存后npm run backend启动，Flask 进入 reloader 模式，改 backend/ 下代码保存即重启。⚠️ 只用于开发，config.py里也写明了 DEBUG 模式勿用于生产。
- 跑一遍后端测试确认基线健康：
cd backend && uv run pytest tests/执行成功后输出X passed，无 failed。失败多半是环境差异（如缺 Python 3.11 特性），先对照前置条件表自查版本。
- 前后端分终端启动，方便边看日志边改码：
npm run backend # 终端 1 npm run frontend # 终端 2执行成功后终端 1 只有 Flask 日志，终端 2 只有 Vite 日志，两边互不干扰，前端保存热更、后端保存重启。
自测点
FLASK_DEBUG=True下改一行 backend/app/ 代码，Flask 日志出现 reloader 重启记录uv run pytest tests/全绿，与 main 分支一致- Vite 终端在每次保存后打印
hmr update类输出 - 前端页面触发一次完整工作流（如上传文本文件），后端日志能看到对应
/api请求落进来
图 3：一次完整推演后生成的预测报告，也是你联调功能时的验收样本
验收：3 步确认服务真的活着
这节做完，你能用"界面 + 功能 + 日志"三重证据确认部署成功，而不是只看端口通了。
- 界面能打开：访问 http://localhost:3000，首页正常渲染，右上角能切换中英文（i18n 资源来自 locales/）。
- 核心功能点一次：上传一份 pdf 或 md 文件（backend/app/config.py 里限制 50MB，支持 pdf/md/txt/markdown），进入图谱构建步骤，页面能拿到后端返回的进度。
- 日志无报错：Docker 部署看
docker compose logs --tail 100，源码部署看两个终端，没有 Traceback、没有ECONNREFUSED、没有 5xx 刷屏。
排障对照表：报错、可能原因、解法
这节做完，你手里有一张速查表，90% 的部署卡点都能 1 分钟内定位。
| 报错/现象 | 可能原因 | 解法 |
|---|---|---|
port is already allocated/ 端口已被占用 | 3000 或 5001 被其他程序占了 | 容器路线：改 docker-compose.yml 的ports，如"3001:3000"；源码路线：Vite 会顺延 3001 并提示，或先lsof -i :3000找出占用进程 |
npm run setup:all中途失败 | 网络波动导致单个包下载超时；Node 版本低于 18 触发引擎检查 | 重跑同一命令续装；node -v确认 ≥18；前端可删node_modules后再npm install |
| 后端启动即退出，打印"配置错误" | .env缺LLM_API_KEY或ZEP_API_KEY | 补齐两个 key；注意.env必须放在项目根目录，config.py只从那里读 |
| 界面能打开，但一操作就 404/跨域 | 后端没起，或前端代理没连上 5001 | 容器路线docker compose ps看是否Restarting；源码路线确认npm run dev而不是只起了前端 |
| 首次启动卡住没反应 | 在等镜像拉取 | docker compose logs -f看拉取进度；慢的话换成 docker-compose.yml 里注释的加速镜像地址 |
调优：硬件档位与三条立竿见影的优化
这节做完，你清楚该给机器多少资源，以及先动哪三个旋钮。
| 档位 | CPU | 内存 | 存储 |
|---|---|---|---|
| 基础（体验、小规模推演） | 4 核 | 8 GB | 100 GB SSD |
| 标准（常规模拟） | 8 核 | 16 GB | 200 GB SSD |
| 高级（多轮、多智能体并行） | 16 核 | 32 GB | 500 GB SSD |
三条可直接落地的优化：
- 控制模拟轮数：
config.py默认OASIS_DEFAULT_MAX_ROUNDS=10，README 也建议先从 40 轮以下开始试跑——推演耗时大头在这里，先用小轮数验证流程再拉满。 - 收敛报告 Agent 的工具调用：
REPORT_AGENT_MAX_TOOL_CALLS（默认 5）和REPORT_AGENT_MAX_REFLECTION_ROUNDS（默认 2）在.env里可降，报告生成阶段明显提速。 - 上传目录挂盘：Docker 路线已把
./backend/uploads映射到容器外，把宿主机这块放在 SSD 上，种子文件和模拟产物读写不会拖累 IO。
图 4：模拟运行中的群体交互视图，智能体在 Twitter/Reddit 双平台上发帖与互动
改配置别只改一处：.env是唯一的变量入口，FLASK_DEBUG、轮数、工具调用上限都走它。跑起来之后有任何报错，直接开仓库 issue 贴上日志，比猜快得多。
【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎，预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
