feat: add sticky rotation strategy (#107) (#110)

* feat: add sticky rotation strategy with admin UI (#107)

Keep using the same account until rate-limited or quota exhausted,
instead of rotating across multiple accounts.

- Add "sticky" to rotation_strategy config enum
- Implement sticky sort in selectByStrategy() (last_used desc)
- Add GET/POST /admin/rotation-settings endpoints
- Add RotationSettings component (sticky vs rotation radio group)
- Add i18n translations (en + zh)
- 13 new tests (account-pool-sticky + rotation-settings routes)

* refactor: extract ROTATION_STRATEGIES constant to eliminate hardcoded duplication

Single source of truth for valid rotation strategies — route handler
and Zod schema both reference the exported constant.

---------

Co-authored-by: icebear0828 <icebear0828@users.noreply.github.com>

CHANGELOG.md

@@ -8,6 +8,13 @@
 
 ### Added
 
+- Sticky rotation strategy（#107）：新增 `sticky` 账号轮换策略，持续使用同一账号直到限速或额度耗尽
+  - `src/config.ts`：`rotation_strategy` 枚举新增 `"sticky"` 选项
+  - `selectByStrategy()` 按 `last_used` 降序排列，优先复用最近使用的账号
+  - `GET/POST /admin/rotation-settings` 端点：读取和更新轮换策略（支持 Bearer auth）
+  - Dashboard：RotationSettings 组件（粘滞 vs 轮换两层 radio group）
+  - i18n：中英文翻译（策略名称 + 描述）
+  - 13 个新测试覆盖 sticky 选择逻辑 + 路由端点
 - `POST /admin/refresh-models` 端点：手动触发模型列表刷新，解决 model-fetcher ~1h 缓存过时导致新模型不可用的问题；支持 Bearer auth（当配置 proxy_api_key 时）
 - Plan routing integration tests：通过 proxy handler 完整路径验证 free/team 账号的模型路由（7 cases），覆盖 plan map 更新后请求解除阻塞的场景
 

shared/hooks/use-rotation-settings.ts

@@ -0,0 +1,59 @@
+import { useState, useEffect, useCallback } from "preact/hooks";
+
+export type RotationStrategy = "least_used" | "round_robin" | "sticky";
+
+export interface RotationSettingsData {
+  rotation_strategy: RotationStrategy;
+}
+
+export function useRotationSettings(apiKey: string | null) {
+  const [data, setData] = useState<RotationSettingsData | null>(null);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [saved, setSaved] = useState(false);
+
+  const load = useCallback(async () => {
+    try {
+      const resp = await fetch("/admin/rotation-settings");
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+      const result: RotationSettingsData = await resp.json();
+      setData(result);
+      setError(null);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }, []);
+
+  const save = useCallback(async (patch: Partial<RotationSettingsData>) => {
+    setSaving(true);
+    setSaved(false);
+    setError(null);
+    try {
+      const headers: Record<string, string> = { "Content-Type": "application/json" };
+      if (apiKey) {
+        headers["Authorization"] = `Bearer ${apiKey}`;
+      }
+      const resp = await fetch("/admin/rotation-settings", {
+        method: "POST",
+        headers,
+        body: JSON.stringify(patch),
+      });
+      if (!resp.ok) {
+        const body = await resp.json().catch(() => ({ error: `HTTP ${resp.status}` }));
+        throw new Error((body as { error?: string }).error ?? `HTTP ${resp.status}`);
+      }
+      const result = await resp.json() as { success: boolean } & RotationSettingsData;
+      setData({ rotation_strategy: result.rotation_strategy });
+      setSaved(true);
+      setTimeout(() => setSaved(false), 3000);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setSaving(false);
+    }
+  }, [apiKey]);
+
+  useEffect(() => { load(); }, [load]);
+
+  return { data, saving, saved, error, save, load };
+}

shared/i18n/translations.ts

@@ -189,6 +189,18 @@ export const translations = {
     quotaThresholdsHint: "Comma-separated percentages (1–100). Highest = critical, rest = warning.",
     quotaSkipExhausted: "Auto-skip exhausted accounts",
     quotaSaved: "Saved",
+    rotationSettings: "Account Selection",
+    rotationStrategy: "Selection Mode",
+    rotationStrategyHint: "How accounts are selected for each request.",
+    rotationSticky: "Sticky",
+    rotationStickyDesc: "Keep using the same account until rate-limited or quota exhausted.",
+    rotationRotate: "Rotation",
+    rotationRotateDesc: "Distribute requests across multiple accounts.",
+    rotationLeastUsed: "Least Used",
+    rotationRoundRobin: "Round Robin",
+    rotationLeastUsedDesc: "Prefer the account with fewest requests.",
+    rotationRoundRobinDesc: "Cycle through accounts in order.",
+    rotationSaved: "Saved",
   },
   zh: {
     serverOnline: "\u670d\u52a1\u8fd0\u884c\u4e2d",
@@ -383,6 +395,18 @@ export const translations = {
     quotaThresholdsHint: "\u9017\u53f7\u5206\u9694\u7684\u767e\u5206\u6bd4 (1\u2013100)\uff0c\u6700\u9ad8\u503c=\u4e25\u91cd\uff0c\u5176\u4f59=\u8b66\u544a\u3002",
     quotaSkipExhausted: "\u81ea\u52a8\u8df3\u8fc7\u989d\u5ea6\u8017\u5c3d\u8d26\u53f7",
     quotaSaved: "\u5df2\u4fdd\u5b58",
+    rotationSettings: "\u8d26\u53f7\u9009\u62e9",
+    rotationStrategy: "\u9009\u62e9\u6a21\u5f0f",
+    rotationStrategyHint: "\u6bcf\u6b21\u8bf7\u6c42\u65f6\u5982\u4f55\u9009\u62e9\u8d26\u53f7\u3002",
+    rotationSticky: "\u7c98\u6ede",
+    rotationStickyDesc: "\u6301\u7eed\u4f7f\u7528\u540c\u4e00\u8d26\u53f7\uff0c\u76f4\u5230\u9650\u901f\u6216\u989d\u5ea6\u8017\u5c3d\u3002",
+    rotationRotate: "\u8f6e\u6362",
+    rotationRotateDesc: "\u5c06\u8bf7\u6c42\u5206\u914d\u5230\u591a\u4e2a\u8d26\u53f7\u3002",
+    rotationLeastUsed: "\u6700\u5c11\u4f7f\u7528",
+    rotationRoundRobin: "\u8f6e\u8be2",
+    rotationLeastUsedDesc: "\u4f18\u5148\u4f7f\u7528\u8bf7\u6c42\u6b21\u6570\u6700\u5c11\u7684\u8d26\u53f7\u3002",
+    rotationRoundRobinDesc: "\u6309\u987a\u5e8f\u8f6e\u6d41\u4f7f\u7528\u5404\u8d26\u53f7\u3002",
+    rotationSaved: "\u5df2\u4fdd\u5b58",
   },
 } as const;
 

src/auth/__tests__/account-pool-sticky.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Tests for sticky rotation strategy in AccountPool.
+ *
+ * Sticky: prefer the most recently used account, keeping it in use
+ * until rate-limited or quota-exhausted.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+let mockStrategy: "least_used" | "round_robin" | "sticky" = "sticky";
+
+const mockGetModelPlanTypes = vi.fn<(id: string) => string[]>(() => []);
+
+vi.mock("../../models/model-store.js", () => ({
+  getModelPlanTypes: (...args: unknown[]) => mockGetModelPlanTypes(args[0] as string),
+}));
+
+vi.mock("../../config.js", () => ({
+  getConfig: vi.fn(() => ({
+    server: { proxy_api_key: null },
+    auth: { jwt_token: "", rotation_strategy: mockStrategy, rate_limit_backoff_seconds: 60 },
+  })),
+}));
+
+let profileForToken: Record<string, { chatgpt_plan_type: string; email: string }> = {};
+
+vi.mock("../../auth/jwt-utils.js", () => ({
+  isTokenExpired: vi.fn(() => false),
+  decodeJwtPayload: vi.fn(() => ({ exp: Math.floor(Date.now() / 1000) + 3600 })),
+  extractChatGptAccountId: vi.fn((token: string) => `aid-${token}`),
+  extractUserProfile: vi.fn((token: string) => profileForToken[token] ?? null),
+}));
+
+vi.mock("../../utils/jitter.js", () => ({
+  jitter: vi.fn((val: number) => val),
+}));
+
+vi.mock("fs", () => ({
+  readFileSync: vi.fn(() => JSON.stringify({ accounts: [] })),
+  writeFileSync: vi.fn(),
+  existsSync: vi.fn(() => false),
+  mkdirSync: vi.fn(),
+  renameSync: vi.fn(),
+}));
+
+import { AccountPool } from "../account-pool.js";
+
+describe("account-pool sticky strategy", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    profileForToken = {};
+    mockStrategy = "sticky";
+  });
+
+  it("selects account with most recent last_used", () => {
+    profileForToken = {
+      "tok-a": { chatgpt_plan_type: "free", email: "a@test.com" },
+      "tok-b": { chatgpt_plan_type: "free", email: "b@test.com" },
+      "tok-c": { chatgpt_plan_type: "free", email: "c@test.com" },
+    };
+
+    const pool = new AccountPool();
+    const idA = pool.addAccount("tok-a");
+    const idB = pool.addAccount("tok-b");
+    const idC = pool.addAccount("tok-c");
+
+    // Simulate: B was used most recently, then A, then C
+    const entryC = pool.getEntry(idC)!;
+    entryC.usage.last_used = new Date(Date.now() - 30_000).toISOString();
+    entryC.usage.request_count = 1;
+
+    const entryA = pool.getEntry(idA)!;
+    entryA.usage.last_used = new Date(Date.now() - 10_000).toISOString();
+    entryA.usage.request_count = 2;
+
+    const entryB = pool.getEntry(idB)!;
+    entryB.usage.last_used = new Date(Date.now() - 1_000).toISOString();
+    entryB.usage.request_count = 5;
+
+    // Sticky should pick B (most recent last_used) despite having most requests
+    const acquired = pool.acquire();
+    expect(acquired).not.toBeNull();
+    expect(acquired!.entryId).toBe(idB);
+    pool.release(acquired!.entryId);
+  });
+
+  it("sticks to same account across multiple acquire/release cycles", () => {
+    profileForToken = {
+      "tok-a": { chatgpt_plan_type: "free", email: "a@test.com" },
+      "tok-b": { chatgpt_plan_type: "free", email: "b@test.com" },
+    };
+
+    const pool = new AccountPool();
+    pool.addAccount("tok-a");
+    pool.addAccount("tok-b");
+
+    // First acquire picks one (arbitrary from fresh pool)
+    const first = pool.acquire()!;
+    pool.release(first.entryId);
+
+    // Subsequent acquires should stick to the same account
+    for (let i = 0; i < 5; i++) {
+      const next = pool.acquire()!;
+      expect(next.entryId).toBe(first.entryId);
+      pool.release(next.entryId);
+    }
+  });
+
+  it("falls back when current account is rate-limited", () => {
+    profileForToken = {
+      "tok-a": { chatgpt_plan_type: "free", email: "a@test.com" },
+      "tok-b": { chatgpt_plan_type: "free", email: "b@test.com" },
+    };
+
+    const pool = new AccountPool();
+    const idA = pool.addAccount("tok-a");
+    const idB = pool.addAccount("tok-b");
+
+    // Make A the sticky choice
+    const entryA = pool.getEntry(idA)!;
+    entryA.usage.last_used = new Date().toISOString();
+    entryA.usage.request_count = 5;
+
+    // Rate-limit A
+    pool.markRateLimited(idA, { retryAfterSec: 300 });
+
+    // Should fall back to B
+    const acquired = pool.acquire();
+    expect(acquired).not.toBeNull();
+    expect(acquired!.entryId).toBe(idB);
+    pool.release(acquired!.entryId);
+  });
+
+  it("picks first available when no account has been used yet", () => {
+    profileForToken = {
+      "tok-a": { chatgpt_plan_type: "free", email: "a@test.com" },
+      "tok-b": { chatgpt_plan_type: "free", email: "b@test.com" },
+      "tok-c": { chatgpt_plan_type: "free", email: "c@test.com" },
+    };
+
+    const pool = new AccountPool();
+    pool.addAccount("tok-a");
+    pool.addAccount("tok-b");
+    pool.addAccount("tok-c");
+
+    // All accounts have null last_used — should pick one
+    const first = pool.acquire();
+    expect(first).not.toBeNull();
+    pool.release(first!.entryId);
+
+    // After releasing, the same one should be sticky
+    const second = pool.acquire();
+    expect(second).not.toBeNull();
+    expect(second!.entryId).toBe(first!.entryId);
+    pool.release(second!.entryId);
+  });
+
+  it("respects model filtering", () => {
+    profileForToken = {
+      "tok-free": { chatgpt_plan_type: "free", email: "free@test.com" },
+      "tok-team": { chatgpt_plan_type: "team", email: "team@test.com" },
+    };
+    mockGetModelPlanTypes.mockReturnValue(["team"]);
+
+    const pool = new AccountPool();
+    const idFree = pool.addAccount("tok-free");
+    const idTeam = pool.addAccount("tok-team");
+
+    // Use the free account more recently
+    const entryFree = pool.getEntry(idFree)!;
+    entryFree.usage.last_used = new Date().toISOString();
+    entryFree.usage.request_count = 10;
+
+    // Model requires team plan — sticky should pick team account despite free being more recent
+    const acquired = pool.acquire({ model: "gpt-5.4" });
+    expect(acquired).not.toBeNull();
+    expect(acquired!.entryId).toBe(idTeam);
+    pool.release(acquired!.entryId);
+  });
+
+  it("least_used still works (regression guard)", () => {
+    mockStrategy = "least_used";
+    profileForToken = {
+      "tok-a": { chatgpt_plan_type: "free", email: "a@test.com" },
+      "tok-b": { chatgpt_plan_type: "free", email: "b@test.com" },
+    };
+
+    const pool = new AccountPool();
+    const idA = pool.addAccount("tok-a");
+    const idB = pool.addAccount("tok-b");
+
+    // A has more requests — least_used should prefer B
+    const entryA = pool.getEntry(idA)!;
+    entryA.usage.request_count = 10;
+    entryA.usage.last_used = new Date().toISOString();
+
+    const entryB = pool.getEntry(idB)!;
+    entryB.usage.request_count = 2;
+
+    const acquired = pool.acquire();
+    expect(acquired).not.toBeNull();
+    expect(acquired!.entryId).toBe(idB);
+    pool.release(acquired!.entryId);
+  });
+});

