From afd90564ec08f25650c84d26576bb2296b1f0a20 Mon Sep 17 00:00:00 2001 From: xrj-dsh-agent <351930041+xrj-dsh-agent@users.noreply.github.com> Date: Tue, 3 Nov 2026 23:07:29 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=EF=BC=9A=E4=BC=9A=E8=AF=9D?= =?UTF-8?q?=E7=B2=98=E6=80=A7=E5=86=99=E5=85=A5=E6=94=B6=E6=88=90=E5=94=AF?= =?UTF-8?q?=E4=B8=80=E5=87=BA=E5=8F=A3=20+=20=E5=A4=B1=E6=95=88=E6=97=A5?= =?UTF-8?q?=E5=BF=97=EF=BC=88issue=20#2=20/=20=E4=B8=8A=E6=B8=B8=20#443?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 修复:自定义提供商成功分支漏写会话粘性 —— 内置 / 会话式 / 自定义三条成功 路径收成一个 remember_session 出口,空键、TTL 档位、清除代次等判据下沉到 StickySessions::bind,新增转发路径不会再因为「忘了调 sticky_bind」而静默 不粘。 2. 修复:会话粘滞列表按查询档位淘汰绑定 —— 打开一次管理页(auto 5 分钟档) 会把 6 小时档的绑定一起清掉;改为按每条绑定自己的 TTL 清理,读取不再有 副作用(查找只判不删,也不再改写写下时的 TTL)。 3. 新增:粘性失效/变化日志(logs 表)—— account-switch、identity-changed、 evicted-ttl、evicted-capacity、cleared、skipped-empty-key(每进程一次)、 skipped-stale-generation。 4. 优化:会话键提取链与来源标签同源(不再两份名单),补不带 x- 前缀的 opencode-session / session-affinity;请求日志的路由快照新增 stickySource, 直接看出这次会话键来自哪个字段。 5. 测试:绑定→查找闭环、TTL 过期、列表读取不淘汰、来源标签一致性、选路层 「同会话第二条请求命中并置顶」。 --- .../src/server/core/upstream/provider_loop.rs | 61 +++-- .../core/upstream/provider_loop/tests.rs | 90 +++++++ .../src/server/core/upstream/route_state.rs | 173 +++++++++--- .../src/server/core/upstream/route_sticky.rs | 249 ++++++++++++++++-- 4 files changed, 503 insertions(+), 70 deletions(-) diff --git a/desktop-tauri/src-tauri/server/src/server/core/upstream/provider_loop.rs b/desktop-tauri/src-tauri/server/src/server/core/upstream/provider_loop.rs index b266ec473..a5374393c 100644 --- a/desktop-tauri/src-tauri/server/src/server/core/upstream/provider_loop.rs +++ b/desktop-tauri/src-tauri/server/src/server/core/upstream/provider_loop.rs @@ -655,6 +655,32 @@ fn filter_by_key_scope( .with_code("model_not_found")) } +/// 转发成功的「记住这个会话的承载账号」出口 —— **三条成功路径共用这一个**。 +/// +/// 抽出来的理由不是省几行:粘性的写入曾经在自定义提供商那条路径上整条漏掉 +/// (issue #2 / 上游 #443 —— v3.0.8 的 `attempt_custom` 成功分支里没有 +/// `sticky_bind`,自定义家转发的会话因此永远不粘,而请求日志里只看得到 +/// `stickyHit:false`、没有任何报错)。三条路径各写一遍 `sticky_bind`,就还会 +/// 有第四次的遗漏;写成唯一出口之后,「新增一条转发路径」与「粘性写没写」 +/// 不再需要靠人记着对上。 +/// +/// 判据(空会话键 / TTL 档位 / 清除代次)全部在 `StickySessions::bind` 里, +/// 本函数只把「此刻的配置」换算成 TTL —— 与选路侧 `routing::sticky_ttl_ms` +/// 同一来源,免得写与读各用一个档位。 +fn remember_session( + service: &UpstreamService, + conv_key: &str, + model: &str, + account_id: &str, + source: &str, + generation: u64, +) { + let ttl = config::routing_settings().sticky.ttl_ms().unwrap_or(0); + service + .route + .sticky_bind(conv_key, model, account_id, source, logging::now_ms(), ttl, generation); +} + /// 账号循环:每一轮从候选池里按全局优先级选一个账号,用它所属家的适配器发一次。 /// /// 按 `is_stateful` 分流(架构文档 §4.2.1): @@ -762,7 +788,15 @@ async fn attempt_queue( // 决策快照挂进 telemetry(最后一次为准:请求日志的「路由回放」显示 // 的是最终承载那次选路的完整排序 —— 与 attempts 明细的换号链互补, // 那边回答「试了谁」,这边回答「当时为什么这么排」)。 - if let Some(decision) = target.decision.clone() { + if let Some(mut decision) = target.decision.clone() { + // 会话键的**来源标签**(哪条提取链生效):路由回放要能回答「这次 + // 请求的会话键是哪个字段给的」。只记标签,不记原始键值。 + if let Some(object) = decision.as_object_mut() { + object.insert( + "stickySource".to_string(), + Value::String(sticky_source.to_string()), + ); + } ctx.telemetry.set_route_decision(decision); } // 连接计数改绑到这一轮选中的账号:失败重试换账号时计数跟着走, @@ -781,9 +815,8 @@ async fn attempt_queue( match attempt_custom(service, ctx, target, slot, connections, degraded).await { Ok(outcome) => { if let Some(account_id) = custom_account_id.as_deref() { - service.route.sticky_bind( - &conv_key, &model, account_id, sticky_source, logging::now_ms(), - config::routing_settings().sticky.ttl_ms().unwrap_or(0), sticky_generation, + remember_session( + service, &conv_key, &model, account_id, sticky_source, sticky_generation, ); service.route.backoff_clear(account_id); service.route.sink_clear(account_id); @@ -929,9 +962,8 @@ async fn attempt_queue( { Ok(outcome) => { if let Some(account_id) = stateful_account_id.as_deref() { - service.route.sticky_bind( - &conv_key, &model, account_id, sticky_source, logging::now_ms(), - config::routing_settings().sticky.ttl_ms().unwrap_or(0), sticky_generation, + remember_session( + service, &conv_key, &model, account_id, sticky_source, sticky_generation, ); service.route.backoff_clear(account_id); service.route.sink_clear(account_id); @@ -1395,15 +1427,12 @@ async fn attempt_queue( ); } } - if let (Some(_ttl), true, Some(account_id)) = ( - route_settings.sticky.ttl_ms(), - !conv_key.is_empty(), - target.account_id.as_deref(), - ) { - service.route.sticky_bind( - &conv_key, &model, account_id, sticky_source, - logging::now_ms(), route_settings.sticky.ttl_ms().unwrap_or(0), - sticky_generation, + if let Some(account_id) = target.account_id.as_deref() { + // 判据(空键 / TTL 档位 / 清除代次)在 `StickySessions::bind` + // 里,这里不再重复一遍 —— 三处各写一份闸门正是此前自定义 + // 家成功分支整条漏掉绑定的成因(issue #2)。 + remember_session( + service, &conv_key, &model, account_id, sticky_source, sticky_generation, ); } // Antigravity 的会话键随信封带出(签名缓存兜底档的写入键, diff --git a/desktop-tauri/src-tauri/server/src/server/core/upstream/provider_loop/tests.rs b/desktop-tauri/src-tauri/server/src/server/core/upstream/provider_loop/tests.rs index a885f2413..090f2092e 100644 --- a/desktop-tauri/src-tauri/server/src/server/core/upstream/provider_loop/tests.rs +++ b/desktop-tauri/src-tauri/server/src/server/core/upstream/provider_loop/tests.rs @@ -125,6 +125,33 @@ fn single(name: &str) -> Vec { vec![name.to_string()] } +/// 一份临时库 + 指定 provider 下的若干账号(`uids` 按给定顺序落库)。 +/// +/// 与 [`temp_service`] 的差别只有两处:provider 可指定、账号可多于一条。 +/// 后者是选路用例必须的 —— 只有一条账号时「粘住」与「没粘住」的结论相同, +/// 断言不出任何东西。 +fn temp_service_for(provider: &str, uids: &[&str]) -> (TempDbDir, UpstreamService) { + use crate::server::core::account_store::AccountStore; + use crate::server::core::auth::AuthService; + use crate::server::db::Db; + + let seq = TEMP_SEQ.fetch_add(1, Ordering::SeqCst); + let dir = std::env::temp_dir().join(format!("pl-sticky-{}-{seq}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + let store = AccountStore::with_db(Some(Db::open(&dir.join("agent2api.db")).expect("临时库应当能建起来"))); + for uid in uids { + store + .add_account( + &json!({"auth": {"accessToken": "at"}, "account": {"uid": uid}}), + None, + Some(provider), + ) + .expect("临时账号应当能建起来"); + } + let service = UpstreamService::new(store.clone(), AuthService::for_store(store)); + (TempDbDir(dir), service) +} + #[test] fn stateful_quota_bookkeeping_keeps_the_adapter_reset_at() { let (_dir, service, id) = temp_service(); @@ -429,3 +456,66 @@ fn a_deterministic_404_skips_the_in_place_resend() { "404 的豁免不许顺手把 400 也豁免了" ); } + +// ── 会话粘性的写入 → 查找闭环(issue #2)────────────────────────────── +// +// 这一组用例钉的是「失败了也不会报错」的那半边:写入侧(成功后 +// `sticky_bind`)与查找侧(选路时 `snapshot_for_model`)必须用**同一把键**、 +// **同一个 TTL 口径**。任何一侧漏了 model、时间戳或账号 id 的换算,症状都只是 +// `route.stickyHit` 恒为 false(请求照样成功、账号照样轮换),不会抛错。 + +/// 同一会话键的第二条请求必须命中第一条绑定的账号。 +/// +/// 账号挂在 `custom-` 前缀的提供商下:那类账号不受「插件是否已安装」的可见性 +/// 闸门约束(见 `account_store::account_visible`),于是这条用例在任何测试环境 +/// 里都能走到真实的 `select_target_account` 选路,而不是被候选池为空提前短路。 +#[tokio::test] +async fn a_second_request_on_the_same_session_sticks_to_the_first_account() { + use crate::server::core::routing::CooldownKeys; + use crate::server::core::upstream::rotate::select_target_account; + use crate::server::core::upstream::route_state::RouteState; + use axum::http::HeaderMap; + + let provider = "custom-sticky-test"; + let (_dir, service) = temp_service_for(provider, &["sticky-1", "sticky-2"]); + let body = json!({ + "model": "sticky-model", + "messages": [{ "role": "user", "content": "hello" }], + }); + let key = RouteState::conversation_key(&HeaderMap::new(), &body); + assert!(!key.is_empty(), "带 messages 的请求必须有会话键,否则粘性永远不生效"); + let keys = CooldownKeys::new("sticky-model"); + + // 第一条:没有绑定,正常选路(转发成功后由 attempt_queue 调 sticky_bind) + let first = select_target_account(&service, &[provider], &keys, &[], None, &key) + .await + .expect("第一条请求应当选到账号"); + assert_eq!( + first.decision.as_ref().map(|decision| decision["stickyHit"].clone()), + Some(json!(false)), + "首次请求不该命中粘性" + ); + let bound = first.account_id.clone().expect("应当选到有 id 的账号"); + + // 与转发成功出口逐字同源的写入 + let ttl = config::routing_settings().sticky.ttl_ms().unwrap_or(0); + assert!(ttl > 0, "测试环境的粘性档位必须开着(默认 auto)"); + service.route.sticky_bind( + &key, + "sticky-model", + &bound, + "content-hash", + logging::now_ms(), + ttl, + service.route.sticky_generation(), + ); + + // 第二条:同一会话、同一模型 → 命中,并且仍然用同一个账号 + let second = select_target_account(&service, &[provider], &keys, &[], None, &key) + .await + .expect("第二条请求应当选到账号"); + let decision = second.decision.clone().expect("选路要带决策快照"); + assert_eq!(decision["stickyHit"], json!(true), "同一会话的第二条请求应当命中粘性"); + assert_eq!(decision["picked"], json!(bound), "命中后应当置顶原账号"); + assert_eq!(second.account_id.as_deref(), Some(bound.as_str())); +} diff --git a/desktop-tauri/src-tauri/server/src/server/core/upstream/route_state.rs b/desktop-tauri/src-tauri/server/src/server/core/upstream/route_state.rs index 1198bd189..4f3fd178e 100644 --- a/desktop-tauri/src-tauri/server/src/server/core/upstream/route_state.rs +++ b/desktop-tauri/src-tauri/server/src/server/core/upstream/route_state.rs @@ -187,23 +187,39 @@ impl RouteState { format!("{:016x}", hasher.finish()) } - /// 显式会话标识的提取链(顺序即优先级,见 [`Self::conversation_key`])。 + /// 显式会话标识的提取链(顺序即优先级,见 [`Self::conversation_key`]) + /// 连同**来源标签**一起返回。 + /// + /// **为什么值和标签必须同一处产出**:来源标签要落进绑定表(管理页展示) + /// 与日志(`identity-changed` 事件)。曾经它是另一个函数按同一份名单再判 + /// 一遍的 —— 那种「两份判据」正是 issue #2 的形态:只要一侧漏掉某个键, + /// 就不会有任何报错,只是粘性静默失效。名单只有这一份。 /// /// **端点无关**:同一套标识在不同协议端点上语义相同,按路径收窄反而会在 /// 客户端换端点时丢掉同一个会话(上游的内容哈希同样是端点无关的)。 - fn explicit_conversation_id(headers: &HeaderMap, body: &serde_json::Value) -> Option { + fn explicit_conversation( + headers: &HeaderMap, + body: &serde_json::Value, + ) -> Option<(String, &'static str)> { // ① AxonHub 的**会话级**头。⚠️ 别换成 `AH-Trace-Id`:那个的粒度是 // 「单条用户消息 + 它触发的所有请求」(AxonHub 的层级是 Thread → Trace // → Request),一个客户端每轮都会给它一个新值,拿它当会话键会让粘性 // 逐轮断裂 —— 比下面那条内容哈希(跨轮稳定)还差。上游原实现读的正是 // Trace,2026-10-14 订正为 Thread。 - if let Some(value) = Self::header_text(headers, "ah-thread-id") { - return Some(value); - } - // ② OpenCode 系(三个头按新旧顺序) - for name in ["x-opencode-session", "x-session-id", "x-session-affinity"] { + // + // ② OpenCode 系:带 `x-` 前缀的三个在前(新旧顺序),再认不带前缀的 + // 写法 —— 有的客户端或中间代理会把前缀去掉,语义与带前缀的完全相同; + // 排在带前缀的后面,带前缀的客户端行为因此逐字不变。 + for (name, label) in [ + ("ah-thread-id", "AH-Thread-Id"), + ("x-opencode-session", "X-Opencode-Session"), + ("x-session-id", "X-Session-Id"), + ("x-session-affinity", "X-Session-Affinity"), + ("opencode-session", "Opencode-Session"), + ("session-affinity", "Session-Affinity"), + ] { if let Some(value) = Self::header_text(headers, name) { - return Some(value); + return Some((value, label)); } } // ③ OpenAI Chat 的 prompt_cache_key:**翻译网关这条路唯一的会话标识**。 @@ -229,7 +245,7 @@ impl RouteState { .map(str::trim) .filter(|value| !value.is_empty()) { - return Some(value.to_string()); + return Some((value.to_string(), "prompt_cache_key")); } // ④ Claude Code:`metadata.user_id`(两种可辨认的形状,见 // [`Self::parse_claude_code_user_id`])。解析不出就当没有 —— 宁可没有 @@ -241,12 +257,12 @@ impl RouteState { .and_then(serde_json::Value::as_str) .and_then(Self::parse_claude_code_user_id) { - return Some(value); + return Some((value, "Claude Code")); } // ⑤ Codex:会话头,或 turn metadata 里的 session_id for name in ["session_id", "session-id"] { if let Some(value) = Self::header_text(headers, name) { - return Some(value); + return Some((value, "Session-Id")); } } if let Some(metadata) = headers @@ -260,13 +276,18 @@ impl RouteState { .map(str::trim) .filter(|value| !value.is_empty()) { - return Some(session.to_string()); + return Some((session.to_string(), "X-Codex-Turn-Metadata")); } } } None } + /// 只要值的那一半(其余调用方不关心来源标签)。 + fn explicit_conversation_id(headers: &HeaderMap, body: &serde_json::Value) -> Option { + Self::explicit_conversation(headers, body).map(|(value, _)| value) + } + /// 头值读取:缺失 / 非 ASCII 一律当「没有」(不做 URL 解码等额外处理)。 /// /// `HeaderMap::get` 大小写不敏感(HTTP 头名不区分大小写),用小写名查询 @@ -343,26 +364,18 @@ impl RouteState { self.sticky.clear(id, model) } + /// 会话键的**来源标签**(落进绑定表与管理日志,回答「这条绑定是从哪个 + /// 字段来的」)。 + /// + /// 与 [`Self::explicit_conversation`] 同一条链:这里不再另写一份名单 —— + /// 两份判据漂移正是「写入与查找各读一个字段」那类静默失效的来源。 pub(super) fn conversation_source(headers: &HeaderMap, body: &serde_json::Value) -> &'static str { - if Self::explicit_conversation_id(headers, body) - .is_none_or(|value| value.chars().count() > Self::EXPLICIT_ID_MAX_CHARS) - { - return "content-hash"; - } - for (name, label) in [ - ("ah-thread-id", "AH-Thread-Id"), - ("x-opencode-session", "X-Opencode-Session"), - ("x-session-id", "X-Session-Id"), - ("x-session-affinity", "X-Session-Affinity"), - ] { - if Self::header_text(headers, name).is_some() { return label; } + match Self::explicit_conversation(headers, body) { + // 与 `conversation_key` 的长度闸同一判据:超长的显式标识按内容哈希 + // 处理,来源也就必须如实写成内容哈希。 + Some((value, label)) if value.chars().count() <= Self::EXPLICIT_ID_MAX_CHARS => label, + _ => "content-hash", } - if body.get("prompt_cache_key").and_then(serde_json::Value::as_str) - .is_some_and(|key| !key.trim().is_empty()) { return "prompt_cache_key"; } - if body.pointer("/metadata/user_id").and_then(serde_json::Value::as_str) - .and_then(Self::parse_claude_code_user_id).is_some() { return "Claude Code"; } - if Self::explicit_conversation_id(headers, body).is_some() { return "Codex"; } - "content-hash" } /// 取轮转游标并前进一格,返回**计数** —— 取模交给调用方做。 @@ -618,6 +631,9 @@ mod tests { (headers(&[("x-opencode-session", "sess-opencode")]), body.clone(), "id:sess-opencode"), (headers(&[("x-session-id", "sess-x")]), body.clone(), "id:sess-x"), (headers(&[("x-session-affinity", "sess-affinity")]), body.clone(), "id:sess-affinity"), + // 不带 `x-` 前缀的写法(有的客户端/代理会去掉前缀) + (headers(&[("opencode-session", "sess-opencode-bare")]), body.clone(), "id:sess-opencode-bare"), + (headers(&[("session-affinity", "sess-affinity-bare")]), body.clone(), "id:sess-affinity-bare"), (headers(&[("session-id", "sess-codex")]), body.clone(), "id:sess-codex"), ( headers(&[("x-codex-turn-metadata", "{\"session_id\":\"sess-turn\"}")]), @@ -636,6 +652,50 @@ mod tests { } } + /// 来源标签与提取链必须同源:每条能产生显式键的输入,`conversation_source` + /// 都不得报成 `content-hash`。 + /// + /// 钉的是 issue #2 那类**静默失效**:写入侧与查找侧(或展示侧)各读一份 + /// 名单,只要一侧漏了某个字段就不会报错 —— 只表现为「会话粘性看起来没生效」。 + #[test] + fn the_reported_source_agrees_with_the_extracted_key() { + let body = chat_body(); + let cases: Vec<(HeaderMap, serde_json::Value)> = vec![ + (headers(&[("ah-thread-id", "thread-abc")]), body.clone()), + (headers(&[("x-opencode-session", "sess-opencode")]), body.clone()), + (headers(&[("x-session-id", "sess-x")]), body.clone()), + (headers(&[("x-session-affinity", "sess-affinity")]), body.clone()), + (headers(&[("opencode-session", "sess-opencode-bare")]), body.clone()), + (headers(&[("session-affinity", "sess-affinity-bare")]), body.clone()), + (headers(&[("session-id", "sess-codex")]), body.clone()), + ( + headers(&[("x-codex-turn-metadata", "{\"session_id\":\"sess-turn\"}")]), + body.clone(), + ), + (HeaderMap::new(), json!({ "prompt_cache_key": "sess-cache" })), + ( + HeaderMap::new(), + json!({ "metadata": { "user_id": "{\"session_id\":\"sess-claude\"}" } }), + ), + ]; + for (headers, body) in &cases { + let key = RouteState::conversation_key(headers, body); + assert!(key.starts_with("id:"), "这些输入都该产生显式会话键"); + assert_ne!( + RouteState::conversation_source(headers, body), + "content-hash", + "产生了显式键的输入,来源标签不该报成内容哈希" + ); + } + // 对照:没有显式标识时两边都落在内容哈希上 + let plain = RouteState::conversation_key(&HeaderMap::new(), &chat_body()); + assert!(!plain.starts_with("id:")); + assert_eq!( + RouteState::conversation_source(&HeaderMap::new(), &chat_body()), + "content-hash" + ); + } + /// 形状不对的 `metadata.user_id` 不该被当成会话 id —— 宁可没有粘性。 #[test] fn a_malformed_claude_user_id_falls_back_to_the_content_hash() { @@ -720,4 +780,57 @@ mod tests { let snap = state.snapshot("", now, 0); assert!(!snap.sunk.contains_key("a1"), "成功后应当立刻解除垫底"); } + + /// 粘性的**写入 → 查找**闭环(issue #2 的最小复现面)。 + /// + /// `sticky_bind` 与 `snapshot_for_model` 必须用同一把键(会话键 + 请求模型), + /// 否则记录下来了也永远查不到 —— 而那种失败没有任何报错,只表现为 + /// `route.stickyHit` 恒为 false。 + #[test] + fn a_bound_session_is_found_by_the_next_lookup() { + let state = RouteState::new(); + let now = 1_700_000_000_000i64; + let ttl = 6 * 60 * 60 * 1000; + let generation = state.sticky_generation(); + + // 写入侧(`attempt_queue` 成功出口那一份参数的形状) + state.sticky_bind("conv-key", "model-x", "acct-a", "content-hash", now, ttl, generation); + + // 查找侧(`select_target_account` 的调用形状) + let hit = state.snapshot_for_model("conv-key", "model-x", now + 1, ttl); + assert_eq!(hit.sticky_hit.as_deref(), Some("acct-a"), "同一会话键必须查回绑定的账号"); + + // 键的两半都参与:换模型、换会话键都应当落空 + assert!(state.snapshot_for_model("conv-key", "model-y", now + 1, ttl).sticky_hit.is_none()); + assert!(state.snapshot_for_model("other-key", "model-x", now + 1, ttl).sticky_hit.is_none()); + + // TTL 到点自动失效(6 小时档)。注意 TTL 是**从最近一次使用**起算的: + // 上面那次命中把 `last_seen` 续到了 `now + 1`,所以要越过它再走一整段。 + let expired = state.snapshot_for_model("conv-key", "model-x", now + 1 + ttl + 1, ttl); + assert!(expired.sticky_hit.is_none(), "超过会话粘性 TTL 后不该再命中"); + } + + /// 管理页读取**不得**用查询档位淘汰别人的绑定。 + /// + /// 钉的是 2026-11 修的一处缺陷:`list()` 曾按调用方传进来的 TTL 清理整张表, + /// 于是「切到 auto(5 分钟)打开一次会话粘滞页」就会把 6 小时档的绑定全部 + /// 清掉 —— 读一次管理页不该改变任何状态。 + #[test] + fn reading_the_sticky_list_keeps_longer_lived_bindings() { + let state = RouteState::new(); + let now = 1_700_000_000_000i64; + let session_ttl = 6 * 60 * 60 * 1000; + let auto_ttl = 5 * 60 * 1000; + let generation = state.sticky_generation(); + state.sticky_bind("conv-key", "model-x", "acct-a", "content-hash", now, session_ttl, generation); + + // 用更短的 auto 档看一眼列表:这条 6 小时档的绑定必须还在。 + let listed = state.sticky_list(None, now + auto_ttl + 1, auto_ttl); + assert_eq!(listed.len(), 1, "读取列表不该淘汰 TTL 更长的绑定"); + assert_eq!(listed[0]["remainingMs"], json!(session_ttl - auto_ttl - 1)); + + // 回 session 档查:仍然命中 + let hit = state.snapshot_for_model("conv-key", "model-x", now + auto_ttl + 1, session_ttl); + assert_eq!(hit.sticky_hit.as_deref(), Some("acct-a")); + } } diff --git a/desktop-tauri/src-tauri/server/src/server/core/upstream/route_sticky.rs b/desktop-tauri/src-tauri/server/src/server/core/upstream/route_sticky.rs index 40a645d5e..5128e1ef8 100644 --- a/desktop-tauri/src-tauri/server/src/server/core/upstream/route_sticky.rs +++ b/desktop-tauri/src-tauri/server/src/server/core/upstream/route_sticky.rs @@ -1,11 +1,39 @@ //! 进程本地会话粘滞。管理读取不续期,清除后在途请求不得把旧绑定写回来。 +//! +//! ── 为什么「失效」必须留痕(issue #2)──────────────────────────── +//! 粘性是一层**静默**优化:命中与否只体现在 `requests.route.stickyHit` 这一个 +//! 布尔上,失效时请求照样成功、账号照样轮换。于是「绑定根本没写进去」和 +//! 「写了但每次都被淘汰」在外部看起来完全一样 —— 上游 #443 的 655 条请求 +//! 0 次命中就是这么被发现的:没有任何一条日志能指出哪一侧断了。 +//! +//! 因此本模块把**状态变化**(不是每次命中)记进日志库,事件名取排查时可以直接 +//! 搜的词:`account-switch`(同一会话换了账号)、`identity-changed`(同一把会话键 +//! 的来源变了)、`evicted-ttl`(过期释放)、`evicted-capacity`(表满淘汰)、 +//! `cleared`(人工/设置清空)、`skipped-*`(写入被跳过的原因)。 +//! +//! ── 为什么事件要先收集再打日志 ────────────────────────────── +//! 日志落库可能碰 SQLite 的锁,而本模块的锁只该护住那张内存表。所有事件都在 +//! 释放 `table` 之后才写日志(见各方法里的 `let event = { … };` 形状)。 use std::collections::HashMap; +use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::Mutex; use serde_json::{json, Value}; use sha2::{Digest, Sha256}; +use crate::server::logging; + +/// 绑定表的上限(活跃会话数)。到顶后淘汰最久未用的那条。 +const MAX_ENTRIES: usize = 10_000; + +/// 「会话键为空,粘性不生效」只提示一次的开关。 +/// +/// 这条不是逐请求的事实(同一台机器上可能条条如此),逐条记录会把日志页刷满, +/// 反而看不到真正稀缺的失效事件;而完全不提又正是 issue #2 里最难排的那种 +/// 「静默不生效」。取「每个进程第一次」—— 有就一眼看见,没有就闭嘴。 +static EMPTY_KEY_WARNED: AtomicBool = AtomicBool::new(false); + #[derive(Clone)] struct StickyEntry { id: String, @@ -29,6 +57,69 @@ pub(super) struct StickySessions { table: Mutex, } +/// 需要落日志的状态变化(在释放表锁之后统一写)。 +enum Event { + /// 同一会话换了承载账号(前一个账号不可用 / 失败顺延过来)。 + AccountSwitch { preview: String, from: String, to: String, model: String }, + /// 同一把会话键的来源标签变了(例如从内容哈希换成了客户端显式标识)。 + IdentityChanged { preview: String, from: String, to: String, model: String }, + /// 表满淘汰。 + CapacityEvicted { preview: String, account_id: String, capacity: usize }, + /// 过期释放(只记「恰好被这次查找撞上」的那条,不做批量统计 —— 批量统计 + /// 会在每次惰性清理时刷一行,量级由流量决定,不是有价值的事件)。 + EvictedTtl { preview: String, account_id: String, ttl_ms: i64 }, + /// 人工 / 设置变更清空。 + Cleared { removed: usize, scope: String }, + /// 写入被丢弃(本请求期间清空过,代次已变)。 + StaleGeneration, +} + +impl Event { + fn log(self) { + match self { + Self::AccountSwitch { preview, from, to, model } => logging::log( + "[Upstream]", + &format!( + "会话粘性切换账号(account-switch):会话 {preview} 的绑定由账号 {from} 改为 {to}(模型 {model})" + ), + ), + Self::IdentityChanged { preview, from, to, model } => logging::log( + "[Upstream]", + &format!( + "会话粘性标识来源变化(identity-changed):会话 {preview} 的键来源由 {from} 变为 {to}(模型 {model}),绑定延续到新来源" + ), + ), + Self::CapacityEvicted { preview, account_id, capacity } => logging::log( + "[Upstream]", + &format!( + "会话粘性容量淘汰(evicted-capacity):绑定表已满 {capacity} 条,移除最久未用的会话 {preview}(账号 {account_id})" + ), + ), + Self::EvictedTtl { preview, account_id, ttl_ms } => logging::log( + "[Upstream]", + &format!( + "会话粘性过期(evicted-ttl):会话 {preview} 超过 {} 分钟没有再来往,绑定账号 {account_id} 已释放,本次重新选路", + ttl_ms / 60_000 + ), + ), + Self::Cleared { removed, scope } => logging::log( + "[Upstream]", + &format!("会话粘性清除(cleared):{scope},移除 {removed} 条绑定"), + ), + Self::StaleGeneration => logging::log( + "[Upstream]", + "会话粘性写入被丢弃(skipped-stale-generation):本请求执行期间绑定表被清空过,不把旧绑定写回来", + ), + } + } +} + +/// 日志里的会话标识:取条目 id 前 12 位(与 `/api/routing/sticky` 的 +/// `keyPreview` 同一形态)。不落原始会话键 —— 那可能是客户端的会话标识原文。 +fn preview(id: &str) -> String { + format!("{}…", &id[..id.len().min(12)]) +} + pub(super) fn entry_id(key: &str, model: &str) -> String { let mut hasher = Sha256::new(); hasher.update(model.trim().to_ascii_lowercase().as_bytes()); @@ -46,14 +137,36 @@ impl StickySessions { if key.is_empty() || ttl_ms <= 0 { return None; } let id = entry_id(key, model); let mut table = self.table.lock().ok()?; + // 先判「这次要查的这条是不是已经到了**它自己**的 TTL」,再统一清理: + // 过期事件要归到「谁回来得太晚」这条会话上,批量清理那一步只知道条数。 + let expired = table + .entries + .get(&id) + .filter(|entry| now.saturating_sub(entry.last_seen) > entry.ttl_ms) + .map(|entry| (entry.account_id.clone(), entry.ttl_ms)); table.entries.retain(|_, entry| now.saturating_sub(entry.last_seen) <= entry.ttl_ms); + if let Some((account_id, own_ttl)) = expired { + drop(table); + Event::EvictedTtl { + preview: preview(&id), + account_id, + ttl_ms: own_ttl, + } + .log(); + return None; + } let entry = table.entries.get_mut(&id)?; + // 当前档位比写下时更短(例如从 session 切到 auto)时,按**当前**档位 + // 判失效,但**不删**这条绑定:档位是「这会儿还愿不愿意沿用」的策略, + // 不是「销毁别人记录」的指令 —— 切回更长的档位后,只要它自己的 TTL + // 还没到,绑定就该继续有效(管理页的读取同理,见 `list`)。 if now.saturating_sub(entry.last_seen) > ttl_ms { - table.entries.remove(&id); return None; } + // 只续「最近使用时刻」,**不改**写下时的 TTL:读取不是重写。否则一条 + // 6 小时档的绑定在 auto 档下被命中一次就缩成 5 分钟,切回 session 后 + // 到点被清掉 —— 读操作又把别人的记录改短了。 entry.last_seen = now; - entry.ttl_ms = ttl_ms; entry.hits = entry.hits.saturating_add(1); Some(entry.account_id.clone()) } @@ -62,45 +175,117 @@ impl StickySessions { &self, key: &str, model: &str, account_id: &str, source: &str, now: i64, ttl_ms: i64, generation: u64, ) { - if key.is_empty() || account_id.is_empty() || ttl_ms <= 0 { return; } - let Ok(mut table) = self.table.lock() else { return }; - if table.generation != generation { return; } - table.entries.retain(|_, entry| now.saturating_sub(entry.last_seen) <= entry.ttl_ms); - let id = entry_id(key, model); - if table.entries.len() >= 10_000 && !table.entries.contains_key(&id) { - if let Some(oldest) = table.entries.iter().min_by_key(|(_, entry)| entry.last_seen) - .map(|(id, _)| id.clone()) - { - table.entries.remove(&oldest); + if key.is_empty() { + // 逐条记录会刷屏,但第一次必须说:这正是「粘性从来没生效」的最常见 + // 原因(请求既没有显式会话标识,也没有带 messages 的会话特征)。 + if !EMPTY_KEY_WARNED.swap(true, Ordering::Relaxed) { + logging::log( + "[Upstream]", + "会话粘性不生效(skipped-empty-key):有请求既没有显式会话标识(AH-Thread-Id / X-Session-Id / prompt_cache_key 等)、也没有可用的首条用户消息,无法建立会话键;本条每个进程只提示一次", + ); } + return; + } + if account_id.is_empty() || ttl_ms <= 0 { + // ttl 为 0 是用户的显式选择(off / turn 档),不是故障。 + return; + } + let mut event: Option = None; + { + let Ok(mut table) = self.table.lock() else { return }; + if table.generation != generation { + event = Some(Event::StaleGeneration); + } else { + table.entries.retain(|_, entry| now.saturating_sub(entry.last_seen) <= entry.ttl_ms); + let id = entry_id(key, model); + if table.entries.len() >= MAX_ENTRIES && !table.entries.contains_key(&id) { + // 先取出「最久未用」的键与账号(借用在这里就结束),再删。 + let oldest = table + .entries + .iter() + .min_by_key(|(_, entry)| entry.last_seen) + .map(|(key, entry)| (key.clone(), entry.account_id.clone())); + if let Some((oldest_key, oldest_account)) = oldest { + table.entries.remove(&oldest_key); + event = Some(Event::CapacityEvicted { + preview: preview(&oldest_key), + account_id: oldest_account, + capacity: MAX_ENTRIES, + }); + } + } + // `or_insert_with` 会吞掉「之前是谁」这个事实,而 account-switch / + // identity-changed 判的就是它 —— 先取一份旧值再覆盖。 + let previous = table + .entries + .get(&id) + .map(|entry| (entry.account_id.clone(), entry.source.clone())); + let entry = table.entries.entry(id.clone()).or_insert_with(|| StickyEntry { + id, + account_id: account_id.to_string(), + model: model.to_string(), + source: source.to_string(), + created_at: now, + last_seen: now, + ttl_ms, + hits: 0, + }); + match previous { + Some((previous_account, previous_source)) => { + if previous_account != account_id { + event = Some(Event::AccountSwitch { + preview: preview(&entry.id), + from: previous_account, + to: account_id.to_string(), + model: model.to_string(), + }); + } else if previous_source != source { + event = Some(Event::IdentityChanged { + preview: preview(&entry.id), + from: previous_source, + to: source.to_string(), + model: model.to_string(), + }); + } + } + None => {} + } + entry.account_id = account_id.to_string(); + entry.source = source.to_string(); + entry.last_seen = now; + entry.ttl_ms = ttl_ms; + } + } + if let Some(event) = event { + event.log(); } - let entry = table.entries.entry(id.clone()).or_insert_with(|| StickyEntry { - id, account_id: account_id.to_string(), model: model.to_string(), - source: source.to_string(), created_at: now, last_seen: now, ttl_ms, hits: 0, - }); - entry.account_id = account_id.to_string(); - entry.last_seen = now; - entry.ttl_ms = ttl_ms; } + /// 管理页读取:**不续期**(`last_seen` / `hits` 一律不动),只按每条绑定 + /// **自己的** TTL 清过期项。 + /// + /// 为什么清理用 `entry.ttl_ms` 而不是查询传进来的 `ttl_ms`:那是「这次查询 + /// 想看的档位」,不是这条绑定写下时的档位。用手上的档位淘汰别人的记录, + /// 会在「切到 auto 看一眼、再切回 session」之后把本该还有效的 6 小时绑定 + /// 全部清掉 —— 读一次管理页不该有副作用。 pub(super) fn list(&self, model: Option<&str>, now: i64, ttl_ms: i64) -> Vec { let Ok(mut table) = self.table.lock() else { return Vec::new() }; if ttl_ms <= 0 { return Vec::new(); } - table.entries.retain(|_, entry| now.saturating_sub(entry.last_seen) <= ttl_ms.min(entry.ttl_ms)); + table.entries.retain(|_, entry| now.saturating_sub(entry.last_seen) <= entry.ttl_ms); let mut entries: Vec<&StickyEntry> = table.entries.values() .filter(|entry| model.map_or(true, |model| entry.model.eq_ignore_ascii_case(model))) .collect(); entries.sort_by_key(|entry| std::cmp::Reverse(entry.last_seen)); entries.into_iter().map(|entry| json!({ "id": entry.id, - "keyPreview": format!("{}…", &entry.id[..12]), + "keyPreview": preview(&entry.id), "accountId": entry.account_id, "model": entry.model, "source": entry.source, "createdAt": entry.created_at, "lastSeen": entry.last_seen, - "expiresAt": entry.last_seen + ttl_ms.min(entry.ttl_ms), - "remainingMs": (entry.last_seen + ttl_ms.min(entry.ttl_ms) - now).max(0), + "expiresAt": entry.last_seen + entry.ttl_ms, + "remainingMs": (entry.last_seen + entry.ttl_ms - now).max(0), "hits": entry.hits, })).collect() } @@ -112,7 +297,23 @@ impl StickySessions { !(id.map_or(true, |id| id == key) && model.map_or(true, |model| entry.model.eq_ignore_ascii_case(model))) }); + let removed = before - table.entries.len(); + // 清空会推进代次:清空之前发起的那些请求**不得**把旧绑定写回来 + // (见 `bind` 的代次判定),否则「清空」在并发下只是暂时的。 table.generation = table.generation.wrapping_add(1); - before - table.entries.len() + drop(table); + if removed > 0 { + Event::Cleared { + removed, + scope: match (id, model) { + (Some(id), Some(model)) => format!("指定绑定 {id}(模型 {model})"), + (Some(id), None) => format!("指定绑定 {id}"), + (None, Some(model)) => format!("模型 {model} 的全部绑定"), + (None, None) => "全部绑定".to_string(), + }, + } + .log(); + } + removed } }