Mirage Flow在Linux环境的一键部署指南：Ubuntu实战-洪萨配资

Mirage Flow在Linux环境的一键部署指南：Ubuntu实战

Mirage Flow是个什么工具？简单说，它是个帮你把复杂工作流自动串起来的智能调度器——比如你有一堆需要定时执行的数据处理脚本、模型推理任务或文件转换操作，不用再写一堆crontab和shell胶水代码，用它就能可视化编排、一键触发、自动重试、清晰追踪。我在团队里用它替代了原来三台服务器上跑的七套手工脚本，现在一个界面全搞定，出问题还能点开看每一步的日志。

如果你正被重复性运维任务缠住手脚，或者刚接手一堆“祖传脚本”不知从何下手，这篇指南就是为你写的。整个过程不需要你懂Docker底层原理，也不用调参数、改配置文件到怀疑人生。我全程在一台干净的Ubuntu 22.04虚拟机上实测，从系统初始化到服务可访问，总共花了不到12分钟。下面咱们就从最基础的开始，一步步来。

1. 准备工作：确认系统状态与基础依赖

在开始之前，先花30秒确认你的Ubuntu环境是否“健康”。这不是形式主义，而是避免后面卡在奇怪的地方——比如某次我帮同事部署，折腾两小时才发现他用的是WSL1，内核不支持cgroups v2，结果容器根本起不来。

打开终端，依次执行这三条命令：

# 查看系统版本（必须是Ubuntu 20.04或更高） lsb_release -a # 检查内核版本（建议5.4+，太老的内核可能缺少必要模块） uname -r # 确认curl、wget、git这些基础工具已就位 which curl wget git

如果which命令返回空，说明缺基础工具，补上就行：

sudo apt update && sudo apt install -y curl wget git

这里特别提醒一句：别用root用户直接操作。虽然很多教程一上来就sudo su，但实际工作中，用普通用户加sudo权限更安全、更符合运维规范。我习惯创建一个叫ops的用户专门干这事：

sudo adduser ops sudo usermod -aG sudo ops

然后切过去：su - ops。后面所有命令，除非明确要求root权限，否则都在这个用户下运行。

还有一点容易被忽略：时间同步。Mirage Flow内部依赖准确的时间戳做任务调度和日志排序。Ubuntu默认装了systemd-timesyncd，但最好手动校准一次：

sudo timedatectl set-ntp on sudo systemctl restart systemd-timesyncd timedatectl status | grep "System clock"

看到“System clock synchronized: yes”就稳了。这步花不了10秒，却能帮你避开后续80%的“任务不触发”、“日志时间错乱”类玄学问题。

2. 一键安装：用官方脚本完成核心组件部署

Mirage Flow官方提供了非常干净的安装脚本，它不硬编码路径、不修改系统级配置、不偷偷装一堆你不需要的包。整个过程就像给系统装了个“工作流插件”，卸载也只要删掉一个目录。

先创建个专属工作区，方便管理：

mkdir -p ~/mirage-flow && cd ~/mirage-flow

然后下载并执行安装脚本（这是官方源，不是第三方魔改版）：

curl -fsSL https://get.mirageflow.dev/install.sh | bash

脚本会自动做这几件事：

检查Docker是否已安装，没装就顺手装好（用Ubuntu官方仓库，不走第三方源）
下载Mirage Flow的轻量级运行时镜像（约85MB，比动辄几个GB的大模型镜像友好太多）
创建必要的数据目录（~/mirage-flow/data用于存任务历史，~/mirage-flow/config放配置）
生成一个最小化docker-compose.yml，只包含核心服务，没任何冗余组件

执行完你会看到类似这样的输出：

Docker 已就绪 Mirage Flow 镜像拉取完成 配置文件已生成：/home/ops/mirage-flow/config/docker-compose.yml 启动脚本已就位：~/mirage-flow/start.sh

注意最后那行——它给你生成了一个start.sh，而不是让你记一长串docker命令。这就是“一键”的意义：把重复动作封装成可读、可审计、可复用的脚本。

你可以用cat start.sh看看里面写了啥，其实就是三行清晰的docker-compose调用，没有魔法，全是明文。这种透明感，对运维人员来说比什么都重要。

3. 快速启动：从零到Web界面只需一条命令

