子网路由与运行数据

读取或维护子网路由，并查询用量和活动日志。本页完整列出 5 个受支持操作的请求与响应契约。

路径均相对于 https://<nsd-host>。先设置 NSD_BASE_URL=https://<nsd-host>/api/v1 和 NSD_TOKEN；示例 ID 与数据均为虚构值。

列出子网路由

GET/api/v1/subnetsread-only / full

请求示例

curl --silent --show-error --fail-with-body -X GET \
  "$NSD_BASE_URL/subnets" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`200`	Subnet mappings for the caller's Network.	`array<MappingResponse>`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`500`	Subnet mapping authority unavailable	`ProblemDetails`

200 响应

字段	类型	必有	说明
`[].active_gateway_machine_id`	`string \| null`	否	Gateway currently publishing the mapping, absent while none is healthy.
`[].display_label`	`string`	是	Operator-facing label derived from the mapping.
`[].generation`	`integer`	是	Mapping revision; advances when the mapping itself changes.
`[].mapped_prefix`	`string`	是	Overlay prefix this LAN is reachable at inside the Network.
`[].real_cidr`	`string`	是	Real IPv4 LAN CIDR, normalized to the network address.
`[].selection_generation`	`integer`	是	Active-gateway selection revision; advances on every failover.
`[].standby_gateway_machine_ids`	`array<string>`	是	Gateways that have joined the mapping and can take over.
`[].subnet_id`	`integer`	是	Stable subnet mapping ID within the Network.
`[].withdrawn`	`boolean`	是	Whether the mapping was withdrawn. Its allocation is retained and never reused, so a withdrawn mapping still occupies its prefix.

[
  {
    "active_gateway_machine_id": "n-01K4NODE000000000000000",
    "display_label": "example",
    "generation": 1,
    "mapped_prefix": "100.96.10.0/24",
    "real_cidr": "192.168.10.0/24",
    "selection_generation": 1,
    "standby_gateway_machine_ids": [
      "n-01K4NODE000000000000000"
    ],
    "subnet_id": 1,
    "withdrawn": false
  }
]

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

创建或加入子网路由

POST/api/v1/subnetsfull

请求体

字段	类型	必填	说明
`gateway_machine_id`	`string`	是	Registered gateway machine that publishes this mapping.
`join_subnet_id`	`integer \| null`	否	Existing mapping to join; omitted creates an independent mapping.
`real_cidr`	`string`	是	Real IPv4 LAN CIDR. Host bits are normalized to the network address.

request.json

{
  "gateway_machine_id": "n-01K4NODE000000000000000",
  "join_subnet_id": 1,
  "real_cidr": "192.168.10.0/24"
}

请求示例

curl --silent --show-error --fail-with-body -X POST \
  "$NSD_BASE_URL/subnets" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data @request.json

响应状态

状态	含义	响应结构
`201`	Mapping created, or the caller joined an existing one	`MappingResponse`
`400`	Malformed IPv4 CIDR, gateway machine id, or subnet id	`ProblemDetails`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`403`	Gateway is not a member of the caller's Network	`ProblemDetails`
`409`	Join CIDR does not match the target mapping, or the Network address authority is missing	`ProblemDetails`
`500`	Subnet mapping authority unavailable	`ProblemDetails`
`503`	Address allocation retries exhausted; retry	`ProblemDetails`

201 响应

字段	类型	必有	说明
`active_gateway_machine_id`	`string \| null`	否	Gateway currently publishing the mapping, absent while none is healthy.
`display_label`	`string`	是	Operator-facing label derived from the mapping.
`generation`	`integer`	是	Mapping revision; advances when the mapping itself changes.
`mapped_prefix`	`string`	是	Overlay prefix this LAN is reachable at inside the Network.
`real_cidr`	`string`	是	Real IPv4 LAN CIDR, normalized to the network address.
`selection_generation`	`integer`	是	Active-gateway selection revision; advances on every failover.
`standby_gateway_machine_ids`	`array<string>`	是	Gateways that have joined the mapping and can take over.
`subnet_id`	`integer`	是	Stable subnet mapping ID within the Network.
`withdrawn`	`boolean`	是	Whether the mapping was withdrawn. Its allocation is retained and never reused, so a withdrawn mapping still occupies its prefix.

