智能NAS系统

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

---

智能NAS系统以CasaOS服务、OpenClaw智能体为核心，通过语音或文本下达指令，系统自动规划并调用工具，完成文件管理、相册整理、影音下载、知识问答与图片处理，带来"一句话搞定"的智能交互体验。

开发资源汇总

开发配件清单

配件名称	数量	规格参数
Quectel Pi H1智能主控板	1块	-
USB-C电源线充电器	1个	27W USB Type-C接口充电器1.2米线长中规电源PD电源适用于树莓派5代
Micro HDMI线	1根	规格：Micro HDMI 2.0；线长：1m；接口：HDMI-A（公头）-HDMI-D（公头）
网线	1根	线长：1m；传输速率：千兆
CPU散热风扇（可选）	1个	树莓派5代官方原装散热器带导热贴
2PIN PH1.25接口喇叭	1个	2030腔体喇叭8Ω 2W方形喇叭高音质小体积扬声器2PIN PH1.25接口
USB麦克风（可选）	1个	标准款48kHz高采样★360°全指向拾音
显示屏	1个	24英寸HDMI显示器

配件实物参考

快速上手

开发准备

Quectel Pi H1 智能主控板出厂默认搭载 Debian 13 系统镜像，因此无需再次烧录镜像，仅需按照如下步骤操作即可。

硬件连接

1. 显示连接：将Micro HDMI线一端接入智能主控板的Micro HDMI接口，另一端接入显示器的HDMI接口。

2. 网络连接：将网线一端接入智能主控板的千兆网口，另一端接入路由器的网口（确保路由器已联网）。

3. 输入设备连接：将USB键盘、鼠标等接入智能主控板的USB接口；若用无线输入设备，将接收器插入智能主控板的USB口即可。

4. 供电连接：将USB-A电源线的USB-A端接入电源适配器，USB-C端接入智能主控板的电源口（通常标注 POWER IN）。

5. 散热风扇连接（可选）：先将散热风扇的排线插入智能主控板的FAN插槽中，再将散热器两端固定在主控板预留插孔中。

6. 喇叭连接：将2PIN PH1.25接口的喇叭连接到智能主控板的SPK插槽中。

麦克风说明：喇叭用于 TTS 语音播报，麦克风用于唤醒与语音指令。系统默认 优先使用 USB 麦克风，USB 不可用时自动回退到 主控板板载麦克风；两者都不可用时，网页文本模式不受影响。优先级与设备名全部由 .env 控制。

项目实现

1. 在智能主控板上打开终端，使用git克隆项目代码。

sudo apt update && sudo apt install -y git
git clone https://github.com/Quectel-Pi/demo-smart-nas-system.git NAS-Demo

执行完成后，用户主目录下应生成NAS-Demo文件夹。

2. 在智能主控板的终端下依次执行下面命令，终端显示安装完成则说明部署完成。

cd ~/NAS-Demo
bash install.sh 

说明：install.sh 可重复执行（幂等），会在保留现有服务的前提下更新模型配置。

推荐用交互式安装（默认只需输入 API Key）：

• Base URL 直接回车（默认 https://api.deepseek.com/v1）

• 粘贴 API Key（输入不回显）

• Model ID 默认 deepseek-chat

常见提供商参数：

DeepSeek: base-url=https://api.deepseek.com/v1                         model-id=deepseek-v4-flash
通义千问:  base-url=https://dashscope.aliyuncs.com/compatible-mode/v1   model-id=qwen-plus
OpenAI:   base-url=https://api.openai.com/v1                           model-id=gpt-4o-mini

如果后续修改了 ~/NAS-Demo/.env 里的模型配置（例如 MODEL_BASE_URL、MODEL_API_KEY、MODEL_ID），执行下面命令立即生效：

./oc.sh model-apply

如果改的是语音桥相关环境变量，保存后再执行：

sudo systemctl restart voice-bridge

3. 打开 CasaOS控制台

在终端输入下面命令复制输出的链接到浏览器打开并注册用户：

bash ./oc.sh casaos-url

先在 CasaOS 应用页确认/配置其它应用（如 openclaw、Immich、Jellyfin、文件浏览、网页对话助手）。

4. 打开 OpenClaw 控制台并配对

在 CasaOS 上点击打开 OpenClaw 控制台。

首次可能提示自签证书风险，点“继续访问”即可；然后在终端输入下面命令进行 approve 设备配对。

./oc.sh pair-list
./oc.sh pair-approve <request_id>

5. 登录 Immich 相册

在 CasaOS 上点击打开 Immich 控制台。

• 首次打开点击 Getting Started 按页面创建管理员账号和密码（邮箱用 admin@immich.app）

• 若直接进入登录页，请使用你已创建的管理员账号密码

• 选择语言，后面使用默认配置继续下一步即可

• 在 Immich：Account Settings→ API Keys → 新建 API Key（全选） → Create

• 把密钥写入 ~/NAS-Demo/.env 文件的 IMMICH_API_KEY 字段

在终端输入下面命令注册 immich 工具，成功后会提醒 “Completed: Immich Finished”。

cd ~/NAS-Demo
./oc.sh tools-immich-setup

6. 首次配置 Jellyfin

在 CasaOS 上点击打开 Jellyfin 控制台。

首次向导步骤：

• 选择语言，继续下一步

• 创建管理员账号和密码

• 添加媒体库：

  • 类型「电影」→文件夹路径填 /media/Movies

  • 类型「节目」→ 文件夹路径填 /media/TV Shows

  • 若选择器里只能看到 /media、点不开子目录，回到终端执行 ./oc.sh tools-media-setup，然后点击文件夹列表上方的「刷新」重新浏览即可选择

