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/SERVICE_COMPENSATION.md

66 lines
5.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.

# 实例可用时间补偿
实例可用时间补偿用于故障后由管理员延长受影响实例的预付费服务期限。它是 PHP 和数据库内的业务账本操作,不联系宿主机 Agent,也不更改虚拟机电源、磁盘或网络配置。
## 管理范围与资格
管理员在 `/admin/service-compensations` 先预览,再按预览返回的 `audience_digest` 创建批次。支持三种范围:
- 单个实例;
- 某个计算节点上的全部实例;
- 某个公网地址池当前持有的实例。
只有未删除、`service_status=active`、当前到期时间仍在未来,且具有一致尾服务周期的实例可以进入执行队列。过期、豁免、已删除、尾周期缺失或账本矛盾的实例不会被猜测补偿;它们分别记录为拒绝或需核对。相同 `incident_key + instance_id` 只能存在一次,避免同一事故重复加时。预览后实例范围或资格变化会使旧摘要失效,管理员必须重新预览。
## 账本效果
每个成功明细在一个数据库事务中完成以下投影:
1. 将实例 `expires_at` 和当时最新的尾服务周期结束时间增加相同秒数;
2. 若该周期已有有限流量权益,只延长该权益的结束窗口,不增加总字节,也不创建新的流量权益;
3. 若该周期已有自动备份权益,只延长该权益的结束窗口,不新建、不重新启用已不存在的备份权益;
4. 写入终态、本地 `dispatch_attempts=0` 的实例操作审计任务,供用户实例操作记录和管理员任务中心查询;
5. 原子记录补偿前后到期时间及关联账本 ID。
补偿不修改用户余额,不扣款、不退款、不生成账单或零元账单,也不改变套餐、续费价格和流量字节额度。成功后只显示最新到期时间,不另外维护一个会与真实账本漂移的“累计补偿”字段。
未支付续费账单若仍以旧到期时间为锚点,会按新的到期时间重新判断提醒窗口;支付创建中、支付结果未知或已结算结果与服务账本矛盾时,明细不会越过资金栅栏。可安全等待的情况进入 `deferred`,证据矛盾进入 `attention`,两者都不能用人工重复创建同一事故来绕过。
## 执行、租约和审计
普通 `cloudWorker` 每轮最多领取一个补偿明细。明细使用 120 秒租约;租约丢失、数据库或投影暂时故障使用有界尝试和指数退避。已确认补偿还未发生、只是在等待删除、迁移、实例任务或支付收敛时,则每 300 秒重新核对原状态且不消耗技术失败预算;外部状态结束后会继续原明细。领取、业务投影、审计任务和明细终态遵循同一数据库事务边界。租约或数据库故障不会调用 Agent,也不会产生宿主机未知副作用。
批次公开状态为 `pending`、`applying`、`completed`、`partial` 或 `attention`。管理员应从批次详情查看每个实例的前后到期时间、审计任务和错误代码:
- `deferred`:支付或其他短期条件尚未收敛,worker 后续按原明细继续处理;
- `rejected`:实例在执行时已不再符合补偿条件,不会加时;
- `attention`:账本或证据矛盾,需要先核对数据库事实,不能盲目重跑;
- `applied`:相关服务、流量窗口、备份窗口和审计任务已在同一事务内提交。
不要通过直接修改实例到期时间、复制补偿明细或重新使用其他幂等键来“解除”异常。先核对批次和本地审计任务,再修复导致 `attention` 的账本根因;已应用明细不得回滚或再次加时。
## 用户通知
只有批次业务明细全部进入终态后,系统才按用户汇总实际 `applied` 的实例,并冻结收件邮箱、邮件载荷及 SHA-256。未成功补偿的实例不会出现在邮件中;管理员关闭通知时不创建收件人。
`cloudWorker --notification-only` 同时驱动维护通知和补偿通知,每种通道每轮最多处理一个收件人,任一通道异常不阻塞另一通道。邮件使用 300 秒租约。SMTP 已开始后返回 `false`、抛出异常或租约过期都记为 `unknown`,不会自动重发;用户删除、邮箱改变或黑名单命中会在 SMTP 前记为 `skipped`。
## 部署
全新数据库必须由当前 `CloudSetup` 创建并验证 `go-agent-wss-v38-backup-publication-preparation` 完整 schema;其中补偿模块包括:
- `cloud_service_compensations`;
- `cloud_service_compensation_items`;
- `cloud_service_compensation_recipients`;
- 对应唯一键、领取索引、CHECK 和外键。
`php xcat cloudInit` 只用于空数据库,不能作为既有数据库的增量升级工具。既有安装必须先备份数据库,再用经过审核的一次性迁移把当前 v38 结构完整落地,核对 schema 指纹后删除迁移脚本。只更新 PHP 而没有升级数据库会明确失败,不能在生产代码中忽略缺表。
发布后需要重启普通 worker 和 `virt-cloud-notification-worker.service` 使其加载新 PHP 代码。功能不调用 Agent/Gateway,也不改变宿主机协议,因此不需要编译或更新 Agent、Gateway AMD64 二进制。
## 验证边界
最低验收覆盖:范围预览摘要漂移、同事故去重、余额和流量字节不变、尾周期/现有权益窗口一起延长、支付中延后、异常进入核对、审计任务原子生成、邮件冻结与无盲重放、只读管理员无写入口,以及桌面和窄屏页面。
SQLite 行为测试能验证业务事务和幂等结果,但不能证明 MariaDB/MySQL 的行锁顺序、死锁重试和真实并发安全。上线前仍需在与生产同版本的隔离数据库中并发执行:同一实例的两个补偿、补偿与续费支付、补偿与实例删除、补偿与账期/流量推进,并确认只有合法顺序提交、没有双重加时或资金/权益漂移。