【Fnos-a_pex-mcp-bridge · 体验篇】这个周末，让你的飞牛NAS学会"听话"

注：因平台内容策略，本文中 a_pex 指代项目名称中的 a p e x，项目全称为 fnos-a_pex_mcp_bridge，下同。

提示：帖子比较长。没耐心的话，转发给你的 AI 智能体，让它帮你读。
再次提示：虽然看起来长，感觉比较复杂，其实很简单，是我比较啰嗦，无非就是 ，跑docker ，安装插件 ，烧录硬件 ，然后用智能体控制它。

1.1 这篇帖子是干什么的？

📖 前置阅读：

• 引入篇：当你的飞牛NAS学会"听话"——不只是存储，更是你的全域智能中枢
• 知识篇：Fnos-a_pex-mcp-bridge · 智能时代的火种正在燎原

这篇是要你亲手干的。
体验目标，就是把我之前引入篇的功能，实现。简单地说，在传统音响上，播放飞牛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 你需要准备什么硬件？

博主的环境

🖼️ 硬件**刑具
**
**

硬件要求：上述所有硬件功能正常。ESP32-S3 必须能通过 USB 被电脑识别并烧录。飞牛NAS 已正常联网，Docker 功能已开启。

1.3 你需要准备什么软件？

不需要装 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

端口说明

⚠️ 如果你的飞牛NAS开启了防火墙，请放行以上两个端口。

3.1.1 Docker 可视化部署

不需要记命令行。飞牛NAS 的 Docker 管理界面全部是图形化的，点按钮就行。

🎬 占位：Docker 可视化部署视频演示链接

大致流程：Docker → 项目 → 新建项目 → 填入以下 docker-compose 内容 → 启动。

下面的配置，里面被打码。

下载链接也可以

附件：docker-compose.zip

****直接复制不行 ****，里面有 a_pex 被 ** 替换了， 需要 将 ** 还原成 a_pex 去掉下划线。

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 里。它做五件事：

3.1.5 系统功能简介

一句话说清楚这个系统在做什么：

让授权过的智能体，通过 MCP 协议，安全地调用你 NAS 上的服务和局域网里的设备。

围绕这个目标，系统的配置逻辑很简单——五步走：

1. 配置谁：创建用户 → 用户管理
2. 配置有什么事：装插件（NAS 服务 → MCP 工具）+ 注册设备（IoT 硬件 → MCP 工具） → 插件管理 / 设备管理
3. 配置授权：给智能体发令牌，绑权限 → MCP 令牌管理 / MCP 权限管理
4. 提供 MCP：智能体接入 → MCP 端点
5. 审计：谁在什么时候调了什么，干了什么，全部可查 → 审计中心

所以系统内置了以下功能模块：

审计中心

管理后台

🖼️ ：Web 管理后台截图

🎬 占位：系统功能演示视频——审计中心 + 管理后台全览

3.2 插件下载与安装

3.2.1 插件仓库

插件就是把 NAS 某个服务翻译成 MCP 工具的模块。装了 SMB 文件插件 = 智能体能浏览你的 NAS 文件。

3.2.2 安装步骤

不需要命令行。三步搞定：

1. 打开上面的仓库链接，找到你需要的插件文件夹（如 smb-file-plugin）
2. 下载整个文件夹
3. 上传到你的插件目录（Docker 中 ./data/service-plugins/ 对应的宿主机路径）

📂 插件目录位置：在你放 docker-compose.yml 的目录下，./data/service-plugins/。往里面丢文件夹即可，系统会自动识别。

🎬 占位：插件下载 + 上传操作视频演示

🖼️ ：插件上传到目录后的截图

3.2.3 配置插件

插件文件夹上传后，进入 Web 管理后台 → 插件管理，你会看到已上传的插件。点击配置，填入插件所需的参数（如 SMB 路径、用户名、密码等）。

🎬 占位：插件配置演示视频

🖼️ 插件配置页面截图

配置完成后，插件即时生效，对应的 MCP 工具立刻可用。

3.3 硬件固件下载与烧录

这里是重头戏。我们要做一块能被 AI 智能体控制的 ESP32 硬件。

3.3.1 下载固件项目

克隆到本地：

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 示意图优先，实物图后续补）：

🖼️ 占位：Fritzing 接线示意图（ESP32-S3 + PM5102 引脚连线），标清楚每根线接哪个脚

🖼️ 占位：焊接完成后的实物图——正面 + 背面各一张

🔥 这条线你要是接反了，板子冒烟别找我。 先看图，再动手。不懂就问，别硬来。

3.3.5 上电配网

接好线、烧录完固件后，给设备通电。设备首次启动会进入配网模式。

配网步骤：

1. 打开手机 WiFi 列表，找到一个以 ESP32 或 ** 开头的无线设备
2. 连接这个热点
3. 打开手机浏览器，输入 192.168.4.1
4. 进入登录界面，输入密码 **123
5. 在配置界面中输入你家的 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上周杰伦的《东风破》。"

智能体会：

1. 通过 SMB 插件 → 搜索 NAS 音乐文件夹 → 找到《东风破》
2. 通过 MQTT → 向 ESP32+PM5102 下发播放指令
3. 音响响了。

从一句话，到音乐响起。中间没有人碰过手机、没有找过遥控、没有切过信号源。

🎬 占位：一句话播放 NAS 音乐——端到端演示视频

🖼️ ：智能体对话截图——"客厅音响，播放飞牛NAS上周杰伦的《东风破》" + 音响正在播放的实拍照片

再试试：

"下一首。"
"音量调到 40%。"
"来点爵士乐。"

这就是全域联动。服务（NAS 文件）+ 设备（ESP32+音响）+ 智能体（大脑）= 你只负责说。

如果你做到了这里——恭喜。你已经完成了一整套"服务 + 设备 + 智能体"的全域联动闭环。

4 常见问题排查

🔗 占位：详细排查文档链接（如有）

5 体验完了，然后呢？

刚才你做了这些事：

1. 在飞牛NAS上部署了 fnos-a_pex_mcp_bridge
2. 装了插件，NAS 文件服务变成了 MCP 工具
3. 烧录了一块 ESP32 硬件，注册为 MCP 设备
4. 智能体连上了 Bridge，一句话读了文件、控了设备

你现在已经具备了"部署智能体场景内全域服务设备联动"的能力。

接下来你可以：

最后

回顾一下知识篇那句话——

"你手上的飞牛NAS，就是第一根火柴。fnos-a_pex-mcp_bridge，就是打火石。MCP协议，就是那阵风。"

如果你跟到了这里，亲自部署完了、验证过了、智能体控起来了——你已经划亮了这根火柴。

接下来怎么烧、烧多大、烧给谁看——是你的事。

社区评论区，等着你的体验反馈。踩了坑的、跑通的、觉得某一步可以优化的——尽管说。

项目代号：FnOS-a_pex-Mcp-Bridge

技术路线：Rust + MCP + Docker @ 飞牛NAS

体验环境：树莓派 4B（飞牛 ARM 系统）+ ESP32-S3 16MB + PM5102