You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/docs/ADMIN_OPERATIONS.md

4.2 KiB

系统运行与异常任务

管理员入口为 /admin/operations。页面直接读取业务数据库中的任务与运行心跳;打开列表、详情或任务中心都不会联系 Agent,更不会重新提交宿主机变更。

任务语义

  • 提交接口只在任务已经持久化后返回 HTTP 202 Accepted。这表示“任务已接收”,不表示宿主机操作成功。
  • 每个任务最多派发一次。派发前拒绝、派发后断线、Agent 超时、worker 退出和回执截止都会在固定期限内落为 failed,不会重新排队。
  • 终态只有 succeeded、failed,一旦写入便不可改变。晚到回执只能得到幂等 ACK,不能翻转任务、退款或释放资源。
  • effect_may_have_applied=true 表示底层副作用可能已经发生。任务本身仍然已经结束;破坏性操作的相关资源继续被安全栅栏保护,新的冲突请求会立即返回错误,不会排队等待。固定存储池配置是非破坏性的例外:保留失败证据但不保留跨任务栅栏,可按已定义 pool 的同一路径,或只修正尚未定义的角色后显式创建新任务。
  • 普通用户和管理员界面均不提供任务重试按钮。需要再次执行时,必须先完成只读核验和人工处置,再创建一个经过重新授权的新任务。
  • 只有具备种类专用业务账本终结器的失败任务才能解除栅栏。开通只允许用新鲜缺失证据确认 not_applied,并原子退款与释放资源;支付根据签名回调或管理员已在外部平台核验的证据收敛本地账本。其他类型当前拒绝假解锁,但任务本身已是终态失败,不会继续占用 worker 或重试。

管理操作

管理端只保留以下能力:

GET  /api/v1/admin/operations
GET  /api/v1/admin/operations/jobs/{id}
GET  /api/v1/admin/operations/health
POST /api/v1/admin/operations/jobs/{id}/inspect
POST /api/v1/admin/operations/jobs/{id}/resolve-effect
POST /api/v1/admin/operations/jobs/{id}/force-delete

这些接口需要管理员会话,响应禁止缓存,POST 需要管理端 CSRF 令牌。

  1. inspect 是独立的只读检查。它可以读取 Agent Journal、Domain/XML、当前 libvirt job、卷、过滤器和存储池证据,但不能调用 destroy、undefine、define、卷删除、过滤器删除、作业中止或原 mutation 的任何续作。检查结果不会改变原任务终态。
  2. resolve-effect 只允许超级管理员在完成新鲜证据核验后使用。开通路径可向 Agent 写入一次不调用 libvirt 的审计栅栏元数据,然后在 PHP 同一事务完成退款和资源释放;响应丢失时只做一次只读核验,不重发写请求。支付路径不联系 Agent 或重新向渠道下单。原任务始终保持 failed。
  3. force-delete 是单独授权的新破坏性任务。它需要既有正常删除任务已经明确返回 force_required,并要求超级管理员再次确认数据丢失风险;它不能由超时、失联或仅看到 Domain 仍在运行自动产生。

已经删除的旧恢复入口——停止自动核对、自动 reconcile、确认旧检查结果、中止 libvirt job、清理残留——不得重新加入路由或前端。宿主机人工维护必须在变更窗口完成,并以新的只读检查确认结果;原任务只作为不可变审计记录保留。

运行状态

  • 数据库健康只代表受限的只读探测成功,不代表全部业务正确。
  • Agent 健康只代表已认证 WSS 会话、签名 API 和本地 Journal 可用,不代表某台虚拟机正常。
  • Redis、worker、生命周期和策略 worker 的状态来自有界探测或本机心跳,不是 systemctl 的替代品。
  • 健康检查失败只显示故障,不改变任务,不延长任务截止时间,也不触发变更请求。

worker 在 web/storage/cloud-runtime/ 原子写入不含凭据的私有心跳。读取失败显示未知,但不能阻塞业务任务。常驻 PHP、Gateway 和 Agent 部署新版本后必须显式重启;全新安装只使用当前 SQL 和当前 Agent Journal 格式,不升级旧任务、旧数据库或旧 Journal。

完整状态机、回执和资源安全规则见 TASK_EXECUTION.md。