用户额度与 Endpoint 启停说明

本文说明普通用户余额如何计算，以及余额耗尽时系统如何自动停用对应的火山 Ark Endpoint。
当前实现是“用户绑定同步配置决定管哪些 Endpoint，额度管理配置决定用哪组 AK/SK 去启停 Endpoint”。

关键结论：为了让余额系统能自动停用/恢复 Endpoint，必须在「额度管理」里给 Endpoint 配置一条记录并绑定正确凭证。Token 额度本身可以不作为控制重点，且“到限额自动停用”不需要为用户余额控制勾选；但 Endpoint 与凭证关系必须存在。

额度公式

用户页面展示的可用额度来自本地缓存的消耗金额，不是每次打开页面都实时请求火山账单。

字段	含义
`balance`	累计充值金额。管理员充值或扣减时更新。
`consumed_amount`	系统根据已同步任务计算出的总消耗金额。
`consumed_baseline`	首次充值时记录的历史消耗基线，用于避免把充值前任务重复扣费。
`remaining`	当前可用额度。

actualConsumed = max(0, consumed_amount - consumed_baseline)
remaining = balance - actualConsumed

当 remaining <= 0 时，系统认为用户额度耗尽，会触发 Endpoint 停用流程。

用户与 Endpoint 的绑定关系

普通用户不直接保存 Endpoint 列表。系统通过用户绑定的“同步配置”找到需要控制的 Endpoint。

普通用户

allowed_sync_config_ids

同步配置

TaskSyncConfig.targets

Endpoint

target_id / endpoint_id

额度配置

QuotaConfig

凭证

Credential AK/SK

所以一个用户能被余额系统控制的 Endpoint，必须已经出现在该用户绑定的同步配置 targets 中。

用哪组 AK/SK 启停 Endpoint

Endpoint 启停使用的是「额度管理」里该 Endpoint 绑定的凭证，不是普通用户自己的 AK/SK，也不是同步配置里的 Ark API Key。

endpoint_id
  -> QuotaConfig.findOne({ endpoint_id })
  -> QuotaConfig.credential_id
  -> Credential.getFullCredential(credential_id)
  -> Credential.ak / Credential.sk
  -> StartEndpoint / StopEndpoint

配置位置	作用
同步配置	决定用户关联哪些 Endpoint，并用于同步任务消耗。
额度管理	通过 Endpoint ID 绑定 Credential，决定启停 Endpoint 使用哪组 AK/SK。
凭证管理	保存火山或 BytePlus 的 AK/SK、项目名、区域等信息。

如果额度管理没有该 Endpoint 的配置，或者没有绑定 Credential，余额耗尽时系统会跳过这个 Endpoint，不会删除任何记录。

关于“到限额自动停用”：这个开关只控制额度管理自身的日/月 Token 或金额限额。用户余额耗尽触发的停用不依赖这个开关。

停止触发时机

1. 后台定时检查

服务启动后会启动余额检查器。检查器每 1 分钟 tick 一次，但每个用户按自己的“余额检查间隔”决定是否真正刷新消耗，默认 3 分钟。

balance-checker tick: every 1 minute
per-user interval: balance_check_interval minutes, default 3

2. 普通用户点击刷新消耗

普通用户页面点击“刷新消耗”后，后端会重新计算 consumed_amount。如果可用额度小于等于 0，会异步停用 Endpoint。

3. Relay 创建任务前检查

如果 Relay 账号能通过 API Key 前缀关联到某个用户绑定的同步配置，创建任务前会检查该用户余额。余额不足会返回 402 BALANCE_EXCEEDED，并触发异步停用。

充值后如何恢复

管理员给普通用户充值后，系统重新计算可用额度。如果 remaining > 0，会调用恢复流程。

remaining > 0
  -> startUserEndpoints(userId)
  -> StartEndpoint(endpoint_id, credential AK/SK)

恢复使用同一条链路查找 Endpoint 和 Credential：用户绑定同步配置、同步配置 targets、额度管理 QuotaConfig、凭证 Credential。

配置清单

检查项	要求
普通用户	用户角色为普通用户，并绑定了需要统计消耗的同步配置。
同步配置	`targets` 中包含要控制的 Endpoint ID。
额度管理	存在同 Endpoint ID 的配置记录。
到限额自动停用	仅用于额度管理自身的日/月 Token 或金额限额；只做用户余额控制时不需要勾选。
凭证管理	额度管理记录绑定了正确 Credential。
AK/SK 权限	Credential 对应 AK/SK 有 Ark `StartEndpoint` / `StopEndpoint` 权限。
Project / Region	Credential 的项目名、区域、火山/BytePlus 类型与目标 Endpoint 匹配。

常见问题

不配置 token 额度可以吗？

可以。余额启停 Endpoint 依赖的是额度管理记录中的 Endpoint 与 Credential 绑定关系。Token 额度可以不作为控制重点，但额度管理记录必须存在并绑定正确凭证。

“到限额自动停用”需要勾选吗？

如果只是为了普通用户余额耗尽时自动停用 Endpoint，不需要勾选。用户余额耗尽停用会直接调用余额服务，不读取 auto_stop。

只有当你希望额度管理按 daily_token_limit、monthly_token_limit、daily_amount_limit 或 monthly_amount_limit 超限后自动停用 Endpoint，才需要勾选“到限额自动停用”。如果不勾选，额度管理超限时只会标记状态，不会真的调用火山 StopEndpoint。

为什么余额不足但 Endpoint 没停？

用户没有绑定包含该 Endpoint 的同步配置。
额度管理没有该 Endpoint 的配置记录。
额度管理记录没有绑定 Credential。
AK/SK 没有 StartEndpoint / StopEndpoint 权限。
ProjectName、Region 或 BytePlus/火山类型不匹配。

为什么充值后没有恢复？

恢复链路和停止链路一样，也需要能通过 QuotaConfig 找到正确 Credential。如果配置缺失，系统会跳过该 Endpoint。

同步配置里的 Ark API Key 会用来停 Endpoint 吗？

不会。同步配置的 Ark API Key 用于同步任务和统计消耗；Endpoint 启停使用额度管理绑定的 Credential AK/SK。

KYC Service · 用户额度控制说明