docs: clarify temp-unavailable TTL defaults and account overrides

.env.example

@@ -156,6 +156,10 @@ ENABLE_CORS=true
 TRUST_PROXY=true
 
 # ⏱️ 上游错误自动暂停配置（秒）
+# 说明：
+# 1) 这是全局默认值
+# 2) Claude 官方 OAuth 账号可在后台单独覆盖 503/5xx 冷却（留空=跟随全局，0=关闭该类型）
+# 3) 若账号勾选“禁用临时冷却”，则不会因 503/5xx 进入 temp_unavailable
 # UPSTREAM_ERROR_503_TTL_SECONDS=60          # 503错误暂停时间（默认60秒）
 # UPSTREAM_ERROR_5XX_TTL_SECONDS=300         # 500/502等5xx错误暂停时间（默认5分钟）
 # UPSTREAM_ERROR_OVERLOAD_TTL_SECONDS=600     # 529过载暂停时间（默认10分钟）

README.md

@@ -373,6 +373,31 @@ docker-compose.yml 已包含：
 
 **注意**: 如果你在国内，这一步可能需要科学上网。
 
+### 2.1 临时暂停（503/5xx）与账号级 TTL 覆盖
+
+系统会在上游异常时临时暂停账号路由，默认由全局配置控制（见 `.env.example`）：
+
+- `UPSTREAM_ERROR_503_TTL_SECONDS`
+- `UPSTREAM_ERROR_5XX_TTL_SECONDS`
+- `UPSTREAM_ERROR_OVERLOAD_TTL_SECONDS`
+- `UPSTREAM_ERROR_AUTH_TTL_SECONDS`
+- `UPSTREAM_ERROR_TIMEOUT_TTL_SECONDS`
+
+在管理后台编辑 **Claude 官方 OAuth 账号** 时，可做账号级覆盖：
+
+- `禁用该账号临时冷却`：该账号不再因 503/5xx 进入临时暂停
+- `503 冷却秒数`：留空=跟随全局，`0`=关闭该账号 503 冷却
+- `5xx 冷却秒数`：留空=跟随全局，`0`=关闭该账号 5xx 冷却
+
+优先级从高到低：
+
+1. 账号级“禁用临时冷却”
+2. 账号级 503/5xx 冷却秒数
+3. 代码调用时传入的自定义 TTL（若有）
+4. 全局环境变量默认值
+
+账户列表会显示“不可路由原因”，包含错误类型、HTTP 状态码、内部冷却总时长、剩余时间和预计恢复时间；点击 `重置状态` 可清除异常状态并恢复参与路由。
+
 ### 3. 创建API Key
 
 给每个使用者分配一个Key：

README_EN.md

@@ -227,6 +227,31 @@ This step is quite important, requires OAuth authorization:
 
 **Note**: If you're in China, this step may require VPN.
 
+### 2.1 Temporary Pause (503/5xx) and Account-Level TTL Overrides
+
+When upstream errors happen, the router can temporarily pause an account. Global defaults are controlled by `.env.example`:
+
+- `UPSTREAM_ERROR_503_TTL_SECONDS`
+- `UPSTREAM_ERROR_5XX_TTL_SECONDS`
+- `UPSTREAM_ERROR_OVERLOAD_TTL_SECONDS`
+- `UPSTREAM_ERROR_AUTH_TTL_SECONDS`
+- `UPSTREAM_ERROR_TIMEOUT_TTL_SECONDS`
+
+For **Claude official OAuth accounts**, you can override policy per account in Admin UI:
+
+- `Disable temporary cooldown for this account`: skip 503/5xx temp pause for this account
+- `503 cooldown seconds`: empty = follow global default, `0` = disable 503 cooldown for this account
+- `5xx cooldown seconds`: empty = follow global default, `0` = disable 5xx cooldown for this account
+
+Priority order (high to low):
+
+1. Account-level "disable temporary cooldown"
+2. Account-level 503/5xx cooldown override
+3. Call-site custom TTL (if provided)
+4. Global env default TTL
+
+In Accounts view, "Routing blocked reason" shows error type, HTTP status, total cooldown, remaining time, and recovery time. Use `Reset Status` to clear abnormal state and restore routing eligibility.
+
 ### 3. Create API Key
 
 Assign a key to each user:
@@ -609,4 +634,4 @@ This project uses the [MIT License](LICENSE).
 
 **🤝 Feel free to submit Issues for problems, welcome PRs for improvement suggestions**
 
-</div>
+</div>

config/config.example.js

@@ -231,6 +231,8 @@ const config = {
   },
 
   // ⏱️ 上游错误自动暂停配置
+  // 说明：此处是全局默认值。Claude 官方 OAuth 账号可在后台做账号级 503/5xx 覆盖，
+  // 且可通过账号设置禁用 temp_unavailable（账号级策略优先于全局默认值）。
   upstreamError: {
     serviceUnavailableTtlSeconds:
       parseInt(process.env.UPSTREAM_ERROR_503_TTL_SECONDS) || 60, // 503错误暂停秒数