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

11 KiB

系统运行与异常任务

管理员入口:/admin/operations。沿用 Venix 管理主题,任务列表由业务数据库直接渲染;运行检查随后异步加载,不等待宿主机 Agent 才显示任务。

宿主机容量和公网 IP 以资源池、调度策略及面板 reservation/IP 账本为准。本页不触发宿主机盘点,也不依赖盘点诊断表;实例创建和换 IP 请求会把具体 reservation、地址池、IP 与 operation_id 交给目标宿主机 Agent 做最终校验。响应不确定时按操作标识核对,不能重复执行原请求。

查看范围

  • 覆盖创建、电源操作、重装、救援、删除及到期、流量策略任务。
  • 默认“需要关注”:失败、待核对、needs_attention、已可调度超过 5 分钟且无有效租约的排队任务、执行租约已过期的运行中任务。未来的重试等待和无租约的正常核对轮次不会仅因等待而标为租约过期。
  • 可按任务状态、类型、宿主机、任务编号、操作标识、实例名称或 UUID 筛选;每页 20/50/100 条。摘要统计跟随当前筛选。
  • 详情区分操作人和实例所属用户,展示调度时间、尝试次数、脱敏错误和关联入口。实例已经删除或关联丢失时仍保留任务记录,不猜测所属用户。
  • Agent 返回的稳定 cause_code 仅在管理员任务 DTO 中映射为 agent_cause_code,用于定位最初根因。管理员详情只显示固定白名单生成的中文处理提示,不直接显示机器码、路径或自由文本;目前覆盖原生外部快照、正在删除的原生快照、共享磁盘、共享过滤器和正常关机结果不明。该字段不进入普通用户 DTO,也不替换面板公开 error_code。

列表、详情和健康检查保持数据库快照读取。超级管理员处理异常任务时使用四种分离的操作:

  1. 立即核对:仅对已经记录 dispatched_at 的任务显示。面板调用 Agent 的只读 inspect,只读取 Domain、XML、当前 job、卷、过滤器和存储池证据。证据明确时,面板使用 Agent 签发的 64 位核对凭证调用 confirm-inspection;Agent 再执行一次新鲜的只读核对且凭证完全匹配后,才把同一 operation 的 Journal 和 PHP 账本收敛到终态。该流程不继续目标状态、不清理宿主机资源,也不接受网页指定成功或失败;证据变化或不足时保留原 blocker。尚未下发的任务直接以面板记录为准,不向 Agent 发出无效核对。
  2. 停止自动核对:只在数据库事务中将未结束任务标记为 cancelled、清除执行租约并阻止后续 worker 领取。不删除任务、不退款,也不向 Agent 或 libvirt 发送中止请求。已经派发的调用仍可能完成并返回。
  3. 请求中止 libvirt 作业:当前只在立即核对确认 Domain 存在与该快照操作、目标卷和 backup XML 精确匹配的 push backup 时可用。请求必须带回核对签发的 inspection_token;Agent 在中止前重新验证,发出中止后继续只读核对终态。系统目前不持久化 block job 归属,因此发现 block job 只会阻止清理,不会显示中止按钮。
  4. 清理已确认残留:只有立即核对返回明确、非空的清理步骤和 plan_id 时可用。网页必须展示步骤并二次确认;Agent 执行前重新核对同一计划,计划变化则拒绝。

请求中止作业与清理残留不会同时可用。普通待核对任务最多同时展示“立即核对”“停止自动核对”以及其中一个受证据约束的动作。正常删除或到期清理只有在 ShutdownFlags 已确认成功、原调用完成正常关机等待且 Domain 仍活动时才进入 force_required,退出自动 worker;从派发崩溃恢复、关机请求返回错误或只读核对观察到 Domain 活动都不能产生该授权。派发边界崩溃留下的无 cause uncertain/needs_attention 在重新取得资源准入、确认 Domain 仍活动后,会明确失败为“正常关机未确认”,释放旧 operation blocker,并允许面板或生命周期用新的 operation ID 重新发起正常关机;仍处于 dispatching 的在途调用不能这样结案。关机请求返回错误后若来宾始终活动,旧任务同样明确失败并允许新 operation 重试;若活动状态也无法读取,旧任务保留待核对,之后只读确认仍活动只能把它结案为未确认失败。以上路径都不能授权强制删除。只有超级管理员明确确认 ack_data_loss=true 后,面板才以新的 operation_id 创建独立 force-delete 任务。自动核对绝不跨过该边界。强制任务活跃时隐藏重复按钮;明确失败后原任务恢复 force_required。强制调用已派发但结果丢失且 Domain 仍活动时,自动核对继续保持不确定;管理员执行“立即核对”后,Agent 用 token 绑定的第二次新鲜读确认旧强制 operation 失败,面板才恢复原任务的确认入口,管理员必须再次确认数据丢失风险并创建新的强制 operation。原生外部快照、revertDisks 或未完成快照删除会阻止删除;管理员必须先在宿主机安全完成原生快照处理,再立即核对。快照/删除关联状态会保守保留为待核对,租约过期不等于操作失败,不应据此手动重放破坏性操作。

