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

# 创建 GPU 节点

> 通过提供 SSH 凭据、标签与硬件规格，在咏唱引擎 PIN 中注册一个新的 GPU 节点。

注册一个新的 GPU 节点，以便咏唱引擎 PIN 能够在其上管理智能体。提供 SSH 连接详情以及可选的规格与标签集合。节点以 active 状态创建。

## 接口

**POST** `/v1/gpu-nodes`

认证：需要 Bearer API 密钥。

## 请求体

<ParamField body="name" type="string" required>
  便于识别的节点名称。
</ParamField>

<ParamField body="ip" type="string" required>
  用于 SSH 访问的节点 IP 地址。
</ParamField>

<ParamField body="ssh_user" type="string" required>
  SSH 用户名。
</ParamField>

<ParamField body="ssh_port" type="integer">
  SSH 端口（默认 22）。
</ParamField>

<ParamField body="ssh_key" type="string">
  SSH 私钥（明文，存储前加密）。
</ParamField>

<ParamField body="ssh_password" type="string">
  SSH 密码（明文，存储前加密）。
</ParamField>

<ParamField body="spec" type="string">
  硬件规格摘要。
</ParamField>

<ParamField body="labels" type="array of strings">
  调度标签。
</ParamField>

## 响应

<ResponseField name="code" type="integer">
  响应码（成功为 0）。
</ResponseField>

<ResponseField name="data" type="object" required>
  所创建的 GPU 节点对象。

  <Expandable>
    <ResponseField name="id" type="string" required>
      节点标识符，例如 gn\_abc123de。
    </ResponseField>

    <ResponseField name="name" type="string" required>
      节点名称。
    </ResponseField>

    <ResponseField name="ip" type="string" required>
      节点 IP。
    </ResponseField>

    <ResponseField name="ssh_port" type="integer">
      SSH 端口。
    </ResponseField>

    <ResponseField name="ssh_user" type="string" required>
      SSH 用户名。
    </ResponseField>

    <ResponseField name="spec" type="string">
      规格摘要。
    </ResponseField>

    <ResponseField name="labels" type="array of strings">
      标签。
    </ResponseField>

    <ResponseField name="status" type="string">
      创建时的状态，例如 active。
    </ResponseField>

    <ResponseField name="created_at" type="string (ISO 8601)">
      创建时间戳。
    </ResponseField>

    <ResponseField name="updated_at" type="string (ISO 8601)">
      更新时间戳。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">
  成功时为空。
</ResponseField>

## 示例

```bash theme={null}
curl -s -X POST http://<pin-host>:8001/v1/gpu-nodes \
  -H "Authorization: Bearer $ARIA_PIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "node-01",
    "ip": "10.0.1.10",
    "ssh_user": "ubuntu",
    "ssh_port": 22,
    "ssh_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
    "spec": "A100-80G x8",
    "labels": ["training", "a100"]
  }'
```

```json theme={null}
{
  "code": 0,
  "data": {
    "id": "gn_a1b2c3d4",
    "name": "node-01",
    "ip": "10.0.1.10",
    "ssh_port": 22,
    "ssh_user": "ubuntu",
    "spec": "A100-80G x8",
    "labels": ["training", "a100"],
    "status": "active",
    "created_at": "2024-05-01T12:00:00Z",
    "updated_at": "2024-05-01T12:00:00Z"
  },
  "message": ""
}
```