src/auth/account-pool.ts

@@ -133,6 +133,15 @@ export class AccountPool {
       this.roundRobinIndex++;
       return selected;
     }
+    if (config.auth.rotation_strategy === "sticky") {
+      // Sticky: prefer most recently used account (keep reusing until unavailable)
+      candidates.sort((a, b) => {
+        const aTime = a.usage.last_used ? new Date(a.usage.last_used).getTime() : 0;
+        const bTime = b.usage.last_used ? new Date(b.usage.last_used).getTime() : 0;
+        return bTime - aTime; // desc — most recent first
+      });
+      return candidates[0];
+    }
     // least_used: sort by request_count asc → window_reset_at asc → last_used asc (LRU)
     candidates.sort((a, b) => {
       const diff = a.usage.request_count - b.usage.request_count;

src/config.ts

@@ -6,6 +6,8 @@ import { loadStaticModels } from "./models/model-store.js";
 import { triggerImmediateRefresh } from "./models/model-fetcher.js";
 import { getConfigDir } from "./paths.js";
 
+export const ROTATION_STRATEGIES = ["least_used", "round_robin", "sticky"] as const;
+
 const ConfigSchema = z.object({
   api: z.object({
     base_url: z.string().default("https://chatgpt.com/backend-api"),
@@ -30,7 +32,7 @@ const ConfigSchema = z.object({
     jwt_token: z.string().nullable().default(null),
     chatgpt_oauth: z.boolean().default(true),
     refresh_margin_seconds: z.number().min(0).default(300),
-    rotation_strategy: z.enum(["least_used", "round_robin"]).default("least_used"),
+    rotation_strategy: z.enum(ROTATION_STRATEGIES).default("least_used"),
     rate_limit_backoff_seconds: z.number().min(1).default(60),
     oauth_client_id: z.string().default("app_EMoamEEZ73f0CkXaXp7hrann"),
     oauth_auth_endpoint: z.string().default("https://auth.openai.com/oauth/authorize"),

src/routes/__tests__/rotation-settings.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Tests for rotation settings endpoints.
+ * GET  /admin/rotation-settings — read current rotation strategy
+ * POST /admin/rotation-settings — update rotation strategy
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// --- Mocks (before any imports) ---
+
+const mockConfig = {
+  server: { proxy_api_key: null as string | null },
+  auth: { rotation_strategy: "least_used" as string },
+  quota: {
+    refresh_interval_minutes: 5,
+    warning_thresholds: { primary: [80, 90], secondary: [80, 90] },
+    skip_exhausted: true,
+  },
+};
+
+vi.mock("../../config.js", () => ({
+  getConfig: vi.fn(() => mockConfig),
+  reloadAllConfigs: vi.fn(),
+  ROTATION_STRATEGIES: ["least_used", "round_robin", "sticky"],
+}));
+
+vi.mock("../../paths.js", () => ({
+  getConfigDir: vi.fn(() => "/tmp/test-config"),
+  getPublicDir: vi.fn(() => "/tmp/test-public"),
+  getDesktopPublicDir: vi.fn(() => "/tmp/test-desktop"),
+  getDataDir: vi.fn(() => "/tmp/test-data"),
+  getBinDir: vi.fn(() => "/tmp/test-bin"),
+  isEmbedded: vi.fn(() => false),
+}));
+
+vi.mock("../../utils/yaml-mutate.js", () => ({
+  mutateYaml: vi.fn(),
+}));
+
+vi.mock("../../tls/transport.js", () => ({
+  getTransport: vi.fn(),
+  getTransportInfo: vi.fn(() => ({})),
+}));
+
+vi.mock("../../tls/curl-binary.js", () => ({
+  getCurlDiagnostics: vi.fn(() => ({})),
+}));
+
+vi.mock("../../fingerprint/manager.js", () => ({
+  buildHeaders: vi.fn(() => ({})),
+}));
+
+vi.mock("../../update-checker.js", () => ({
+  getUpdateState: vi.fn(() => ({})),
+  checkForUpdate: vi.fn(),
+  isUpdateInProgress: vi.fn(() => false),
+}));
+
+vi.mock("../../self-update.js", () => ({
+  getProxyInfo: vi.fn(() => ({})),
+  canSelfUpdate: vi.fn(() => false),
+  checkProxySelfUpdate: vi.fn(),
+  applyProxySelfUpdate: vi.fn(),
+  isProxyUpdateInProgress: vi.fn(() => false),
+  getCachedProxyUpdateResult: vi.fn(() => null),
+  getDeployMode: vi.fn(() => "git"),
+}));
+
+vi.mock("@hono/node-server/serve-static", () => ({
+  serveStatic: vi.fn(() => vi.fn()),
+}));
+
+vi.mock("@hono/node-server/conninfo", () => ({
+  getConnInfo: vi.fn(() => ({ remote: { address: "127.0.0.1" } })),
+}));
+
+import { createWebRoutes } from "../web.js";
+import { mutateYaml } from "../../utils/yaml-mutate.js";
+
+const mockPool = {
+  getAll: vi.fn(() => []),
+  acquire: vi.fn(),
+  release: vi.fn(),
+} as unknown as Parameters<typeof createWebRoutes>[0];
+
+describe("GET /admin/rotation-settings", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockConfig.auth.rotation_strategy = "least_used";
+  });
+
+  it("returns current rotation strategy", async () => {
+    const app = createWebRoutes(mockPool);
+    const res = await app.request("/admin/rotation-settings");
+    expect(res.status).toBe(200);
+    const data = await res.json();
+    expect(data).toEqual({ rotation_strategy: "least_used" });
+  });
+
+  it("reflects config value", async () => {
+    mockConfig.auth.rotation_strategy = "sticky";
+    const app = createWebRoutes(mockPool);
+    const res = await app.request("/admin/rotation-settings");
+    const data = await res.json();
+    expect(data.rotation_strategy).toBe("sticky");
+  });
+});
+
+describe("POST /admin/rotation-settings", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockConfig.server.proxy_api_key = null;
+    mockConfig.auth.rotation_strategy = "least_used";
+  });
+
+  it("updates strategy to sticky", async () => {
+    const app = createWebRoutes(mockPool);
+    const res = await app.request("/admin/rotation-settings", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ rotation_strategy: "sticky" }),
+    });
+    expect(res.status).toBe(200);
+    const data = await res.json();
+    expect(data.success).toBe(true);
+    expect(mutateYaml).toHaveBeenCalledOnce();
+  });
+
+  it("accepts all three valid strategies", async () => {
+    const app = createWebRoutes(mockPool);
+    for (const strategy of ["least_used", "round_robin", "sticky"]) {
+      vi.mocked(mutateYaml).mockClear();
+      const res = await app.request("/admin/rotation-settings", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ rotation_strategy: strategy }),
+      });
+      expect(res.status).toBe(200);
+    }
+  });
+
+  it("rejects invalid strategy with 400", async () => {
+    const app = createWebRoutes(mockPool);
+    const res = await app.request("/admin/rotation-settings", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ rotation_strategy: "random" }),
+    });
+    expect(res.status).toBe(400);
+    const data = await res.json();
+    expect(data.error).toBeDefined();
+  });
+
+  it("rejects missing strategy with 400", async () => {
+    const app = createWebRoutes(mockPool);
+    const res = await app.request("/admin/rotation-settings", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("requires auth when proxy_api_key is set", async () => {
+    mockConfig.server.proxy_api_key = "my-secret";
+    const app = createWebRoutes(mockPool);
+
+    // No auth → 401
+    const res1 = await app.request("/admin/rotation-settings", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ rotation_strategy: "sticky" }),
+    });
+    expect(res1.status).toBe(401);
+
+    // With auth → 200
+    const res2 = await app.request("/admin/rotation-settings", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: "Bearer my-secret",
+      },
+      body: JSON.stringify({ rotation_strategy: "sticky" }),
+    });
+    expect(res2.status).toBe(200);
+  });
+});

