TrueNAS AIops

TrueNAS AIops

免责声明：由社区维护的开源项目。与 iXsystems 或 TrueNAS 项目无关联，未获其认可，也未受其赞助。“TrueNAS”是其所有者的商标。采用 MIT 许可。

借助 内置治理机制，通过 AI 执行 TrueNAS SCALE 存储运维 — 统一审计日志、令牌／失控预算防护、撤销令牌记录，以及描述性风险等级。支持 两种 TrueNAS API：REST v2.0 和在 TrueNAS 26 中取代它的 JSON-RPC/WebSocket API。

验证状态：已通过两种传输方式，在真实的 TrueNAS SCALE 25.04.2.1 设备上进行实时验证，包括完整的写入 → 审计 → 撤销 → 验证还原流程。各端点的覆盖情况及缺口均列在 docs/VERIFICATION.md 中。请阅读该文档，不要将“已验证”理解为“所有内容都已验证”。

支持的 TrueNAS 版本 — 以及使用的 API

truenas-aiops 支持 两种 TrueNAS API，并会选择仍将继续存在的 API：

TrueNAS 版本	REST API v2.0	基于 WebSocket 的 JSON-RPC	此工具的行为
≤ 25.10.0	支持	—	REST
25.04 – 25.10.x	已弃用（每次调用都会触发设备警报）	已提供，位于 /api/current	WebSocket（自动选择）
26 及更高版本	已移除	必需	WebSocket

在 config.yaml 中为每个目标设置 transport:：

targets:
  - name: nas1
    host: nas1.example.com
    transport: auto        # default — probe /api/current, prefer WebSocket
    # transport: websocket # pin the API that survives TrueNAS 26
    # transport: rest      # pin REST while migrating

auto 会通过低成本的 HTTP 升级（不消耗凭据）探测 /api/current。如果设备提供该接口，工具就会使用它；否则会回退到 REST，在 25.10 及更早版本上仍然适用。

iXsystems 文档指出，升级到 TrueNAS 26 会撤销现有的 API 密钥 — 因此请预期升级后需要重新创建密钥。我们尚未亲自复现此情况；此处信息来自上游发行说明，而非经过验证的升级。请将其视为警示，而非实测结果。

truenas-aiops doctor 会告知连接实际使用的传输方式、读取服务器版本，并在使用 REST 时明确说明 REST 处于受支持、已弃用还是已移除状态。如果无法解析版本号，它会报告 UNKNOWN，绝不会在无法确认时给出一切正常的结论。

功能

• CLI（truenas-aiops ...）：init、overview、system、pool list/get/status/scrub-status/capacity/scrub-start、dataset list/get/create、diagnose pool-health/alerts、snapshot list/create/delete、disk list/smart、alert list、service list/restart、replication list/cloudsync、secret set/list/rm/migrate/rotate-password、doctor、mcp。
• MCP 服务（truenas-aiops mcp 或 truenas-aiops-mcp）：25 个工具（19 个读取工具，6 个写入工具），每个工具都由内置的 @governed_tool 治理机制封装。
• 加密凭据：TrueNAS API 密钥保存在加密存储 ~/.truenas-aiops/secrets.enc 中（Fernet + scrypt）— 绝不以明文形式存储在磁盘上。通过 TRUENAS_AIOPS_MASTER_PASSWORD（MCP/CI）或交互式提示词（CLI）输入主密码解锁。
• 可逆性：snapshot_create 会记录一个反向 snapshot_delete 撤销描述符。不可逆的 snapshot_delete（high 风险）会在审计记录中捕获快照的删除前状态，并声明没有撤销操作。
• 安全性：破坏性 CLI 操作（snapshot delete、service restart）需要双重确认，并支持 --dry-run。

这个工具会做什么，以及不会决定什么

它会准确、高效地执行 TrueNAS SCALE 存储操作——读取和写入——并记录每一项操作。它不会决定是否允许执行写入。这由 Agent 自行判断，或由你连接时使用的账户权限决定：将 TrueNAS API 密钥限定为权限有限的账户，写入操作就会在设备端失败——真正掌握权限的地方。

因此，无需配置只读开关、策略文件或审批关卡。这个工具唯一能保证的是，绝不会有操作悄无声息：通过 MCP 和 CLI 发起的每次调用，都会写入一条审计记录，保存至 ~/.truenas-aiops/audit.db；可撤销的写入操作还会捕获操作前状态并记录反向操作。

每个工具都会声明一个 risk_level，并通过测试确保其与 [READ]/[WRITE] 文档标签一致；该级别也会作为描述性等级写入审计记录，因此审核者可以一眼看出某条记录对应高风险删除操作。它只是标签，不是关卡。

正在运行更小型的本地模型？请参阅 agent-guardrails.md——其中列出了此工具现在会为你强制执行的防护措施（因此你无需在提示词预算中重复说明），并提供了现成的系统提示词，用于处理剩余事项。

操作手册：排查降级的存储池

truenas-aiops diagnose pool-health            # worst-first: bad state, error counters, capacity
# → e.g. CRITICAL tank "pool status is DEGRADED", and "read=4 checksum=2" on a vdev
truenas-aiops pool status tank                # inspect the topology / scan detail it cited
truenas-aiops pool scrub-start tank           # kick an integrity scrub (governed, medium risk)
truenas-aiops diagnose alerts                 # cross-check active alerts + any datasets near full

每项发现都会列出触发告警的实测数值（状态字符串、错误计数、已用百分比），让你了解触发标记的原因，然后指出可采取操作的确切读写命令。

功能矩阵（25 个 MCP 工具）

