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

45 lines
4.8 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 系统运行与异常任务
管理员入口为 `/admin/operations`。页面直接读取业务数据库中的任务与运行心跳;打开列表、详情或任务中心都不会联系 Agent,更不会重新提交宿主机变更。
## 任务语义
- 提交接口只在任务已经持久化后返回 HTTP `202 Accepted`。这表示“任务已接收”,不表示宿主机操作成功。
- 每个任务最多派发一次。派发前拒绝、派发后断线、Agent 超时、worker 退出和回执截止都会在固定期限内落为 `failed`,不会重新排队。
- 终态只有 `succeeded`、`failed`,一旦写入便不可改变。晚到回执不能翻转任务、退款或重放资源变更;策略表覆盖的实例电源、重装/救援、公网 IP、实例设置、实例升级、快照、防火墙、删除/强制删除、生命周期网络、模板与 ISO 叶子任务,可以用精确回执或 operation-bound 只读证据通过种类专用终结器收敛 PHP 账本并解除 effect fence,原任务仍保持 `failed`。
- `effect_may_have_applied=true` 表示底层副作用可能已经发生。任务本身仍然已经结束;破坏性操作的相关资源继续被安全栅栏保护,新的冲突请求会立即返回错误,不会排队等待。固定存储池配置是非破坏性的例外:保留失败证据但不保留跨任务栅栏,可按已定义 pool 的同一路径,或只修正尚未定义的角色后显式创建新任务。
- 普通用户和管理员界面均不提供任务重试按钮。需要再次执行时,必须先完成只读核验和人工处置,再创建一个经过重新授权的新任务。
- 只有具备种类专用业务账本终结器的失败任务才能解除栅栏。上述策略类型会一直保留在低频恢复队列,不受六小时、十二次或其他累计预算限制。Agent 离线、回执错误、操作身份冲突、密文损坏和实例/账本状态矛盾都只会保留安全栅栏并显示具体异常,修复根因后同一 operation 继续核对。开通只允许用新鲜缺失证据确认 `not_applied`,并原子退款与释放资源;支付根据签名回调或管理员已在外部平台核验的证据收敛本地账本。
## 管理操作
管理端只保留以下能力:
```text
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 仍在运行自动产生。
已经删除的通用旧恢复入口——重放 mutation、确认旧检查结果、中止 libvirt job、自动清理残留——不得重新加入路由或前端。内部只读恢复只对显式策略表中、具有种类专用账本终结器的 Agent 叶子任务开放,且只能写与原操作三元身份精确匹配的 Agent 栅栏审计元数据;原任务仍作为不可变审计记录保留。
## 运行状态
- 数据库健康只代表受限的只读探测成功,不代表全部业务正确。
- Agent 健康只代表已认证 WSS 会话、签名 API 和本地 Journal 可用,不代表某台虚拟机正常。
- Redis、worker、生命周期和策略 worker 的状态来自有界探测或本机心跳,不是 `systemctl` 的替代品。
- 健康检查失败只显示故障,不改变任务,不延长任务截止时间,也不触发变更请求。
worker 在 `web/storage/cloud-runtime/` 原子写入不含凭据的私有心跳。读取失败显示未知,但不能阻塞业务任务。常驻 PHP、Gateway 和 Agent 部署新版本后必须显式重启;全新安装只使用当前 SQL 和当前 Agent Journal 格式,不升级旧任务、旧数据库或旧 Journal。
完整状态机、回执和资源安全规则见 [TASK_EXECUTION.md](TASK_EXECUTION.md)。