接口详情
GET /v1/admin/control-upgrade-plan
Read native standalone publication and matching execution status
- operationId
getNativeControlUpgradePlanStatus- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.manage
说明（契约原文）
Available only in explicitly enabled native-standalone mode. Requires a platform session with control.upgrades.manage and rejects every query parameter. This no-store projection does not expose signed bundle bytes, download URLs, tokens, process identifiers, or filesystem paths. Unknown, corrupt, stale, or mismatched execution evidence is unavailable, never an invented not_started or success. Publication revision is zero exactly when publication is null. A running or completed execution is bound to that publication's plan, bundle digest, release sequence and, for a receipt, its versions and native-standalone target.
响应
getNativeControlUpgradePlanStatus 响应| 状态码 | 说明 |
|---|
200 | Installation-bound publication, execution, and runtime readiness. 字段：schema: string observed_at: string(date-time) mode: string publication_revision: integer(int64) publication: PublicationReceipt | null execution: NativeExecutionStatus runtime: object |
|---|
400 | Stable error code and request identifier. |
|---|
401 | Stable error code and request identifier. |
|---|
403 | Stable error code and request identifier. |
|---|
503 | Stable error code and request identifier. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/control-upgrade-plan
Publish a verified signed control-plane upgrade bundle
- operationId
publishControlUpgradePlan- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.manage
说明（契约原文）
Requires a platform session with control.upgrades.manage. If-Match is the current publication revision and Idempotency-Key is bound to the exact signed bundle. The bundle is verified against the local License trust snapshot before the Kubernetes Secret or installation-bound systemd PostgreSQL repository is updated with revision compare-and-swap. Systemd HA uses the same repository as the internal plan source and does not relax its strict-majority quorum. Native-standalone uses a separate root-owned executor, package digest and fail-closed maintenance gate; a new publication requires a trusted ready runner and recent authenticated plan-source read. It may interrupt the single management host and is not an HA upgrade. An exact authenticated native replay remains a read-only operation during drain and after the installed version changes: raw bundle bytes, idempotency key, expected revision, actor and scope must match the durable publication. The original publication receipt and ETag are returned.
参数
publishControlUpgradePlan 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
If-Match | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
响应
publishControlUpgradePlan 响应| 状态码 | 说明 |
|---|
201 | A new monotonic publication was persisted. 字段：schema: string receipt_id: string plan_id: string(uuid) bundle_sha256: string publication_revision: integer(int64) expected_revision: integer(int64) channel_revision: integer(int64) release_sequence: integer(int64) installation_id: string(uuid) component: string current_version: string current_digest: string target_version: string target_digest: string rollback_version: string rollback_digest: string protocol_version: integer idempotency_sha256: string request_id: string actor_user_id: string(uuid) actor_scope_id: string(uuid) published_at: integer(int64) |
|---|
200 | The exact idempotent publication was replayed without another write. 字段：schema: string receipt_id: string plan_id: string(uuid) bundle_sha256: string publication_revision: integer(int64) expected_revision: integer(int64) channel_revision: integer(int64) release_sequence: integer(int64) installation_id: string(uuid) component: string current_version: string current_digest: string target_version: string target_digest: string rollback_version: string rollback_digest: string protocol_version: integer idempotency_sha256: string request_id: string actor_user_id: string(uuid) actor_scope_id: string(uuid) published_at: integer(int64) |
|---|
400 | Stable error code and request identifier. |
|---|
401 | Stable error code and request identifier. |
|---|
403 | Stable error code and request identifier. |
|---|
409 | Stable error code and request identifier. |
|---|
415 | Stable error code and request identifier. |
|---|
503 | Stable error code and request identifier. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/control-upgrade-plan/issue
Have the License service issue a signed plan and publish it
- operationId
issueNativeControlUpgradePlan- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.manage
说明（契约原文）
Available only in native-standalone mode. Requires a platform session with control.upgrades.manage, exactly one Idempotency-Key and no query parameter. The control API asks the License service for a parent upgrade grant (the channel target, the pin, or requested_artifact_id from the version picker) and a signed plan artifact bundle, then publishes it as POST /v1/admin/control-upgrade-plan does, at the current publication revision. A target the License service refuses is 409 upgrade_target_blocked with its reason_code (for example same_version when the parent grant is a reinstall, downgrade_not_supported for a rollback). Any other License business refusal (403/409/422 with a code) is passed through as 409 with the License code, for example upgrade_plan_artifact_bundle_unavailable or installation_banned. Only an unreachable License service, a timeout or a License 5xx is 503 control_upgrade_state_unavailable. Without a License client the answer is 503 plan_source_unavailable; a draining master is 503 control_upgrade_draining.
参数
issueNativeControlUpgradePlan 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
issueNativeControlUpgradePlan 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
requested_artifact_id | string(uuid) | 否 | The chosen option's artifact_id (lower case canonical UUID); absent keeps the channel target or the pin. |
|---|
响应
issueNativeControlUpgradePlan 响应| 状态码 | 说明 |
|---|
201 | A new monotonic publication was persisted. 字段：schema: string receipt_id: string plan_id: string(uuid) bundle_sha256: string publication_revision: integer(int64) expected_revision: integer(int64) channel_revision: integer(int64) release_sequence: integer(int64) installation_id: string(uuid) component: string current_version: string current_digest: string target_version: string target_digest: string rollback_version: string rollback_digest: string protocol_version: integer idempotency_sha256: string request_id: string actor_user_id: string(uuid) actor_scope_id: string(uuid) published_at: integer(int64) |
|---|
200 | The exact idempotent publication was replayed without another write. 字段：schema: string receipt_id: string plan_id: string(uuid) bundle_sha256: string publication_revision: integer(int64) expected_revision: integer(int64) channel_revision: integer(int64) release_sequence: integer(int64) installation_id: string(uuid) component: string current_version: string current_digest: string target_version: string target_digest: string rollback_version: string rollback_digest: string protocol_version: integer idempotency_sha256: string request_id: string actor_user_id: string(uuid) actor_scope_id: string(uuid) published_at: integer(int64) |
|---|
400 | Stable error code and request identifier. |
|---|
401 | Stable error code and request identifier. |
|---|
403 | Stable error code and request identifier. |
|---|
409 | version_conflict, idempotency_conflict, control_upgrade_plan_conflict, a passed-through License refusal code (ErrorEnvelope), or upgrade_target_blocked with reason_code. |
|---|
415 | Stable error code and request identifier. |
|---|
503 | Stable error code and request identifier. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/control-upgrade-plan/options
List the versions the master may upgrade to (version picker)
- operationId
listNativeControlUpgradeOptions- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.manage
说明（契约原文）
Available only in native-standalone mode. Requires a platform session with control.upgrades.manage and rejects every query parameter. The License service lists the installation's selectable versions for the running control API version and protocol. Without a License client the answer is 503 plan_source_unavailable; a License service that cannot list versions is 503 upgrade_options_unavailable.
响应
listNativeControlUpgradeOptions 响应| 状态码 | 说明 |
|---|
200 | The License service's upgrade options. 字段：schema: string observed_at: string(date-time) options: UpgradeOptions |
|---|
400 | Stable error code and request identifier. |
|---|
401 | Stable error code and request identifier. |
|---|
403 | Stable error code and request identifier. |
|---|
503 | Stable error code and request identifier. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/control-upgrade-plan/run-log
Read the native master upgrade script log and service-log tail
- operationId
getNativeControlUpgradeRunLog- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：control.upgrades.manage
说明（契约原文）
Available only in native-standalone mode. Requires a platform session with control.upgrades.manage and rejects every query parameter. The root-owned runner publishes a bounded log for the current execution: stable event and reason codes (rendered per locale by the console, never server text) and, at terminal points, the last journal lines of the control API, gateway and runner. Journal lines are stripped of control characters and redacted (URL query strings and userinfo, bearer/basic credentials, JWTs, secret-named flags and key/value pairs, private keys) by the runner and again before this response. Download events record only the artifact host. A log of another plan or sequence, or one that is missing or corrupt, is state unavailable with a null run_log.
响应
getNativeControlUpgradeRunLog 响应| 状态码 | 说明 |
|---|
200 | The current execution's run log, or unavailable. 字段：schema: string observed_at: string(date-time) state: string: available / unavailable run_log: NativeRunLog | null |
|---|
400 | Stable error code and request identifier. |
|---|
401 | Stable error code and request identifier. |
|---|
403 | Stable error code and request identifier. |
|---|
503 | Stable error code and request identifier. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表