类别	工具	数量	读/写
概览 / 系统	overview、system_info	2	读取
诊断 / 根因分析	pool_health_rca、alert_and_capacity_rca	2	读取
存储池	pool_list、pool_get、pool_status、scrub_status、pool_capacity	5	读取
	pool_scrub_start	1	写入（中）
数据集	dataset_list、dataset_get	2	读取
	dataset_create	1	写入（中）
快照	snapshot_list	1	读取
	snapshot_create（中）、snapshot_delete（高）	2	写入
磁盘	disk_list、smart_test_results	2	读取
告警	alert_list	1	读取
服务	service_list	1	读取
	service_restart	1	写入（中）
复制	replication_list、cloudsync_list	2	读取
撤销（治理）	undo_list	1	读取
	undo_apply	1	写入（中）

快速开始

作为 Claude Code 插件

安装一次，即可让 Agent 同时获得技能和 MCP 服务：

/plugin marketplace add AIops-tools/marketplace
/plugin install truenas-aiops@aiops-tools

MCP 服务会通过 uv 获取，并固定到此插件声明的软件包版本，因此可以追溯审计记录对应的写入代码。凭据仍需通过 truenas-aiops init 配置——见下文。

作为 OpenClaw 插件

同一套插件也发布在 ClawHub，安装一次即可同时获得技能和 MCP 服务：

openclaw plugins install clawhub:@zw008/truenas-aiops
openclaw skills info truenas-aiops          # expect: Visible to model: yes

之后请重启 OpenClaw 网关，使其加载插件。MCP 服务会通过 uv 获取，并固定到此确切版本，因此 uvx 必须位于 PATH 中——若缺少它，技能仍会安装，但会报告 Visible to model: no。凭据按下文所述配置。

作为 CLI 或独立 MCP 服务

uv tool install truenas-aiops
truenas-aiops init        # interactive wizard: connection details + encrypted API key
truenas-aiops doctor      # verify config, encrypted store, connectivity (hits /system/info)

init 会写入 ~/.truenas-aiops/config.yaml（非敏感的连接详情），并将 API 密钥加密后存储在 ~/.truenas-aiops/secrets.enc。生成的配置示例：

targets:
  - name: nas1
    host: 10.0.0.30
    port: 443
    verify_ssl: false          # self-signed lab certs only
    api_path: /api/v2.0

在 TrueNAS 界面的 Credentials → API Keys 下创建 API 密钥。对于非交互式使用（MCP 服务、CI、cron），请导出主密码，以便无需提示即可解锁存储：

export TRUENAS_AIOPS_MASTER_PASSWORD='your-master-password'

密码之后会存放在哪里：导出的变量可被此 shell 启动的每个进程读取，也会记录在 shell 历史中。在共享或长期运行的主机上，最好使用交互式提示，或在需要该密码的单条命令运行期间，从密钥管理器注入密码。

管理密钥

truenas-aiops secret set nas1             # prompts hidden for the API key
truenas-aiops secret list                 # names only, values never shown
truenas-aiops secret rm nas1
truenas-aiops secret rotate-password      # re-encrypt under a new master password
truenas-aiops secret migrate              # import a legacy plaintext .env, then deletes it

仍会将旧版明文环境变量 TRUENAS_<TARGET_NAME_UPPER>_APIKEY 作为回退选项（并显示弃用警告；使用 truenas-aiops secret migrate 迁移）。

支持范围 / Supported scope

版本：通过 JSON-RPC/WebSocket 支持 TrueNAS SCALE 25.04 及更新版本，也支持仍提供 REST v2.0 的任何版本——会自动选择传输方式。请参阅支持的 TrueNAS 版本。 请注意，iXsystems 文档指出，升级到 TrueNAS 26 会撤销现有 API 密钥（这是上游的说法，本文未予复现）。

读取：系统信息、ZFS 池（列表/获取/状态/清理状态/容量）、数据集（列表/获取）、快照（列表）、磁盘及 S.M.A.R.T. 结果、警报、服务、复制和云同步任务、一次性健康概览，以及只读诊断 / RCA（pool_health_rca、alert_and_capacity_rca）。变更操作（受治理；破坏性操作需试运行 + 二次确认）：pool_scrub_start、dataset_create、snapshot_create、snapshot_delete、service_restart。

缺少功能？(Missing something?) 支持范围有意聚焦。欢迎在 github.com/AIops-tools/TrueNAS-AIops 提交问题或 PR——功能请求、贡献和评论都非常欢迎。

注意事项

• 已通过 TrueNAS SCALE 25.04.2.1 对两种传输方式进行实时验证——读取结果与设备自身 API 交叉核对，并完成了完整的写入 → 审计 → 撤销 → 验证恢复流程。涵盖与未涵盖的内容按端点列于 docs/VERIFICATION.md；请阅读文档，不要想当然地认为“已验证”就代表全部内容。
• 仍未验证：故障介质上的 S.M.A.R.T.（需要真实硬件——virtio 完全不提供 S.M.A.R.T.）、针对真实目标的复制/云同步，以及 TrueNAS 26 的 auth.login_ex（25.04 仅测试了回退方式）。
• CLI 退出代码：0 表示已确认，1 表示失败或拒绝，2 表示结果未确定（操作可能仍在执行——重试前请先轮询）。
• 按设计不在范围内：任何会销毁大量数据的操作（删除数据集/池、会覆盖数据的复制运行）——只有 snapshot_delete 会删除数据，且其风险等级为 high，需要二次确认。

不适用范围

其他 NAS/存储或备份产品、虚拟机监控程序的 VM 生命周期管理、容器集群或网络设备——这些都不属于此工具的范围。

许可证

MIT — github.com/AIops-tools/TrueNAS-AIops