OmniRoute 模型目錄同步指南/v1/models 如何用緩存、哈希與降級策略保持模型列表穩定 【免費下載鏈接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 450 contributors項目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 是一個免費開源的 AI 網關通過統一的/v1/models端點聚合 350 供應商、1200 模型的目錄列表。本文拆解 OmniRoute 模型目錄同步機制的核心響應緩存、API Key 哈希指紋、版本號失效以及上游探測失敗時的降級策略幫助你理解為什么并發查詢不會雪崩、配置修改為何能即時生效。一、為什么 /v1/models 需要專門的同步機制/v1/models返回 OpenAI 兼容的模型列表。一次目錄構建需要遍歷8 個模型注冊表并查詢 SQLite 中的連接、Combos、自定義模型與別名。在 Next.js 單線程 App Router 中N 個并發請求會被串行執行第 N 個請求的延遲是單次構建耗時的 N 倍生產環境曾測得一次構建約 49 秒。因此 OmniRoute 為這個端點設計了獨立的緩存層響應體構建器src/app/api/v1/models/route.ts緩存核心模塊src/app/api/v1/models/catalogCache.ts并發請求會被合并到同一個進行中的構建上#6408共享一次結果而不是排隊執行 N 次。二、緩存60 秒 TTL 與寫操作即時失效1. TTL 緩存窗口緩存默認 TTL 為60 秒CATALOG_CACHE_TTL_MS_DEFAULT可通過settings.cache.modelCatalogCacheTtlMs配置上限同為 60 秒。這個窗口解決的是沒有任何寫操作場景下重復請求的問題——重放幾秒前構建好的響應體正是緩存的價值所在。2. 版本號失效改配置立刻生效TTL 只控制沒人動過配置的情況。真正的實時性由版本號機制保證src/lib/db/readCache.ts 維護一個單調遞增的modelCatalogCacheVersion每次對settings、connections、combos、pricing的寫入都會觸發invalidateDbCache()使版本號 1緩存層在每次訪問和每次構建完成時都會比對版本號一旦變化整個緩存 Map 被清空下一次讀取同步構建新目錄這意味著你在 Dashboard 上增刪一個供應商連接下一個/v1/models請求就能看到新模型——不需要等 60 秒。3. 代際隔離防止過期構建污染新緩存進行中的構建會綁定它啟動時的版本號generation。如果構建進行中有寫操作使代際前移新請求不會加入這個過期構建過期構建完成后不會回填緩存只返回給原本等待它的那個請求這一設計杜絕了寫操作前狀態被緩存并長期服務的臟數據問題。三、哈希API Key 如何安全地進入緩存鍵不同 API Key 看到的模型范圍不同權限隔離所以緩存鍵必須包含身份維度。但密鑰絕不能以明文進入進程內存中的 Map 鍵。OmniRoute 的做法是用固定上下文標簽omniroute-catalog-cache-fingerprint-v1對 Key 做HMAC-SHA256摘要截取前 16 位十六進制作為指紋#10313避免原始憑據留在進程堆中最終緩存鍵由 6 個維度拼接prefix、是否 Codex 客戶端、Key 指紋、configuredOnly、是否隱藏自動 Combo、是否隱藏 no-think 變體完整鍵構建邏輯見 catalogCache.ts 的 buildCatalogCacheKey指紋函數在 fingerprintCatalogAuthKey。四、降級策略過期緩存與探測失敗的兩道保險1. Stale-While-Revalidate過期也能秒回Claude Code 等 CLI 客戶端的目錄發現超時只有 3 秒絕不允許它等待一次完整重建。因此緩存過期后還有一層30 秒的過期寬限窗口CATALOG_STALE_WHILE_REVALIDATE_MS窗口內的過期條目立即原樣返回僅限成功狀態 200 的條目同時通過 Next.js 的after()調度后臺重建——after()保證響應先沖刷到客戶端再執行重建避免同步構建器占滿事件循環、讓秒回名不副實#8728、#11574超過 30 秒窗口則退回冷路徑等待重建防止持續失敗的刷新永久釘住一份古老目錄2. 模型同步的三級回退與拒絕持久化在供應商模型同步/api/providers/{id}/sync-models中遠程探測失敗時按優先級降級遠程發現→ 失敗則 2.已緩存目錄附帶warning字段如 Models probe failed (401) — using cached catalog→ 仍無緩存則 3.本地靜態目錄local_catalog關鍵規則降級結果不得被持久化為同步目錄否則過期的 Key 會悄悄釘死一份陳舊目錄、掩蓋真實故障。判定邏輯在 degradedLocalCatalog.tsisDegradedLocalCataloglocal_catalog來源且非有意為之Reka 等本地目錄型供應商標記了intentional: true不受影響isDegradedCachedCatalogcache來源且攜帶warning普通緩存命中不帶警告同步路由 sync-models/route.ts 據此拒絕把降級發現當作成功導入。3. HEAD 探測的輕量降級OpenAI SDK 等客戶端會用 HEAD 做健康探測。OmniRoute 提供顯式 HEAD 處理器直接返回空 200#6400避免自動推導的 HEAD 把 200 供應商的完整目錄流式寫出導致約 6 秒掛起。五、如何驗證與調整場景建議操作修改供應商后列表未更新正常不應發生檢查寫操作是否走了invalidateDbCache()路徑目錄構建慢、并發高確認默認 60s TTL 生效并發請求已合并為單次構建CLI 客戶端發現超時30s 寬限窗口內會自動秒回舊目錄并后臺刷新模型同步報無新模型檢查是否收到source: cache且帶warning的降級響應相關測試覆蓋了并發合并v1-models-concurrent-6408.test.ts、TTL 行為v1-models-catalog-ttl.test.ts與緩存鍵哈希10313-catalog-cache-key-hashing.test.ts。六、總結OmniRoute 的/v1/models同步機制可以用一句話概括TTL 緩存扛并發、HMAC 哈希保安全、版本號保新鮮、寬限窗口保可用、降級標記保誠實。五層設計協同工作讓 1200 模型的目錄既快又準。核心文件速查路由入口src/app/api/v1/models/route.ts緩存與哈希src/app/api/v1/models/catalogCache.ts版本號失效src/lib/db/readCache.ts降級判定src/app/api/providers/[id]/sync-models/degradedLocalCatalog.ts【免費下載鏈接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 450 contributors項目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考