hybrid-perps-spec

上线与回滚手册（MVP）

本文档规定化永续期货平台（方案二）的灰度策略、应急响应、开关矩阵与回滚流程。旨在确保Phase 2与Phase 3的平稳上线与故障恢复。

一、灰度策略

Phase 2灰度（路由+对冲）

目标: 7天内全量路由HL运行零故障，风控计算精度验证通过

灰度周期: 7天（共4个阶段）

阶段1：全量路由HL（第1-3天）

路由决策: 所有订单无论大小全部转发HL（NORMAL_MODE强制覆盖）
对冲引擎: 仅观测净敞口，不触发对冲指令
清算: 仅观测，不实际清算（仅测试用户）
风险: 极低（平台不承受对赌风险）
验收指标:
- HL代理执行零偏差(实际成交价 vs 回执价 ≤1bp)
- API延迟<5ms P99
- 订单转发→HL回执<50ms P99
- 零故障、零数据丢失

阶段2：风控观测（第4-5天）

路由决策: 继续全量HL
对冲引擎: 开启净敞口计算，但不执行对冲指令（仅记录日志）
对账: 对比观测净敞口 vs 计算值，精度目标>99%
验收指标:
- 净敞口观测精度>99%
- 对冲指令日志完整（符号、数量、价格）
- 零故障

阶段3：模拟对冲（第6-7天）

路由决策: 继续全量HL
对冲引擎: 生成对冲指令但不执行，记录日志供审计
模拟清算: 运算清算指令但不触发实际平仓
验收指标:
- 对冲指令生成符合阈值逻辑(>$100K触发50%对冲等)
- 指令价格合理(不超过当时市价5%)
- 日志无遗漏

通过标准

✓ 7天内HL代理执行零偏差
✓ 路由决策延迟<5ms P99, 99.5%时间<10ms
✓ API响应<100ms P95
✓ 可用性>99.9%
✓ 无数据丢失事件
✓ 风控观测精度>99.5%

失败处理: 任何阶段发现>1%错误率 → 回滚到Phase 1, 修复后重新灰度

Phase 3灰度（对赌上线）

目标: 内部测试1周，BTC/ETH对赌开放，逐步放量到生产

灰度周期: 10天（共4个阶段）

阶段1：极保守模式（第1-3天）

允许对赌币种: BTC (ETH/其他待命)
NORMAL_MODE阈值: $1,000 (极保守，99%订单走HL)
最大净敞口: $50K (自动暂停对赌)
最大单笔: $1,000 (超过转HL)
准备金触发: 仅观测，暂不熔断
目标: 验证对赌引擎稳定性、清算逻辑正确性
验收指标:
- 对赌成交<10ms (市价单)
- 限价单触达成交成功率>99.5%
- 清算延迟<1s
- PnL计算误差<0.01%

阶段2：低风险运行（第4-5天）

允许对赌币种: BTC, ETH (BTC阈值提高, ETH新增)
BTC阈值: $5,000 (提高50%)
ETH阈值: $1,000 (新币种保守起步)
最大净敞口: $100K (BTC+ETH合并)
准备金触发: 如果<$400K开始限制下单量
目标: 验证多币种协同、对冲稳定性
验收指标:
- 多币种对赌零冲突
- 对冲执行准时性>99%
- 清算精度(维保率计算) >99%

阶段3：接近目标配置（第6-7天）

允许对赌币种: BTC, ETH (目标值)
BTC阈值: $10,000 (最终目标值)
ETH阈值: $10,000 (最终目标值)
最大净敞口: $500K
准备金触发: 仅观测(<$200K暂停, 仅日志)
目标: 接近生产配置，压力测试
验收指标:
- 高并发下延迟<10ms (1000req/s)
- 对账精度>99.9%
- 准备金充足(>$500K)

阶段4：全量放开（第8-10天）

允许对赌币种: BTC, ETH (生产配置)
配置: 同最终设计(NORMAL_MODE $10K, BETTING_MODE $50K)
生产风控: 全部启用(清算、熔断、准备金)
广告宣传: 开放用户注册和小额对赌
目标: 验证生产配置稳定性，积累用户反馈
验收指标:
- 实际交易量>100万USDT/天
- 清算次数>50笔/天（验证清算逻辑）
- 用户反馈无关键问题

通过标准

