核心用法
本 Skill 通过 REST/WebSocket API 与 TrueNAS SCALE 交互，覆盖六大核心场景：
1. 存储池与数据集管理
- 监控 ZFS 池健康状态（
pool.query） - 创建/删除数据集，查看使用率
- 手动/自动快照管理（
zfs.snapshot.create） - 复制任务状态追踪（replication health）
2. 应用生命周期管理
- 查询官方应用商店安装状态与更新可用性
- 支持 TrueNAS Apps 的完整安装流程
- 应用状态监控与门户链接获取
3. Dockge 容器编排
- 通过 Socket.IO 协议管理非官方 Docker Compose 堆栈
- 批量更新容器镜像（
dockge-update.mjs） - 智能跳过 TrueNAS 托管的
ix-前缀堆栈
4. 系统监控告警
- 实时警报列表（alert level + formatted message）
- 运行服务枚举
- 一键健康检查清单（pool + alerts + services + apps + replication）
5. Homelab 服务生态
内置 20+ 款常用服务的 API 集成参考：
- 媒体管理：Overseerr、Sonarr、Radarr、Plex、Tautulli
- 下载工具：qBittorrent、SABnzbd
- 自动化：n8n、Syncthing、ChangeDetection
- 书签与知识：Karakeep（AI 标签）、NocoDB
6. 双协议 API 支持
- REST API（24.10/25.x 兼容，26.04 起废弃）
- WebSocket API（DDP/Meteor 协议，面向未来）
显著优点
| 维度 | 优势 |
|------|------|
| **生态完整** | 同时覆盖 TrueNAS 原生应用 + Dockge 自定义编排，填补官方 App 生态缺口 |
| **协议前瞻性** | 优先采用 WebSocket API 应对 REST 废弃，脚本化迁移路径清晰 |
| **TLS 友好** | 默认跳过自签名证书验证（`curl -k` / `rejectUnauthorized: false`），一键切换严格模式 |
| **权限最小化** | 支持只读 API Key 作用域，凭证仅本地运行时读取 |
| **homelab 原生** | 内置 Sonarr/Radarr/Overseerr 等 *arr 生态及 MeTube、Audiobookshelf 等垂直场景 |
潜在缺点与局限性
- 版本碎片化：REST/WebSocket API 行为随 TrueNAS 版本变化（24.10→25.04→26.04），需持续关注兼容性
- Node.js 依赖：Dockge 管理需要本地 Node 18+ 及 npm 安装，增加部署复杂度
- 凭证密集：涉及 20+ 组环境变量（URL + API Key），配置管理负担较重
- Socket.IO 非标准：Dockge 使用 Socket.IO 而非标准 REST，调试与故障排查门槛更高
- 破坏性操作风险：数据集删除、快照回滚等操作无二次确认机制，依赖用户显式确认
适合人群
- 自托管 NAS 管理员：运行 TrueNAS SCALE 的 homelab 用户
- 媒体服务器运维者：管理 Plex + *arr 生态的影音自动化工作流
- Docker Compose 重度用户：需要官方 Apps 之外的自定义容器编排
- 多服务整合需求者：希望统一入口管理 NAS 存储、应用、书签、通知等
常规风险
| 风险类别 | 具体描述 | 缓解建议 |
|----------|----------|----------|
| API 废弃 | REST API 在 26.04 完全移除，历史脚本将失效 | 优先使用 WebSocket 封装脚本（`truenas-ws.mjs`） |
| 凭证泄露 | API Key 通过环境变量注入，存在进程泄露风险 | 使用最小权限 Key，避免 shell 历史记录 |
| 数据丢失 | 数据集删除、快照覆盖无回收站机制 | 操作前强制人工确认，启用复制任务异地备份 |
| TLS 降级 | 默认跳过证书验证，存在中间人攻击可能 | 内网可信网络环境或显式启用 `TRUENAS_VERIFY_TLS=1` |
| 容器更新中断 | Dockge 批量更新可能拉取不兼容镜像 | 更新前检查镜像变更日志，分批次滚动更新 |