492f33a129
- DEFAULT_CHAIN_ADMISSION.md: reviewed and approved, real artifact refs added - DEFAULT_DATA_IDEMPOTENT_RELEASE_GATE.md: reviewed and approved - scripts/setup_default_data.sh: idempotent init with --dry-run/--apply/artifact - scripts/test/test_default_data.sh: 4 test cases all pass - scripts/acceptance/verify_user_key_self_service.sh: Phase 0 skeleton - .gitignore: add generated artifact directories
3.1 KiB
3.1 KiB
Key / Account Governance
日期：2026-06-04 状态：待审核 适用版本：vNext.3
目的
建立 key 与 provider account 的治理语义，避免把人工状态、健康状态、额度状态混入同一个字段，污染路由决策与用户展示。
设计原则
- 管理员动作与系统健康判断分离
- 配额/额度状态与人工暂停分离
- route resolve 只消费明确状态组合，不消费模糊字符串
- portal 展示使用面向用户的聚合状态，不泄露内部细节
三态模型
1. admin_status
含义：人工治理动作结果 枚举：
activepauseddisabledretired
说明：
paused：可恢复disabled：不可直接恢复，需管理员处理retired：退役，不再用于分发
2. health_status
含义：系统探测得到的线路健康状态 枚举：
healthydegradedunhealthyunknown
说明：
- 由 probe / runtime failure / cooldown 写入
- 不等于人工暂停
3. quota_status
含义：额度或速率状态 枚举：
okexhaustedlimitedunknown
说明：
exhausted：当前不可再分配流量limited：可服务但有限制
路由决策规则
active route 最小条件
route 进入 active pool 至少满足：
admin_status=activehealth_status in (healthy, degraded)quota_status in (ok, limited)HostReady=trueSchedulable=true
必须排除
以下组合必须排除：
admin_status!=activehealth_status=unhealthyquota_status=exhaustedHostReady=falseSchedulable=false
用户展示映射
内部状态组合要映射成面向用户的解释：
| admin_status | health_status | quota_status | 用户展示 |
|---|---|---|---|
| active | healthy | ok | 可用 |
| active | degraded | ok | 可用（线路降级） |
| paused | any | any | 已暂停 |
| active | unhealthy | ok | 暂不可用 |
| active | healthy | exhausted | 已超限 |
| active | healthy | limited | 可用（受限） |
管理动作
管理员至少支持：
- pause key
- resume key
- pause account
- resume account
- set quota / request limit
- retire account
每个动作都必须：
- 写 audit log
- 写 reason
- 写 operator
- 写 timestamp
失败回写
真实代理调用失败后，必须定义如何回写治理状态：
- 429 / quota 类错误 →
quota_status=limited/exhausted - 5xx / timeout 连续超阈值 →
health_status=degraded/unhealthy - 人工操作不应写入
health_status
验收要求
至少需要：
- 状态组合单元测试
- route resolve 组合状态过滤测试
- 用户态展示映射测试
- 管理动作审计测试
- 暂停/恢复/超限后的真实用户调用验收
与本轮范围关系
本文件属于 vNext.3 设计文档。 在当前 vNext.1 审核阶段，只作为后续治理设计真相源，不进入实现。