【Fnos-a_pex-mcp-bridge · 体验篇】这个周末，让你的飞牛NAS学会"听话"
注：因平台内容策略，本文中 a_pex 指代项目名称中的 a p e x，项目全称为 fnos-a_pex_mcp_bridge，下同。
提示：帖子比较长。没耐心的话，转发给你的 AI 智能体，让它帮你读。
再次提示：虽然看起来长，感觉比较复杂，其实很简单，是我比较啰嗦，无非就是 ，跑docker ，安装插件 ，烧录硬件 ，然后用智能体控制它。
内心独白：平时博主看的屎山，最高的是一个文件 2w 行，ide都干崩了，只能用记事本看 干脆我叫屎山两万行算了。
1.1 这篇帖子是干什么的？
📖 前置阅读：
这篇是要你亲手干的。
体验目标，就是把我之前引入篇的功能，实现。简单地说，在传统音响上，播放飞牛NAS里面的音乐，让你的智能体干。
不是看我说，不是看我帖子。是去干，不复杂，你干了，你才有资格评价这个帖子，如果有人在帖子下留言之前，先拍一张，证明你干了。然后有问题，有报错，有不实，有问题，有建议，我都认
有问题 我处理，有报错，我改bug，有不实，我承认，有建议，我听从调整。
当然，成功了，也请你拍一下。让大家看到，我们是一起进步，一起折腾。
我会带你从零开始，在你的飞牛NAS上部署 fnos-a_pex_mcp_bridge，安装插件，烧录一个 ESP32 硬件设备，然后——用你的智能体，一句话联动起来，当然芯片和模块如果碰巧你没有，你可以先体验智能体获取服务的能力，验证授权，如果你有，那太好了，不用我费劲说怎么烧录了。
体验完之后，你将具备什么能力？
- 你会在飞牛NAS上部署一个标准的 MCP Server
- 你会把 NAS 服务封装为智能体可调用的 MCP 工具 而且不止于NAS ，你的服务器，你的数据库，你的网络打印机，你能想象到的任何网络服务。
- 你会做出一块能被 AI 智能体控制的物联网硬件，不止于音响，还能控制灯、开关、电机等。你没思路，后期我会写，怎么控狗，怎么控人，怎么改造老旧物联网设备。
- 你会把本地场景里的服务和设备全部打通
这些能力值多少钱？ ——别问我，问你的智能体。把这段话说给它听：
"我刚刚在飞牛NAS上部署了一个 MCP Bridge，把NAS文件服务和一块ESP32硬件都接入了，任何支持MCP的智能体都能调度。这个能力有什么商业价值？能怎么变现？"
听听它怎么回答。答案可能会让你意外。
在开始之前，先理解一个核心概念：约束式生成
你以为后面提到的"智能体帮你写代码"是 AI 从零瞎编？
不是。AI 是在框架模板的规则和约束下，按需生成。 这套模板已经帮你写好了 MCP 接入层、MQTT 通信层、所有底层逻辑。你不需要懂。你只需要对着模板说需求。
- 硬件开发：ESP-IDF 环境配好一次，以后想做智能灯、智能电机，把模板丢给智能体，说一句"GPIO4 改 GPIO5，加 PWM 调光"——固件生成，硬件开发变配置化。
- 插件开发：把
smb-file-plugin 文件夹复制一份，丢给智能体说"改成 WebDAV 协议"——几秒钟新插件诞生，后端开发也变配置化。
人人都是嵌入式工程师。人人都是后端开发者。框架约束 + 智能体生成 = 你只需要描述需求。
记住这个概念，后面每一步你就不会觉得"这人是不是在吹牛"了。
1.2 你需要准备什么硬件？
博主的环境
| 硬件 |
型号 |
备注 |
| 飞牛NAS |
树莓派 4B，飞牛 ARM 系统 |
你用 x86 飞牛NAS 也一样 |
| 开发板 |
ESP32-S3 16MB Flash |
必须 16MB，8MB 可能不够 或者 多场景利用 |
| 音源输出模块 |
PM5102 |
用于输出传统音响接收的音频 音频孔 aux 的那个 |
| 线束 |
杜邦线若干 |
连接模块用 |
| 焊接工具 |
电烙铁、焊丝、电烙铁架 |
把模块焊到EPS32-S3上 |
🖼️ 硬件**刑具
**
**
硬件要求：上述所有硬件功能正常。ESP32-S3 必须能通过 USB 被电脑识别并烧录。飞牛NAS 已正常联网，Docker 功能已开启。
1.3 你需要准备什么软件？
| 软件 |
用途 |
获取方式 |
| 一些未加密的歌曲 |
用来放啊，没歌怎么放，加密了怎么放 |
见 2.1 目录 |
| 插件文件夹 |
下载下来插件文件夹，然后放到项目绑定的插件文件夹，就有了插件功能 |
见 2.1 目录 |
| 硬件固件项目 |
ESP32-S3 设备固件，烧录后，通电，配网，系统操作接入 |
见 2.1 目录 |
不需要装 IDE、不需要配开发环境、不需要学嵌入式——你的智能体会帮你处理代码。
上面这句话存疑，我不信智能体还能把bin程序 直接烧录？
2.1 目录 · 快速跳转
帖子较长，按需跳转：
3.0 前置准备：飞牛NAS 环境准备
我们的目标：让智能体播放 NAS 上的音乐。 所以第一步，先把音乐准备好。
① 创建 everyone 用户
在飞牛NAS 控制面板 → 用户管理 → 新建用户，创建一个名为 everyone 的普通用户，设置好密码。这个用户将用于 SMB 共享访问。
🖼️ ：创建 everyone 用户截图
② 准备音乐文件夹
在 NAS 存储空间中创建一个 音乐 文件夹，放入一些未加密的音乐文件（MP3、FLAC 等）。
③ 共享文件夹
将 音乐 文件夹通过 SMB 共享，授权 everyone 用户读取权限。
🖼️ SMB 共享设置截图
完成后，你的飞牛NAS 已经有了一个可供智能体访问的音乐共享目录。
上面是智能体生成的。如果这个不会，回飞牛NAS 论坛 人道毁灭。 关键是知道 放哪个文件夹 ，哪个用户，密码是什么，因为飞牛好像不支持everyone 匿名角色，所以 ，设置一个 匿名角色 。
🎬 占位：博主演示视频——创建 everyone 用户 + 音乐文件夹 + SMB 共享全过程
3.1 项目部署：Docker 部署 fnos-a_pex_mcp_bridge
端口说明
| 端口 |
用途 |
备注 |
1883 |
标准 MQTT 端口 |
设备通过 MQTT 接入 Bridge |
8018 |
项目运行端口 |
Web 管理后台 + MCP 端点 |
⚠️ 如果你的飞牛NAS开启了防火墙，请放行以上两个端口。
3.1.1 Docker 可视化部署
不需要记命令行。飞牛NAS 的 Docker 管理界面全部是图形化的，点按钮就行。
🎬 占位：Docker 可视化部署视频演示链接
大致流程：Docker → 项目 → 新建项目 → 填入以下 docker-compose 内容 → 启动。
services:
**-mcp-bridge:
image: crpi-qlruqqugcjs2bo3w.cn-shanghai.personal.cr.aliyuncs.com/**_mcp_bridge/server:latest
container_name: **-mcp-bridge
hostname: **-mcp-bridge
restart: unless-stopped
ports:
- "${SERVER_PORT:-8018}:${SERVER_PORT:-8018}"
depends_on:
mariadb:
condition: service_healthy
environment:
- SERVER_PORT=${SERVER_PORT:-8018}
- DATABASE_URL=mysql://${MARIADB_USER:-**_remote}:${MARIADB_PASSWORD:-**1234}@mariadb:3306/**_db
- JWT_SECRET=${JWT_SECRET:-}
- RUNNING_IN_DOCKER=true
- HOST_HOSTNAME=${HOSTNAME:-}
volumes:
- ./data/logs:/app/logs
- ./data/uploads:/app/uploads
- ./data/service-plugins:/app/service_plugins
- ./data/plugins-venv:/app/.plugins-venv
mariadb:
image: mariadb:11
container_name: **-mcp-bridge-mariadb
restart: unless-stopped
environment:
MARIADB_ROOT_PASSWORD: ${MARIADB_ROOT_PASSWORD:-**1234}
MARIADB_DATABASE: **_db
MARIADB_USER: ${MARIADB_USER:-**_remote}
MARIADB_PASSWORD: ${MARIADB_PASSWORD:-**1234}
MARIADB_ROOT_HOST: '%'
MARIADB_CHARACTER_SET: utf8mb4
MARIADB_COLLATE: utf8mb4_unicode_ci
volumes:
- ./data/mariadb:/var/lib/mysql
healthcheck:
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
interval: 10s
timeout: 5s
retries: 3
start_period: 15s
📋 复制粘贴到飞牛 Docker 的项目配置里，直接启动即可。不用改任何一行——环境变量都有默认值。
⚠️ 安全提示：默认数据库密码 **1234 仅用于体验部署。局域网环境下够用，如果你打算长期使用或未来希望到暴露公网，请务必修改 MARIADB_ROOT_PASSWORD 和 MARIADB_PASSWORD 为强密码。
🖼️ Docker 部署操作截图 ×2
等几十秒，容器拉取镜像、启动完成。
3.1.2 确认跑起来了
在 Docker 容器列表中，看到容器状态为"运行中"，说明部署成功。
3.1.3 部署后参数设置
部署完成后，在飞牛 Docker 管理界面找到 **-mcp-bridge 项目，编辑环境变量：
① 核心设置 — HOST_HOSTNAME
将 HOST_HOSTNAME 环境变量的值改为你的飞牛NAS的局域网 IP 地址（如 192.168.1.100）。这个参数影响智能体回调地址和设备注册路由。
🖼️ Docker 环境变量配置截图（HOST_HOSTNAME）
② 端口确认
确认 在docker 端口设置中 宿主MQTT 端口（1883）和容器端口（1883）已正确映射。
确认 在docker 端口设置中 宿主8018 端口（8018）和容器端口（8018）已正确映射。
最后再提醒一下 ，有防火墙的记得腿收一下。
🖼️ Docker 端口映射配置截图
3.1.4 项目是什么？
fnos-a_pex_mcp_bridge 是一个标准的 MCP Server，跑在你的飞牛NAS Docker 里。它做五件事：
| 能力 |
说明 |
| 协议翻译 |
把 NAS 的 SMB/NFS 方言、设备的 MQTT 方言 → 翻译成 MCP 普通话 |
| 工具收敛 |
不管你有多少个服务和设备，智能体只看到 1 个 MCP 入口 |
| 五重安全 |
令牌鉴权 + 权限校验 + 时效校验 + 防绕过检测 + 频率限制 |
| 插件扩展 |
SMB 文件管理、MQTT 设备接入……插件化，按需安装。目前我只提供了一个 SMB MIT文件管理插件，这个是种子插件，其他插件都可以基于这个插件扩展，拷贝给你的智能体，先让它看下项目结构，然后一句话说你的需求 |
| 硬件框架 |
提供消费级芯片（ESP32-S3、ESP32-C3 未来持续扩展芯片架构，支持更多芯片）的MIT开源模板框架。利用框架的规则和约束，智能体可以按你的需求快速生成物联网设备固件，也能对传统物联网芯片设备进行改造兼容 |
3.1.5 系统功能简介
一句话说清楚这个系统在做什么：
让授权过的智能体，通过 MCP 协议，安全地调用你 NAS 上的服务和局域网里的设备。
围绕这个目标，系统的配置逻辑很简单——五步走：
- 配置谁：创建用户 → 用户管理
- 配置有什么事：装插件（NAS 服务 → MCP 工具）+ 注册设备（IoT 硬件 → MCP 工具） → 插件管理 / 设备管理
- 配置授权：给智能体发令牌，绑权限 → MCP 令牌管理 / MCP 权限管理
- 提供 MCP：智能体接入 → MCP 端点
- 审计：谁在什么时候调了什么，干了什么，全部可查 → 审计中心
所以系统内置了以下功能模块：
审计中心
| 功能 |
说明 |
| 审计统计 |
操作次数、设备调用频率、令牌使用情况可视化 |
| 操作审计 |
每次智能体调用了什么工具、参数是什么、结果如何 |
| 授权审计 |
令牌创建/变更/失效的完整记录 |
| 令牌审计 |
各令牌的使用频率、来源 IP、异常行为标记 |
管理后台
| 功能 |
说明 |
| 用户管理 |
创建/禁用/删除可访问系统的用户 |
| 设备管理 |
查看已注册的 IoT 设备、设备状态（在线/离线）、设备能力列表 |
| 插件管理 |
安装/卸载/启用/禁用插件，每个插件对应一组 MCP 工具 |
| MCP 权限管理 |
将具体工具/设备绑定到令牌，细粒度控制"谁能干什么" |
| MCP 令牌管理 |
创建/续期/作废智能体访问令牌 |
| 系统设置 |
基础配置（端口、日志级别、HOST_HOSTNAME 等） |
🖼️ ：Web 管理后台截图
🎬 占位：系统功能演示视频——审计中心 + 管理后台全览
3.2 插件下载与安装
3.2.1 插件仓库
插件就是把 NAS 某个服务翻译成 MCP 工具的模块。装了 SMB 文件插件 = 智能体能浏览你的 NAS 文件。
| 线路 |
地址 |
| 国内（Gitee） |
https://gitee.com/freen/**-mcp-service-plugins |
| 国外（GitHub） |
https://github.com/**-freen/**-mcp-service-plugins |
3.2.2 安装步骤
不需要命令行。三步搞定：
- 打开上面的仓库链接，找到你需要的插件文件夹（如
smb-file-plugin）
- 下载整个文件夹
- 上传到你的插件目录（Docker 中
./data/service-plugins/ 对应的宿主机路径）
📂 插件目录位置：在你放 docker-compose.yml 的目录下，./data/service-plugins/。往里面丢文件夹即可，系统会自动识别。
🎬 占位：插件下载 + 上传操作视频演示
🖼️ ：插件上传到目录后的截图
3.2.3 配置插件
插件文件夹上传后，进入 Web 管理后台 → 插件管理，你会看到已上传的插件。点击配置，填入插件所需的参数（如 SMB 路径、用户名、密码等）。
🎬 占位：插件配置演示视频
🖼️ 插件配置页面截图
配置完成后，插件即时生效，对应的 MCP 工具立刻可用。
3.3 硬件固件下载与烧录
这里是重头戏。我们要做一块能被 AI 智能体控制的 ESP32 硬件。
3.3.1 下载固件项目
| 线路 |
地址 |
| 国内（Gitee） |
https://gitee.com/freen/**-mcp-esp32-s3-v6 |
| 国外（GitHub） |
https://github.com/**-freen/**-mcp-esp32-s3-v6 |
克隆到本地：
git clone https://gitee.com/freen/**-mcp-esp32-s3-v6.git
cd **-mcp-esp32-s3-v6
3.3.2 用智能体生成/修改固件
这就是精髓所在——你不用写一行嵌入式代码。
打开你的智能体（TRAE / WorkBuddy / Claude Code），把项目里的框架模板文件喂给它，然后说：
"按照这个框架模板的约束，帮我生成 ESP32-S3 固件：暴露 device_info() 和 device_ping() 两个 MCP 工具。MQTT Broker 地址是 mqtt://你的NAS_IP:1883，设备名称叫 我的第一块AI硬件。"
你的智能体会按照模板的约束自动生成代码。 你只需要复制、编译、烧录。
3.3.3 编译烧录
本项目基于 ESP-IDF v6.0 框架，固件代码也是 v6.0 版本。
🎬 占位：ESP-IDF v6.0 编译烧录演示视频
关键参数：
- 框架：ESP-IDF v6.0
- 芯片：ESP32-S3
- Flash：16MB
- 端口：选择你电脑识别到的 USB 串口
🖼️ 编译成功 + 烧录完成截图
3.3.4 硬件接线 啊，后续补充
⚠️ 焊接前请断开所有电源。接错线会烧板子，认真看。
PM5102 引脚对照（Fritzing 示意图优先，实物图后续补）：
| ESP32-S3 引脚 |
PM5102 引脚 |
说明 |
占位 |
占位 |
占位：具体引脚对照待博主确认后填入 |
🖼️ 占位：Fritzing 接线示意图（ESP32-S3 + PM5102 引脚连线），标清楚每根线接哪个脚
🖼️ 占位：焊接完成后的实物图——正面 + 背面各一张
🔥 这条线你要是接反了，板子冒烟别找我。 先看图，再动手。不懂就问，别硬来。
3.3.5 上电配网
接好线、烧录完固件后，给设备通电。设备首次启动会进入配网模式。
配网步骤：
- 打开手机 WiFi 列表，找到一个以
ESP32 或 ** 开头的无线设备
- 连接这个热点
- 打开手机浏览器，输入
192.168.4.1
- 进入登录界面，输入密码
**123
- 在配置界面中输入你家的 WiFi 名称和密码，还有你的飞牛IP地址，或者hostname，保存
🖼️ ：配网登录界面截图（192.168.4.1 登录页）
🖼️ ：配网配置界面截图——标注重要配置项：WiFi SSID、WiFi 密码、MQTT Broker 地址
为什么不能自动连？为什么需要密码？
① 防设备被盗用：如果设备被偷，没有配网密码，偷走的人用不了——它还是你的。至少它不会那么容易改姓。
② 防恶意设备冒充：如果任何设备都能自动接入你的 MQTT Broker，坏人拿块芯片就能冒充你的设备、渗透你的局域网。手动配网加密码，是在物理世界入口处就拦住。
🎬 占位：设备上电配网演示视频
配网完成后，设备会自动通过 MQTT 注册到你的 fnos-a_pex_mcp_bridge。
🎬 占位：已入网设备的配置页面演示视频
3.3.6 约束式生成
这就是开篇说的"框架模板 + 智能体生成"。忘了的话，翻回帖子最前面看那个引用块。
3.4 验证：冒烟测试
确认 Bridge 正常
在浏览器打开 http://你的NAS_IP:8018，看到管理后台首页。
确认插件可用
在后台"工具列表"中，看到已安装插件对应的 MCP 工具。
🖼️ ：工具列表截图
确认设备在线
在后台"设备列表"中，看到你的 ESP32 设备，状态为"在线"。
🖼️ 设备列表截图，显示 ESP32 在线
3.5 将 fnos-a_pex_mcp_bridge 添加到你的智能体
获取令牌
在 Web 管理后台 → "令牌管理" → "创建令牌"，复制令牌值。
🖼️ 令牌创建页面截图
添加 MCP Server
根据你使用的智能体客户端：
TRAE：
{
"mcpServers": {
"fnos-**-bridge": {
"url": "http://你的NAS_IP:8018/mcp",
"headers": {
"Authorization": "Bearer 你的令牌"
}
}
}
}
🔗 占位：WorkBuddy / Claude Code / Codex 各自配置方法链接
配置完成后，刷新智能体的 MCP 连接。你应该能在工具列表中看到 NAS 文件浏览、设备控制等工具。
🖼️ 智能体工具列表截图（显示 fnos-a_pex-mcp_bridge 的工具）
3.6 第一个场景：让智能体读你的 NAS 文件
对你的智能体说：
"帮我看看飞牛NAS上有什么文件。"
智能体会调用 nas_file_list 工具，返回你的 NAS 共享目录下的文件列表。
🖼️ ：智能体返回文件列表的对话截图
试试更进一步：
"NAS 上有没有周杰伦的歌？"
"帮我找一下上个月的合同文件。"
"NAS 还剩多少空间？"
3.7 第二个场景：用智能体控制你的 ESP32 设备
对你的智能体说：
"查一下我的第一块 AI 硬件的信息。"
智能体会调用 device_info() 工具，返回设备的型号、状态、上线时间。
🖼️ ：智能体返回设备信息的对话截图
再来一个：
"ping 一下我的第一块 AI 硬件。"
智能体调用 device_ping()，设备回复，确认通路正常。
🖼️ ：智能体 ping 设备的对话截图
3.8 第三个场景：让你的传统音响响起来
还记得最初的目标吗？——"让智能体播放 NAS 上的音乐。"
前面文件能读了，设备能控了。现在，该让它们联动起来。
⚠️ 前提：ESP32-S3 + PM5102 已正确接线，传统音响的 AUX 线已插入 PM5102 的音频口。
对你的智能体说：
"客厅音响，播放飞牛NAS上周杰伦的《东风破》。"
智能体会：
- 通过 SMB 插件 → 搜索 NAS 音乐文件夹 → 找到《东风破》
- 通过 MQTT → 向 ESP32+PM5102 下发播放指令
- 音响响了。
从一句话，到音乐响起。中间没有人碰过手机、没有找过遥控、没有切过信号源。
🎬 占位：一句话播放 NAS 音乐——端到端演示视频
🖼️ ：智能体对话截图——"客厅音响，播放飞牛NAS上周杰伦的《东风破》" + 音响正在播放的实拍照片
再试试：
"下一首。"
"音量调到 40%。"
"来点爵士乐。"
这就是全域联动。服务（NAS 文件）+ 设备（ESP32+音响）+ 智能体（大脑）= 你只负责说。
如果你做到了这里——恭喜。你已经完成了一整套"服务 + 设备 + 智能体"的全域联动闭环。
4 常见问题排查
| 问题 |
可能原因 |
解决方向 |
| Docker 容器启动失败 |
端口冲突 |
修改 docker-compose.yml 端口映射 |
| 插件工具不显示 |
配置文件有误 |
检查 SMB 路径和认证信息 |
| ESP32 烧录失败 |
驱动未装 / 端口选错 |
安装 CH340/CP2102 驱动，检查串口号 |
| 设备离线 |
MQTT Broker 地址配错 / WiFi 没连上 |
检查固件中的 MQTT 地址和 WiFi 配置 |
| 智能体看不到工具 |
令牌未配置 / URL 不对 / 网络不通 |
确认智能体所在设备能访问 NAS 的 IP |
| 智能体调用报错 |
权限不足 |
在后台给令牌分配对应工具的权限 |
🔗 占位：详细排查文档链接（如有）
5 体验完了，然后呢？
刚才你做了这些事：
- 在飞牛NAS上部署了 fnos-a_pex_mcp_bridge
- 装了插件，NAS 文件服务变成了 MCP 工具
- 烧录了一块 ESP32 硬件，注册为 MCP 设备
- 智能体连上了 Bridge，一句话读了文件、控了设备
你现在已经具备了"部署智能体场景内全域服务设备联动"的能力。
接下来你可以：
| 方向 |
做什么 |
参考 |
| 更多插件 |
对接数据库、打印机、下载服务…… |
[占位：插件开发指南链接] |
| 更多设备 |
做灯、做传感器、做音响控制…… |
[占位：硬件开发指南链接] |
| 场景联动 |
"回家自动开灯放音乐"、"会议室一键准备"…… |
[占位：场景编排教程链接] |
| 安全加固 |
精细化令牌权限、时效配置、频率限制调优 |
[占位：安全配置文档链接] |
| 给商家装一套 |
帮楼下咖啡馆/民宿/公司部署 |
用你刚学会的流程，一模一样 |
| 做出你的硬件产品 |
把你的创意做成实物，通过框架模板让智能体生成固件 |
[占位：框架模板使用指南链接] |
最后
回顾一下知识篇那句话——
"你手上的飞牛NAS，就是第一根火柴。fnos-a_pex-mcp_bridge，就是打火石。MCP协议，就是那阵风。"
如果你跟到了这里，亲自部署完了、验证过了、智能体控起来了——你已经划亮了这根火柴。
接下来怎么烧、烧多大、烧给谁看——是你的事。
社区评论区，等着你的体验反馈。踩了坑的、跑通的、觉得某一步可以优化的——尽管说。
项目代号：FnOS-a_pex-Mcp-Bridge
技术路线：Rust + MCP + Docker @ 飞牛NAS
体验环境：树莓派 4B（飞牛 ARM 系统）+ ESP32-S3 16MB + PM5102
