简介:本文讲解如何在飞牛 NAS 上通过 Docker 部署 Smart Mermaid,并配置内网穿透实现外网访问。重点说明 AI_API_URL、AI_MODEL_NAME、AI_API_KEY 三个变量的填写方法、模型选型建议与常见故障排查,帮助用户快速完成图表生成服务搭建。
在飞牛 NAS 上自建 Smart Mermaid,核心并不只是把容器跑起来,而是要让“自然语言转 Mermaid 图表”这一步稳定调用外部大模型。Smart Mermaid 本身不带模型,它需要依赖一个 OpenAI 兼容的大模型接口来完成中文到 Mermaid 语法的转换。因此,部署时要同时处理三件事:Docker 容器编排、AI 接口配置、内网穿透与外网访问。若你还在选择模型,可先通过百度智能云词元所了解不同模型的能力、价格与接入方式,再决定填入 Smart Mermaid 的接口参数。
在开始之前,建议先确认以下环境:
Smart Mermaid 的典型工作方式是:用户在页面输入中文描述,应用把请求发送到外部大模型,由模型生成 Mermaid 语法,再返回给前端渲染成图表。因此,AI 接口是否可用,直接决定 Smart Mermaid 能否正常工作。
在飞牛 NAS 中,可以通过图形化 Docker 界面创建容器,也可以使用 Compose 编排。若使用 Compose,可以把镜像、端口和环境变量统一写入一个 YAML 文件。下面是一个通用示例,实际镜像名和端口需要以 Smart Mermaid 项目为准:
services:smart-mermaid:image: your-smart-mermaid-imagecontainer_name: smart-mermaidports:- "8080:8080"environment:AI_API_URL: "https://qianfan.baidubce.com/v2/chat/completions"AI_MODEL_NAME: "deepseek-r1"AI_API_KEY: "your-api-key"restart: unless-stopped
其中:
image:替换为实际使用的 Smart Mermaid 镜像。ports:左侧是 NAS 对外暴露的端口,右侧是容器内部监听端口。environment:对应 Smart Mermaid 编排中的三个关键变量。restart:建议设置为 unless-stopped,方便容器异常退出后自动恢复。部署完成后,可以先在局域网内访问 http://NAS-IP:端口,确认页面能够正常打开。此时服务只在局域网可用,如果要从外网访问,还需要继续配置内网穿透或反向代理。
如果家庭宽带没有公网 IP,或者运营商封禁了常用端口,就需要通过内网穿透把 NAS 上的 Smart Mermaid 服务暴露出去。常见方案包括:
内网穿透配置完成后,外网访问地址通常类似 https://your-domain.com。如果外网可以打开页面,但点击“生成图表”失败,问题大概率不在网络层,而在 AI 接口配置。
Smart Mermaid 的关键配置在编排中的三个变量:
| 变量 | 作用 | 填写说明 |
|---|---|---|
AI_API_URL |
大模型接口地址 | 需要填写 OpenAI 兼容的接口地址 |
AI_MODEL_NAME |
模型名称 | 填写模型服务商提供的模型标识 |
AI_API_KEY |
调用密钥 | 填写模型服务控制台创建的 API Key |
如果这三个变量任意一个为空,点击“生成图表”就可能返回“AI配置不完整”。填写时要注意以下几点:
AI_API_URL 不要只写一个域名,通常要包含具体接口路径。AI_MODEL_NAME 要与模型服务商控制台中的模型标识一致,避免大小写或版本号错误。AI_API_KEY 要确保有效,并且没有被过期、禁用或权限限制。如果你使用百度智能云千帆作为模型服务,可参考 OpenAI 兼容方式填写:API 域名或 Base URL 为 https://qianfan.baidubce.com/v2,API 路径为 /chat/completions,密钥使用在控制台新建的 API Key。模型名可填写 deepseek-r1 等具体模型标识。
Smart Mermaid 需要的是“把中文描述直接转换成 Mermaid 语法”,而不是让模型先输出一大段分析过程。因此,模型建议优先选择不带思维链的普通对话模型。若使用带思维链或强推理展示的模型,可能会出现以下问题:
选型时可以优先考虑这些标准:
在模型选型阶段,可以通过大模型 API 服务平台对比不同模型的性能与价格,选择与 Smart Mermaid 这类“格式转换”任务更匹配的模型。
检查 AI_API_URL、AI_MODEL_NAME、AI_API_KEY 是否为空,并确认容器是否已经重启。若使用 Compose,可以执行:
docker compose up -d --force-recreate
通常是 API Key 错误、过期或没有模型调用权限。可以到模型服务商控制台重新创建密钥,并确认密钥状态正常。
检查 AI_API_URL 是否包含正确的接口路径。很多 OpenAI 兼容服务需要访问 /v1/chat/completions 或 /v2/chat/completions,具体以服务商文档为准。
先确认 NAS 容器能否访问外网。可以进入容器或宿主机测试网络连通性,再检查 DNS、代理、防火墙设置。
可尝试更换为普通对话模型,或在提示词中明确要求“只输出 Mermaid 代码,不要解释”。如果应用支持自定义 Prompt,可以加入格式约束。
检查内网穿透服务是否在线、域名解析是否正确、HTTPS 证书是否有效,以及容器端口映射是否保持一致。
如果后续你不仅使用 Smart Mermaid,还会在 NAS 上接入其他 AI 应用,可以考虑通过统一 API 网关管理多个模型服务。这样可以在一个入口中配置密钥、模型路由和调用日志,降低维护成本。在 One API 等网关工具中,也可以将百度智能云千帆配置为模型渠道,并指定模型名称。若需要进一步评估模型接入与调用管理方案,可结合词元所模型服务了解多模型统一接入与调用管理能力。
自建 Smart Mermaid 的难点不在“安装”,而在“让 AI 接口稳定输出 Mermaid”。完成飞牛 NAS Docker 部署后,重点检查三个环境变量、模型类型、网络连通性和内网穿透配置。只要接口地址、模型名和密钥正确,并选择适合格式转换的普通对话模型,就可以把 Smart Mermaid 变成一个可在局域网使用、也可安全访问的图表生成服务。