src/routes/web.ts

@@ -5,7 +5,7 @@ import { getConnInfo } from "@hono/node-server/conninfo";
 import { readFileSync, existsSync } from "fs";
 import { resolve } from "path";
 import type { AccountPool } from "../auth/account-pool.js";
-import { getConfig, getFingerprint, reloadAllConfigs } from "../config.js";
+import { getConfig, getFingerprint, reloadAllConfigs, ROTATION_STRATEGIES } from "../config.js";
 import { getPublicDir, getDesktopPublicDir, getConfigDir, getDataDir, getBinDir, isEmbedded } from "../paths.js";
 import { getTransport, getTransportInfo } from "../tls/transport.js";
 import { getCurlDiagnostics } from "../tls/curl-binary.js";
@@ -446,6 +446,49 @@ export function createWebRoutes(accountPool: AccountPool): Hono {
 
   // --- Settings endpoints ---
 
+  // --- Rotation settings endpoints ---
+
+  app.get("/admin/rotation-settings", (c) => {
+    const config = getConfig();
+    return c.json({
+      rotation_strategy: config.auth.rotation_strategy,
+    });
+  });
+
+  app.post("/admin/rotation-settings", async (c) => {
+    const config = getConfig();
+    const currentKey = config.server.proxy_api_key;
+
+    if (currentKey) {
+      const authHeader = c.req.header("Authorization") ?? "";
+      const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
+      if (token !== currentKey) {
+        c.status(401);
+        return c.json({ error: "Invalid current API key" });
+      }
+    }
+
+    const body = await c.req.json() as { rotation_strategy?: string };
+    const valid: readonly string[] = ROTATION_STRATEGIES;
+    if (!body.rotation_strategy || !valid.includes(body.rotation_strategy)) {
+      c.status(400);
+      return c.json({ error: `rotation_strategy must be one of: ${ROTATION_STRATEGIES.join(", ")}` });
+    }
+
+    const configPath = resolve(getConfigDir(), "default.yaml");
+    mutateYaml(configPath, (data) => {
+      if (!data.auth) data.auth = {};
+      (data.auth as Record<string, unknown>).rotation_strategy = body.rotation_strategy;
+    });
+    reloadAllConfigs();
+
+    const updated = getConfig();
+    return c.json({
+      success: true,
+      rotation_strategy: updated.auth.rotation_strategy,
+    });
+  });
+
   app.get("/admin/settings", (c) => {
     const config = getConfig();
     return c.json({ proxy_api_key: config.server.proxy_api_key });

web/src/App.tsx

@@ -11,6 +11,7 @@ import { AnthropicSetup } from "./components/AnthropicSetup";
 import { CodeExamples } from "./components/CodeExamples";
 import { SettingsPanel } from "./components/SettingsPanel";
 import { QuotaSettings } from "./components/QuotaSettings";
+import { RotationSettings } from "./components/RotationSettings";
 import { TestConnection } from "./components/TestConnection";
 import { Footer } from "./components/Footer";
 import { ProxySettings } from "./pages/ProxySettings";
@@ -150,6 +151,7 @@ function Dashboard() {
           />
           <SettingsPanel />
           <QuotaSettings />
+          <RotationSettings />
           <TestConnection />
         </div>
       </main>

web/src/components/RotationSettings.tsx

@@ -0,0 +1,155 @@
+import { useState, useCallback } from "preact/hooks";
+import { useT } from "../../../shared/i18n/context";
+import { useRotationSettings, type RotationStrategy } from "../../../shared/hooks/use-rotation-settings";
+import { useSettings } from "../../../shared/hooks/use-settings";
+
+type Mode = "sticky" | "rotation";
+type RotationSub = "least_used" | "round_robin";
+
+function toMode(strategy: RotationStrategy): Mode {
+  return strategy === "sticky" ? "sticky" : "rotation";
+}
+
+function toStrategy(mode: Mode, sub: RotationSub): RotationStrategy {
+  return mode === "sticky" ? "sticky" : sub;
+}
+
+export function RotationSettings() {
+  const t = useT();
+  const settings = useSettings();
+  const rs = useRotationSettings(settings.apiKey);
+
+  const current = rs.data?.rotation_strategy ?? "least_used";
+  const currentMode = toMode(current);
+  const currentSub: RotationSub = current === "sticky" ? "least_used" : (current as RotationSub);
+
+  const [draftMode, setDraftMode] = useState<Mode | null>(null);
+  const [draftSub, setDraftSub] = useState<RotationSub | null>(null);
+  const [collapsed, setCollapsed] = useState(true);
+
+  const displayMode = draftMode ?? currentMode;
+  const displaySub = draftSub ?? currentSub;
+  const displayStrategy = toStrategy(displayMode, displaySub);
+  const isDirty = displayStrategy !== current;
+
+  const handleSave = useCallback(async () => {
+    if (!isDirty) return;
+    await rs.save({ rotation_strategy: displayStrategy });
+    setDraftMode(null);
+    setDraftSub(null);
+  }, [isDirty, displayStrategy, rs]);
+
+  const radioCls = "w-4 h-4 text-primary focus:ring-primary cursor-pointer";
+  const labelCls = "text-[0.8rem] font-medium text-slate-700 dark:text-text-main cursor-pointer";
+
+  return (
+    <section class="bg-white dark:bg-card-dark border border-gray-200 dark:border-border-dark rounded-xl shadow-sm transition-colors">
+      <button
+        onClick={() => setCollapsed(!collapsed)}
+        class="w-full flex items-center justify-between p-5 cursor-pointer select-none"
+      >
+        <div class="flex items-center gap-2">
+          <svg class="size-5 text-primary" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M19.5 12c0-1.232-.046-2.453-.138-3.662a4.006 4.006 0 00-3.7-3.7 48.678 48.678 0 00-7.324 0 4.006 4.006 0 00-3.7 3.7c-.017.22-.032.441-.046.662M19.5 12l3-3m-3 3l-3-3m-12 3c0 1.232.046 2.453.138 3.662a4.006 4.006 0 003.7 3.7 48.656 48.656 0 007.324 0 4.006 4.006 0 003.7-3.7c.017-.22.032-.441.046-.662M4.5 12l3 3m-3-3l-3 3" />
+          </svg>
+          <h2 class="text-[0.95rem] font-bold">{t("rotationSettings")}</h2>
+        </div>
+        <svg class={`size-5 text-slate-400 dark:text-text-dim transition-transform ${collapsed ? "" : "rotate-180"}`} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M19.5 8.25l-7.5 7.5-7.5-7.5" />
+        </svg>
+      </button>
+
+      {!collapsed && (
+        <div class="px-5 pb-5 border-t border-slate-100 dark:border-border-dark pt-4 space-y-4">
+          <p class="text-xs text-slate-400 dark:text-text-dim">{t("rotationStrategyHint")}</p>
+
+          {/* Mode: Sticky vs Rotation */}
+          <div class="space-y-3">
+            {/* Sticky */}
+            <label class="flex items-start gap-3 p-3 rounded-lg border border-gray-200 dark:border-border-dark cursor-pointer hover:bg-slate-50 dark:hover:bg-bg-dark transition-colors">
+              <input
+                type="radio"
+                name="rotation-mode"
+                checked={displayMode === "sticky"}
+                onChange={() => setDraftMode("sticky")}
+                class={radioCls + " mt-0.5"}
+              />
+              <div>
+                <span class={labelCls}>{t("rotationSticky")}</span>
+                <p class="text-xs text-slate-400 dark:text-text-dim mt-0.5">{t("rotationStickyDesc")}</p>
+              </div>
+            </label>
+
+            {/* Rotation */}
+            <label class="flex items-start gap-3 p-3 rounded-lg border border-gray-200 dark:border-border-dark cursor-pointer hover:bg-slate-50 dark:hover:bg-bg-dark transition-colors">
+              <input
+                type="radio"
+                name="rotation-mode"
+                checked={displayMode === "rotation"}
+                onChange={() => setDraftMode("rotation")}
+                class={radioCls + " mt-0.5"}
+              />
+              <div class="flex-1">
+                <span class={labelCls}>{t("rotationRotate")}</span>
+                <p class="text-xs text-slate-400 dark:text-text-dim mt-0.5">{t("rotationRotateDesc")}</p>
+              </div>
+            </label>
+
+            {/* Sub-strategy (only when rotation mode) */}
+            {displayMode === "rotation" && (
+              <div class="ml-10 space-y-2">
+                <label class="flex items-center gap-2 cursor-pointer">
+                  <input
+                    type="radio"
+                    name="rotation-sub"
+                    checked={displaySub === "least_used"}
+                    onChange={() => setDraftSub("least_used")}
+                    class={radioCls}
+                  />
+                  <div>
+                    <span class="text-xs font-medium text-slate-600 dark:text-text-main">{t("rotationLeastUsed")}</span>
+                    <span class="text-xs text-slate-400 dark:text-text-dim ml-1.5">{t("rotationLeastUsedDesc")}</span>
+                  </div>
+                </label>
+                <label class="flex items-center gap-2 cursor-pointer">
+                  <input
+                    type="radio"
+                    name="rotation-sub"
+                    checked={displaySub === "round_robin"}
+                    onChange={() => setDraftSub("round_robin")}
+                    class={radioCls}
+                  />
+                  <div>
+                    <span class="text-xs font-medium text-slate-600 dark:text-text-main">{t("rotationRoundRobin")}</span>
+                    <span class="text-xs text-slate-400 dark:text-text-dim ml-1.5">{t("rotationRoundRobinDesc")}</span>
+                  </div>
+                </label>
+              </div>
+            )}
+          </div>
+
+          {/* Save button + status */}
+          <div class="flex items-center gap-3">
+            <button
+              onClick={handleSave}
+              disabled={rs.saving || !isDirty}
+              class={`px-4 py-2 text-sm font-medium rounded-lg transition-colors whitespace-nowrap ${
+                isDirty && !rs.saving
+                  ? "bg-primary text-white hover:bg-primary/90 cursor-pointer"
+                  : "bg-slate-100 dark:bg-[#21262d] text-slate-400 dark:text-text-dim cursor-not-allowed"
+              }`}
+            >
+              {rs.saving ? "..." : t("submit")}
+            </button>
+            {rs.saved && (
+              <span class="text-xs font-medium text-green-600 dark:text-green-400">{t("rotationSaved")}</span>
+            )}
+            {rs.error && (
+              <span class="text-xs font-medium text-red-500">{rs.error}</span>
+            )}
+          </div>
+        </div>
+      )}
+    </section>
+  );
+}