From c4229d7c70e8c415f2a1b49edf9d7216636519fc Mon Sep 17 00:00:00 2001 From: XHG Date: Sun, 6 Sep 2026 20:35:20 +0800 Subject: [PATCH 1/2] feat: configurable 429 rate-limit degradation threshold A single upstream 429 used to immediately mark an account as cooling. Add a rate_limit_threshold setting (admin settings page + ZCODE_RATE_LIMIT_THRESHOLD, default 1 = previous behavior): accounts only enter cooling after N consecutive 429s, and 0 disables degradation entirely. 429s still switch to the next account for the current request in all cases. The consecutive counter resets on a successful request and when cooling is applied. Also patch store.update_account in tests that stream success responses so running the suite no longer persists test accounts into the live data/accounts.db. Co-Authored-By: Claude Sonnet 5 --- .env.example | 2 + README.md | 1 + app/models.py | 2 + app/routes/admin_api.py | 7 +++ app/routes/async_pool.py | 17 +++++-- app/routes/gateway.py | 28 ++++++++++- app/settings.py | 2 + app/store.py | 11 +++++ tests/test_async_pool.py | 42 ++++++++++++++++ tests/test_gateway_captcha.py | 93 +++++++++++++++++++++++++++++++++++ 10 files changed, 200 insertions(+), 5 deletions(-) diff --git a/.env.example b/.env.example index 6d24fa7..f98bf55 100644 --- a/.env.example +++ b/.env.example @@ -17,6 +17,8 @@ ZCODE_DATA_DIR=./data ZCODE_QUOTA_REFRESH_INTERVAL=60 # 限流冷却时长(秒) ZCODE_COOLING_SECONDS=300 +# 连续多少次上游 429 才将账号标记为限流冷却;0 = 不因 429 降级 +ZCODE_RATE_LIMIT_THRESHOLD=1 # ── 无痕验证求解(无浏览器:Node + jsdom)────────── # Node 可执行文件(默认走 PATH 中的 node) diff --git a/README.md b/README.md index 7b23b76..e7fcb5a 100644 --- a/README.md +++ b/README.md @@ -179,6 +179,7 @@ python main.py export [file] / import # 导出 / 导入账号 | `ZCODE_QUOTA_REFRESH_INTERVAL` | 60 | 后台刷新额度间隔(秒),0 关闭 | | `ZCODE_CLIENT_VERSION` | 3.7.7 | ZCode 客户端版本(额度请求会附带此版本)| | `ZCODE_COOLING_SECONDS` | 300 | 限流冷却时长(秒)| +| `ZCODE_RATE_LIMIT_THRESHOLD` | 1 | 连续多少次上游 429 才将账号标记为限流冷却;0 表示不因 429 降级(仍会切换下一个账号)| | `ZCODE_NODE_PATH` | node | 无痕验证求解器使用的 Node 可执行文件 | | `ZCODE_CAPTCHA_TIMEOUT` | 40 | 单次验证码求解超时(秒)| | `ZCODE_CAPTCHA_RETRIES` | 4 | 验证码求解失败重试次数 | diff --git a/app/models.py b/app/models.py index bc572cb..77f5cc2 100644 --- a/app/models.py +++ b/app/models.py @@ -93,6 +93,8 @@ class Account: use_count: int = 0 fail_count: int = 0 + # 连续 429 计数:达到降级阈值才标记 cooling,成功请求后清零 + rate_limit_count: int = 0 # 累計調度 token 用量(僅計成功回應,由 UsageCollector 餵入) total_input_tokens: int = 0 total_output_tokens: int = 0 diff --git a/app/routes/admin_api.py b/app/routes/admin_api.py index 63a722c..bedf30f 100644 --- a/app/routes/admin_api.py +++ b/app/routes/admin_api.py @@ -613,6 +613,7 @@ async def get_settings(): "admin_key": store.admin_key(), "gateway_key": store.gateway_key(), "quota_refresh_interval": store.quota_refresh_interval(), + "rate_limit_threshold": store.rate_limit_threshold(), } @@ -635,6 +636,12 @@ async def update_settings(payload: dict = Body(...)): except (TypeError, ValueError): raise HTTPException(400, "刷新间隔必须是非负整数") store.set_setting("quota_refresh_interval", str(interval)) + if "rate_limit_threshold" in payload: + try: + threshold = max(0, int(payload["rate_limit_threshold"])) + except (TypeError, ValueError): + raise HTTPException(400, "限流降级阈值必须是非负整数") + store.set_setting("rate_limit_threshold", str(threshold)) return {"ok": True} diff --git a/app/routes/async_pool.py b/app/routes/async_pool.py index 3b32044..fd5c34c 100644 --- a/app/routes/async_pool.py +++ b/app/routes/async_pool.py @@ -32,6 +32,7 @@ _is_captcha_error, _model_allowed, _normalize_body, + _register_rate_limit, ) router = APIRouter() @@ -137,6 +138,7 @@ async def _forward_sse(resp, queue, account) -> None: pass usage.finish() account.accumulate_tokens(usage.as_dict()) + account.rate_limit_count = 0 store.update_account(account) await queue.put({"type": "done"}) @@ -218,9 +220,18 @@ async def _process_ticket(ticket_id: str): if resp.status_code in (429, 503): account.fail_count += 1 - account.status = Status.COOLING - account.cooling_until = time.time() + settings.COOLING_SECONDS - account.last_error = f"上游服務暫時不可用 HTTP {resp.status_code}" + if resp.status_code == 429: + should_cool, hint = _register_rate_limit(account) + if should_cool: + account.status = Status.COOLING + account.cooling_until = time.time() + settings.COOLING_SECONDS + account.last_error = "上游限流 429" + else: + account.last_error = f"上游限流 429({hint})" + else: + account.status = Status.COOLING + account.cooling_until = time.time() + settings.COOLING_SECONDS + account.last_error = f"上游服務暫時不可用 HTTP {resp.status_code}" store.update_account(account) network_retry = True last_network_error = text diff --git a/app/routes/gateway.py b/app/routes/gateway.py index 10d13c8..786bf65 100644 --- a/app/routes/gateway.py +++ b/app/routes/gateway.py @@ -177,6 +177,23 @@ def _mark(account: Account, status_value: str, error: str | None = None) -> None store.update_account(account) +def _register_rate_limit(account: Account) -> tuple[bool, str]: + """记录一次上游 429,返回 (是否应标记 cooling, 未降级原因)。 + + 降级阈值取自后台设置:1 = 一次 429 即降级;N = 连续 N 次 429 才降级; + 0 = 不降级。账号连续计数在成功请求后清零。 + """ + threshold = store.rate_limit_threshold() + if not threshold: + account.rate_limit_count = 0 + return False, "降级已关闭" + account.rate_limit_count += 1 + if account.rate_limit_count >= threshold: + account.rate_limit_count = 0 + return True, "" + return False, f"未达降级阈值({account.rate_limit_count}/{threshold})" + + def _mark_model_exhausted(account: Account, model: object, error: str) -> None: """只停用已耗盡的請求模型;所有已知模型皆耗盡時才停用整個帳號。""" if not account.mark_model_exhausted(model): @@ -360,8 +377,14 @@ async def _try_account(req_id, account, body, payload, incoming_headers, port, n ) if status_code == 429: - _mark(account, Status.COOLING, "上游限流 429") - logs.warn(req_id, f"账号 {account.name} 被限流 429,切换下一个") + should_cool, hint = _register_rate_limit(account) + if should_cool: + _mark(account, Status.COOLING, "上游限流 429") + logs.warn(req_id, f"账号 {account.name} 被限流 429,达到降级阈值进入冷却,切换下一个") + else: + account.last_error = f"上游限流 429({hint})" + store.update_account(account) + logs.warn(req_id, f"账号 {account.name} 被限流 429({hint}),切换下一个") return _NEXT_ACCOUNT if status_code == 503: @@ -432,6 +455,7 @@ async def _try_account(req_id, account, body, payload, incoming_headers, port, n # 成功:记录用量并流式透传 account.use_count += 1 account.last_used_at = time.time() + account.rate_limit_count = 0 if account.status in (Status.COOLING, Status.EXHAUSTED): account.status = Status.ACTIVE store.update_account(account) diff --git a/app/settings.py b/app/settings.py index dc53ff5..a733a3f 100644 --- a/app/settings.py +++ b/app/settings.py @@ -103,6 +103,8 @@ def _load_or_generate_device_mid() -> str: QUOTA_REFRESH_INTERVAL = _int("ZCODE_QUOTA_REFRESH_INTERVAL", 60) # 限流(cooling)冷却时长(秒) COOLING_SECONDS = _int("ZCODE_COOLING_SECONDS", 300) +# 限流降级阈值:账号连续收到多少次上游 429 才标记 cooling。0 = 不降级 +RATE_LIMIT_THRESHOLD = max(0, _int("ZCODE_RATE_LIMIT_THRESHOLD", 1)) # ── 上游端点 ───────────────────────────────────────────────────────────────── UPSTREAM = { diff --git a/app/store.py b/app/store.py index 4ac0b92..8a2a355 100644 --- a/app/store.py +++ b/app/store.py @@ -77,6 +77,10 @@ def _init_db(self) -> None: f"INSERT OR IGNORE INTO {_META} (key, value) VALUES ('quota_refresh_interval', ?)", (str(settings.QUOTA_REFRESH_INTERVAL),), ) + conn.execute( + f"INSERT OR IGNORE INTO {_META} (key, value) VALUES ('rate_limit_threshold', ?)", + (str(settings.RATE_LIMIT_THRESHOLD),), + ) conn.commit() def _bootstrap_auth_keys(self, conn: sqlite3.Connection) -> None: @@ -125,6 +129,7 @@ def _load(self) -> None: self._settings.setdefault("admin_key", "") self._settings.setdefault("gateway_key", "") self._settings.setdefault("quota_refresh_interval", str(settings.QUOTA_REFRESH_INTERVAL)) + self._settings.setdefault("rate_limit_threshold", str(settings.RATE_LIMIT_THRESHOLD)) self._accounts = {p: [] for p in PROVIDERS} rows = conn.execute( @@ -194,6 +199,12 @@ def quota_refresh_interval(self) -> int: except (TypeError, ValueError): return settings.QUOTA_REFRESH_INTERVAL + def rate_limit_threshold(self) -> int: + try: + return max(0, int(self.get_setting("rate_limit_threshold", settings.RATE_LIMIT_THRESHOLD))) + except (TypeError, ValueError): + return settings.RATE_LIMIT_THRESHOLD + # ── 代理設定 ──────────────────────────────────────────────────────────── def list_proxy_profiles(self) -> list[dict]: """讀取命名代理出口;設定以 JSON 儲存在 meta 表中。""" diff --git a/tests/test_async_pool.py b/tests/test_async_pool.py index e7d9b42..a0b8160 100644 --- a/tests/test_async_pool.py +++ b/tests/test_async_pool.py @@ -89,6 +89,7 @@ async def test_code_3007_refreshes_token_and_forwards_sse(self): with ( patch.object(async_pool.store, "select", return_value=account), + patch.object(async_pool.store, "update_account"), patch.object(async_pool.captcha_manager, "get_verify_param", tokens), patch.object(async_pool.captcha_manager, "invalidate") as invalidate, patch.object(async_pool, "make_async_client", _FakeClient), @@ -195,3 +196,44 @@ async def test_chat_completions_defaults_to_whitelisted_model(self): self.assertIsInstance(resp, StreamingResponse) self.assertEqual(async_pool._tickets[next(iter(async_pool._tickets))]["body"]["model"], "GLM-5.3") + + +class AsyncPoolRateLimitTests(unittest.IsolatedAsyncioTestCase): + async def test_429_below_threshold_keeps_account_active(self): + """async 池的 429 同样遵循降级阈值,未达标不标记 cooling。""" + account = Account.create("zai", "async-429", "header.payload.signature") + _FakeClient.responses = [ + _FakeResponse(429, '{"error":"rate limited"}'), + _FakeResponse(429, '{"error":"rate limited"}'), + ] + _FakeClient.calls = [] + ticket_id = "ticket-429" + queue: asyncio.Queue = asyncio.Queue() + async_pool._tickets[ticket_id] = { + "status": "pending", + "body": {"model": "GLM-5.3", "max_tokens": 8, "messages": [{"role": "user", "content": "ping"}]}, + "queue": queue, + "created_at": 0, + } + + with ( + patch.object(async_pool.store, "select", return_value=account), + patch.object(async_pool.captcha_manager, "get_verify_param", AsyncMock(return_value=CaptchaToken("token", "sgp"))), + patch.object(async_pool, "make_async_client", _FakeClient), + patch.object(async_pool.store, "update_account"), + patch.object(async_pool.store, "rate_limit_threshold", return_value=3), + patch.object(async_pool.settings, "ASYNC_MAX_RETRIES", 1), + patch.object(async_pool.asyncio, "sleep", AsyncMock()), + ): + await async_pool._process_ticket(ticket_id) + + events = [] + while not queue.empty(): + events.append(queue.get_nowait()) + async_pool._tickets.pop(ticket_id, None) + + self.assertEqual(len(_FakeClient.calls), 2) + self.assertEqual(events[-1]["type"], "error") + self.assertEqual(account.status, "active") + self.assertEqual(account.rate_limit_count, 2) + self.assertIn("未达降级阈值", account.last_error or "") diff --git a/tests/test_gateway_captcha.py b/tests/test_gateway_captcha.py index 0416c17..0f0087a 100644 --- a/tests/test_gateway_captcha.py +++ b/tests/test_gateway_captcha.py @@ -245,5 +245,98 @@ async def test_success_stream_accumulates_token_usage(self): update.assert_called() +class GatewayRateLimitThresholdTests(unittest.IsolatedAsyncioTestCase): + """429 限流降级阈值:连续计数达标才标记 cooling,成功后清零。""" + + def _sequence(self, statuses_bodies): + _SequenceClient.responses = [_SequenceResponse(s, b) for s, b in statuses_bodies] + _SequenceClient.calls = 0 + + async def _run(self, account, body=None, consume=False): + with ( + patch.object(gateway.store, "update_account"), + patch.object(gateway.store, "rate_limit_threshold", return_value=self.threshold), + patch.object(gateway.httpx, "AsyncClient", _SequenceClient), + patch.object(gateway.asyncio, "create_task", side_effect=lambda coroutine: coroutine.close()), + ): + response = await gateway._try_account( + "req", account, body if body is not None else {"stream": True, "model": "GLM-5.3"}, b"{}", {}, None, False + ) + if consume and response is not gateway._NEXT_ACCOUNT: + chunks = [chunk async for chunk in response.body_iterator] + return response, chunks + return response, None + + async def test_first_429_cools_with_default_threshold(self): + self.threshold = 1 + account = Account.create("zai", "rl-default", "header.payload.signature") + self._sequence([(429, '{"error":"rate limited"}')]) + response, _ = await self._run(account) + + self.assertIs(response, gateway._NEXT_ACCOUNT) + self.assertEqual(account.status, "cooling") + self.assertGreater(account.cooling_until or 0, 0) + self.assertEqual(account.rate_limit_count, 0) + + async def test_429_below_threshold_keeps_account_active(self): + self.threshold = 3 + account = Account.create("zai", "rl-tolerant", "header.payload.signature") + self._sequence([(429, '{"error":"rate limited"}')]) + response, _ = await self._run(account) + + self.assertIs(response, gateway._NEXT_ACCOUNT) + self.assertEqual(account.status, "active") + self.assertEqual(account.rate_limit_count, 1) + self.assertIn("未达降级阈值", account.last_error or "") + + async def test_consecutive_429s_cool_after_threshold(self): + self.threshold = 3 + account = Account.create("zai", "rl-cumulative", "header.payload.signature") + for _ in range(2): + self._sequence([(429, '{"error":"rate limited"}')]) + response, _ = await self._run(account) + self.assertIs(response, gateway._NEXT_ACCOUNT) + self.assertEqual(account.status, "active") + + self._sequence([(429, '{"error":"rate limited"}')]) + response, _ = await self._run(account) + self.assertIs(response, gateway._NEXT_ACCOUNT) + self.assertEqual(account.status, "cooling") + self.assertGreater(account.cooling_until or 0, 0) + self.assertEqual(account.rate_limit_count, 0) + + async def test_success_resets_rate_limit_count(self): + self.threshold = 3 + account = Account.create("zai", "rl-reset", "header.payload.signature") + self._sequence([ + (429, '{"error":"rate limited"}'), + (200, '{"ok":true}'), + (429, '{"error":"rate limited"}'), + (429, '{"error":"rate limited"}'), + ]) + await self._run(account) # 429 → count 1 + response, chunks = await self._run(account, body={}, consume=True) # 成功 → 计数清零 + self.assertEqual(response.status_code, 200) + self.assertEqual(chunks, [b'{"ok":true}']) + self.assertEqual(account.rate_limit_count, 0) + + await self._run(account) # count 1 + response, _ = await self._run(account) # count 2,仍未达阈值 + self.assertIs(response, gateway._NEXT_ACCOUNT) + self.assertEqual(account.status, "active") + self.assertEqual(account.rate_limit_count, 2) + + async def test_zero_threshold_never_cools_on_429(self): + self.threshold = 0 + account = Account.create("zai", "rl-disabled", "header.payload.signature") + for _ in range(4): + self._sequence([(429, '{"error":"rate limited"}')]) + response, _ = await self._run(account) + self.assertIs(response, gateway._NEXT_ACCOUNT) + self.assertEqual(account.status, "active") + self.assertEqual(account.rate_limit_count, 0) + self.assertIn("降级已关闭", account.last_error or "") + + if __name__ == "__main__": unittest.main() From 5766aefbb94a5520c13a135ff7910307ffdcebb3 Mon Sep 17 00:00:00 2001 From: XHG Date: Sun, 6 Sep 2026 21:03:18 +0800 Subject: [PATCH 2/2] feat: expose rate-limit threshold in React settings page The old admin settings.html was replaced by the React SPA upstream; add the rate_limit_threshold field to frontend settings page and the SettingsResponse type. Co-Authored-By: Claude Sonnet 5 --- frontend/src/lib/types.ts | 1 + frontend/src/pages/settings.tsx | 22 ++++++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/frontend/src/lib/types.ts b/frontend/src/lib/types.ts index 8d77701..38c7216 100644 --- a/frontend/src/lib/types.ts +++ b/frontend/src/lib/types.ts @@ -91,6 +91,7 @@ export interface SettingsResponse { admin_key: string gateway_key: string quota_refresh_interval: number + rate_limit_threshold: number } export interface EgressInfo { diff --git a/frontend/src/pages/settings.tsx b/frontend/src/pages/settings.tsx index 4cf2e8e..1b58355 100644 --- a/frontend/src/pages/settings.tsx +++ b/frontend/src/pages/settings.tsx @@ -20,6 +20,7 @@ export function SettingsPage() { const [adminKeyInput, setAdminKeyInput] = useState('') const [gatewayKey, setGatewayKey] = useState('') const [quotaInterval, setQuotaInterval] = useState('60') + const [rateLimitThreshold, setRateLimitThreshold] = useState('1') const [saving, setSaving] = useState(false) /* 載入完成後填入表單(僅在尚未編輯時同步) */ @@ -28,6 +29,7 @@ export function SettingsPage() { setAdminKeyInput(data.admin_key || '') setGatewayKey(data.gateway_key || '') setQuotaInterval(String(data.quota_refresh_interval ?? 60)) + setRateLimitThreshold(String(data.rate_limit_threshold ?? 1)) }, [data]) async function save(e: FormEvent) { @@ -45,12 +47,18 @@ export function SettingsPage() { toast.error('刷新間隔必須是非負整數') return } + const threshold = parseInt(rateLimitThreshold, 10) + if (isNaN(threshold) || threshold < 0) { + toast.error('限流降級閾值必須是非負整數') + return + } setSaving(true) try { await api('PUT', '/settings', { admin_key: adminKeyInput.trim(), gateway_key: gatewayKey.trim(), quota_refresh_interval: interval, + rate_limit_threshold: threshold, }) /* 同步本機儲存的密鑰,避免改密後被登出 */ await adminKey.set(adminKeyInput.trim()) @@ -108,6 +116,20 @@ export function SettingsPage() { onChange={(e) => setQuotaInterval(e.target.value)} /> +
+ +
+ 帳號連續收到多少次上游 429 後,才標記為「限流」並冷卻一段時間。1 = 一次 429 即降級(預設);設為更大值可容忍偶發限流;0 = 不降級(429 只切換下一個帳號,不標記冷卻)。修改後即時生效。 +
+ setRateLimitThreshold(e.target.value)} + /> +