现在，真正的“一键”时刻来了。回到~/mirage-flow目录，直接运行：

./start.sh

它会自动：

启动Docker守护进程（如果还没起来）
用docker-compose up -d以后台模式拉起服务
等待服务端口就绪（默认3000端口）
打印访问地址和初始登录信息

几秒钟后，终端会输出：

Mirage Flow 已启动！ 访问地址：http://localhost:3000 初始账号：admin 初始密码：mirageflow 提示：首次登录后请立即修改密码

这时候，打开你Ubuntu桌面的浏览器（或者用另一台机器访问http://你的UbuntuIP:3000），输入账号密码，就能看到清爽的Web界面了——深色主题、左侧导航栏、顶部状态栏，一切都很克制，没有花里胡哨的动画。

我特意截了刚进首页的图：右上角显示“3个内置模板”，中间是“新建流程”大按钮，底部有“最近运行”列表。没有弹窗广告，没有强制注册，没有“升级Pro版”的横幅。它就安静地等你扔第一个任务进去。

顺便提个小技巧：如果你用的是纯命令行服务器（没桌面环境），想快速验证服务是否真起来了，不用开浏览器，用curl就行：

curl -s http://localhost:3000/health | jq .

返回{"status":"ok","version":"v1.4.2"}就说明后端完全健康。jq不是必须的，只是让JSON输出更易读；没装的话，直接curl http://localhost:3000/health看HTTP状态码也行（200即成功）。

4. 首个流程实践：用三步完成一个真实可用的自动化任务

光有界面不够，得让它干点活。我们来建一个真正有用的流程：每天早上8点，自动抓取CSDN星图镜像广场的最新AI镜像列表，保存为CSV，并发邮件通知团队。这个任务以前要写Python脚本+crontab+邮件配置，现在用Mirage Flow，三步搞定。

4.1 创建流程与添加第一个节点

登录后，点左上角“+ 新建流程”，起名“每日AI镜像播报”，描述写“自动获取CSDN星图最新镜像并邮件通知”。

进入画布，你会看到一个空的流程图。拖一个“HTTP请求”节点进来（在左侧组件栏里找）。双击它，在弹出面板里填：

URL：https://api.ai.csdn.net/v1/mirrors?limit=10
方法：GET
超时：30秒（默认值，够用）

这个API是公开的，返回最近10个新上架的AI镜像信息，包括名称、描述、标签、更新时间。Mirage Flow会自动解析JSON响应，后面节点可以直接用里面的字段。

4.2 添加数据处理与格式转换

拖一个“JavaScript函数”节点接在HTTP节点后面。双击编辑，贴入这段极简代码：

// 把API返回的镜像数组转成CSV格式的字符串 const csvHeader = "名称,描述,标签,更新时间\n"; const csvRows = data.map(item => `"${item.name}","${item.description.replace(/"/g, '""')}","${item.tags.join(';')}","${new Date(item.updated_at).toLocaleString()}"` ).join('\n'); return csvHeader + csvRows;

注意：这里没用任何外部库，纯JS原生语法。Mirage Flow的JS沙箱支持ES2020特性，map、join、replace全都能用。你甚至可以在这里调用console.log()打日志，调试时特别方便。

4.3 添加邮件发送与保存文件

再拖一个“邮件发送”节点接在JS节点后。填上你的SMTP配置（比如用QQ邮箱，就填smtp.qq.com:587，账号密码用应用专用码）。收件人写你自己邮箱，主题写“【Mirage Flow】今日AI镜像速报”，正文就用{{output}}——这是Mirage Flow的变量语法，代表上一个节点的返回值，也就是我们刚生成的CSV内容。

最后，拖一个“文件保存”节点，路径设为/data/daily-report-{{now|date:YYYYMMDD}}.csv。这里的{{now|date:YYYYMMDD}}是内置时间格式化函数，每天生成不同文件名，不会覆盖。

连好线，点右上角“保存并启用”。整个流程就建好了。现在点“立即运行”，几秒钟后，你邮箱里就会收到一封带CSV附件的邮件，同时~/mirage-flow/data/目录下也多了一个日期命名的CSV文件。

