Task

概览

Task 是在矿机上执行的操作。Nonce 以 Task Batch 为单位下发：多个 Task 编成一组一起执行。

Task vs Task Batch

概念	描述
Task	作用于一台矿机的单次操作
Task Batch	同批创建的一组 Task，共享 Task 名称和基础参数

通过 API 创建的一定是 Task Batch，系统会为每台目标矿机自动生成对应的 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.ip_diagnosis.create`	运行 IP 诊断并上传 CSV 报告
`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.pool.lock`	锁定或解锁矿池配置
`miner.firmware.update`	更新矿机固件

矿机事件 Task

更新矿机清单元数据的特殊 Task。

需要 miner_ids 指定目标矿机。

Task 名称	描述
`miner.tags.update`	添加或移除矿机的运维标签
`miner.record.delete`	将矿机在清单中标记为已删除
`miner.rack_location.update`	更新矿机的机架位置元数据

Task 参数

每种 Task 有各自的参数。

miner.system.reboot

重启矿机设备。

参数	类型	必填	描述
`force`	boolean	否	即使矿机正在挖矿也强制重启（默认：false）

miner.log.get

从矿机收集诊断日志。无需额外参数。

miner.light.update

切换矿机的 LED 指示灯。

参数	类型	必填	描述
`mode`	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`）

agent.ip_diagnosis.create

运行 Agent IP 诊断并上传 CSV 报告。

参数	类型	必填	描述
`target_scope`	string	否	诊断目标范围（默认 `known_with_custom`）
`custom_targets`	array	否	自定义诊断目标
`ping_only`	boolean	否	对无本地上下文的目标仅执行 ICMP ping 检查

miner.pool.lock

通过 auth package 锁定或解锁矿池配置。锁定期间可防止未授权的矿池修改。

参数	类型	必填	描述
`firmware_url`	string	是	auth package 文件的 URL
`action`	string	是	`lock` 固定强制矿池配置；`unlock` 恢复可配置矿池

miner.tags.update

添加或移除矿机的运维标签。仅影响元数据，不影响挖矿运行。

参数	类型	必填	描述
`add`	string[]	否	为所选矿机添加的标签（每台矿机最多 50 个）
`remove`	string[]	否	从所选矿机移除的标签

miner.record.delete

将矿机在清单中标记为已删除。矿机物理下架后使用。

参数	类型	必填	描述
`comment`	string	否	删除操作的可选备注

miner.rack_location.update

更新矿机的机架位置元数据。使用顶层 updates 数组，不使用 miner_ids + params。

字段	类型	必填	描述
`updates[].miner_id`	string	是	目标矿机 ID
`updates[].rack`	string \| null	是	机架标识（最长 50 字符）；`null` 表示清除
`updates[].position`	number \| null	是	机架内的槽位序号；`null` 表示清除

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"
    }
  }'

上面的请求创建一个 Task Batch，把指定矿机的功耗模式改为 low。

响应格式

API 响应中的 meta 字段汇总 Task 的创建结果。

meta 字段说明创建过程的实际结果：哪些 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"]
      }
    ]
  }
}

Meta 摘要

字段	类型	描述
`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 不存在或无法访问

快速开始

核心概念

MCP

API Reference

概览

Task vs Task Batch

Task 名称

Agent 级别 Task

矿机级别 Task

矿机事件 Task

Task 参数

miner.system.reboot

miner.log.get

miner.light.update

miner.power_mode.update

miner.pool.update

miner.firmware.update

agent.scan.create

agent.ip_diagnosis.create

miner.pool.lock

miner.tags.update

miner.record.delete

miner.rack_location.update

Task 状态

Task 生命周期

Batch 状态

挖矿模式

各厂商支持的模式

模式说明

示例：创建 Task Batch

响应格式

Meta 摘要

跳过原因

​概览

​Task vs Task Batch

​Task 名称

​Agent 级别 Task

​矿机级别 Task

​矿机事件 Task

​Task 参数

​miner.system.reboot

​miner.log.get

​miner.light.update

​miner.power_mode.update

​miner.pool.update

​miner.firmware.update

​agent.scan.create

​agent.ip_diagnosis.create

​miner.pool.lock

​miner.tags.update

​miner.record.delete

​miner.rack_location.update

​Task 状态

​Task 生命周期

​Batch 状态

​挖矿模式

​各厂商支持的模式

​模式说明

​示例：创建 Task Batch

​响应格式

​Meta 摘要

​跳过原因

概览

Task vs Task Batch

Task 名称

Agent 级别 Task

矿机级别 Task

矿机事件 Task

Task 参数

miner.system.reboot

miner.log.get

miner.light.update

miner.power_mode.update

miner.pool.update

miner.firmware.update

agent.scan.create

agent.ip_diagnosis.create

miner.pool.lock

miner.tags.update

miner.record.delete

miner.rack_location.update

Task 状态

Task 生命周期

Batch 状态

挖矿模式

各厂商支持的模式

模式说明

示例：创建 Task Batch

响应格式

Meta 摘要

跳过原因