✓ 清算检测延迟<1s (100%时间)
✓ PnL计算误差<0.1% (与HL对账)
✓ 准备金充足(>$500K)
✓ 可用性>99.95% (P0告警响应<5分钟)
✓ 无用户资产损失事件

失败处理:

清算失效 → 立即关闭对赌，回滚到Phase 2全量HL
清算误触发 → 关闭自动清算，人工审核
准备金不足 → 暂停新对赌订单，暂停提现(恐慌)

二、开关矩阵（Risk Manager可控）

所有开关存储在配置中心(Consul/etcd)，修改后10秒内全局生效（无需重启）。

开关名称	类型	默认值	控制范围	操作权限	回滚动作	生效延迟
global_betting_enabled	bool	false	全局对赌开关 (true=对赌模式, false=纯HL)	Super Admin	关闭→全量HL路由	<1s
routing_mode	enum	HL_MODE	路由模式切换	Risk Manager	切回HL_MODE	<1s
normal_threshold	money	$10,000	NORMAL_MODE下: 金额≤阈值→INTERNAL, >阈值→HL	Risk Manager	提高或设$0(走HL)	<5s
betting_threshold	money	$50,000	BETTING_MODE下: 金额≤阈值→INTERNAL	Risk Manager	降低或关闭	<5s
auto_mode_switch	bool	false	自动模式切换(基于敞口)	Risk Manager	关闭(防误触)	<5s
hedge_enabled	bool	true	对冲引擎开关	Risk Manager	关闭→手动对冲	<1s
hedge_max_leverage	float	3.0x	对冲最大杠杆	Risk Manager	降低到1.5x(保守)	<5s
per_symbol_betting	list	BTC,ETH	允许对赌的币种列表	Risk Manager	清空(禁止对赌)	<5s
liquidation_enabled	bool	true	清算引擎开关(关闭=极端故障)	Super Admin	关闭(人工清算)	<1s
liquidation_detection_interval_ms	int	500	清算检测频率(ms)	Risk Manager	改为2000(降低CPU)	<5s
withdrawal_enabled	bool	true	提现开关(挤兑防御)	Super Admin	关闭(暂停提现)	<1s
max_internal_exposure_usd	money	$500,000	单币内部净敞口上限	Risk Manager	降低到$100K	<5s
hedge_threshold_tier1	money	$100,000	第一层对冲触发(50%对冲)	Risk Manager	提高到$500K	<5s
hedge_threshold_tier2	money	$500,000	第二层对冲触发(80%对冲)	Risk Manager	提高到$1M	<5s
risk_reserve_min_usd	money	$200,000	准备金最低警线(低于此暂停对赌)	Risk Manager	提高到$300K	<5s
daily_net_loss_limit	money	$500,000	日净亏损熔断线	Risk Manager	提高或关闭	<5s
max_order_size_internal	money	$10,000	单笔对赌最大金额(超过转HL)	Risk Manager	降低到$1K	<5s
force_hl_volatility_threshold	float	5.0%	波动超过此值→强制HL	Risk Manager	提高到10%	<5s
force_hl_latency_threshold_ms	int	500	HL延迟超过此值→强制HL	Risk Manager	提高到1000ms	<5s

权限等级:

Super Admin: 全局对赌、清算、提现 (CEO/CTO级)
Risk Manager: 路由、对冲、准备金、熔断 (风控经理级)
Operations: 仅查询和提现审核 (无修改权)

变更审计:

所有开关变更记录到不可删改的审计日志
格式: timestamp | user | switch_name | old_value | new_value | reason
支持开关变更回滚: rollback_switch(switch_name, timestamp)

三、告警体系与应急响应

P0告警（5分钟内响应，值班人员必应）

告警	触发条件	立即动作	进一步措施
HL连接断裂	WebSocket/REST连接中断>1分钟	告警Slack/PagerDuty, 自动暂停新订单	重连机制启动; 若>5分钟未恢复→人工介入
HL账户保证金率<150%	HL account margin_ratio < 150%	立即暂停所有HL新开仓	1. 补资金到>200%, 2. 撤回高风险对冲单
对冲账户保证金率<200%	对冲专用账户保证金率<200%	同上，额外降杠杆到2x	紧急补资或清仓高风险对冲
清算引擎失效	清算检测失败连续>5次或清算执行失败>10%	关闭liquidation_enabled, 人工清算	排查清算逻辑BUG, 修复后重启
热钱包余额<$100K	热钱包可用余额<$100K	暂停大额提现(>$10K)	紧急从冷钱包转入
单笔偏差>5%	某笔HL订单实际价格 vs 计算价格偏差>5%	暂停该币种HL路由(转对赌)	排查原因(滑点/时间差/BUG)
用户资产对账不平>0.1%	用户查询资产 vs 系统记录偏差>0.1%	立即暂停交易，启动人工对账	手动兜底调整