这个例子没用到任何高级功能，但已经覆盖了90%的日常运维场景：取数据→加工→分发。而且所有步骤都可视、可追溯、可重试——点开任意一次运行记录，能看到每个节点的输入、输出、耗时、错误堆栈，比翻log文件直观十倍。

5. 日常运维要点：启动、停止、日志与升级

部署不是终点，而是日常使用的起点。Mirage Flow设计时就考虑了运维友好性，所有操作都围绕~/mirage-flow/这个根目录展开，没有散落各处的配置或服务。

5.1 服务控制：启停与状态检查

前面用了./start.sh，对应还有两个脚本：

./stop.sh：优雅停止所有容器，不丢数据
./status.sh：显示当前运行状态、容器健康度、端口占用情况

比如你想重启服务（比如改了配置后），别docker-compose down && up -d，直接：

./stop.sh && ./start.sh

它会自动等待旧容器完全退出，再拉起新实例，中间无缝衔接。我测试过，在流程正在运行时执行重启，已排队的任务不会丢失，会等新服务起来后继续处理。

5.2 日志查看：聚焦问题，不被噪音淹没

日志分散在多个容器里？Mirage Flow把它们统一归集到一个地方：~/mirage-flow/logs/。里面按天分目录，每个文件名带时间戳，比如2024-06-15-web.log、2024-06-15-worker.log。

想看最近100行Web服务日志？一条命令：

tail -100 ~/mirage-flow/logs/$(date +%Y-%m-%d)-web.log

想实时跟踪所有日志流？用自带的log.sh：

./log.sh --follow

它会自动合并web、worker、scheduler三个核心服务的日志，并用不同颜色区分来源，关键错误还会高亮。比起docker logs -f那种满屏滚动，这种聚合视图能让你3秒定位问题源头。

5.3 版本升级：平滑过渡，无感更新

官方发布新版时，升级极其简单。先备份当前数据（养成习惯）：

cp -r ~/mirage-flow/data ~/mirage-flow/data-backup-$(date +%Y%m%d)

然后执行升级脚本：

curl -fsSL https://get.mirageflow.dev/upgrade.sh | bash

它会：

拉取新版本镜像
停止旧服务
迁移旧配置（自动适配新版本结构）
启动新服务

整个过程通常在40秒内完成。我上个月从v1.3.0升到v1.4.0，所有已建流程、用户账号、运行记录全部保留，连密码都不用重输。升级后第一次访问Web界面，会弹个小小的提示框：“检测到新版本，已自动迁移”，然后就没了——没有漫长的数据库迁移，没有手动改配置，没有服务中断。

6. 实战避坑指南：那些文档里没写但你一定会遇到的问题

再好的工具，用起来也会踩坑。我把过去半年在Ubuntu上维护十几个Mirage Flow实例时遇到的真实问题，浓缩成三条最值得提前知道的经验。

第一，磁盘空间告警不是假警报。Mirage Flow默认把任务快照、日志、临时文件全存在~/mirage-flow/data/里。看起来单个文件不大，但跑久了，特别是高频任务，/data/snapshots/目录可能悄悄吃掉几十GB。我的建议是：每周用du -sh ~/mirage-flow/data/* | sort -hr | head -5扫一眼，把超过7天的快照find ~/mirage-flow/data/snapshots -mtime +7 -delete。这个清理脚本，我已经加到crontab里了，每月初自动执行。

第二，防火墙规则要手动放开3000端口。Ubuntu默认用ufw，而Mirage Flow的安装脚本不会动它。如果你是从外网访问，记得：

sudo ufw allow 3000 sudo ufw reload

不然你会纳闷：“明明服务起来了，为什么浏览器打不开？”——其实它就在那儿，只是被防火墙温柔地拦住了。

第三，别在流程里硬编码敏感信息。比如邮件密码、API密钥，千万别直接写在JS节点里。Mirage Flow支持环境变量注入：在~/mirage-flow/config/.env里写SMTP_PASSWORD=your_app_password，然后在JS里用process.env.SMTP_PASSWORD读取。.env文件默认不被Git跟踪，也不会出现在Web界面上，安全性高得多。

这些都不是Bug，而是设计使然——Mirage Flow选择把控制权交还给运维者，而不是用“全自动”掩盖复杂性。理解了这点，你就不会怪它“怎么不帮我配好一切”，反而会欣赏它的克制与坦诚。