truenas-skill

核心用法

TrueNAS Skill 是一款面向 TrueNAS SCALE 服务器的综合管理工具，通过官方 API 和 WebSocket 协议实现深度集成。用户可通过环境变量配置连接信息后，执行存储池健康检查、数据集管理、快照创建与复制监控、应用生命周期管理等核心操作。该技能同时支持 Dockge 容器编排平台的 Socket.IO 接口，可统一管理 Docker Compose 栈的更新与状态监控。此外，技能内置丰富的 homelab 服务参考文档，涵盖 Sonarr、Radarr、Plex、n8n 等 20+ 常见自托管服务的 API 集成模式。

显著优点

协议前瞻性：主动适配 TrueNAS API 演进，在 REST API 废弃前即提供 WebSocket 实现，确保 25.10+ 版本的兼容性。生态完整性：不仅覆盖 TrueNAS 原生功能，更延伸至周边 homelab 生态，形成从存储到媒体管理、从自动化到通知推送的完整工具链。安全透明性：所有凭据均通过环境变量注入，无硬编码风险；TLS 验证可配置，兼顾自签名证书场景与严格安全需求。运维友好性：提供标准化的健康检查清单和一键式容器更新脚本，大幅降低重复性运维负担。

潜在缺点与局限性

环境依赖较重：需要 Node.js 18+ 运行时及 curl、jq 等系统工具，对轻量级环境不够友好。来源可信度限制：作为个人开发者项目（T3），缺乏组织级背书，企业用户可能顾虑长期维护稳定性。网络配置敏感：默认跳过 TLS 验证虽便利 homelab 场景，但若用户误用于公网环境将引入中间人攻击风险。功能边界模糊：集成过多第三方服务参考文档，可能导致技能职责不够聚焦，增加认知负担。

适合的目标群体

该技能主要面向三类用户：一是运行 TrueNAS SCALE 的家庭服务器爱好者，需要自动化监控和批量运维能力；二是构建 homelab 生态的技术玩家，希望统一纳管存储、媒体、自动化等多类服务；三是具备基础 Linux/Node.js 知识的自托管实践者，能够理解和配置环境变量及网络参数。不适合无技术背景的家庭用户、需要审计合规的企业环境，以及追求极简工具链的轻量级用户。

使用风险

证书验证风险：默认 TRUENAS_VERIFY_TLS 未启用，在不可信网络中可能遭受证书欺骗攻击。权限扩散风险：API key 以环境变量形式存在，多用户共享主机时存在凭据泄露可能。版本锁定风险：TrueNAS 26.04 将完全移除 REST API，若用户未及时升级技能版本可能导致功能中断。依赖供应链风险：虽当前依赖均为官方 npm 包，但未来版本更新需持续关注 socket.io-client 和 ws 的安全公告。

核心用法

TrueNAS Skill 是一款面向家庭 NAS 管理员的多功能自动化工具，通过 TrueNAS WebSocket API 和 Dockge Socket.IO 实现对存储系统的全面管理。

主要功能模块：

| 模块 | 能力 | 典型命令 |

|------|------|---------|

| 存储管理 | 池健康检查、数据集 CRUD、ZFS 快照 | `pool.query`, `zfs.snapshot.create` |

| 应用管理 | TrueNAS Apps 状态监控、更新检查 | `app.query`, 筛选 `upgrade_available` |

| 容器编排 | Dockge Docker Compose 栈管理 | `dockge-list.mjs`, `dockge-update.mjs` |

| 监控告警 | 系统警报、复制任务状态、服务运行状态 | `alert/list`, `replication` |

| 扩展服务 | 媒体管理（Sonarr/Radarr/Plex）、书签（Karakeep）等 | 参考 `references/` 目录 |

API 演进注意： TrueNAS 24.10+ 已弃用 REST API，本 Skill 已全面迁移至 WebSocket API（DDP-like 协议），通过 truenas-ws.mjs 脚本提供向前兼容支持。2026.04 后版本将完全移除 REST 支持。

显著优点

1. 协议前瞻性：主动适配 TrueNAS API 演进，避免用户在未来版本升级时遭遇功能中断
2. 生态整合度：原生对接 15+ 种常见家庭实验室服务（Arr 套件、Plex、n8n 等），形成统一入口
3. 安全默认值：凭证严格环境变量隔离，无硬编码；支持可选 TLS 强制验证
4. 自托管友好：专为自签名证书家庭服务器场景优化，同时提供生产级安全开关

潜在局限

• TLS 验证默认关闭：为兼容家庭服务器自签名证书，rejectUnauthorized 默认为 false，需手动启用 TRUENAS_VERIFY_TLS=1 才能获得银行级传输安全
• Node.js 依赖：需额外安装 Node 18+ 及 npm 依赖，纯 shell 环境无法运行 WebSocket 组件
• 版本锁定风险：TrueNAS 26.04 将完全移除 REST API，若用户滞留在旧版 Skill 可能失效
• 权限粒度依赖 TrueNAS：API 密钥权限由 TrueNAS 侧控制，Skill 本身无法强制最小权限原则

适合人群

• 运行 TrueNAS SCALE 24.10+ 的家庭 NAS 管理员
• 需要统一入口管理存储 + 容器 + 媒体栈的 homelab 用户
• 熟悉命令行、愿意配置环境变量的技术型用户
• 追求"基础设施即代码"的自动化爱好者

常规风险

| 风险类别 | 具体表现 | 缓释措施 |

|---------|---------|---------|

| 配置错误导致数据丢失 | 数据集删除、快照回滚等操作不可逆 | 所有破坏性操作强制用户二次确认 |

| API 密钥泄露 | 环境变量被其他进程读取 | 使用只读密钥，定期轮换，避免提交到版本控制 |

| 中间人攻击 | 默认跳过 TLS 证书验证 | 生产环境强制启用 `TRUENAS_VERIFY_TLS=1` |

| 供应链攻击 | npm 依赖被篡改 | 已锁定版本（package-lock.json），建议定期 `npm audit` |