• 元数据语言默认即可，完成向导

向导完成后，创建一个 API 密钥：

• 在 Jellyfin：控制台 → 高级 → API 密钥 → 新增 API 密钥

• 把生成的密钥写入 ~/NAS-Demo/.env 文件中的 JELLYFIN_API_KEY 字段

• 输入命令验证配置是否生效

cd ~/NAS-Demo
./oc.sh jellyfin-apply  # 一键校验 .env 与运行态是否一致、接口是否 401

以后 media_downloader 下载的视频放入 ~/nas_share/downloads/Movies（Jellyfin 容器内该目录挂载为 /media），Jellyfin 会自动扫描入库。

7. 启用语音入口

语音/网页对话是 默认交互入口，首次使用必须启用。

验证两个入口：

systemctl is-active voice-bridge          # 输出 active 即正常
curl -sS http://127.0.0.1:28082/healthz   # 返回 OK 即正常
journalctl -u voice-bridge -f             # 实时日志（对着麦克风用小远同学唤醒）

8. 试试说一句话

在Voice Assistant中输入文本/语音进行对话（或通过唤醒词“小远同学”唤醒进行对话）：

指令示例：
下载测试视频并播放
帮我把家庭相册的照片分类，先预览
把家庭相册下的照片加复古滤镜，先预览
住房合同在哪

说明：上述语音指令示例已在当前语音桥中验证通过；如果目录名本身是中文（例如 测试样例），英文回复中保留原始目录名属于正常现象，不代表语音识别失败。

日常维护

所有维护命令统一走 oc.sh 由 install.sh 一键安装时自动使用。执行 ./oc.sh 或 ./oc.sh help 可随时查看完整命令列表。

./oc.sh status                # 查看 openclaw 容器状态
./oc.sh logs                  # 查看 openclaw 日志（默认最近 120 行）
./oc.sh logs all 60 --level=error   # 汇总所有服务最近 60 行的错误日志
./oc.sh health                # 网关健康检查
./oc.sh url                   # 打印控制台访问地址（含 token）
./oc.sh casaos-url            # 打印 CasaOS 首页地址
./oc.sh model                 # 查看当前模型配置
./oc.sh model-apply           # 改完 .env 的模型配置后立即生效
./oc.sh deploy                # 重新部署核心服务
./oc.sh reset                 # 重置 OpenClaw 配置为出厂模板并重启
./oc.sh ui-fix                # 重新应用 CasaOS Legacy 卡片过滤
./oc.sh pair-list             # 待配对设备列表
./oc.sh pair-approve <id>     # 批准设备配对
./oc.sh mic-mode status       # 查看当前麦克风模式（.env + 运行态）
./oc.sh mic-mode usb          # 切到 USB 优先（不可用时回退板载）
./oc.sh mic-mode onboard      # 仅使用板载麦克风
./oc.sh docker-mirror         # 配置 Docker 镜像加速
./oc.sh jellyfin-apply        # 应用 Jellyfin 的 .env 配置到语音桥并校验（重启+鉴权）

语音桥是 systemd 服务，不走 ./oc.sh logs：用 journalctl -u voice-bridge -f 查看实时日志。

应用演示

smart-nas-zh

常见问题及解决方案

现象	处理
CasaOS 页面里看不到 OpenClaw/Immich/Jellyfin，或点击应用打不开	运行 ./oc.sh openclaw-app-deploy、./oc.sh immich-apply、./oc.sh jellyfin-deploy 重新注册应用入口
bash ./oc.sh casaos-url 打不开	提示“未检测到 CasaOS Web 服务”时，执行 curl -fsSL https://get.casaos.io | sudo bash 安装 CasaOS
Voice Assistant（28083）发消息报 502 / connection refused	语音桥（28082）未运行。重跑 bash install.sh 自动安装，或手动执行 cd ~/NAS-Demo/local_voice_chat && ./install_voice_bridge_service.sh
语音识别全单字/无反应	systemd 缺 PulseAudio 环境。确认 voice-bridge.service 含 LD_PRELOAD + PULSE_SERVER 后 sudo systemctl restart voice-bridge
语音桥安装报“找不到装有 numpy/sherpa_onnx 的 python3”	依赖未装：python3 -m pip install --user sherpa-onnx numpy 后重试
Voice Assistant 播放被拦（Chrome/Edge 提示 Block Audio）	浏览器自动播放策略所致，非服务故障。点击地址栏左侧锁/权限图标 → Permissions → 把 Autoplay 改成 Audio and Video
Immich 照片搜不到	后台 CLIP 任务未完成：管理界面触发 Smart Search，或 ./oc.sh immich-sync-jobs
照片分类卡死	immich-machine-learning 可能退出：sudo docker start immich-machine-learning
改了 .env 的模型配置不生效	执行 ./oc.sh model-apply（读 .env 立即应用并重启）
改了 .env 的 JELLYFIN_API_KEY 不生效 / 日志出现 Jellyfin 401	执行 ./oc.sh jellyfin-apply（会重启语音桥并校验 .env 与运行态是否一致）
安装后只有「NAS Files」成功，其它应用缺失或反复安装失败	多为拉取大镜像时被重置（日志 /var/log/casaos/app-management.log 出现 connection reset by peer）。执行 ./oc.sh docker-mirror 配置镜像加速后重新安装

技术支持与贡献

如在使用过程中遇到问题，欢迎在 移远官方论坛 提交技术咨询，我们的技术支持团队将及时为您解答。

项目开源地址： https://github.com/Quectel-Pi/demo-smart-nas-system

欢迎提交Issue反馈问题或Pull Request贡献代码改进！