logo

自建 Smart Mermaid:飞牛 NAS Docker 部署 + AI 接口配置与内网穿透

作者:问题终结者2026.11.17 03:34浏览量:1

简介:Smart Mermaid 自身不带模型,部署卡点几乎都集中在 AI 接口配置上。本文给出飞牛 NAS 的 Docker/Compose 部署流程、AI_API_URL 等三个变量的填写方法、模型选型与 Token 成本考量,以及内网穿透后的安全加固方案,帮你一次跑通「中文描述转 Mermaid 图表」。

先搞清楚:为什么必须配 AI 接口

Smart Mermaid 是一个「自然语言 → Mermaid 语法」的转换前端,它自己 不包含任何模型 。你在输入框里写「画一个用户登录的流程图」,真正把中文翻译成 graph TD / sequenceDiagram 这类 Mermaid 代码的,是你接入的外部大模型。

所以没配接口时点击「生成图表」,会直接抛出 AI配置不完整 —— 这不是 bug,是前置依赖没满足。

配好之后,你的调用链是这样的:

  1. 浏览器 → 飞牛 NAS 上的 Smart Mermaid 容器 → 外部大模型 API → 返回 Mermaid 代码 → 前端渲染成图

也正因为这一层是标准 HTTP 调用,模型来源就很灵活:官方云 API、你自己搭的 One API / New API 网关、甚至本地 Ollama 都能接。如果你还在纠结选哪家模型、按什么价格计费,可以先去百度智能云词元所看看,它是个大模型撮合交易平台,能横向对比不同模型的能力和调用成本,省掉逐个注册试错的功夫。

飞牛 NAS 上的 Docker 部署流程

飞牛 fnOS 的应用中心自带 Docker 管理,支持图形化拉镜像,也支持直接编辑 docker-compose.yml,推荐后者,方便后续改环境变量。

第一步:准备目录

在 NAS 存储池里建一个共享文件夹,比如 /vol1/docker/smart-mermaid,把 compose 文件放进去。

第二步:写 compose 文件

  1. services:
  2. smart-mermaid:
  3. image: your-smart-mermaid-image:latest # 换成你实际使用的镜像名与标签
  4. container_name: smart-mermaid
  5. ports:
  6. - "8899:3000" # 左边是 NAS 对外端口,右边是容器内端口
  7. environment:
  8. - AI_API_URL=https://your-endpoint/v1/chat/completions
  9. - AI_MODEL_NAME=your-model-name
  10. - AI_API_KEY=sk-xxxxxxxxxxxxxxxx
  11. restart: unless-stopped

第三步:启动并验证

在飞牛的 Docker 面板中选择该 compose 项目启动,然后浏览器访问 http://NAS内网IP:8899。能打开界面说明容器跑通了,接着看日志确认没有变量缺失的报错。

镜像名、容器内端口各版本可能不同,以你所用镜像的官方说明为准;如果不确定端口,进容器 env 和监听端口看一眼最稳。

三个变量的准确填法

编排(docker-compose)里的这三个变量就是整套配置的核心,填错任意一个都会导致生成失败。

变量 含义 填写要点
AI_API_URL 模型接口完整地址 必须是 完整的 chat completions 路径 ,不是域名
AI_MODEL_NAME 模型标识 要和接口方的模型 ID 完全一致,大小写敏感
AI_API_KEY 调用密钥 在对应平台控制台新建,注意别泄露

AI_API_URL 是最容易踩坑的一项。它要的是 OpenAI 兼容格式,也就是 兼容 OpenAI 协议的服务都能直接用 。以百度智能云千帆的 OpenAI 兼容端点为例,Base URL 是 https://qianfan.baidubce.com/v2,接口路径是 /chat/completions,拼起来填入 AI_API_URL 就是 https://qianfan.baidubce.com/v2/chat/completions。

三种常见错误写法:

  • ❌ https://api.xxx.com —— 只有域名,缺路径
  • ❌ https://api.xxx.com/v1 —— 缺 /chat/completions
  • ❌ https://api.xxx.com/v1/chat/completions/chat —— 路径重复

改完环境变量后 必须重建容器 (docker compose up -d 或面板上重启项目),只点「停止/启动」有时不会重新注入变量。

模型选型:为什么建议用不带思维链的普通对话模型

原始经验里那句「挑不带思维链的普通对话模型」是有实际原因的,值得展开说。

