wanghanlin/RAG: 本地 RAG 知识库 - RAG - Gitea: Git with a cup of tea

本地 RAG 知识库

History

wanghanlin 5a553ec813 feat(sdk): SDK 内置 Token 自动刷新，支持每请求前向宿主取 Token 问题：SDK Token 默认仅 2 小时有效，而 SDK 此前没有任何刷新入口 —— token 只能在 init() 时传一次、只存内存，收到 401 只回调 onError 报错，想换 Token 只能 destroy() 重建整个 DOM，第三方页面长时间挂载必然掉线。取 Token 的四种触发方式（client/src/token.ts） - 临期主动刷新：阈值取「总寿命 10% 与 5 分钟」的较小值，需传 expiresIn - 每请求前取：tokenStrategy: 'always'，每个受保护请求发出前都向宿主取一次，完全不推算过期时间（该模式下不排定时器、不认「返回同一 Token」的静默窗口） - 401 兜底重试：换一次 Token 后自动重试原请求，UI 上不会闪错误 - 手动入口：ChatbotSDK.setToken(token, expiresIn?) / refreshToken() 取 Token 的两种来源（二选一，getToken 回调优先并明确告警） - getToken 回调：由宿主实现，可复用其请求封装与鉴权头 - tokenUrl 地址：SDK 直接 GET，兼容 {token,expiresIn} 与 {success,token,expiresIn,roles}；用 credentials: 'same-origin'（同源带 Cookie、跨域不带，避免把宿主站点 Cookie 泄露给别的域）两者都让 API Key 留在宿主服务端，不进浏览器；后端零改动。关键实现约束（均有单测覆盖） - 临期阈值必须自适应：后端 clampExpirationMillis 允许的最短 ttl 恰为 300s，固定 5 分钟会让它永远处于临期态，定时器延迟算成 0 退化成秒级无限刷新循环 - expiresIn 只做 24h 上界钳制、绝不做下界，避免把「只剩 20s 的 Token」当成 300s 而带着已过期 Token 发请求（上界同时防 setTimeout 溢出与毫秒误传） - provider 调用自带 10s 超时，refreshPromise 在 finally 无条件清空：宿主回调永不 settle 时，挂起会经 single-flight 传染给后续所有受保护请求 - setToken 自增 generation 但不碰 refreshPromise：既防止在途刷新返回的旧值覆盖宿主刚推来的新值，又不破坏 single-flight - 刷新失败统一进 60s 熔断窗口（判断在 refreshNow 内，不在 ensureFresh），窗口内请求照常发出、由 401 兜底，避免宿主取 Token 挂死时每个请求多等一次超时 - isProtectedPath 改用 URL.pathname 判定并与后端 SdkAuthFilter.shouldNotFilter 逐字对齐；顺带修掉旧实现 endsWith('/feedback') 遇 query 参数漏注入、 /attachment/upload 注入了 Token 却不享受 401 处理的两处不一致 - 401 透明重试对写请求（POST /feedback、/attachment/upload、DELETE 会话）安全，依据是 SdkAuthFilter 的 401 全部发生在 chain.doFilter 之前（401 ⇒ 业务逻辑未执行）；该前提已写入代码注释与 CLAUDE.md，改过滤器时需重新评估顺带修复 - chat.ts：首 token 前点「停止生成」会反而多发一个同步 /ai/chat 请求 - tests/config.test.ts：2 条断言早已因窗口默认值改动而变红（不修平的话 npm test 无法充当回归门） - 文档：修正 width 默认值 380->500、enableRag 默认值 false->true、roleId 幽灵参数、「仅 console.error 输出」（控制台日志早已全量关闭）等过时描述，并补齐 token/expiresIn/getToken/tokenStrategy/tokenUrl 全部鉴权参数验证 - client 单测 92 个全绿（新增 token.test.ts 60 个 + config 新增 9 个）， npx tsc --noEmit 通过 - npm run build（SDK）与 frontend npm run build 均通过， mvn clean package -P prod 构建成功 - 浏览器端未实测（按项目惯例由用户在 IDEA 启动服务，避免抢占 9090 端口），面板已加 TTL 输入与 tokenStrategy 选择开关供手工验证	2 weeks ago
..
favicon.svg	重构后台前端项目，整体迁移到TDesign Starter for Vue架构下，并已全部测试通过	2 months ago

