# 智能NAS系统

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

---

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

```{image} images/image_GHKwbOfzRoI6z4xEI5nclvVcnBh.webp
:width: 1374px
:height: 800px
```

# 开发资源汇总

## 开发配件清单

```{note}
```

| <div style="text-align: center"><br><strong>配件名称</strong><br></div> | <div style="text-align: center"><br><strong>数量</strong><br></div> | <div style="text-align: center"><br><strong>规格参数</strong><br></div> |
| --- | --- | --- |
| Quectel Pi H1智能主控板 | <div style="text-align: center"><br>1块<br></div> | <div style="text-align: center"><br>-<br></div> |
| USB-C电源线充电器 | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br><a href="https://www.waveshare.net/shop/PSU-27W-USB-C-CN-B.htm">27W USB Type-C接口充电器1.2米线长中规电源PD电源适用于树莓派5代</a><br></div> |
| Micro HDMI线 | <div style="text-align: center"><br>1根<br></div> | <div style="text-align: center"><br>规格：Micro HDMI 2.0；线长：1m；接口：HDMI-A（公头）-HDMI-D（公头）<br></div> |
| 网线 | <div style="text-align: center"><br>1根<br></div> | <div style="text-align: center"><br>线长：1m；传输速率：千兆<br></div> |
| CPU散热风扇（可选） | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br><a href="https://www.waveshare.net/shop/Raspberry-Pi-5-Official-Active-Cooler.htm">树莓派5代官方原装散热器带导热贴</a><br></div> |
| 2PIN PH1.25接口喇叭 | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br><a href="https://www.waveshare.net/shop/8ohm-2W-Speaker-B.htm">2030腔体喇叭8Ω 2W方形喇叭高音质小体积扬声器2PIN PH1.25接口</a><br></div> |
| USB麦克风（可选） | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br><a href="https://detail.tmall.com/item.htm?ali_refid=a3_430673_1006%3A1103572855%3AH%3AOGUEKIe7UMT1buAI2jOPCA%3D%3D%3A7efc0e7c06fb19134182c0ddd0cda5ac&ali_trackid=318_7efc0e7c06fb19134182c0ddd0cda5ac&id=644888833113&loginBonus=1&mi_id=0000OmTLBkqlFFSLum0w5MKisZouCwvWW8JldamBTuSTSEg&mm_sceneid=0_0_27850903_0&priceTId=215044b517884903728806866e1139&spm=a21n57.sem.item.1&utparam=%7B%22aplus_abtest%22%3A%22e821570be433bef170bbc443bc6ac92f%22%7D&xxc=ad_ztc&sku_properties=165354720%3A6536025">标准款48kHz高采样★360°全指向拾音</a><br></div> |
| 显示屏 | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br>24英寸HDMI显示器<br></div> |

## 配件实物参考

```{image} images/image_LMNZbvLFWo5phoxzEYCczMkRnue.webp
:width: 1033px
:height: 659px
:align: center
```

# 快速上手

## 开发准备

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

## 硬件连接

```{image} images/image_SbJKbF14qoirt4xsc5Tc6jbvnMf.webp
:width: 796px
:height: 456px
```

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克隆项目代码。

```bash
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. 在智能主控板的终端下依次执行下面命令，终端显示安装完成则说明部署完成。

```bash
cd ~/NAS-Demo
bash install.sh 
```

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

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

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

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

- Model ID 默认 `deepseek-chat`

常见提供商参数：

```plaintext
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`），执行下面命令立即生效：

```bash
./oc.sh model-apply
```

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

```bash
sudo systemctl restart voice-bridge
```

3. 打开 CasaOS控制台

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

```bash
bash ./oc.sh casaos-url
```

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

4. 打开 OpenClaw 控制台并配对

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

```{image} images/image_AYRVb1Nhxo4xOdxyg4wcEQIfnbg.webp
:width: 1377px
:height: 792px
:align: center
```

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

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

```{image} images/image_OJl5b1zKVoRcBIx0SHpcKj0wnQe.webp
:width: 890px
:height: 367px
:align: center
```

```{image} images/image_CXzObRieroiYuDx7ICxcAnT0nVb.webp
:width: 880px
:height: 195px
:align: center
```

5. 登录 Immich 相册

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

```{image} images/image_G5N1b8U9poK8CzxM1bbc56fenbb.webp
:width: 1374px
:height: 805px
:align: center
```

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

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

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

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

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

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

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

6. 首次配置 Jellyfin

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

```{image} images/image_F2bKbd566ouPClxZr0ecvQGynVg.webp
:width: 1374px
:height: 800px
```

首次向导步骤：

- 选择语言，继续下一步

- 创建管理员账号和密码

- 添加媒体库：  
    - 类型「电影」→文件夹路径填 `/media/Movies`  
    - 类型「节目」→ 文件夹路径填 `/media/TV Shows`  
    - 若选择器里只能看到 `/media`、点不开子目录，回到终端执行 `./oc.sh tools-media-setup`，然后点击文件夹列表上方的「刷新」重新浏览即可选择

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

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

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

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

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

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

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

7. 启用语音入口

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

验证两个入口：

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

8. 试试说一句话

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

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

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

## 日常维护

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

```bash
./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` 查看实时日志。

# 应用演示

<div class="video-preview">
  <video width="100%" controls preload="none">
    <source src="videos/video_QONobI4KToFYvHxi4UAcoeLPn1e.mp4" type="video/mp4">
    Your browser does not support the video tag.
  </video>
  <div class="video-caption">
    <strong>smart-nas-zh</strong>
  </div>
</div>


# 常见问题及解决方案

| **现象** | **处理** |
| --- | --- |
| 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://forumschinese.quectel.com/c/quectel-pi/58>) 提交技术咨询，我们的技术支持团队将及时为您解答。

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

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