前言¶
在 DSH 裏讓智能體操作 NAS，常見做法是自建 REST 封裝或手寫腳本。TrueNAS 自 25.04 起棄用 REST，27 版本起移除；當前應走版本化的 JSON-RPC 2.0 WebSocket API（/api/current）。本文介紹社區插件 dsh-truenas（維護者 Taoidle，分類：聯網工具）：把一臺或多臺 TrueNAS 的配置與 API 密鑰納入 DSH 工具鏈，供智能體與設置頁共用，不依賴額外運行時服務。
這是什麼¶
TrueNAS manager for DSH（包名 dsh-truenas，當前資料記載版本 0.10.0，MIT 許可證）是 DeepSeek Harness 插件。它通過 WebSocket 直連 NAS：在新版本上用 auth.login_ex 與 API_KEY_PLAIN 機制，舊版本回退到 auth.login_with_api_key。README 寫明除 @deepseek-ai/schemastery 外無額外運行時依賴。
核心功能¶
多實例與憑證¶
- 設置頁 Settings → TrueNAS（也可從側欄 Plugins → TrueNAS manager → Included parts → Configure 進入）爲每個 NAS 提供地址、用戶、API 密鑰與 TLS 選項。
- 密鑰在寫入 DSH 憑證庫前會先向 NAS 校驗，避免 typo 留下半配置實例。
- 配置頁與工具
truenas_instances管理同一列表；未指定instance時默認使用列表第一項，Make default 可將某臺移到首位。 - API 密鑰不寫入 JSON 配置，而是按實例名派生憑證名（例如
lab-nas→TRUENAS_APIKEY_LAB_NAS）。
全局配置結構示例（資料原文）：
{
"instances": [
{ "name": "lab-nas", "url": "https://nas.lab.local", "username": "root", "insecureTls": true },
{ "name": "backup-nas", "url": "https://10.0.0.9", "username": "admin" }
],
"timeoutMs": 60000,
"jobTimeoutMs": 600000
}
傳輸與安全¶
插件拒絕 http:// / ws:// 地址再發送密鑰：TrueNAS 在非加密連接上展示 API 密鑰會立即吊銷。insecureTls（頁面上的 Skip TLS certificate verification）僅對該實例關閉證書校驗，連接仍須 TLS；自籤場景更推薦信任 NAS 證書或使用 CA 簽發證書。
側欄概覽面板¶
安裝 Better Sidebar 後，本 bundle 在右側欄增加 TrueNAS overview 標籤：多實例時用下拉切換。面板通過同源路由 GET /dsh-truenas/panel、GET /dsh-truenas/panel/stream（SSE）、POST /dsh-truenas/panel/action 與 NAS 通信，瀏覽器不直連 NAS；標籤不可見時不刷新。流每 2.5 秒推送快照，無 EventSource 或斷流時回退爲每 6 秒輪詢。
面板覆蓋 CPU/內存/池健康、快照一鍵創建、服務啓停與開機項、應用與磁盤自檢、證書倒計時、複製與雲同步狀態、告警消除、作業進度與中止等；部分區塊按各自節奏緩存以降低負載。
智能體工具集¶
README 列出面向智能體的工具（節選）：
| 工具 | 用途 |
|---|---|
truenas_instances |
列出 / 增刪改 / 測試已配置實例 |
truenas_system |
版本與硬件、告警、服務、引導環境、更新、SSH、可調項等 |
truenas_storage |
池、數據集、創建刪除數據集、scrub |
truenas_snapshots |
快照列出、創建、刪除、回滾、克隆 |
truenas_shares |
SMB/NFS 共享管理 |
truenas_apps |
TrueNAS Apps / Docker 相關操作 |
truenas_jobs |
作業查詢、等待、中止 |
truenas_network |
接口、路由、主機名與 DNS 等 |
truenas_users |
用戶組、ACL、權限、API 密鑰 |
truenas_replication |
複製任務 |
truenas_cloud |
雲同步與雲備份任務 |
truenas_alerts |
當前告警（含 dismiss） |
資料在表格處截斷，完整列表以倉庫 README 爲準。
安裝與啓用¶
在具備 Node 與 npm 的環境中，按 README 準備插件目錄：
git clone https://github.com/Taoidle/dsh-truenas.git
cd dsh-truenas
npm install
在 DSH 會話中安裝 bundle（路徑須爲絕對路徑）：
plugin_manager action=install_bundle target=/absolute/path/to/dsh-truenas
重新加載 DSH Web UI 後，側欄 Plugins 中出現 TrueNAS manager。
典型用法¶
用工具添加實例¶
與設置頁等價的一種寫法：
truenas_instances action="add" name="lab-nas" url="https://nas.lab.local" apiKey="1-xxxxxxxx" insecureTls=true
配置多 NAS¶
可同時管理多臺；刪除實例需二次確認並會刪除對應存儲的密鑰。
適用場景與注意¶
適合誰：已在用 DSH 編排智能體、且需要對話或自動化裏操作 ZFS 池、快照、共享、Apps、複製與雲任務等的運維或 homelab 用戶。
權限與審閱：插件以當前 DSH 進程權限運行，工具調用等同你對 NAS 的管理能力。安裝前請閱讀 GitHub 倉庫 源碼與 MIT 許可證，確認實例 URL 與 API 密鑰來源可信。
生態說明：DSH 奉行「一切皆插件」；SkillHub 目錄頁 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-truenas 把 TrueNAS 的 WebSocket JSON-RPC 封成 DSH 工具與設置頁，順應 REST 退場後的官方 API 方向，並可選配合 Better Sidebar 做只讀/輕量操控面板。進一步瞭解可從目錄頁與 GitHub 進入：
