Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,7 @@ commandcode:
- name: main
api_key: your-command-code-api-key
enabled: true
pause_below_credits: 10
- name: backup
api_key: another-command-code-api-key
host: localhost
Expand Down Expand Up @@ -165,6 +166,7 @@ New configs exclude `gpt-`, `claude-`, and `gemini-` by default. These prefixes
Every chat request is sent with the next enabled account in round-robin order. When an account fails with `401`, `403`, `429`, or a 5xx, the request is retried with the next account automatically:

- A `429` puts the account into cooldown for the upstream `Retry-After` duration (60 seconds by default); cooldown accounts are skipped until they recover. If every enabled account is cooling down, the client receives `429 rate_limit_error` with the earliest recovery time.
- `pause_below_credits` parks an account while its remaining monthly credits are at or below that value (`0` disables it). The value is counted in plan credits, not USD — the same unit the quota bars show. Parked accounts are skipped and resume automatically once a quota refresh shows the balance recovered. If every enabled account is parked, the client receives `503 quota_paused`.
- `400`/`422` (bad request) and client-canceled contexts are not retried.
- Failover happens before any bytes are sent to the client; once a stream has started it is never replayed on another account.
- Per-account request/token counters persist in `usage.json`; error state, last error, and cooldown windows are runtime-only and visible in the WebUI.
Expand Down Expand Up @@ -220,7 +222,7 @@ The UI talks to a JSON API under `/admin/api/*`, authenticated with `Authorizati
GET /admin/api/overview
GET /admin/api/accounts
POST /admin/api/accounts {"name": "...", "api_key": "..."}
PATCH /admin/api/accounts/{id} {"enabled": true}, {"name": "..."} or {"api_key": "..."}
PATCH /admin/api/accounts/{id} {"enabled": true}, {"name": "..."}, {"api_key": "..."} or {"pause_below_credits": 10}
DELETE /admin/api/accounts/{id}
POST /admin/api/accounts/{id}/test
POST /admin/api/accounts/{id}/quota/refresh
Expand Down
4 changes: 3 additions & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,7 @@ commandcode:
- name: main
api_key: your-command-code-api-key
enabled: true
pause_below_credits: 10
- name: backup
api_key: another-command-code-api-key
host: localhost
Expand Down Expand Up @@ -165,6 +166,7 @@ exclude_models:
每次 chat 请求按轮询方式使用下一个启用的账号。账号返回 `401`、`403`、`429` 或 5xx 时自动换下一个账号重试:

- `429`:按上游 `Retry-After` 冷却该账号(缺省 60 秒),冷却期内跳过;全部账号都在冷却时向客户端返回 `429 rate_limit_error` 和最早恢复时间。
- `pause_below_credits`:账号剩余月度积分不高于该值时暂停使用(`0` 表示关闭)。该数值按套餐积分计算,不是美元,与额度进度条同一单位。暂停的账号会被跳过,积分刷新后自动恢复。所有启用账号都暂停时,客户端收到 `503 quota_paused`。
- `400` / `422`(请求本身有问题)与客户端主动取消不重试。
- 故障转移只发生在向客户端写出任何字节之前;流式响应一旦开始不会在另一个账号上重放。
- 每个账号的请求 / token 计数持久化在 `usage.json`;错误信息、冷却窗口等运行时状态可在 WebUI 中查看。
Expand Down Expand Up @@ -221,7 +223,7 @@ UI 通过 `/admin/api/*` 访问管理接口,鉴权方式为 `Authorization: Be
GET /admin/api/overview
GET /admin/api/accounts
POST /admin/api/accounts {"name": "...", "api_key": "..."}
PATCH /admin/api/accounts/{id} {"enabled": true} 或 {"name": "..."}
PATCH /admin/api/accounts/{id} {"enabled": true}、{"name": "..."} 或 {"pause_below_credits": 10}
DELETE /admin/api/accounts/{id}
POST /admin/api/accounts/{id}/test
POST /admin/api/accounts/{id}/quota/refresh
Expand Down
149 changes: 120 additions & 29 deletions internal/app/accounts.go
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,19 @@ type Account struct {
lastUsedAt time.Time
rateLimitedUntil time.Time
authFailures int
pauseBelow float64
paused bool
lastRemaining *float64
}

func newAccount(name, apiKey string, enabled bool) *Account {
return &Account{ID: accountID(apiKey), Name: name, APIKey: apiKey, Enabled: enabled}
func newAccount(name, apiKey string, enabled bool, pauseBelow float64) *Account {
return &Account{
ID: accountID(apiKey),
Name: name,
APIKey: apiKey,
Enabled: enabled,
pauseBelow: pauseBelow,
}
}

// accountID derives a stable identifier from the key so stats survive renames
Expand All @@ -58,6 +67,55 @@ func (a *Account) RateLimited(now time.Time) bool {
return now.Before(a.rateLimitedUntil)
}

// Paused reports whether the credit threshold currently parks this account.
// A paused account is skipped by the pool but keeps its configuration and
// history; it resumes automatically once the balance recovers.
func (a *Account) Paused() bool {
a.mu.Lock()
defer a.mu.Unlock()
return a.paused
}

// PauseThreshold returns the configured remaining-credit floor, 0 when unset.
func (a *Account) PauseThreshold() float64 {
a.mu.Lock()
defer a.mu.Unlock()
return a.pauseBelow
}

// SetPauseThreshold changes the floor and re-evaluates the pause state against
// the last observed balance, so lowering it takes effect immediately.
func (a *Account) SetPauseThreshold(v float64) {
a.mu.Lock()
defer a.mu.Unlock()
a.pauseBelow = v
a.applyPauseLocked()
}

// ApplyQuotaThreshold re-evaluates the pause state from the latest remaining
// monthly balance. A nil balance means the value is unknown (no quota data
// yet) and leaves the current state untouched.
func (a *Account) ApplyQuotaThreshold(remaining *float64) {
if remaining == nil {
return
}
a.mu.Lock()
defer a.mu.Unlock()
value := *remaining
a.lastRemaining = &value
a.applyPauseLocked()
}

// applyPauseLocked parks the account when the balance is at or below the
// configured floor. The caller holds a.mu.
func (a *Account) applyPauseLocked() {
if a.pauseBelow <= 0 || a.lastRemaining == nil {
a.paused = false
return
}
a.paused = *a.lastRemaining <= a.pauseBelow
}

func (a *Account) RecordSuccess() {
now := time.Now()
a.mu.Lock()
Expand Down Expand Up @@ -99,18 +157,20 @@ const authErrorThreshold = 3
// AccountView is the JSON projection of an account for the admin API. It never
// contains the raw key.
type AccountView struct {
ID string `json:"id"`
Name string `json:"name"`
KeyMasked string `json:"key_masked"`
Enabled bool `json:"enabled"`
RateLimited bool `json:"rate_limited"`
Status string `json:"status"`
Errors int64 `json:"errors"`
AuthFailures int `json:"auth_failures"`
LastError string `json:"last_error,omitempty"`
LastErrorAt *time.Time `json:"last_error_at,omitempty"`
LastUsedAt *time.Time `json:"last_used_at,omitempty"`
RateLimitedUntil *time.Time `json:"rate_limited_until,omitempty"`
ID string `json:"id"`
Name string `json:"name"`
KeyMasked string `json:"key_masked"`
Enabled bool `json:"enabled"`
RateLimited bool `json:"rate_limited"`
Paused bool `json:"paused"`
PauseBelowCredits float64 `json:"pause_below_credits"`
Status string `json:"status"`
Errors int64 `json:"errors"`
AuthFailures int `json:"auth_failures"`
LastError string `json:"last_error,omitempty"`
LastErrorAt *time.Time `json:"last_error_at,omitempty"`
LastUsedAt *time.Time `json:"last_used_at,omitempty"`
RateLimitedUntil *time.Time `json:"rate_limited_until,omitempty"`
}

func (a *Account) View() AccountView {
Expand All @@ -119,12 +179,14 @@ func (a *Account) View() AccountView {
defer a.mu.Unlock()

view := AccountView{
ID: a.ID,
Name: a.Name,
KeyMasked: a.MaskedKey(),
Enabled: a.Enabled,
Errors: a.Errors.Load(),
AuthFailures: a.authFailures,
ID: a.ID,
Name: a.Name,
KeyMasked: a.MaskedKey(),
Enabled: a.Enabled,
Paused: a.paused,
PauseBelowCredits: a.pauseBelow,
Errors: a.Errors.Load(),
AuthFailures: a.authFailures,
}
if a.lastError != "" {
view.LastError = a.lastError
Expand All @@ -147,6 +209,8 @@ func (a *Account) View() AccountView {
view.Status = "rate_limited"
case a.authFailures >= authErrorThreshold:
view.Status = "auth_error"
case a.paused:
view.Status = "paused"
default:
view.Status = "ok"
}
Expand All @@ -166,14 +230,15 @@ func NewAccountPool(list []AccountConfig) *AccountPool {
if strings.TrimSpace(ac.APIKey) == "" {
continue
}
pool.accounts = append(pool.accounts, newAccount(ac.Name, ac.APIKey, ac.IsEnabled()))
pool.accounts = append(pool.accounts, newAccount(ac.Name, ac.APIKey, ac.IsEnabled(), ac.PauseBelowCredits))
}
return pool
}

// Acquire picks the next eligible account in round-robin order. Disabled and
// rate-limited accounts are skipped; nil means every enabled account is
// currently rate limited (or the pool is empty).
// Acquire picks the next eligible account in round-robin order. Disabled,
// rate-limited and credit-paused accounts are skipped; nil means every enabled
// account is currently cooling down or parked below its threshold (or the pool
// is empty).
func (p *AccountPool) Acquire() *Account {
now := time.Now()
p.mu.RLock()
Expand All @@ -186,7 +251,7 @@ func (p *AccountPool) Acquire() *Account {
start := int((p.cursor.Add(1) - 1) % uint64(n))
for i := 0; i < n; i++ {
a := p.accounts[(start+i)%n]
if !a.Enabled || a.RateLimited(now) {
if !a.Enabled || a.RateLimited(now) || a.Paused() {
continue
}
return a
Expand Down Expand Up @@ -259,7 +324,7 @@ func (p *AccountPool) Add(name, apiKey string, enabled bool) (*Account, error) {
}
p.mu.Lock()
defer p.mu.Unlock()
account := newAccount(name, apiKey, enabled)
account := newAccount(name, apiKey, enabled, 0)
p.accounts = append(p.accounts, account)
return account, nil
}
Expand All @@ -285,6 +350,31 @@ func (p *AccountPool) SetEnabled(id string, enabled bool) bool {
return true
}

// SetPauseBelowCredits updates one account's remaining-credit floor. Zero
// clears the guard and resumes the account immediately.
func (p *AccountPool) SetPauseBelowCredits(id string, v float64) bool {
a := p.Get(id)
if a == nil {
return false
}
a.SetPauseThreshold(v)
return true
}

// PausedCount reports how many enabled accounts are parked below their
// credit threshold.
func (p *AccountPool) PausedCount() int {
p.mu.RLock()
defer p.mu.RUnlock()
n := 0
for _, a := range p.accounts {
if a.Enabled && a.Paused() {
n++
}
}
return n
}

func (p *AccountPool) Rename(id, name string) bool {
a := p.Get(id)
if a == nil {
Expand Down Expand Up @@ -387,9 +477,10 @@ func (p *AccountPool) Config() []AccountConfig {
for _, a := range p.accounts {
enabled := a.Enabled
list = append(list, AccountConfig{
Name: a.Name,
APIKey: a.APIKey,
Enabled: &enabled,
Name: a.Name,
APIKey: a.APIKey,
Enabled: &enabled,
PauseBelowCredits: a.PauseThreshold(),
})
}
return list
Expand Down
59 changes: 56 additions & 3 deletions internal/app/accounts_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,59 @@ func TestAccountPoolRoundRobin(t *testing.T) {
}
}

func TestAccountPauseBelowCredits(t *testing.T) {
pool := NewAccountPool([]AccountConfig{{Name: "main", APIKey: "key-a", PauseBelowCredits: 5}})
acct := pool.Get(accountID("key-a"))
if acct == nil {
t.Fatal("account missing")
}

// At the floor the account parks: Acquire must skip it.
acct.ApplyQuotaThreshold(floatPtr(5))
if !acct.Paused() {
t.Fatal("account not paused at the threshold")
}
if got := pool.Acquire(); got != nil {
t.Fatalf("Acquire() = %v, want nil for a paused pool", got)
}
if n := pool.PausedCount(); n != 1 {
t.Fatalf("PausedCount() = %d, want 1", n)
}
view := acct.View()
if view.Status != "paused" || !view.Paused || view.PauseBelowCredits != 5 {
t.Fatalf("view = %+v, want paused at 5", view)
}

// Recovery above the floor resumes it.
acct.ApplyQuotaThreshold(floatPtr(5.01))
if acct.Paused() {
t.Fatal("account still paused after recovery")
}
if got := pool.Acquire(); got != acct {
t.Fatalf("Acquire() = %v, want the recovered account", got)
}

// Lowering the floor re-evaluates immediately against the last balance.
acct.ApplyQuotaThreshold(floatPtr(3))
if !acct.Paused() {
t.Fatal("account not paused at 3 with a floor of 5")
}
pool.SetPauseBelowCredits(acct.ID, 2)
if acct.Paused() {
t.Fatal("lowering the floor did not resume the account")
}
if got := pool.Config(); len(got) != 1 || got[0].PauseBelowCredits != 2 {
t.Fatalf("persisted config = %+v", got)
}

// Zero clears the guard; an unknown balance never pauses on its own.
pool.SetPauseBelowCredits(acct.ID, 0)
acct.ApplyQuotaThreshold(nil)
if acct.Paused() {
t.Fatal("account paused with the guard disabled")
}
}

func TestAccountPoolSkipsDisabledAndRateLimited(t *testing.T) {
pool := poolWithKeys("key-a", "key-b", "key-c")
pool.SetEnabled(accountID("key-a"), false)
Expand Down Expand Up @@ -76,7 +129,7 @@ func TestAccountPoolAllLimitedReturnsNil(t *testing.T) {
}

func TestAccountRecordFailureTracksAuthFailures(t *testing.T) {
a := newAccount("x", "key-x", true)
a := newAccount("x", "key-x", true, 0)
a.RecordFailure(&upstreamAPIError{Status: http.StatusUnauthorized, Message: "bad key"})
a.RecordFailure(&upstreamAPIError{Status: http.StatusForbidden, Message: "no"})
view := a.View()
Expand Down Expand Up @@ -296,7 +349,7 @@ func TestShouldFailoverMatrix(t *testing.T) {

func TestUsageForAccountRecordsSeparately(t *testing.T) {
usage := &UsageTracker{}
acct := newAccount("main", "key-a", true)
acct := newAccount("main", "key-a", true, 0)

usage.ForAccount(acct).Record(10, 20, 0, 0)
usage.ForAccount(acct).Record(1, 2, 3, 0)
Expand Down Expand Up @@ -324,7 +377,7 @@ func TestUsageSnapshotPersistsAccounts(t *testing.T) {
t.Cleanup(func() { usageFile = oldFile })

usage := &UsageTracker{}
usage.ForAccount(newAccount("main", "key-a", true)).Record(5, 6, 0, 0)
usage.ForAccount(newAccount("main", "key-a", true, 0)).Record(5, 6, 0, 0)
if err := usage.save(); err != nil {
t.Fatal(err)
}
Expand Down
17 changes: 14 additions & 3 deletions internal/app/admin.go
Original file line number Diff line number Diff line change
Expand Up @@ -235,14 +235,25 @@ func handleAdminAccountPatch(pool *AccountPool, cfg *Config, usage *UsageTracker
return func(w http.ResponseWriter, r *http.Request) {
id := r.PathValue("id")
var body struct {
Enabled *bool `json:"enabled"`
Name *string `json:"name"`
APIKey *string `json:"api_key"`
Enabled *bool `json:"enabled"`
Name *string `json:"name"`
APIKey *string `json:"api_key"`
PauseBelowCredits *float64 `json:"pause_below_credits"`
}
if err := decodeJSONBody(w, r, &body); err != nil {
writeAdminError(w, r, 400, err.Error())
return
}
if body.PauseBelowCredits != nil {
if *body.PauseBelowCredits < 0 {
writeAdminError(w, r, 400, "pause_below_credits cannot be negative")
return
}
if !pool.SetPauseBelowCredits(id, *body.PauseBelowCredits) {
writeAdminError(w, r, 404, "account not found")
return
}
}
if body.Enabled != nil && !pool.SetEnabled(id, *body.Enabled) {
writeAdminError(w, r, 404, "account not found")
return
Expand Down
Loading
Loading