aliyun-model-proxy/docs/state-file.md

状态文件说明

本服务使用 JSON 文件保存模型冷却状态。这样服务重启后，已经进入冷却期的 DashScope key 与 MODEL_ID 组合不会丢失。

默认状态文件路径：

STATE_PATH=./data/proxy-state.json

状态文件不会保存明文 DashScope API Key。代码会对每个 key 计算 SHA-256，并把结果写入 modelState。

文件结构

状态文件是一个版本化 JSON 对象：

{
  "version": 1,
  "modelState": {},
  "runtimeState": {}
}

modelState

modelState 保存每个 DashScope key 与 MODEL_ID 组合的状态。

例如配置：

DASHSCOPE_API_KEYS=key1,key2
MODEL_IDS=modelA,modelB,modelC

那么 modelState 会有 2 * 3 = 6 条记录。

字段说明：

字段	说明
keyHash	DashScope API Key 的 SHA-256 hash。用于区分不同 key，但不保存明文 key。
modelId	模型 ID，来自 MODEL_IDS。
cooldownUntil	冷却截止时间，Unix 毫秒时间戳。0 表示没有冷却。如果这个值大于当前时间，该 key+model 组合不可用。
failureCount	该 key+model 组合触发免费额度耗尽 403 的次数。
lastError	最近一次免费额度耗尽时，上游返回的错误信息。
lastUsedAt	最近一次成功使用该 key+model 组合的时间，Unix 毫秒时间戳。
updatedAt	最近一次状态更新时间，Unix 毫秒时间戳。

runtimeState

runtimeState 保存调度游标，避免服务每次重启后都从第一个 key、第一条 model 开始打。

当前会使用的记录：

name	说明
key_cursor	当前优先使用的 DashScope API Key 下标。
model_cursor:<key_hash>	某个 key 当前优先使用的模型下标。

每条记录包含：

字段	说明
value	状态值。当前主要保存数字游标，但统一用文本存储。
updatedAt	最近一次更新时间，Unix 毫秒时间戳。

写入策略

状态变更会同步写入文件。写入时先写临时文件，再用 rename 替换正式状态文件，降低进程中断时写坏文件的风险。

如果启动时发现状态文件不是有效 JSON，或结构不符合当前版本，服务会把原文件重命名为：

proxy-state.json.bak.<timestamp>

然后创建新的空状态。

调度规则

当前实现是“key 优先”的切换策略：

1. 先使用 key_cursor 指向的 key。
2. 在这个 key 内部，从该 key 的 model_cursor 指向的模型开始尝试。
3. 如果某个模型返回免费额度耗尽 403，只冷却这个 keyHash + modelId 组合。
4. 继续尝试同一个 key 下的下一个可用模型。
5. 只有当前 key 下所有模型都不可用时，才切换到下一个 key。
6. 如果所有 key+model 组合都不可用，服务返回 503。

冷却规则

默认冷却时间是 1 个月：

MODEL_COOLDOWN_SECONDS=2592000

当某个 key+model 组合进入冷却：

cooldownUntil = 当前时间 + MODEL_COOLDOWN_SECONDS
failureCount = failureCount + 1
lastError = 上游错误信息
updatedAt = 当前时间

当某个 key+model 组合成功返回：

lastUsedAt = 当前时间
lastError = null
updatedAt = 当前时间

成功返回不会清零 failureCount，这个字段保留历史失败次数。