> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nonce.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 矿箱、模板与布局

> Nonce 如何描述矿箱、矿箱内的机架，以及矿箱在矿场中的摆放位置

> [!NOTE]
>
> 矿箱、模板与布局目前是 beta 功能，只能通过 [Nonce MCP](https://docs.nonce.app/zh/api-guide/mcp/index.md) 使用，相关接口不会出现在 API Reference 中。

## 概览

矿场用三类对象描述现场布置：

| 对象 | 描述内容 |
| - | - |
| **矿箱（Rack group）** | 一个集装箱或类似单元，用网段确定其中的矿机 |
| **模板（Template）** | 矿箱里有几个机架、每个机架几行几列，以及矿机如何对应机位 |
| **布局（Layout）** | 各矿箱在矿场中的位置：排、位置、上下叠放和通道 |

Nonce 根据矿机的 IP 计算它所在的机位，因此矿场需要给矿机分配固定 IP。矿机 IP 变化后，机位也会随之变化。

***

## 矿箱

矿箱有自己的 `id`。网段 `subnets` 是矿箱的属性：一个或多个 /16 到 /24 的 IPv4 网段，网段内的矿机属于这个矿箱。

| 字段 | 说明 |
| - | - |
| `id` | 矿箱 ID |
| `name` | 矿场内唯一；未命名时为 `null` |
| `subnets` | 矿箱的网段，CIDR 格式 |
| `template_id` | 矿箱使用的模板；没有模板时为 `null` |
| `start_offset` | 按 IP 顺序分配机位时，1 号机位对应的网段内偏移 |
| `miner_count` | 网段内的矿机数量，包含 stale 矿机 |
| `summary` | 矿箱内矿机的实时健康状况，统计口径与 `QueryFarmMinerMetrics` 统计矿场时一致 |

每个有矿机、但还没有矿箱覆盖的 /24 网段，会在下一次读取矿箱时自动生成一个未命名矿箱。所以矿箱始终覆盖矿场内的全部 IPv4 矿机，初始化时只需给已有矿箱命名并配置。

要查询某个矿箱内的矿机，用该矿箱的网段作为 `ip_ranges` 搜索矿机。

### 修改网段

一个集装箱跨多个 /24 网段时，把其中一个矿箱的网段改为完整范围。

> [!WARNING]
>
> 新网段会合并所有完全落在其中的其他矿箱，被合并的矿箱连同名称和模板一起删除。新网段与其他矿箱只有部分重叠时，请求会被拒绝。修改网段前，请先核对会受影响的矿箱。

***

## 模板

模板规定矿箱内的机架数量、每个机架的行数和列数，以及矿机如何对应机位。

| 字段 | 范围 | 说明 |
| - | - | - |
| `racks` | 1–20 | 矿箱内的机架数 |
| `rows` | 1–50 | 每个机架的行数 |
| `columns` | 1–50 | 每个机架的列数 |
| `mode` | `sequential` 或 `dynamic` | 矿机对应机位的方式 |

### 机位分配方式

| 方式 | 规则 |
| - | - |
| `sequential` | 每个 IP 对应固定机位。1 号机位对应网段内偏移为 `start_offset` 的矿机，之后的 IP 依次对应后续机位；缺少矿机的位置保持空位。 |
| `dynamic` | 矿机按 IP 顺序依次填满机位，不留空位。 |

矿箱只有一个 /24 网段时，`start_offset` 就是第一台矿机 IP 的最后一段。例如 `start_offset` 为 `11` 时，`x.x.x.11` 的矿机在 1 号机位。

### 系统模板与矿场模板

| 类型 | 说明 |
| - | - |
| 系统模板 | 描述常见的集装箱型号，所有矿场共用，只读 |
| 矿场模板 | 矿场为系统模板未覆盖的型号自行创建，名称在矿场内唯一 |

用 `ListRackGroupTemplates` 查看矿场可用的模板。修改矿场模板后，所有使用该模板的矿箱随之变化；删除矿场模板后，这些矿箱变为没有模板。

***

## 布局

布局描述矿箱在矿场中的位置，每次整体保存。

* **排**：从矿场前方排到后方。
* **位置**：沿每一排排列。一个位置可以为空，也可以从下往上叠放一到两个矿箱。
* **通道**：每排之后可以是冷通道（`cold`）、热通道（`hot`），或者没有通道。
* 一个矿箱最多占一个位置。

还没有人编排过的矿场，`rows` 为 `null`。已保存的布局可能引用之后被删除的矿箱，例如修改网段时被合并的矿箱，读取时跳过即可。

### 并发修改

用 `UpdateFarmLayout` 保存时，把 `GetFarmLayout` 读到的 `updated_at` 作为 `expected_updated_at` 传入；从未保存过布局时传 `null`。如果期间有其他人保存过布局，请求会返回 `409`。此时重新读取布局，重新应用修改后再保存。

***

## 旧机架

矿箱取代了原来的机架（rack）模型。

| 项目 | 状态 |
| - | - |
| `ListRacks` | 已弃用，仍可读取机架，请改用 `ListRackGroups` |
| 矿机的 `rack` 字段 | 保留，可以读取 |
| `CreateRackUpdateTaskBatch` | 已移除 |

没有逐台写入矿机机位的接口。机位由 IP、矿箱模板和 `start_offset` 共同决定。

***

## 权限

| 操作 | 权限 |
| - | - |
| 读取矿箱、模板和布局 | `miner.read` |
| 修改矿箱、模板和布局 | `miner.manage` |

两种权限都按目标矿场检查。这些写入只改变矿场配置，不会向矿机下发命令。

## 接口

| 接口 | 说明 |
| - | - |
| `ListRackGroups` | 列出矿场的全部矿箱及矿机汇总，不分页。 |
| `UpdateRackGroups` | 在一个事务中给矿箱命名、设置模板和起始偏移，或替换网段。 |
| `ListRackGroupTemplates` | 列出系统模板和矿场模板。 |
| `CreateRackGroupTemplate` | 创建矿场模板。 |
| `UpdateRackGroupTemplate` | 修改矿场模板。 |
| `DeleteRackGroupTemplate` | 删除矿场模板。 |
| `GetFarmLayout` | 获取矿场布局。 |
| `UpdateFarmLayout` | 整体替换矿场布局。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.