POST /v1/node-registrations
Self-register a node host (called by install-node.sh)
- operationId
registerNode- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Unauthenticated except for the registration credential in the body; rate limited per source IP (10/min) and globally (120/min) per control-api process. Creates a pending node (待初始化) named after the host and records the observed public source IP and OS details, then returns a one-time initial_enrollment token (10 minutes) for the Gateway enrollment. Dedupe: the node ID is a keyed hash of the machine fingerprint, so the same machine reuses its pending node (200) instead of creating a duplicate; once it has enrolled or been initialized the call returns 409 node_already_registered. A deleted (retired) node lets the machine register again as a new node. Self-registered nodes stay pending after enrollment and receive no configuration until an administrator sets admin_state=active. A new node gets the region of the region catalog when it has exactly one region, else an empty region.
请求体
application/json · 必填：是
registerNode 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
credential | string | 是 | — |
|---|
machine_fingerprint | string | 是 | Lowercase hex SHA-256 of "cdnca-node-registration-v1" NUL machine-id NUL DMI product_uuid (empty when unreadable). |
|---|
hostname | string | 否 | — |
|---|
os_name | string | 否 | — |
|---|
kernel_version | string | 否 | — |
|---|
architecture | string | 否 | — |
|---|
响应
registerNode 响应| 状态码 | 说明 |
|---|
201 | Pending node created. 字段：node: Node enrollment_token: IssuedEnrollmentToken reused: boolean |
|---|
200 | Existing pending node of this machine reused; a fresh token is issued. 字段：node: Node enrollment_token: IssuedEnrollmentToken reused: boolean |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | invalid_registration_credential - the credential is invalid or was reset. |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
429 | node_registration_rate_limited; retry after the Retry-After seconds. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。429 被限速：等待后再试，降低并发。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/node-registrations/identity
Fetch the issued identity of an interrupted node install (called by install-node.sh --resume)
- operationId
recoverNodeRegistrationIdentity- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
For an install whose Gateway enrollment committed on the controller (certificate issued) but whose host never wrote its identity directory. Authenticated by the registration credential in the body and rate limited together with POST /v1/node-registrations (same per source IP and global window). Returns the live initial certificate of this machine's registered node whose enrollment CSR has the given SHA-256, in the agent.v1.EnrollResponse JSON shape; the Agent binds it to the private keys it kept in its pending enrollment state. Any miss (unknown machine, no issued certificate, CSR digest mismatch) is 404 node_identity_not_found, so the response never reveals whether another node exists. Every lookup of a registered machine is audited as node.registration.identity_fetch (success or denied). A node installed with a one-time enrollment token has no reusable credential and cannot use this endpoint.
请求体
application/json · 必填：是
recoverNodeRegistrationIdentity 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
credential | string | 是 | — |
|---|
machine_fingerprint | string | 是 | The registration fingerprint sent to POST /v1/node-registrations. |
|---|
csr_sha256 | string | 是 | Lowercase hex SHA-256 of the CSR DER in the Agent's pending enrollment state (edge-agent enroll --print-pending-csr-sha256). |
|---|
响应
recoverNodeRegistrationIdentity 响应| 状态码 | 说明 |
|---|
200 | The issued identity of this machine. 字段：node_id: string(uuid) selected_protocol_version: object artifact_encryption_key_id: string certificate: object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | invalid_registration_credential - the credential is invalid or was reset. |
|---|
404 | node_identity_not_found - no issued identity matches this machine and CSR digest. |
|---|
429 | node_registration_rate_limited; retry after the Retry-After seconds. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。404 资源不存在或不属于当前租户。429 被限速：等待后再试，降低并发。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表