Task 是在矿机上执行的操作。Nonce 使用基于 Task Batch 的系统，多个 Task 可以分组并一起执行。
Task vs Task Batch
| 概念 | 描述 |
|---|
| Task | 在单个矿机上执行的单个操作 |
| Task Batch | 一组一起创建的 Task，共享相同的 Task 名称和基础参数 |
Task 名称
Task 按其目标和用途进行分类。Task Batch 创建请求包含：
{
"task_name": "miner.power_mode.update",
"miner_ids": ["miner-id-1", "miner-id-2"],
"params": {
"mode": "low"
}
}
| 字段 | 类型 | 必填 | 描述 |
|---|
task_name | string | 是 | 要执行的 Task 类型（见下表） |
miner_ids | string[] | 条件性 | 目标矿机 ID 数组（矿机级别的 Task 必填） |
params | object | 否 | Task 特定参数（见 Task 参数） |
Agent 级别 Task
Agent 级别的 Task 不需要 miner_ids 参数。
在 Agent 本身上运行的操作。
| Task 名称 | 描述 |
|---|
agent.scan.create | 扫描网络以发现矿机 |
agent.self.update | 更新 Agent |
矿机级别 Task
通过 Agent 发起矿机的某个任务操作。
需要 miner_ids 参数来指定目标矿机。
| Task 名称 | 描述 |
|---|
miner.system.reboot | 重启矿机设备 |
miner.log.get | 从矿机收集诊断日志 |
miner.light.update | 切换矿机的 LED 指示灯 |
miner.power_mode.update | 更改挖矿功耗模式 |
miner.pool.update | 更新矿池配置 |
miner.firmware.update | 更新矿机固件 |
矿机事件 Task
更新矿机资产元数据的特殊 Task。
需要 miner_ids 参数来指定目标矿机。
| Task 名称 | 描述 |
|---|
miner.asset.update | 更新矿机资产状态（例如，标记为维护中） |
miner.asset.delete | 将矿机资产标记为已删除 |
Task 参数
每种 Task 类型需要特定的参数。
miner.system.reboot
重启矿机设备。
| 参数 | 类型 | 必填 | 描述 |
|---|
force | boolean | 否 | 即使矿机正在挖矿也强制重启（默认：false） |
miner.log.get
从矿机收集诊断日志。无需额外参数。
miner.light.update
切换矿机的 LED 指示灯。
| 参数 | 类型 | 必填 | 描述 |
|---|
action | string | 是 | 灯光模式：on 或 off |
miner.power_mode.update
更改挖矿功耗模式。
| 参数 | 类型 | 必填 | 描述 |
|---|
mode | string | 是 | 挖矿模式（见下方挖矿模式） |
miner.pool.update
更新矿池配置。
| 参数 | 类型 | 必填 | 描述 |
|---|
pools | array | 是 | 矿池配置数组 |
pools[].url | string | 是 | 矿池 URL（例如 stratum+tcp://pool.example.com:3333） |
pools[].user | string | 是 | 矿池用户名/矿工名 |
miner.firmware.update
更新矿机固件。
| 参数 | 类型 | 必填 | 描述 |
|---|
firmware_url | string | 是 | 固件文件的下载 URL |
agent.scan.create
扫描网络以发现矿机。
| 参数 | 类型 | 必填 | 描述 |
|---|
ip_range | string | 否 | 要扫描的 IP 范围（例如 192.168.1.0/24） |
miner.asset.update
更新矿机资产状态。
| 参数 | 类型 | 必填 | 描述 |
|---|
status | string | 是 | 可用的资产状态：online、on_rack、off_rack、transit、maintenance、retired、archived |
comment | string | 否 | 资产状态更新的可选备注 |
miner.asset.delete
将矿机资产标记为已删除。无必填参数。
| 参数 | 类型 | 必填 | 描述 |
|---|
comment | string | 否 | 删除操作的可选备注 |
Task 状态
Task 在其生命周期中会经历不同的状态。
| 状态 | 描述 |
|---|
created | Task 已创建，等待加入队列 |
queuing | Task 已加入队列，等待 Agent 处理 |
pending | Task 正在由 Agent 执行 |
succeed | Task 执行成功 |
failed | Task 执行失败 |
timed_out | Task 执行超过超时限制 |
cancelled | Task 在完成前被取消 |
Task 生命周期
Batch 状态
Task Batch 基于其包含的单个 Task 有汇总状态。
| Batch 状态 | 描述 |
|---|
pending | 部分 Task 仍在运行 |
succeed | 所有 Task 执行成功 |
failed | 所有 Task 执行失败 |
partial_succeed | 部分 Task 成功，部分失败 |
挖矿模式
挖矿功耗模式因制造商而异。并非所有模式都被所有设备支持。
各制造商支持的模式
| 制造商 | 支持的模式 |
|---|
| AntMiner | sleep、low、normal |
| WhatsMiner | low、normal、high |
未来更新可能会添加更多制造商和模式。
模式说明
| 模式 | 功耗 | 描述 |
|---|
sleep | ~5% | 待机模式，最低功耗（仅限 AntMiner） |
low | ~75% | 降低算力，节能模式 |
normal | ~100% | 标准运行，平衡性能 |
high | ~125% | 最大算力，高功耗（仅限 WhatsMiner） |
尝试为矿机设置其制造商不支持的模式将导致验证错误。
示例：创建 Task Batch
curl -X POST "https://api.nonce.app/private-api/v1/{workspace_id}/farms/{farm_id}/tasks/batches" \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"task_name": "miner.power_mode.update",
"miner_ids": ["miner-id-1", "miner-id-2"],
"params": {
"mode": "low"
}
}'
low。
响应格式
API 响应包含一个 meta 字段，提供 Task 创建摘要。
meta 字段提供信息提示，帮助您了解 Task 创建过程中发生了什么。它指示哪些 Task 实际被创建，哪些被跳过，以及跳过的原因。这对于调试和了解为什么某些矿机没有收到 Task 特别有用。
{
"success": true,
"data": { ... },
"error": null,
"meta": {
"summary": {
"created_count": 1,
"skipped_count": 1
},
"skipped": [
{
"reason": "no_change",
"message": "Task skipped: miner already in requested mode",
"miner_ids": ["miner-id-2"]
}
]
}
}
| 字段 | 类型 | 描述 |
|---|
created_count | number | 成功创建的 Task 数量 |
skipped_count | number | 被跳过的 Task 数量 |
跳过原因
当部分矿机被跳过时，skipped 数组提供详细信息：
| 字段 | 类型 | 描述 |
|---|
reason | string | 跳过原因代码（见下表） |
message | string | 人类可读的解释 |
miner_ids | string[] | 受影响的矿机 ID 数组 |
| 原因 | 描述 |
|---|
no_change | 矿机已处于请求的状态 |
unsupported_mode | 请求的模式不被该矿机的制造商支持 |
miner_not_found | 矿机 ID 不存在或无法访问 |
