核心用法
TrueNAS SCALE Skill 是一个面向家庭服务器/ homelab 场景的综合管理工具，通过 TrueNAS REST/WebSocket API 与 Dockge Socket.IO 协议，实现对 NAS 存储、容器编排、应用部署及配套服务的统一管控。
主要功能模块
| 模块 | 能力 |
|------|------|
| **存储管理** | ZFS Pool 健康检查、Dataset 创建/删除、快照手动创建与自动任务监控 |
| **应用生态** | TrueNAS Apps 市场安装/更新/状态查询，覆盖 200+ 官方容器化应用 |
| **容器编排** | Dockge 外部堆栈管理（非官方应用），支持批量更新与 Socket.IO 实时交互 |
| **服务集成** | 预置 15+ 常见 homelab 服务 API 参考（Sonarr/Radarr/Plex/Overseerr/n8n 等） |
| **监控告警** | 池健康状态、活跃告警、服务运行状态、复制任务健康度 |
技术架构
- REST API（24.10-25.x）：传统 curl + jq 交互，部分端点 25.10+ 已废弃
- WebSocket API（25.04+ 推荐）：DDP-like 协议，通过
scripts/truenas-ws.mjs脚本封装调用 - Dockge 集成：Socket.IO 协议实现 Docker Compose 堆栈的列表查询与批量更新
显著优点
1. 原生 API 深度集成：直接对接 TrueNAS 官方 API，非模拟点击，稳定性高
2. 版本兼容策略：明确标注 REST 弃用时间线（25.04 弃用 / 26.04 移除），提供 WebSocket 迁移路径
3. 生态完整性：覆盖从底层存储到上层媒体管理的全链条，预置常见服务的环境变量模板
4. 安全意识：强制 HTTPS、API Key 认证、删除操作前确认提示、自签名证书兼容（-k 标志说明）
潜在缺点与局限性
1. 版本碎片化：REST/WebSocket 双轨并行期（24.10-25.x）需要用户理解 API 迁移逻辑
2. 网络依赖：所有操作需直连 NAS，无离线模式；WebSocket 连接需处理自签名证书异常
3. 权限边界：API Key 权限由 TrueNAS 侧控制，skill 无法细粒度限制（如只读 vs 读写分离）
4. Dockge 耦合：外部容器管理依赖 Dockge 单独部署，非 TrueNAS 原生功能
5. 服务 API 漂移：15+ 第三方服务的 API 版本由上游维护，存在接口变更风险
适合人群
- 运行 TrueNAS SCALE 24.10+ 的家庭服务器管理员
- 需要统一管理存储 + 容器 + 媒体自动化链路的 homelab 爱好者
- 熟悉 Docker Compose 且希望桥接 TrueNAS Apps 与外部编排工具的用户
常规风险
| 风险类型 | 说明 |
|---------|------|
| **数据丢失** | Dataset 删除、快照清理为不可逆操作，需二次确认 |
| **服务中断** | App/堆栈更新可能触发容器重启，影响正在进行的任务 |
| **密钥泄露** | API Key 以环境变量形式存储，需配合主机 secrets 管理 |
| **复制失败** | ZFS 复制任务配置错误可能导致快照堆积或传输中断 |
| **依赖冲突** | Dockge 管理的 `ix-*` 前缀堆栈为 TrueNAS 内部应用，误操作可能破坏系统状态 |