自建 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,是前置依赖没满足。
配好之后,你的调用链是这样的:
浏览器 → 飞牛 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 文件
services:smart-mermaid:image: your-smart-mermaid-image:latest # 换成你实际使用的镜像名与标签container_name: smart-mermaidports:- "8899:3000" # 左边是 NAS 对外端口,右边是容器内端口environment:- AI_API_URL=https://your-endpoint/v1/chat/completions- AI_MODEL_NAME=your-model-name- AI_API_KEY=sk-xxxxxxxxxxxxxxxxrestart: 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 的输入/输出单价。这三项在词元所上可以直接横向对比,比自己翻各家文档拼表格省事。
顺手给个提示词模板,能显著提升成功率:
你是一个 Mermaid 图表生成器。请将用户的中文描述转换为 Mermaid 代码。要求:1. 只输出 Mermaid 代码本身,不要任何解释、前言或总结;2. 不要使用 markdown 代码块包裹;3. 语法必须合法,节点 ID 使用英文,标签可用中文。用户描述:{query}
内网穿透:怎么访问,以及必须做的安全加固
外网访问方案按推荐度排序:
- 组网类(Tailscale / ZeroTier / 飞牛自带远程访问) —— 不开公网端口,设备间点对点加密,最安全,适合个人或小团队。
- Cloudflare Tunnel 等隧道服务 —— 有 CDN 和 HTTPS,不暴露源站 IP。
- frp + 自有 VPS —— 可控性最强,但要自己配 HTTPS 和鉴权。
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 图基本就是一句话的事,比手动画图工具快一个量级。

登录后可评论,请前往 登录 或 注册