应急响应SLA:

P0告警: 值班人员5分钟内确认, 10分钟内采取行动
5分钟内无应答 → 自动升级(告警→电话+SMS)

P1告警（30分钟内响应）

告警	触发条件	动作	优先级
单币净敞口>$500K	某币种净INTERNAL敞口>$500K	Slack通知风控, 提醒对冲	检查对冲是否执行
准备金<$500K	风险准备金余额<$500K	Slack通知风控	评估是否继续对赌
日净亏损>$100K	当日INTERNAL亏损累计>$100K	Slack通知, 仅日志(暂无熔断)	监控实时PnL
提现队列堆积	待审核提现>50笔或等待时间>2小时	Slack通知运营加速审批	可能提现瓶颈
API延迟>100ms P95	连续5分钟P95延迟>100ms	监控页面标红, 内部通知	检查服务健康

四、回滚决策树

故障发生
    ↓
[严重程度判断]
    ├─ 关键路径故障(路由/清算) ──→ Severity=Critical  ──→ 立即回滚
    ├─ 数据一致性故障 ──────────→ Severity=High ──→ 5分钟内回滚
    └─ 非关键路径(市场数据延迟) → Severity=Low ──→ 观察/修复
    ↓
[回滚级别判定]
    ├─ 单模块故障 (e.g. 对冲引擎bug)
    │   └─ 动作: 关闭该开关 (hedge_enabled=false) + 修复 + 灰度重启
    ├─ 跨模块级故障 (e.g. 路由→清算链路)
    │ └─ 动作: 切HL_MODE + 所有对赌禁用 + 人工审查
    └─ 全系统故障 (e.g. 数据库故障)
        └─ 动作: 全服务降级 → 仅提现+查询 → 等待修复
    ↓
[执行回滚]
    └─ 修改配置中心开关 + 观察5分钟 + 确认恢复

[修复与重启]
    └─ 问题修复 → 单元测试通过 → 小流量灰度(5%)
       → 确认正常 → 全量(100%)

五、回滚路径详表

场景1：路由引擎错误路由

症状: 应该走HL的订单被路由到INTERNAL，或反之

立即回滚:

修改routing_mode = HL_MODE (所有订单→HL)
新订单自动转HL；已有INTERNAL订单继续
关闭所有INTERNAL成交(订单状态冻结)

恢复时间: <1分钟

后续修复:

排查路由决策逻辑BUG
单元测试+集成测试覆盖该场景(>10组case)
小流量灰度(5%)验证2小时
全量灰度恢复

场景2：对赌执行引擎崩溃

症状: 对赌订单成交失败，或未正确创建对手方仓位

立即回滚:

修改global_betting_enabled = false
新订单全部转HL
已有INTERNAL仓位继续存在，启动人工对账

恢复时间: <1分钟

后续修复:

排查对赌执行BUG (成交记录/对手方仓位创建)
人工核对用户资产，不平账手动调整
完整功能测试后重启对赌

场景3：清算引擎误触发

症状: 用户仓位不应清算却被强制平仓

立即回滚:

修改liquidation_enabled = false
已经执行的清算保持
后续清算改为人工审核

恢复时间: <1分钟

后续修复:

排查清算触发条件(保证金率计算)
对被误清算用户进行赔付(风险准备金)
修复+完整回归测试后重启自动清算

场景4：对冲引擎异常

症状: 对冲指令价格异常，或对冲仓位失控

立即回滚:

修改hedge_enabled = false
对冲引擎停止生成新指令
既有对冲仓位继续持有，启动人工止损

恢复时间: <1分钟

后续修复:

排查对冲指令生成逻辑(价格/数量/阈值)
校准对冲仓位，清理错误指令
压力测试(1000订单/秒下对冲稳定性)后重启

场景5：HL代理执行失败

症状: 转发到HL的订单执行失败，用户端订单卡住

立即回滚:

自动重试机制启动(指数退避)
若>5分钟仍失败，将订单改为FAIL状态
暂停新的HL订单

恢复时间: 5-10分钟

后续修复:

检查HL API状态(是否故障/限流)
修复订单状态机，重新提交失败订单
对用户进行赔付(如有滑点损失)

场景6：数据库故障

症状: 订单、仓位、用户余额无法查询

立即回滚:

切换到只读副本(replica)
暂停所有写操作(新订单、提现被延迟)
仅允许提现和查询

恢复时间: 15-30分钟

后续修复:

修复主库故障(机器重启/磁盘修复)
主副同步检查
恢复写操作

场景7：全站不可用（灾难情况）

症状: 多个模块同时故障

立即回滚:

激活降级Level 3 (维护模式)
关闭所有API，仅展示”系统维护”页面
禁止新交易和提现(防止状态不一致)

恢复时间: 30-60分钟

后续修复:

逐个模块诊断
必要时切换到备用区域(如有)
降级到Level 2 (只读) → Level 1 (部分功能) → Level 0 (全功能)

六、降级模式定义

降级Level 1：部分功能（风险可控）

触发条件: 对赌引擎故障 / 清算故障（但HL通道正常）

用户可用功能:

查询仓位、资产、交易历史 ✓
提现（标准流程） ✓
新开仓（仅路由HL） ✓
平仓（INTERNAL平仓需人工） ⚠
对赌功能 ✗ (禁用)

平台影响:

无客损收入(对赌收入为0)
仅Builder Fee收入

用户体验:

看起来”正常”，交易可进行，但无对赌优势
显示”对赌功能临时维护中”

切换方式:

global_betting_enabled = false
hedge_enabled = false
routing_mode = NORMAL_MODE

降级Level 2：只读+有限功能（保护资产）

触发条件: 清算引擎完全失效 / 多个关键模块故障

用户可用功能:

查询所有信息 ✓
提现 ✓
平仓（市价单） ✓
新开仓 ✗ (禁用)
对赌 ✗ (禁用)

平台影响:

无收入
仅风险管理

用户体验:

用户知道出问题了
显示”系统异常，仅允许平仓和提现”

切换方式:

global_betting_enabled = false
routing_mode = HL_MODE
liquidation_enabled = false
# 自动禁止所有POST /order (新开仓)

降级Level 3：维护模式（应急止血）

触发条件: 全站崩溃 / 数据库完全不可用 / 用户资产面临风险

用户可用功能:

无 (仅读取静态维护页面)

平台影响:

完全停业

用户体验:

显示: “系统在进行紧急维护，预计X小时恢复”
无法登录、无法交易、无法提现

切换方式:

# 关闭所有API网关
global_api_enabled = false
# 返回503 Service Unavailable
# 前端显示维护公告

触发权限: Super Admin 仅

七、回滚检查清单

执行任何回滚前，按以下清单验证：

八、给开发的落地要点

1. 开关配置管理

所有开关集中存储在Consul/etcd，而非代码硬编码
提供HTTP API: GET /config/switch/{name} 获取开关值
提供命令行工具: set_switch routing_mode HL_MODE --reason "故障回滚"
所有开关变更记录到审计日志(Elasticsearch)，不可删除

2. 灰度发布基础设施

使用流量分流网关实现金丝雀灰度(5% → 20% → 50% → 100%)
支持自动回滚: 若P99延迟增加>20% 或错误率>1%，自动回滚
灰度期间并行运行新旧两个版本(零停机)

3. 故障检测与自愈

清算引擎故障自动检测(每30秒检查一次执行状态)
HL连接故障自动重连(指数退避: 1s → 2s → 4s → 8s，最大5分钟)
对账不平自动告警(每5分钟检查一次，偏差>0.1%即告警)

4. 完整的测试覆盖

对每个开关编写测试: 改变开关值后，系统行为是否符合预期
对每个回滚路径编写演练脚本: 自动化回滚验证
压力测试: Phase 2在5000订单/秒下验证回滚响应

5. 监控与通知

Prometheus: 监控所有关键指标(延迟/错误率/敞口/准备金等)
Grafana: 仪表盘显示实时系统状态
PagerDuty/Slack: P0告警自动通知值班人员
每周”故障演练”: 模拟一个故障场景，验证回滚流程

6. 文档与培训

编写运维手册(中文): 每个开关的含义、使用场景、修改方法
编写故障排查指南: P0告警出现时，按流程诊断
每月进行1次培训: 新员工学习灰度/回滚流程
建立故障库: 记录过去发生的所有故障，用于预防