普通 worker 只领取 queued、running 和 uncertain。同一任务自动核对达到 12 次或达到 6 小时后,面板把它置为 needs_attention 并停止领取;已派发任务从首次派发计时,面板事务在写入派发时间前异常而进入 uncertain 的任务从创建时间计时,普通 queued 不受该计时上限影响。这一步不把实例、订单或退款伪造成已确认失败。needs_attention 以及已经派发后手动停止的 cancelled 任务仍阻止同实例的冲突操作,也继续保护被创建/重装任务引用的模板。实例删除、到期关机和到期删除不绕过未决 firewall blocker。

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}/stop-auto
POST /api/v1/admin/operations/jobs/{id}/inspect
POST /api/v1/admin/operations/jobs/{id}/abort-job
POST /api/v1/admin/operations/jobs/{id}/cleanup
POST /api/v1/admin/operations/jobs/{id}/force-delete

需要管理员会话,响应禁止缓存,POST 还需要管理端 CSRF 令牌。列表与详情不调用 Agent、不读取任务加密载荷或租约令牌、不返回原始结果 JSON;只有显式核对、中止和清理流程联系任务所属宿主机,强制删除则创建由普通 worker 下发的新任务。PHP 对核对响应采用固定枚举白名单,只向网页返回稳定状态码、中文摘要、作业种类、状态绑定核对凭证和清理步骤;终态确认凭证只在 PHP 与 Agent 之间使用,不返回网页。路径、密钥、原始异常和 libvirt 自由文本均不转发。健康检查按已启用宿主机独立发送签名的 Agent 请求;一个 Agent 离线不应把其他宿主机伪装为离线。重复停止同一任务是幂等的;已完成任务、非允许类型或不存在任务返回受控错误。

本阶段复用 cloud_jobs.status 的 cancelled 和 needs_attention 值,并在现有 kind、error_code 和 result_json 中记录独立强制阶段及审计关联,没有新增面板数据库字段;升级只需同步面板代码、静态资源和 Agent 程序。它不会把既有 cancelled 记录自动改写成新的错误码。

运行状态的含义

  • 业务/日志数据库:只读 SELECT 1 成功,不代表全部表结构或业务数据正确。MySQL 使用独立、非持久连接,连接及读取超时各为 2 秒;仅在支持 mysqlnd 的 PDO 驱动下探测,临时读取超时配置在检查后恢复,不修改应用共享连接。驱动或运行环境不支持短超时设置时显示未知,不回退到无界连接;SQLite 保持原有只读查询。日志库未启用则明确显示未启用。DNS 解析不受这些连接/读取超时完整约束,因此不能将它们理解为整个健康接口的硬总时限。
  • 宿主机 Agent:已认证出站 WSS 会话、内层签名健康接口和本地操作日志可用,不代表每台虚拟机都正常。页面分别展示数字 Agent ID、最后测试时间和受控错误,不存储或展示宿主机 endpoint;健康请求必须有短超时。
  • Redis:配置后检查 PING;独立客户端使用 1 秒连接/读写超时,不影响应用共享客户端,也不验证缓存内容。
  • 普通 worker、策略 worker、生命周期调度:读取本机最近运行记录;不是 systemctl 状态,也不是对进程仍然存活的保证。页面可见时每 30 秒检查一次,不刷新整个任务列表;检查失败时明确标记保留的是旧状态。

“近期上报进程数”不是任务数量,也不能证明期望的全部策略 worker 已启动。新安装、进程尚未启动、心跳不可读或只运行过 --once 时显示未知;不要把未知当作正常。

升级与心跳目录

全新安装由 php xcat cloudInit 创建所需表。worker 在 web/storage/cloud-runtime/ 原子写入私有心跳;网页 PHP 与 worker/lifecycle 应使用同一系统用户。目录不可读时页面显示未知,但心跳观测失败不能阻止 worker 执行业务任务。目录位于 Web 文档根之外并已加入 .gitignore。

已运行的 PHP 常驻进程不会自动载入新代码。使用在线更新流程会重启相关服务;手动更新则按现有维护流程,在任务安全的维护窗口重启普通 worker、生命周期调度和实际部署的全部策略 worker。标准服务名为:

virt-cloud-worker.service
virt-cloud-lifecycle.service
virt-cloud-policy-worker@1.service
virt-cloud-policy-worker@2.service
virt-cloud-update.service
virt-cloud-agent-gateway.service

不要仅为获得心跳而中断正在重装/删除的任务。通过既有服务日志确认任务情况;缺少心跳不会改变现有任务处理逻辑。

观测写入失败不会中止任务。记录只包含固定阶段、固定错误分类和时间,不记录密码、邮箱、载荷或原始异常。每个进程独立记录,读取有数量与大小上限,启动时有限清理超过 7 天的私有旧记录。

新鲜度判断:空闲/错误记录 90 秒;策略 worker 忙碌阶段 180 秒;普通 worker 与生命周期的忙碌阶段 1200 秒。长操作宽限仅用于避免把正常等待立即报为失联,不改变任务超时或租约。超时表示“需检查”,不直接判定进程死亡。内部部分任务或账单/邮件处理失败也记录需关注,成功轮次才清除未恢复错误。

这是面板所在机器的辅助诊断入口:不同机器上的 worker 不共享此目录;面板或主数据库完全不可用时仍需要外部监控和 SSH 日志,不能依赖该页面告警。