Mirage Flow在Ubuntu 20.04上的保姆级安装与配置教程
Mirage Flow在Ubuntu 20.04上的保姆级安装与配置教程
如果你刚接触AI大模型，想在Linux系统上快速搭建一个属于自己的开发环境，那么你来对地方了。今天要聊的Mirage Flow，是一个功能强大的大模型推理框架，能让你轻松玩转文本生成、对话等AI能力。但说实话，第一次在Ubuntu上部署这类工具，可能会遇到各种权限、网络或者依赖问题，挺让人头疼的。
这篇教程就是为你准备的。我会用最直白的话，带你一步步在Ubuntu 20.04上把Mirage Flow跑起来。你不用是Linux专家，只要跟着步骤走，遇到问题看看我提到的解决方法，基本都能搞定。我们的目标很简单：从零开始，搭建一个稳定、可用的Mirage Flow环境，并完成一次基础的功能测试。
1. 开始前的准备工作
在动手安装之前，我们先花几分钟把“地基”打好。这就像盖房子，地基稳了，后面才省心。
首先，你需要一台运行Ubuntu 20.04的电脑或者服务器。我强烈建议使用服务器，因为性能更稳定，适合长期运行。如果你用的是个人电脑，确保它有至少8GB的内存和20GB的可用磁盘空间，这样跑起来会更流畅。
接下来，打开你的终端。在Ubuntu里，你可以按Ctrl+Alt+T快捷键快速打开。我们所有的操作都会在这个黑乎乎的窗口里进行，别怕，我会把每一条命令都解释清楚。
我们先来检查一下系统的基本信息，确保我们没跑错地方。在终端里输入：
lsb_release -a回车后，你应该能看到类似下面的输出，确认你的系统是Ubuntu 20.04。
No LSB modules are available. Distributor ID: Ubuntu Description: Ubuntu 20.04.6 LTS Release: 20.04 Codename: focal好了，身份确认完毕，我们可以进入下一步了。
2. 安装与配置Docker环境
Mirage Flow通常被打包成Docker镜像，这样能保证在任何地方运行的效果都一样，避免了“在我机器上好好的”这种尴尬。所以，我们得先请出Docker这位“搬运工”。
2.1 卸载旧版本（如果有的话）
如果你的系统以前装过Docker，为了避免冲突，我们先清理一下。在终端里一条条执行下面的命令：
sudo apt-get remove docker docker-engine docker.io containerd runc这条命令会尝试移除可能存在的旧版本Docker组件。如果系统提示说没找到这些包，那是好事，说明你的系统很干净，直接跳过就行。
2.2 安装Docker官方仓库
现在我们来安装最新版的Docker。Ubuntu自己的软件仓库里的Docker版本可能比较旧，所以我们直接用Docker官方的仓库，这样能保证安装的是最新稳定版。
首先，更新一下系统的软件包列表：
sudo apt-get update接着，安装一些必要的工具，让系统能通过HTTPS使用软件仓库：
sudo apt-get install \ ca-certificates \ curl \ gnupg \ lsb-release然后，添加Docker官方的GPG密钥。这个密钥就像一把“安全锁”，用来验证我们下载的软件包确实是Docker官方发布的，没有被篡改。
sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg最后，把Docker的软件仓库地址添加到系统的源列表里：
echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null2.3 安装Docker引擎
仓库配置好了，我们再次更新软件包列表，这次就能看到Docker的包了：
sudo apt-get update然后，安装Docker引擎、命令行工具以及容器运行时：
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin安装完成后，Docker服务会自动启动。我们可以运行一个经典的测试命令，来验证Docker是否安装成功：
sudo docker run hello-world如果你看到终端里打印出一段欢迎信息，最后有Hello from Docker!这句话，那么恭喜你，Docker安装成功了！这个命令会从网上拉取一个很小的测试镜像并运行它。
2.4 管理Docker用户组（解决权限问题）
你可能注意到了，上面的命令都加了sudo。如果不加，系统会告诉你权限不够。每次都输密码很麻烦，我们可以把你的用户加到docker用户组里，这样以后运行Docker命令就不用sudo了。
执行下面的命令：
sudo groupadd docker # 如果docker组已存在，会提示，忽略即可 sudo usermod -aG docker $USER重要提示：执行完上面的命令后，你需要完全退出当前终端，并重新登录，或者重启系统，这个改动才能生效。这是很多新手会忽略的一步，导致后续命令依然报权限错误。
重新登录后，打开新终端，再运行一次测试命令，这次不加sudo：
docker run hello-world如果能成功运行，说明权限配置正确。如果还报错，可以尝试先执行newgrp docker命令，或者检查一下你是否真的重新登录了。
3. 拉取并运行Mirage Flow镜像
Docker环境就绪，主角Mirage Flow就可以登场了。我们直接从镜像仓库把它“请”到本地来。
3.1 拉取Mirage Flow镜像
运行下面的命令来拉取镜像。这个过程需要从网络下载，时间长短取决于你的网速和镜像大小，请耐心等待。
docker pull mirageflow/mirage-flow:latest命令执行后，你会看到终端开始下载不同的“层”。下载完成后，可以用下面的命令查看本地已有的镜像，确认mirageflow/mirage-flow已经躺在那儿了。
docker images3.2 运行Mirage Flow容器
镜像下载好了，但它只是一个静态的模板。我们需要根据这个模板，创建一个正在运行的“容器”实例。运行容器的命令稍微复杂一点，因为我们需要配置一些参数。
docker run -d \ --name mirage-flow \ -p 7860:7860 \ -v /path/to/your/models:/app/models \ --restart unless-stopped \ mirageflow/mirage-flow:latest我来解释一下这条命令的每个部分：
-d：让容器在“后台”运行，这样你关了终端它也不会停。--name mirage-flow：给这个容器起个名字，方便以后管理，比如停止、重启它。-p 7860:7860：这是端口映射，非常关键。它把容器内部的7860端口“映射”到你电脑的7860端口。这样，你通过浏览器访问http://你的服务器IP:7860就能看到Mirage Flow的界面了。-v /path/to/your/models:/app/models：这是数据卷挂载。冒号前面是你电脑上的一个真实目录路径（比如/home/yourname/models），后面是容器内的目录。这样，你可以把模型文件放在自己电脑的目录里，容器就能访问到，即使容器被删除，你的模型文件也还在。--restart unless-stopped：设置容器自动重启策略。除非你手动停止它，否则如果容器意外退出，Docker会重新启动它，保证服务持续可用。- 最后一行就是指定我们刚才拉取的镜像。
注意：请务必将/path/to/your/models替换成你电脑上真实存在的目录路径。你可以用mkdir命令先创建一个目录，例如mkdir -p ~/mirage-models。
运行命令后，容器就在后台启动了。你可以用下面的命令查看它的运行状态：
docker ps如果看到名为mirage-flow的容器状态是Up，就说明启动成功了。
4. 访问与基础功能测试
容器跑起来了，我们来看看成果如何。
4.1 访问Web用户界面
打开你电脑上的浏览器（比如Chrome, Firefox）。在地址栏输入：
http://localhost:7860如果你是在另一台电脑上操作Ubuntu服务器，那么需要把localhost换成你服务器的实际IP地址。比如http://192.168.1.100:7860。
如果一切顺利，你应该能看到Mirage Flow的Web用户界面了。通常是一个简洁的对话框或操作面板。这意味着服务部署成功！
4.2 进行简单的对话测试
现在我们来试试它的核心功能。在界面上找到输入文本的地方（可能标注着“输入”、“Input”或有一个对话框）。
- 输入一句简单的问候，比如：“你好，请介绍一下你自己。”
- 点击“发送”或“生成”按钮。
稍等片刻，你应该就能看到Mirage Flow生成的回复了。回复内容可能是关于它自身功能的一段描述。这个简单的测试证明了从部署到推理的整个链路是通的。
4.3 常见访问问题排查
如果浏览器打不开页面，别急，我们可以按顺序排查：
- 检查容器状态：回到终端，运行
docker ps，确认mirage-flow容器确实在运行（Status 为 Up）。 - 检查端口映射：运行
docker port mirage-flow，查看容器端口映射情况，确认7860端口是否正确映射。 - 检查防火墙：如果你用的是云服务器（如阿里云、腾讯云），还需要在服务器的安全组规则里，放行7860端口的入站流量。这是被外部访问的关键一步。
- 查看容器日志：运行
docker logs mirage-flow，可以查看容器的运行日志，里面可能有错误信息，能帮你定位问题。
5. 日常管理与维护技巧
环境搭好了，还得知道怎么日常照顾它，这里有几个实用的小技巧。
5.1 常用的Docker容器管理命令
把这些命令记下来，管理容器会非常方便：
- 停止容器：
docker stop mirage-flow - 启动已停止的容器：
docker start mirage-flow - 重启容器：
docker restart mirage-flow - 进入容器内部（用于高级调试）：
docker exec -it mirage-flow /bin/bash - 删除容器（谨慎操作，会丢失容器内未挂载的数据）：
docker rm mirage-flow - 删除镜像：
docker rmi mirageflow/mirage-flow:latest
5.2 更新Mirage Flow版本
当有新版镜像发布时，你可以这样更新：
- 停止并删除旧容器：
docker stop mirage-flow && docker rm mirage-flow - 拉取最新镜像：
docker pull mirageflow/mirage-flow:latest - 用之前
docker run的命令（记得包含你的数据卷路径）重新创建并启动新容器。
5.3 模型文件的管理
之前我们通过-v参数把本地目录挂载到了容器的/app/models。你可以把下载的模型文件（通常是.bin,.safetensors等格式）直接放到你本地挂载的目录里（例如~/mirage-models）。Mirage Flow启动时会自动加载该目录下的模型。
6. 总结与后续建议
走完这一遍，你应该已经在Ubuntu 20.04上成功搭建起Mirage Flow的环境了。整个过程的核心其实就是配置好Docker，然后一条命令把服务跑起来。最难的部分可能在于初次接触Linux命令和Docker概念时的陌生感，以及网络、权限这些琐碎但关键的小问题。
我建议你部署成功后，先别急着探索复杂功能。就在刚才打开的Web界面里，多试几次简单的对话，感受一下模型回复的速度和质量。熟悉了基本操作后，你可以尝试在启动命令里添加更多的环境变量参数，来调整模型的行为，或者去官方文档看看如何加载不同的模型。
这种基于Docker的部署方式最大的好处就是干净、隔离。如果你哪天想彻底清理，直接删除容器和镜像就行，完全不会弄乱你的Ubuntu系统。希望这个教程能帮你顺利跨出第一步，在这个稳定的基础上，再去探索大模型更广阔的世界。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。