{
  "active_gateway_machine_id": "n-01K4NODE000000000000000",
  "display_label": "example",
  "generation": 1,
  "mapped_prefix": "100.96.10.0/24",
  "real_cidr": "192.168.10.0/24",
  "selection_generation": 1,
  "standby_gateway_machine_ids": [
    "n-01K4NODE000000000000000"
  ],
  "subnet_id": 1,
  "withdrawn": false
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

撤销子网路由

DELETE/api/v1/subnets/{subnet_id}full

参数

名称	位置	类型	必填	说明
`subnet_id`	path	`integer`	是	Stable subnet mapping ID.

请求示例

curl --silent --show-error --fail-with-body -X DELETE \
  "$NSD_BASE_URL/subnets/${SUBNET_ID}" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`204`	Mapping withdrawn; its allocation is retained and never reused	`—`
`400`	Malformed subnet id	`ProblemDetails`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`404`	No such mapping in the caller's Network	`ProblemDetails`
`500`	Subnet mapping authority unavailable	`ProblemDetails`

204 响应

成功，无响应体。

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

读取流量用量

GET/api/v1/usageread-only / full

参数

名称	位置	类型	必填	说明
`from`	query	`integer \| null`	否	Count only reports whose window starts at or after this instant.
`to`	query	`integer \| null`	否	Count only reports whose window ends at or before this instant.

请求示例

curl --silent --show-error --fail-with-body -X GET \
  "$NSD_BASE_URL/usage" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`200`	Gateway-metered usage for the caller's realm	`UsageReadoutDto`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`

200 响应

字段	类型	必有	说明
`by_path`	`array<UsageLineDto>`	是	Stably ordered by `(path_class, subject_kind, subject_id)`.
`by_path[].connections_opened`	`integer \| null`	否	Connections opened, summed. Telemetry, never billed.
`by_path[].connections_peak`	`integer \| null`	否	Peak concurrent connections — the `MAX`, never a sum.
`by_path[].path_class`	`string`	是	`terminate` \| `wg_relay` \| `wss_relay` \| `gateway_egress` \| `gateway_exit` \| `public_edge`.
`by_path[].rx_bytes`	`string`	是	Bytes client → gateway, summed.
`by_path[].subject_id`	`string \| null`	否	The machine or user id. Absent on a realm aggregate.
`by_path[].subject_kind`	`string \| null`	否	`machine` \| `user`. Absent on a realm aggregate.
`by_path[].tx_bytes`	`string`	是	Bytes gateway → client, summed.
`from`	`integer \| null`	否	Echo of the requested lower bound.
`org_id`	`string`	是	Billing org that owns the realm.
`realm`	`string`	是	Realm the usage belongs to (the caller's).
`to`	`integer \| null`	否	Echo of the requested upper bound.
`total`	`UsageTotalsDto`	是	Summed across every line in `by_path`.
`total.rx_bytes`	`string`	是	Total bytes client → gateway.
`total.tx_bytes`	`string`	是	Total bytes gateway → client.

{
  "by_path": [
    {
      "connections_opened": 1,
      "connections_peak": 1,
      "path_class": "example",
      "rx_bytes": "example",
      "subject_id": "01K4EXAMPLE0000000000000",
      "subject_kind": "example",
      "tx_bytes": "example"
    }
  ],
  "from": 1,
  "org_id": "01K4EXAMPLE0000000000000",
  "realm": "example",
  "to": 1,
  "total": {
    "rx_bytes": "example",
    "tx_bytes": "example"
  }
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

读取活动日志

GET/api/v1/audit-eventsread-only / full

参数

名称	位置	类型	必填	说明
`limit`	query	`integer \| null`	否	Maximum number of events to return per page.
`cursor`	query	`string \| null`	否	Cursor pagination: last id of the previous page. The audit ledger is descending (newest first), so this anchors `id < cursor`.
`since`	query	`integer \| null`	否	Server-side time lower bound (unix seconds): keep events with `ts >=`.
`outcome`	query	`string \| null`	否	Server-side exact outcome filter (`success` \| `denied` \| `error`).
`q`	query	`string \| null`	否	Server-side case-insensitive substring search on action / actor / resource.

请求示例

curl --silent --show-error --fail-with-body -X GET \
  "$NSD_BASE_URL/audit-events?limit=100" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`200`	Realm-scoped audit events (paginated; supports `outcome` and `q` query filters)	`ListAuditEventsResponse`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`

200 响应

字段	类型	必有	说明
`items`	`array<AuditEventView>`	是	Audit events in this page.
`items[].action`	`string`	是	Action string.
`items[].actor_id`	`string \| null`	否	Actor id.
`items[].actor_label`	`string`	是	Actor label.
`items[].actor_type`	`string`	是	Actor type.
`items[].error_detail`	`string \| null`	否	Error detail.
`items[].id`	`string`	是	Audit event ULID.
`items[].ip`	`string \| null`	否	Source IP.
`items[].outcome`	`string`	是	Outcome.
`items[].realm_id`	`string`	是	Realm ULID.
`items[].resource_id`	`string \| null`	否	Resource id.
`items[].resource_label`	`string \| null`	否	Resource label.
`items[].resource_type`	`string`	是	Resource type.
`items[].ts`	`string`	是	Timestamp.
`next_cursor`	`string \| null`	否	Cursor for the next page, or `null`.

{
  "items": [
    {
      "action": "allow",
      "actor_id": "01K4EXAMPLE0000000000000",
      "actor_label": "example",
      "actor_type": "example",
      "error_detail": "example",
      "id": "01K4EXAMPLE0000000000000",
      "ip": "example",
      "outcome": "example",
      "realm_id": "01K4EXAMPLE0000000000000",
      "resource_id": "01K4EXAMPLE0000000000000",
      "resource_label": "example",
      "resource_type": "example",
      "ts": "example"
    }
  ],
  "next_cursor": "example"
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

返回 API 参考总览。

#子网路由与运行数据

#列出子网路由

#请求示例

#响应状态

#200 响应

#创建或加入子网路由

#请求体

#请求示例

#响应状态

#201 响应

#撤销子网路由

#参数

#请求示例

#响应状态

#204 响应

#读取流量用量

#参数

#请求示例

#响应状态

#200 响应

#读取活动日志

#参数

#请求示例

#响应状态

#200 响应

子网路由与运行数据

列出子网路由

请求示例

响应状态

200 响应

创建或加入子网路由

请求体

请求示例

响应状态

201 响应

撤销子网路由

参数

请求示例

响应状态

204 响应

读取流量用量

参数

请求示例

响应状态

200 响应

读取活动日志

参数

请求示例

响应状态

200 响应