Skip to content

1.10.2.md

Latest commit

 

History

History
81 lines (57 loc) · 6.7 KB

1.10.2.md

File metadata and controls

81 lines (57 loc) · 6.7 KB

📋 所有版本 English | 简体中文

Chats 1.10.2 发布说明

发布日期：2026-03-10（相对 main 以来 47 次提交）

1.10.2 是一次以 Request Trace（请求跟踪） 为核心的可观测性增强版本。新版本新增 入站/出站 HTTP 请求追踪、管理员请求跟踪工作台、可配置的采样/过滤/脱敏/保留策略，并补齐导出、对比、批量删除与自动清理能力。除此之外，还包含少量管理后台统计、消息展示和 Anthropic 协议兼容性改进。

🎯 核心功能

1) Request Trace：入站/出站 HTTP 请求全链路追踪

  • 🔍 双向采集：新增 InboundRequestTraceMiddleware 与 OutboundRequestTraceHandler，同时记录用户进入服务的入站请求和服务调用外部依赖的出站请求。
  • 🧭 链路信息：记录 TraceId、用户、来源、HTTP 方法、完整 URL、状态码、异常类型，以及请求开始、请求体完成、响应头完成、响应体完成等关键时间点，便于定位慢请求和异常链路。
  • 📦 正文与原始数据：同时保存请求/响应头、文本正文和原始二进制数据，并补充请求体/响应体长度统计，适合排查编码、压缩和网关透传问题。
  • 🔗 后端接入范围：请求跟踪已接入多处出站 HTTP 调用场景，便于把用户请求与下游依赖串到同一条排障链路里。

2) 管理后台新增“请求跟踪”工作台

  • 🧑‍💼 独立管理页：管理员后台新增 /admin/request-trace 页面，并加入侧边导航，方便集中查看最近请求记录。
  • 🔎 高级筛选：支持按时间范围、URL、TraceId、用户名和方向（入站/出站）查询，请求列表和筛选条件可直接通过 URL 分享或刷新恢复。
  • 🧱 24 列可选视图：支持自定义显示列，并把列配置持久化到 URL 查询参数，方便不同排障场景快速切换视图。
  • 👀 详情与下载：单条请求支持查看完整请求/响应头体，并提供 .dump 下载和请求/响应原始二进制下载；遇到二进制响应时会明确提示改用 raw 下载。
  • 🆚 双记录对比：支持选中两条 trace 并排对比，并可隐藏相同字段，更适合比较两次请求为何返回不同结果。
  • 📤 导出与清理：支持按当前筛选条件导出 Excel（最多 10000 行），也支持按当前筛选批量删除历史 trace。

3) 采集策略、脱敏与保留周期可配置

  • ⚙️ 独立配置：入站和出站请求跟踪分开配置，可分别控制是否启用、采样率、最小时长、请求头/正文采集和数据保留天数。
  • 🎯 包含/排除规则：支持按来源、URL 模式、HTTP 方法和状态码设置 include/exclude 规则，并提供常见网关/接口的快速预设。
  • 🕶️ 脱敏增强：新增可配置 URL 参数脱敏规则，并改进默认脱敏顺序，减少敏感信息误入库风险。
  • ♻️ 热刷新：追踪配置来自数据库配置表，后台刷新服务会自动加载新配置，无需重启即可生效。

🏗️ 架构与工程

1) 持久化与自动治理能力补齐

  • 🗄️ 双表模型：新增 RequestTrace 与 RequestTracePayload 两张表，元数据与大载荷分离存储，并通过级联删除保持一致性。
  • 📇 索引与清理：新增按 StartedAt、UserId、TraceId、ScheduledDeleteAt 的索引；自动清理服务每 30 分钟删除已过期记录，减少追踪数据无限增长。
  • 🚦 队列保护：新增 RequestTraceQueue:Capacity 配置项，使用有界内存队列承接写入压力，队列满时采用 DropWrite 策略保护主流程。
  • 🧵 异步写入：请求追踪改为队列化异步持久化，并补齐多阶段时间点和异常场景捕获，降低同步 I/O 对业务请求的影响。

2) 请求跟踪链路的细节稳定性打磨

  • 🧪 边界情况覆盖：补充 CaptureStreams、ObservedHttpContent、RequestTraceHelper、RequestTracePersistService、RequestTraceQueue 等单元测试。
  • 🛡️ 稳定性修复：修复 401 入站请求未被记录、空模式匹配、详情滚动显示、冗余 payload 删除、二进制与 JSON 展示等一批 request trace 细节问题。
  • 🧰 配置承载能力：Config.Value 扩展为 NVARCHAR(MAX)，用于存储更复杂的请求跟踪 JSON 配置。

🎨 其它改进

管理后台与消息体验

  • 📊 仪表盘摘要卡片：管理后台统计卡片改为基于当前时间范围计算会话量与活跃用户，摘要口径与筛选条件保持一致。
  • ✂️ 用户消息折叠：长用户消息支持在消息气泡内展开/折叠，默认提供约 5.5 行预览，减少超长输入对刷屏的影响。
  • 🧠 Thinking 展示优化：移除 ThinkingMessage 的固定最大高度限制，长推理内容展开更自然。

协议兼容与依赖更新

  • 🔧 Anthropic 兼容修复：修复 Anthropic 消息转换时 tool result 丢失问题（#122），并修复 DeepSeek Anthropic 协议下的 thinking signature 兼容性。
  • 🔤 MCP JSON 可读性：拉取 MCP 工具输入 schema 时保留可读 Unicode 文本，避免 JSON 被过度转义。
  • ⬆️ 前端依赖升级：前端升级到 Next.js 16.1.6，并同步整理浏览器兼容相关依赖。

🐛 修复与稳定性

  • 修复 Request Trace 默认脱敏策略和字段顺序问题。
  • 修复请求体/响应体观测流的捕获时机，能更早记录请求并改善 body 捕获完整性。
  • 修复 Request Trace 详情对话框在长头部、长正文场景下的滚动和溢出显示。
  • 修复请求跟踪配置弹窗的筛选规则组织方式，简化 include/exclude 的理解成本。

⬆️ 升级提示

  • 运行数据库迁移脚本：src/scripts/db-migration/1.10/1.10.2.sql
    • 新增 RequestTrace 主表和 RequestTracePayload 子表
    • 新增 StartedAt、UserId、TraceId、ScheduledDeleteAt 相关索引
    • 将 Config.Value 扩展为 NVARCHAR(MAX)，以支持更大的 JSON 配置
  • 新增配置项：
    • RequestTraceQueue:Capacity：控制请求跟踪内存队列容量，默认 1000
    • RequestTraceCleanup:Enabled：控制定时自动删除是否启用，默认 true
  • Request Trace 不会因为升级自动对所有流量开启采集；实际采集范围仍取决于管理员在后台配置的入站/出站规则、采样率和保留策略。
  • 如果准备在高并发环境开启请求跟踪，建议先配置采样率、URL 过滤和保留天数，避免产生不必要的数据库写入与存储压力。