wanghanlin 5a553ec813 feat(sdk): SDK 内置 Token 自动刷新，支持每请求前向宿主取 Token

问题：SDK Token 默认仅 2 小时有效，而 SDK 此前没有任何刷新入口 —— token 只能
在 init() 时传一次、只存内存，收到 401 只回调 onError 报错，想换 Token 只能
destroy() 重建整个 DOM，第三方页面长时间挂载必然掉线。

取 Token 的四种触发方式（client/src/token.ts）
- 临期主动刷新：阈值取「总寿命 10% 与 5 分钟」的较小值，需传 expiresIn
- 每请求前取：tokenStrategy: 'always'，每个受保护请求发出前都向宿主取一次，
  完全不推算过期时间（该模式下不排定时器、不认「返回同一 Token」的静默窗口）
- 401 兜底重试：换一次 Token 后自动重试原请求，UI 上不会闪错误
- 手动入口：ChatbotSDK.setToken(token, expiresIn?) / refreshToken()

取 Token 的两种来源（二选一，getToken 回调优先并明确告警）
- getToken 回调：由宿主实现，可复用其请求封装与鉴权头
- tokenUrl 地址：SDK 直接 GET，兼容 {token,expiresIn} 与
  {success,token,expiresIn,roles}；用 credentials: 'same-origin'（同源带
  Cookie、跨域不带，避免把宿主站点 Cookie 泄露给别的域）
两者都让 API Key 留在宿主服务端，不进浏览器；后端零改动。

关键实现约束（均有单测覆盖）
- 临期阈值必须自适应：后端 clampExpirationMillis 允许的最短 ttl 恰为 300s，
  固定 5 分钟会让它永远处于临期态，定时器延迟算成 0 退化成秒级无限刷新循环
- expiresIn 只做 24h 上界钳制、绝不做下界，避免把「只剩 20s 的 Token」当成
  300s 而带着已过期 Token 发请求（上界同时防 setTimeout 溢出与毫秒误传）
- provider 调用自带 10s 超时，refreshPromise 在 finally 无条件清空：宿主回调
  永不 settle 时，挂起会经 single-flight 传染给后续所有受保护请求
- setToken 自增 generation 但不碰 refreshPromise：既防止在途刷新返回的旧值
  覆盖宿主刚推来的新值，又不破坏 single-flight
- 刷新失败统一进 60s 熔断窗口（判断在 refreshNow 内，不在 ensureFresh），窗口
  内请求照常发出、由 401 兜底，避免宿主取 Token 挂死时每个请求多等一次超时
- isProtectedPath 改用 URL.pathname 判定并与后端 SdkAuthFilter.shouldNotFilter
  逐字对齐；顺带修掉旧实现 endsWith('/feedback') 遇 query 参数漏注入、
  /attachment/upload 注入了 Token 却不享受 401 处理的两处不一致
- 401 透明重试对写请求（POST /feedback、/attachment/upload、DELETE 会话）安全，
  依据是 SdkAuthFilter 的 401 全部发生在 chain.doFilter 之前（401 ⇒ 业务逻辑
  未执行）；该前提已写入代码注释与 CLAUDE.md，改过滤器时需重新评估

顺带修复
- chat.ts：首 token 前点「停止生成」会反而多发一个同步 /ai/chat 请求
- tests/config.test.ts：2 条断言早已因窗口默认值改动而变红（不修平的话
  npm test 无法充当回归门）
- 文档：修正 width 默认值 380->500、enableRag 默认值 false->true、roleId 幽灵
  参数、「仅 console.error 输出」（控制台日志早已全量关闭）等过时描述，并补齐
  token/expiresIn/getToken/tokenStrategy/tokenUrl 全部鉴权参数

验证
- client 单测 92 个全绿（新增 token.test.ts 60 个 + config 新增 9 个），
  npx tsc --noEmit 通过
- npm run build（SDK）与 frontend npm run build 均通过，
  mvn clean package -P prod 构建成功
- 浏览器端未实测（按项目惯例由用户在 IDEA 启动服务，避免抢占 9090 端口），
  面板已加 TTL 输入与 tokenStrategy 选择开关供手工验证

2 weeks ago

favicon.svg

重构后台前端项目，整体迁移到TDesign Starter for Vue架构下，并已全部测试通过

2 months ago