MiroFish 部署实战：三步从一条命令启动到能改代码
【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎，预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish
MiroFish 是一款群体智能预测引擎：上传一份种子材料，它就构建出平行数字世界，用智能体交互推演未来走向。这篇教程带你完成 MiroFish 部署：一条命令启动、前后端拆开跑、直到能改代码。
下面三站按操作复杂度递进，对号入座即可：一条命令跑起来（只想看效果）→把后端和前端拆开来启动（想自己托管、改配置）→打开调试开关进入可开发状态（要改代码）。中途卡住了，直接翻到文末的「排障速查」。
一条命令跑起来
前置条件
你的机器上要有 Docker 和 Docker Compose，没有的话先按 Docker 官方文档装好。然后拿到项目代码：
git clone https://gitcode.com/GitHub_Trending/mi/MiroFish cd MiroFish启动命令
在项目根目录执行：
docker-compose up -d⚠️ 这条命令会自动拉取 MiroFish 镜像并在后台启动服务。首次运行因为要拉镜像，可能需要一些时间，耐心等一会儿。
启动成功后，浏览器访问 http://localhost:3000 即可打开 MiroFish 的 Web 界面。
什么算成功
顺带说一句：为什么 Docker 能让部署简单到一条命令？因为它用 namespace 和 cgroups 给每个容器提供独立的网络、进程、文件系统等资源，容器之间相互隔离，相当于把整个应用栈塞进一个独立小系统里，你不用在本机凑环境。
延伸阅读：Docker 的三个核心概念
镜像是一个只读模板，包含运行应用所需的代码、运行时、库、环境变量和配置文件；容器是镜像的运行实例，可以被创建、启动、停止、删除；仓库则是存放镜像的地方。日常部署打交道最多的就是这三个词。
- 访问 http://localhost:3000
- 看到 MiroFish 的启动页面
把后端和前端拆开来启动
想自己托管服务、改配置，就把前后端拆开分别跑。
后端拉起
进入后端目录，建虚拟环境、装依赖、启动：
cd MiroFish/backend python -m venv venv source venv/bin/activate # Linux/Mac venv\Scripts\activate # Windows pip install -r requirements.txt python run.py💡 虚拟环境把依赖关在 venv 里，隔离不同项目的版本冲突；激活后安装的包只对当前项目生效。
后端默认监听 5001 端口，启动无报错即成功。
前端拉起
再开一个终端，进前端目录装依赖并启动开发服务：
cd ../frontend npm install npm run dev⚠️ npm 安装依赖时会从网络拉包，网络不佳容易超时；如果安装报错，删掉本地的 node_modules 目录后重装一次通常能解决。
前端跑在 http://localhost:3000，开发服务器会把/api请求代理到 5001 端口的后端，所以浏览器只需认 3000 一个入口。
之所以前后端拆开部署，是因为后端只提供 API 接口，前端调用接口取数并渲染，两边可以独立开发、独立部署——改界面不用动后端，改业务逻辑不用重打前端。
📌 这类前后端分离一般走 RESTful API：一组约束和风格化约定，前端用统一的方式向后端要数据、交数据。
可改哪些配置
配置都收在环境变量模板里，复制一份再按需修改：
cd .. cp .env.example .env编辑.env，填入你的 API 密钥等环境变量（例如LLM_API_KEY、ZEP_API_KEY等），后端 后端入口 启动时会读取并校验这份配置，缺项会直接报错提示。
- 后端服务启动成功，无报错信息
- 前端服务启动成功，访问 http://localhost:3000 能看到图形界面
- 尝试上传文件，系统能正常处理
打开调试开关进入可开发状态
要改代码、加功能，就需要一套完整的开发环境：源码 + 前后端两套依赖 + 配好的.env。
环境模板
git clone https://gitcode.com/GitHub_Trending/mi/MiroFish cd MiroFish # 安装后端依赖 cd backend pip install -r requirements.txt # 安装前端依赖 cd ../frontend npm install复制环境变量模板并填好密钥：
cd .. cp .env.example .env调试启动
分别在后端、前端各开一个终端：
# 后端：开启调试模式 cd backend python run.py --debug# 前端：开发服务器 cd ../frontend npm run dev💡
--debug参数启用后端的调试模式，改代码能更快反馈，开发过程中定位和解决问题都更省力。
改哪块代码去哪看
开发环境启动后，改动代码可以实时看到效果。核心代码分布：
- 后端服务：backend/app/，API 路由、业务逻辑、工具函数都在这里
- 前端组件：frontend/src/components/，页面的各步骤组件按 Step 划分
顺带说一句开发环境与生产环境的差别：开发环境开着调试模式，方便随时改、随时看；生产环境则关掉调试，优先保证性能、安全和稳定。
- 开发服务器启动成功，调试模式正常工作
- 修改代码后，系统能实时更新
- 能够正常提交代码到版本控制系统
排障速查
| 症状 | 可能原因 | 解决办法 |
|---|---|---|
| 端口冲突 | 启动时报"端口已被占用" | 修改 docker-compose.yml 中的端口映射（见下方示例） |
| 依赖安装失败 | 后端依赖安装时出现错误 | 先升级 pip，再重装依赖（见下方示例） |
| 启动后无法访问 | 服务启动成功，但浏览器访问不到 | 检查防火墙设置，确保 3000 和 5001 端口已开放 |
把占用端口的服务挪到别的端口：
ports: - "3001:3000" # 将 3000 端口映射到主机的 3001 端口 - "5002:5001" # 将 5001 端口映射到主机的 5002 端口依赖装不上时，升级 pip 后重试：
pip install --upgrade pip pip install -r requirements.txt收尾：用一次真实预测验收
无论你走哪一站，最后都按这个动作验收一遍：
- 访问 http://localhost:3000 应看到 MiroFish 启动页
- 上传一份报告文件
- 看到预测结果正常生成
从 clone 到跑通花了多久、卡在哪一步，评论区聊聊。
【免费下载链接】MiroFishA Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎，预测万物项目地址: https://gitcode.com/GitHub_Trending/mi/MiroFish
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
