接口详情
GET /v1/admin/packages
List and filter package products
- operationId
listPackages- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. Unknown or repeated query parameters are rejected.
参数
listPackages 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
search | query | string | 否 | Case-insensitive substring match against the product name. |
|---|
group_id | query | string(uuid) | 否 | Return products whose group_ids contain this exact group UUID. |
|---|
enabled | query | boolean | 否 | — |
|---|
published | query | boolean | 否 | true keeps only products whose current revision is published (purchasable); false only the others. |
|---|
响应
listPackages 响应| 状态码 | 说明 |
|---|
200 | Stable product page ordered by sort order and then name. 字段：items: array<PackageProduct> total: integer(int64) page: integer limit: integer |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/packages
Create a versioned package product
- operationId
createPackage- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. Referenced package groups must exist and be active. Region and node-group UUIDs are currently opaque configuration references and are not validated against region or node-group resources. A reseller's main and backup line groups must be platform line groups granted to it (scope_may_use_line_group_460); an ungranted one returns 400 package_line_group_not_granted. A reseller price below the wholesale price of its line groups in its price list returns 400 package_price_below_wholesale with details period, price_minor, wholesale_minor and price_list.
参数
createPackage 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createPackage 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
description | string | 是 | — |
|---|
group_ids | array<string(uuid)> | 是 | Active package-group UUIDs. These references are validated by the catalog service. |
|---|
region_id | string(uuid) | 是 | Opaque non-zero region UUID. The current catalog does not validate a backing region resource. |
|---|
node_group_id | string(uuid) | 是 | Opaque non-zero primary node-group UUID. The current catalog does not validate a backing node-group resource. |
|---|
backup_node_group_id | string(uuid) | null(uuid) | 是 | Optional opaque backup node-group UUID; when set it must differ from node_group_id. No backing resource existence check is implemented yet. |
|---|
limits | PackageResourceLimits | 是 | — |
|---|
protection | PackageProtectionDescription | 是 | — |
|---|
prices | PackagePrices | 是 | — |
|---|
cname | PackageCNAMEPolicy | 是 | — |
|---|
purchase | PackagePurchasePolicy | 是 | — |
|---|
sort_order | integer | 是 | — |
|---|
enabled | boolean | 是 | Set false to disable the package in the product catalog. |
|---|
响应
createPackage 响应| 状态码 | 说明 |
|---|
201 | Product and immutable revision-one snapshot created, or an identical idempotent request replayed. 字段：id: string(uuid) owner_scope_id: string(uuid) spec: PackageProductSpec revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) cname_sync_job_id?: string(uuid) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/packages/{id}
Get one active package product
- operationId
getPackage- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied.
参数
getPackage 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | Package group or package product UUID. |
|---|
响应
getPackage 响应| 状态码 | 说明 |
|---|
200 | Current product specification and revision. 字段：id: string(uuid) owner_scope_id: string(uuid) spec: PackageProductSpec revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) cname_sync_job_id?: string(uuid) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PATCH /v1/admin/packages/{id}
Replace a package specification, including enable or disable state
- operationId
updatePackage- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. expected_revision is checked atomically, and every successful change creates a new immutable revision snapshot. Region and node-group UUIDs remain opaque configuration references without resource existence validation. A reseller's main and backup line groups must be platform line groups granted to it (scope_may_use_line_group_460); an ungranted one returns 400 package_line_group_not_granted. A reseller price below the wholesale price of its line groups in its price list returns 400 package_price_below_wholesale with details period, price_minor, wholesale_minor and price_list.
参数
updatePackage 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | Package group or package product UUID. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
updatePackage 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
spec | PackageProductSpec | 是 | — |
|---|
响应
updatePackage 响应| 状态码 | 说明 |
|---|
200 | Product specification replaced and revision incremented, or an identical idempotent request replayed. 字段：id: string(uuid) owner_scope_id: string(uuid) spec: PackageProductSpec revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) cname_sync_job_id?: string(uuid) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
DELETE /v1/admin/packages/{id}
Soft-delete a package product
- operationId
deletePackage- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. If-Match supplies the expected revision, and the deletion is recorded as the next immutable product snapshot.
参数
deletePackage 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | Package group or package product UUID. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
响应
deletePackage 响应| 状态码 | 说明 |
|---|
204 | Product soft-deleted, or an identical idempotent request replayed. |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/packages/{id}/cname-sync/{job_id}
Progress of the sync of a package CNAME change to its sold subscriptions
- operationId
getPackageCNAMESync- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. The job is created by the package update that changed the CNAME (cname_sync_job_id). skipped lists at most 200 subscriptions; skipped_count is the total.
参数
getPackageCNAMESync 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | Package group or package product UUID. |
|---|
job_id | path | string(uuid) | 是 | Package CNAME sync job UUID (cname_sync_job_id of the package update response). |
|---|
响应
getPackageCNAMESync 响应| 状态码 | 说明 |
|---|
200 | Sync job counters and skipped subscriptions. 字段：id: string(uuid) product_id: string(uuid) product_revision: integer(int64) state: string: queued / running / succeeded / failed synced_count: integer(int64) site_count: integer(int64) skipped_count: integer(int64) attempt: integer max_attempts: integer last_error_code: string | null skipped: array<object> created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/packages/{id}/cname-sync/{job_id}/retry
Retry a failed package CNAME sync with the caller's session
- operationId
retryPackageCNAMESync- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. Only a failed job (for example actor_session_ended) can be retried; already processed subscriptions are not processed again.
参数
retryPackageCNAMESync 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | Package group or package product UUID. |
|---|
job_id | path | string(uuid) | 是 | Package CNAME sync job UUID (cname_sync_job_id of the package update response). |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
响应
retryPackageCNAMESync 响应| 状态码 | 说明 |
|---|
200 | Job requeued. 字段：id: string(uuid) product_id: string(uuid) product_revision: integer(int64) state: string: queued / running / succeeded / failed synced_count: integer(int64) site_count: integer(int64) skipped_count: integer(int64) attempt: integer max_attempts: integer last_error_code: string | null skipped: array<object> created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/packages/{id}/publish
Publish the current immutable package product revision
- operationId
publishPackageOffer- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：packages.manage
说明（契约原文）
The platform needs packages.manage; an active reseller tenant may publish only its own package with reseller.packages.manage. A reseller package whose line group grant was revoked, or whose price fell below the wholesale price, cannot be published again (400 package_line_group_not_granted / package_price_below_wholesale). packages.count counts the owner's published packages.
参数
publishPackageOffer 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive immutable product revision. |
|---|
Idempotency-Key | header | string | 是 | Exact retries reuse this key with the same action, product, and revision. |
|---|
响应
publishPackageOffer 响应| 状态码 | 说明 |
|---|
200 | Current durable publication head or identical committed replay. 字段：product_id: string(uuid) product_revision: integer(int64) lifecycle_revision: integer(int64) state: string: published / withdrawn published_at: string(date-time) withdrawn_at?: string(date-time) |
|---|
400 | Stable package publication error. |
|---|
401 | Stable package publication error. |
|---|
403 | Stable package publication error. |
|---|
404 | Stable package publication error. |
|---|
409 | Stable package publication error. |
|---|
412 | Stable package publication error. |
|---|
422 | Stable package publication error. |
|---|
503 | Stable package publication error. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/packages/{id}/withdraw
Withdraw the exact immutable package revision named by If-Match
- operationId
withdrawPackageOffer- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：packages.manage
说明（契约原文）
If-Match binds the previously published product revision, not a newer mutable draft revision. Existing sold subscriptions remain unchanged. An active reseller tenant may withdraw only its own package (reseller.packages.manage); revoking a line group grant withdraws the reseller packages that use it.
参数
withdrawPackageOffer 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive immutable product revision. |
|---|
Idempotency-Key | header | string | 是 | Exact retries reuse this key with the same action, product, and revision. |
|---|
响应
withdrawPackageOffer 响应| 状态码 | 说明 |
|---|
200 | Current durable publication head or identical committed replay. 字段：product_id: string(uuid) product_revision: integer(int64) lifecycle_revision: integer(int64) state: string: published / withdrawn published_at: string(date-time) withdrawn_at?: string(date-time) |
|---|
400 | Stable package publication error. |
|---|
401 | Stable package publication error. |
|---|
403 | Stable package publication error. |
|---|
404 | Stable package publication error. |
|---|
409 | Stable package publication error. |
|---|
412 | Stable package publication error. |
|---|
422 | Stable package publication error. |
|---|
503 | Stable package publication error. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/packages/{product_id}/escalate-policy
Read a package's attack escalation policy
- operationId
getPackageEscalatePolicy- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：packages.manage reseller.packages.manage
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; only the package owner (owner_scope_id) reads it, another owner's package returns 403 escalate_permission_denied.
参数
getPackageEscalatePolicy 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
product_id | path | string(uuid) | 是 | — |
|---|
响应
getPackageEscalatePolicy 响应| 状态码 | 说明 |
|---|
200 | The package policy. 字段：product_id?: string(uuid) b: LineGroupRef | null c: LineGroupRef | null c_cloudflare: boolean blackhole_enabled: boolean thresholds: object sustain_seconds: integer recover_permille: integer min_dwell_seconds: integer revision: integer(int64) b_line_group_name?: string c_line_group_name?: string |
|---|
400 | Error. |
|---|
401 | Error. |
|---|
403 | Error. |
|---|
404 | Error. |
|---|
503 | Error. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
PUT /v1/admin/packages/{product_id}/escalate-policy
Write a package's B/C line groups, Cloudflare and blackhole switches and threshold ranges
- operationId
putPackageEscalatePolicy- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：packages.manage reseller.packages.manage
需要开通的功能：module.escalate
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; only the package owner (owner_scope_id) writes it, another owner's package returns 403 escalate_permission_denied. A is the package's main line group. B must be a high defense line group and C an unlimited one the package owner may use (its own or granted to the reseller, 422 escalate_line_group_unusable otherwise). revision is the current revision (0 creates).
参数
putPackageEscalatePolicy 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
product_id | path | string(uuid) | 是 | — |
|---|
请求体
application/json · 必填：是
putPackageEscalatePolicy 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
product_id | string(uuid) | 否 | — |
|---|
b | LineGroupRef | null | 是 | — |
|---|
c | LineGroupRef | null | 是 | — |
|---|
c_cloudflare | boolean | 是 | C may use the site owner's Cloudflare when bound and synced. |
|---|
blackhole_enabled | boolean | 是 | — |
|---|
thresholds | object | 是 | — |
|---|
sustain_seconds | integer | 是 | — |
|---|
recover_permille | integer | 是 | — |
|---|
min_dwell_seconds | integer | 是 | — |
|---|
revision | integer(int64) | 是 | — |
|---|
b_line_group_name | string | 否 | Name of B's line group, filled on every read; absent when B is null. A write ignores it. |
|---|
c_line_group_name | string | 否 | Name of C's line group, filled on every read; absent when C is null. A write ignores it. |
|---|
响应
putPackageEscalatePolicy 响应| 状态码 | 说明 |
|---|
200 | The package policy. 字段：product_id?: string(uuid) b: LineGroupRef | null c: LineGroupRef | null c_cloudflare: boolean blackhole_enabled: boolean thresholds: object sustain_seconds: integer recover_permille: integer min_dwell_seconds: integer revision: integer(int64) b_line_group_name?: string c_line_group_name?: string |
|---|
400 | Error. |
|---|
401 | Error. |
|---|
403 | Error. |
|---|
404 | Error. |
|---|
409 | Error. |
|---|
422 | Error. |
|---|
503 | Error. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表