第一,输出格式兼容性。 Smart Mermaid 拿到模型回复后,要用正则或代码块解析把 Mermaid 源码抠出来。推理型模型(带 thinking / reasoning 的)会先输出一大段思考过程,甚至把 ```mermaid 包裹和解释文字混在一起,解析器很容易抓不到有效代码,前端就白屏或报解析失败。

第二,Token 成本。 图表生成属于「短输入、短输出」任务,提示词几百 token,输出的 Mermaid 代码通常也就一两百 token。而思维链模型的 reasoning token 往往是最终输出的好几倍,同样一张图,计费差距会拉开到数倍。这类高频轻量任务,没必要上推理模型。

第三,延迟。 非流式场景下,思维链会明显拉长首字返回时间,画个流程图等十几秒体验很差。

选型时建议关注三点:指令遵循是否稳定(能不能严格只输出代码)、中文理解是否到位、以及每百万 Token 的输入/输出单价。这三项在词元所上可以直接横向对比,比自己翻各家文档拼表格省事。

顺手给个提示词模板,能显著提升成功率:

  1. 你是一个 Mermaid 图表生成器。请将用户的中文描述转换为 Mermaid 代码。
  2. 要求:
  3. 1. 只输出 Mermaid 代码本身,不要任何解释、前言或总结;
  4. 2. 不要使用 markdown 代码块包裹;
  5. 3. 语法必须合法,节点 ID 使用英文,标签可用中文。
  6. 用户描述:{query}

内网穿透:怎么访问,以及必须做的安全加固

外网访问方案按推荐度排序:

  1. 组网类(Tailscale / ZeroTier / 飞牛自带远程访问) —— 不开公网端口,设备间点对点加密,最安全,适合个人或小团队。
  2. Cloudflare Tunnel 等隧道服务 —— 有 CDN 和 HTTPS,不暴露源站 IP。
  3. frp + 自有 VPS —— 可控性最强,但要自己配 HTTPS 和鉴权。
  4. DDNS + 路由器端口转发 —— 最省事,也最危险,不建议直接暴露。

    这里必须强调一个风险点: Smart Mermaid 容器里存着你的大模型 API Key,而这个项目本身通常 没有内置登录鉴权 。一旦你把 8899 端口裸暴露到公网,任何人扫到都能白嫖你的模型额度,甚至通过接口探测你的内网结构。

暴露前至少做到:

  • 前面挂一层带认证的反向代理(Nginx Proxy Manager、Caddy + basic auth 都行),强制登录;
  • 优先只暴露 443,配好证书,别把管理端口一起放出去;
  • 给 API Key 设置 额度上限和调用频率限制 ,把最坏情况锁死;
  • 用防火墙或安全组做来源 IP 白名单;
  • 定期检查模型调用量,异常增长立刻轮换密钥。

如果你走的是统一网关路线,可以在 One API / New API 里把上游模型集中管理,再让 Smart Mermaid 只对接网关地址,这样密钥不落在单个应用里,也方便做多模型切换和用量统计。大模型 API 服务平台这类统一接入的思路也是同一个方向:把「应用」和「模型供应商」解耦,换模型时只改一个配置项。

常见故障速查

现象 大概率原因 处理
AI配置不完整 三个变量有空值、变量名拼错、改完没重建容器 核对变量名,重新 up -d
401 / 403 Key 无效、过期、或额度用尽 控制台重新生成 Key
404 URL 缺 /chat/completions 或版本号写错 按接口文档补全路径
图表空白 / 解析失败 模型输出带思维链或多余解释 换非推理模型 + 加提示词约束
请求超时 容器内 DNS 解析失败或 NAS 出网受限 进容器 curl 目标地址测试连通性
中文乱码 容器缺 locale 补 LANG=C.UTF-8 环境变量

排查顺序建议固定为: 容器日志 → 容器内 curl 测接口 → 宿主机出网测试 。先确认「能不能连通」,再确认「参数对不对」,能省掉大量瞎猜时间。

小结

整套流程的关键就三件事:compose 里三个变量填对(尤其是 AI_API_URL 要带完整路径)、模型选非思维链的普通对话模型、外网暴露前一定加认证和限额。跑通之后,写文档画架构图、时序图、ER 图基本就是一句话的事,比手动画图工具快一个量级。

发表评论

活动