MiroFish 完整部署指南：群体智能预测引擎从 Docker 一键启动到二次开发

MiroFish 完整部署指南：群体智能预测引擎从 Docker 一键启动到二次开发

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

MiroFish 部署其实不复杂。MiroFish 是一个开源的群体智能预测引擎：你上传一份种子材料（新闻报道、分析报告甚至小说），用自然语言说清楚想预测什么，它就在数字世界里让大量 AI 智能体带着各自的人格和记忆自由交互、演化，最后产出一份可以深入交互的预测报告。本文按由浅入深的顺序带你走完三个阶段：第 1 节用 Docker 五分钟跑起来；第 2 节搭好本地开发环境，改代码立刻见效；第 3 节从 Fork 一路走到提交 PR。只想体验效果的，读完第 1 节就行；想定制或贡献代码的，一路看到最后。

先跑起来：MiroFish Docker 一键启动步骤

1. 环境自检。确认机器上装好了 Docker 和 Compose：

docker --version docker compose version

能看到两行版本号，基础环境就没问题。

2. 拉代码并配置密钥：

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

打开根目录的 .env，把 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL_NAME、ZEP_API_KEY 四项填上，模板注释里写了申请入口。保存后密钥就配好了。

3. 启动：

docker compose up -d

第一次会拉镜像，稍等片刻；命令返回后，前后端就已经在容器里跑起来了。

4. 浏览器验证。先执行 curl http://localhost:5001/health，再打开 http://localhost:3000：

页面能打开、出现上传入口，并且上传一份材料后能跑出预测报告，就说明启动成功了，全程一般不超过 5 分钟。

只想体验核心功能，只需看第 1 节；想改代码，看第 2 节。

敢改代码：MiroFish 本地开发环境搭建

这一节适合要改算法、改界面、接自己业务系统的人。先记住整体结构：backend/ 是 Flask 后端，frontend/ 是 Vue 3 + Vite 前端，前端通过 /api 前缀和后端对接。

后端虚拟环境搭建

要求 Python 3.11 或 3.12（项目锁定了这个版本范围），再装一个 uv 包管理器——它会在 backend/ 下自动创建虚拟环境，不用你手动敲 python -m venv：

cd backend uv sync uv run python run.py

启动后后端跑在 http://localhost:5001，改完代码保存即热重载。配置读的是根目录的 .env，没配过的话先按第 1 节把 cp .env.example .env 做掉。

⚠️ .env 里是 LLM 和 Zep 的 API 密钥，属于敏感信息，不要提交进 Git；生产环境建议改用密钥管理服务或配置中心下发。

三个最常改的位置：

• backend/app/services/：图谱构建、智能体生成、模拟运行、报告生成等核心逻辑
• backend/app/api/：graph / simulation / report 三组路由
• backend/tests/：pytest 用例，改完逻辑记得跑一遍

完整结构见 后端服务源码。

前端环境搭建

要求 Node.js 18+：

cd frontend npm install npm run dev

Vite 开发服务器起在 http://localhost:3000，并且已经内置了把 /api 请求代理到 5001 端口的配置，不用额外配环境变量。界面组件在 frontend/src/components/，接口调用在 frontend/src/api/，中英文文案在 locales/。

想省事的话，在项目根目录执行 npm run setup:all 一次性装好前后端依赖，再 npm run dev 同时拉起两个服务。

要做 MiroFish 二次开发，只需看第 2 节；准备提 PR 的，继续第 3 节。

贡献代码：MiroFish 从 Fork 到 PR 四步走

1. Fork 并克隆：在 GitCode 上把项目 Fork 到自己账号，然后：

git clone https://gitcode.com/<你的用户名>/MiroFish cd MiroFish

2. 建分支：从最新主干切一个特性分支，比如 git checkout -b feature/your-feature，别直接在 main 上改。
3. 本地测试：改完先跑 cd backend && uv run pytest tests/，再按第 2 节的方法起一次服务确认页面行为。工具链一句话带过：提交前过一遍格式化与静态检查（后端 black / flake8，前端 eslint），风格统一，维护者看着也顺眼。
4. 提 PR：git commit 写清楚动机，推到自己仓库，再到 Fork 页面向上游仓库发 Pull Request。

只想给 MiroFish 贡献代码，只需看第 3 节；卡住的细节翻第 4 节。

出错了别慌：MiroFish 部署自检清单

按出现频率排，每条都是「症状 → 解决」：

• 🔧端口冲突：启动时报 Address already in use → 用 lsof -i :3000 和 lsof -i :5001 找出占用进程并结束，或改 docker-compose.yml 里的端口映射（如 3001:3000）。
• 📦依赖安装失败：uv sync 或 npm install 超时、报错 → 升级 pip 与 npm、清缓存重试，国内网络给 npm 换镜像源再装。
• 📡服务无法访问：容器显示 running 但浏览器打不开 3000 → 用 docker compose logs -f 看日志里的真实报错，同时确认防火墙放行了 3000 和 5001。
• 📡密钥类报错：页面能打开，一点任务就 401 或连接失败 → 检查 .env 里四项密钥是否填对，改完执行 docker compose up -d 让容器重新加载配置。
• 💾数据丢失：重启后上传的文件不见了 → 确认 docker-compose.yml 的 volumes 里挂载了 ./backend/uploads，它就是容器里上传文件的落盘位置，重要数据顺手备份一份。

到这里，MiroFish 部署这条线就走完了：5 分钟看效果，半小时改出差异，再往后就是给上游提 PR。想继续定制的，重点翻 核心服务逻辑 和 界面组件；想贡献代码的，提交前先看 测试用例 里已有的写法，照着来最不容易被打回。

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