跳转至

发展路线图

文档版本: 2.3.0 最后更新: 2026-10-24 Git 标签: v3.5.0 作者: Lincoln

本文档描述了 JAiRouter 项目的未来发展规划和功能路线图。

项目愿景

JAiRouter 致力于成为最优秀的开源 AI 模型服务路由网关，为用户提供：

  • 统一接入: 一个网关接入所有 AI 模型服务
  • 智能路由: 基于多种策略的智能负载均衡
  • 高可用性: 完善的容错和故障恢复机制
  • 易于使用: 简单的配置和丰富的文档
  • 高性能: 支持大规模并发和低延迟响应
  • 可观测性: 全面的监控、日志和链路追踪

当前版本状态

✅ v3.5.0（功能：响应脱敏覆盖面收口 + 熔断器治理 + 请求侧配置面移除，已发布 2026-10-24）

状态: 已发布（GitHub Release v3.5.0，2026-10-24；多架构 Docker 镜像随 Release 由 CI 重建：v3.5.0 / 3.5.0 / latest） 范围: v3.4.0（10-21 发布）之后合入的改动，含响应脱敏 #560 系列的四个阶段、熔断器三项收口与一轮控制台验收修正 要点:

  • 响应脱敏覆盖面：/v1/** 非流式 JSON 纳入脱敏（#593）→ 生效范围可配置（#595，response.scope）→ 响应缓冲上限与释放缺陷修复（#594 / #597）→ SSE 逐帧脱敏（#598，sanitize-sse 默认开）。
  • 默认 PII 规则：换成 5 条带边界模式（#561），手机号不再误伤 UUID、身份证与卡号不再漏尾部；traceId 等 JSON 键的值豁免；顺带修掉「OptimizedSanitizationRuleEngine 缺键名豁免 ⇒ 测试绿但生产仍打码」的缺口。
  • 破坏性变更（#601 / #602）：请求侧脱敏配置面整体移除，GET/PUT /api/config/sanitization 只处理 response；Flyway V5 删除历史 request 行与 whitelist_users 列。
  • 熔断器治理（#551 / #554 / #555）：clear-all 走完整重置（resetAll、响应带 matched）；force-open/close 新增 /api/monitoring/metrics-pipeline/circuit-breaker/* 规范路径（旧路径为 @Deprecated 别名）；删除从不生效的 stateSyncIntervalMinutes。
  • 控制台与文档：异常两页去彩虹化、JWT 筛选内联、负载均衡页头收敛、概览页签修回、验收批次界面问题（#584 / #585 / #589）；JWT 文档改真实配置键、中文能力标签统一（#590）。

✅ v3.4.0（功能：控制台重构 + 权限语义化 + 脱敏配置持久化 + 配额小时/月限额，已发布 2026-10-21）

状态: 已发布（GitHub Release v3.4.0，2026-10-21；多架构 Docker 镜像随 Release 由 CI 重建：v3.4.0 / 3.4.0 / latest） 范围: v3.3.6（10-19 发布）之后合入的改动，含控制台 UI 改造（P0-1 ～ P3，33 个页面 + 登录页 + 导航）与后端三项能力 要点:

  • 权限语义化：新增 8 个只读码（55 → 63），URL 规则 68 → 75 条，只读角色的可见面不再依赖写码；内置角色模板加「持写码必持对应读码」不变式。
  • 脱敏配置持久化：新表 sanitization_config（Flyway V4）承接控制台改动，重启后由数据库优先装载；保存改为「先落库、后重建」，失败回滚内存。
  • 配额小时/月限额：API Key 新增 4 个限额（小时请求/Token、月请求/Token），判定顺序 HOUR → DAY → MONTH → MINUTE。
  • 控制台重构：菜单 9 组 40 项 → 7 组 28 项（URL 不变）、侧栏可折叠、暗色语义色校正、窄屏卡片化、33 页去彩虹化、全局搜索（⌘K）与顶部状态条。

✅ v3.3.6（补丁：库结构迁移 + 两处授权收紧 + 页内写门控与契约瘦身，已发布 2026-10-19）

状态: 已发布（GitHub Release v3.3.6，2026-10-19；多架构 Docker 镜像随 Release 由 CI 重建：v3.3.6 / 3.3.6 / latest） 范围: v3.3.5（10-17 发布）之后合入的改动（2026-10-17 → 2026-10-19），含 19 个 feat/fix

领域交付
库结构迁移（#455）黑名单「原因」的 7 个预设值改为语言无关稳定码 + V3__blacklist_reason_codes.sql（H2 / PostgreSQL 双份，幂等改写历史中文值；用户自填文本不动）。回滚语句在 PR #533 正文
授权收紧（#514 / #483 / #487）callhistory:view 不再放行调历史的写/删（改为仅 GET 规则，写/删落 DENY_ALL）；状态持久化的测试写端点抽成 @Profile("!prod") 独立类；配额清理开关改读 jairouter.security.quota.cleanup.enabled 并补 yml（原先读 app.quota.*，运维改不动）
权限码 54 → 55（#454 / #468）新增 monitoring:metrics:write（10 个指标写端点从「靠默认拒绝兜住」变成可授权限）与 monitoring:slowquery:write（慢查询重置）；OPERATOR 按模板自动获得
控制台门控（#468）v-permission 指令 + 9 个页面 33 处写控件（含拖拽排序）按写权限显隐；后端裁决不变，低权限调用仍 403
契约瘦身（#501）删除 PerformanceIssue / activeIssues（恒空）与 ModelCallStats 的 p95ResponseTime / p99ResponseTime / peakQps（无生产者）；黑名单统计 5 个恒空字段改真算；异常事件 lineNumber 取应用帧行号
可观测性（#456 / #495）10 个安全指标接到真实入口（认证 4 / JWT 4 / 脱敏 2）；删除恒 0 的 sanitization.rule.matches 与零调用方 SanitizationMetrics（另 9 条序列）；新增登记面守卫测试
其它/v3/api-docs 空文档修正（#457）· 18 篇过期文档逐篇评审（#547）· 不可逆操作二次确认补全（#460 系列）· 零调用且会 405 的 getServiceInstance 删除（#454）

本轮发布前验证: scripts/test/local-gates.ps1 21 PASS / 0 FAIL / 1 SKIP（SKIP = 相对 github/master 无改动 md，故拼写检查无对象）；三个 PR 的 CI 全绿（test / qodana / 快闸 / 拼写检查 / 文档质量检查），合并后 master 的 Java 测试、前端单元测试、镜像冷启动冒烟、构建和部署文档 亦全 success； 门控的运行态验证为 15-rbac-ui-gating 16/16（⚠️ 全量 E2E 本轮被打断未跑完，故不声称全量通过）。

✅ v3.3.5（补丁：存储契约与健康判定修复 + 错误体形状口径更正，已发布 2026-10-17）

状态: 已发布（GitHub Release v3.3.5，2026-10-17；多架构 Docker 镜像随 Release 由 CI 重建：v3.3.5 / 3.3.5 / latest） 范围: v3.3.4（10-16 早间切片）之后合入的改动（2026-10-16）

领域交付
存储契约：删最后一个条目不再静默失败（#446）JpaStoreManager.saveConfig 去掉空表早退（只留 null 保护 + warn），与 BaseStoreManager / MemoryStoreManager / FileStoreManager 对齐；「空表是合法输入」写进 StoreManager.saveConfig 契约。受影响路径：池 / 路由规则 / 可配置 adapter 的删除。新增 JpaStoreManagerTest 直接驱动真实实现断言「库里留下了什么」，三个 *PersistenceServiceTest 的删除断言补载荷检查 + 真实 MemoryStoreManager 删空往返
健康判定：丢弃率不再让 /actuator/health 永久 503（#447）span 丢弃率超阈值改记 WARNING（HTTP 仍 200，数值仍留在 details 供告警规则用），只有「异步处理器未运行 / 内存 CRITICAL / 性能监控自身 DOWN」才判 DOWN；顺带修掉同段「后写覆盖前写」的问题项丢失。新增 TracingHealthIndicatorTest（原零覆盖）8 例
错误体形状口径更正（#448）/api/** 面上认证链自己写的 401/429 是协议形状、授权层 403 是 text/plain、controller 抛的才是 RouterResponse ⇒ 客户端判据改为「顶层有没有 error 字段」；同步更正 claude-code.md 中「两面都是 RouterResponse」这处对 /v1 也错的表述（中英对称）
其它请求体缺失改 400（#432）· en 侧 TTS/STT 前缀纠正为 /api/v1/audio/*（#436）· 快闸 补配置树与 workflow 触发路径 · 分支清理脚本入库

本轮发布前本地验证: 前端全量 E2E 414/414、接口冒烟 51/51（冷启动全新 H2 库 → 前端构建 → 打包 → 起 8080）。

🏷️ v3.3.4（补丁：错误码语义裁决落地 + 收口 + 内部文档归置，随 v3.3.5 发布 2026-10-16）

状态: 已并入 v3.3.5 的 GitHub Release（2026-10-17） 范围: v3.3.3（10-15 切片）之后合入的改动（2026-10-15 → 2026-10-16）

领域交付
限流错误码语义（#404，已裁决「429 + 拆新码」）两条真实路径拆成两个码、状态都对齐 429：管理面限流器保留 RATE_LIMIT_EXCEEDED（429 扁平体 {"code":...}），API Key 校验链改用新增的 RATE_LIMITED_API_KEY（FullValidationResult 把注册表登记的状态带进 AuthenticationException），认证过滤器不再硬编码 401 而是透出异常携带的状态，/v1/** 与旧形状的 type 一律按状态映射（429 ⇒ rate_limit_error）。注册表 62 → 63 个码；客户端不再需要把 401 当限流处理
错误码状态对齐（#405，混合方案）端点实测状态与规则链推导值两端对齐：BUILTIN_READONLY 两端均为 403（端点原为 400）、RESTART_REQUIRED 两端均为 400（ApiException.legacyResolveStatus 原推导 403）；注册表说明、中英错误码表与 ErrorCodeRegistryTest 的「分歧集合」断言同步更新
死码删除与文档口径更正（#406 / #412 / #414）删除 7 个「只有常量与从未被调用的工厂、全仓无发出点」的码；management-api 两表里 4 个从不发出的码换成注册表真名；RESOURCE_FORBIDDEN → FORBIDDEN_RESOURCE 改口径为「内部常量改名」（客户端不可见）
内部文档归置（#418）会话记忆（mimo-memory/ 393 文件、session-digests/）与两篇内部流程 SOP 移出公开文档站到 innerdoc/；修掉本地文档扫描的 10 处误报，并移除 mkdocs 导航里两个孤儿项

🏷️ v3.3.3（补丁：错误码注册表贯通代码与文档 + 前端生成物卫生；v3.3.2 内容一并发布，随 v3.3.5 发布 2026-10-15）

状态: 已并入 v3.3.5 的 GitHub Release（2026-10-17） 范围: v3.3.1 之后合入的全部改动（2026-10-12 → 2026-10-15）——v3.3.2 曾打 tag 但未单独发布，由本版取代； 详见 更新日志

领域交付
错误码治理（#370 方案 A）注册表补全到 62 个会真正发出的码（码 + 客户端可见状态 + 渲染路径 + 说明，阶段 2 #407）；resolveStatus 只对规则链路径查表（其余路径零行为变化）；中英错误码表按注册表重写（双向 0 差异）；文档门闩换成注册表权威且双向判红（阶段 2 #407）；src/main/java 里不再有裸码字面量（约 175 处发出点 → ErrorCode.X.code()，阶段 3 #410）；新增「码字面量守卫」测试防复发。⚠️ 对外契约变更：TOKEN_USAGE_FORBIDDEN → FORBIDDEN_TOKEN_USAGE（该码写进令牌用量响应体，客户端可见）；另有 RESOURCE_FORBIDDEN → FORBIDDEN_RESOURCE，那只是 AuthorizationException 的内部常量改名、该码全仓没有发出点（客户端不可见）（#403 / #406）
错误码台账RATE_LIMIT_EXCEEDED 同码两状态 429/401（#404，已按裁定拆码解决，见下）；7 个「只有常量与从未被调用的工厂、全仓无发出点」的码已删除（#406）；30 处失败响应此前不带 errorCode（单参 RouterResponse.error）已立 #413
仓库卫生前端生成物不再改脏工作树：package-lock.json 归一化 + 两个 .d.ts 关行尾转换（#408 / #409）
继承自 v3.3.2（一并发布）/v1 流式空体修复（#356）· 告警与审计收口（#306/#309/#313/#394/#397/#400）· 配置诚实性第三批（#319/#322/#323/#329/#331）· 死代码与形状收口（#311/#316/#328/#332/#333/#369/#372/#373）· CI 与文档门闩（#367/#371/#385/#388/#398/#399 及 #250 复评批次）· 依赖安全（Vue 3.5.44，#391）

🏷️ v3.3.2（补丁：/v1 流式空体修复 + 告警/审计收口 + 配置诚实性第三批 + 文档与门闩，已打 tag、随 v3.3.5 发布 2026-10-14）

状态: 已打 tag v3.3.2，未单独发布 —— 其内容随 v3.3.3 并入 v3.3.5 的 GitHub Release（2026-10-17） 范围: v3.3.1（10-10 ~ 10-11 切片）之后合入的 40 项改动（2026-10-12 → 2026-10-14）—— 详见 更新日志

领域交付
流式（/v1）修复正常流返回 200 但响应体 0 字节（#356）：去掉 exchangeToMono 造成的响应体提前释放；协议 error 帧改为仅首块之后补发，首块前失败仍按下游真实状态结束（429 ⇒ 429）；回归钉改为同时驱动两个面（夹具此前写死 /gateway/stream，从未覆盖 /v1）
流式基线客户端可见性基线探针（#298）；/v1 流中失败补 error 帧、不补 [DONE]（#299）；首块前失败状态保真（#305）
告警与审计告警冷却跨副本排他（#306）；审计事件类型一律走枚举名、未知名字不再静默回退（#309）；删死告警阈值/出口配置（#313）
配置诚实性（第三批）删 jairouter.security.audit 7 个无绑定子块（#319）、整棵 jairouter.security.performance（#322）、audit.extended 14 键（#323）；脱敏失败只终止、错误体归中央处理器（#329）；启动校验不再谎称生成随机密码（#331）
死代码与形状删 SecurityAuditApi（#328）、整层 common/api（16 文件，#332）、SecurityStatisticsResponse（#311）；DashboardOverview 类型改为真实载荷（#333）；脱敏测试真正驱动写入路径（#316）
文档与门闩README 事实优先重写（#315）与台账散文化（#330）；两棵已删配置树的文档口径（#325）；「怎么读 CI 门闩」（#326）与「发布节奏」判据（#362）；错误码表按代码重写（#348）；dynamic-config/quick-start 示例改为真实接口并实跑（#341/#349/#351/#353）；围栏配平检查器（#337）
工程与工具本地替代门闩（#336）；镜像冒烟改轮询容器健康（#338）；流式 e2e 夹具让生产处理器进链路（#347）；版本管理脚本单一事实来源 + workflow 覆盖 scripts/docs/**（#359/#360）；v3.3.1 条目补进 master（#364）

✅ v3.3.1（补丁：审计整改 —— 事件循环阻塞 / SSRF 建连绑定 / 用量属主 / 告警接线，已发布 2026-10-14）

状态: 已发布（Git tag / GitHub Release v3.3.1；Docker 镜像随 Release 由 CI 重建） 范围: 取自 v3.3.0 之后的 2026-10-10 ~ 10-11 批次（回切发版，切片点 ea2b7bc2），24 项实质改动； 其后批次的改动在 v3.3.2 交付 —— 详见 更新日志

领域交付
事件循环与阻塞API Key 用量统计（#267）与错误上报落库（#268）移出事件循环；JWT 黑名单同步改锁外批量核对（#273）；TRACING_APPENDER 经 AsyncAppender 挂载（#279）
安全出站解析结果与建连绑定，堵住 DNS 重绑定（#282）；两处自建 WebClient 收归连接池（#284）；用量写入按主体收敛属主（#280）；SecurityAlertService 接到认证失败路径（#277，修复前零调用方）
安全告警与审计判据对齐审计事件类型并下沉存储侧计数（#286）；出口收敛为指标 + 结构化日志、定时排他驱动（#293）；配置面统一并删重复实现（#294）；概览页接出真实近 24h 告警数（#296）
控制台与追踪趋势图接真实统计（#269）；playground 补齐跨 chunk 残行（#270）；搜索页失败改空态（#271）；流式不再打印响应内容并可取消（#274）
清理与依赖删不可达的 ApiKeyAuthenticationProvider / AuthenticationEventListener（#275）与无引用的 useChatRequest（#278）；两处注释与实现对齐（#272、#251）；4 项前端依赖更新（#173/#225/#226/#252）

✅ v3.3.0（次版本：PostgreSQL 与版本化迁移 + 多副本集群 + 配置诚实性，已发布 2026-10-07）

状态: 已发布（Git tag / GitHub Release v3.3.0；Docker 镜像随 Release 由 CI 重建） 范围: v3.2.2 之后合入的 24 项新功能与 29 项修复，详见 更新日志

领域交付
持久化与迁移接入 PostgreSQL（方言 / 数据源 / 索引命名外化，修复 PG 静默丢索引，#160）；引入 Flyway 并以当前 schema 为基线，PG 切 ddl-auto: validate（#190、#214）；老库补丁转版本化迁移 V2，H2 也接上版本化迁移并删除两个启动期补丁组件（#192）；迁移专用入口（migrate profile）退出码反映成败、非 Web 可启动、跑完自退（#193、#195）
多副本与集群跨副本实时事件广播 + 来源副本标识（#164、#181）；跨副本滑动窗口计数，放行量不随副本数放大（#161）；共享态启动自检与缓存收敛（#162）；定时任务按类处置（#163）
安全与鉴权RBAC 三阶段收口至 GET 也 fail-closed（默认 DENY_ALL，可回退，#128）；客户端 IP 信任策略收敛到单一组件（#151）；SSRF 门闩下沉到 WebClientPool（#114）；JWT 强制 issuer + 黑名单可选 fail-closed（#117、#118）；取消 JWT 独立 Redis（#194、#196）；RolePermissionSeeder 增量收敛修复静默权限回退（#144）
限流与配额修复限流器并发安全 / 无界增长 / XFF 绕过（#121–#124）；配额预留中段失败回滚（#119、#120）；结算与用量查询不再在非阻塞线程上阻塞 Redis（#105）
流式与前端流式累积加上界 + 上游空闲看门狗（#126、#127）；流式完成回调的存储写入移出 EventLoop（#115、#125）；前端节流渲染、WS 僵尸重连修复、不再打印令牌、canvas 泄漏修复（#129–#135）
配置诚实性tracing 配置字段四批收口：删 57 个零消费方字段、接 3 个（memory-usage / export-latency-p99 / histogram-buckets）；采样策略真正接线 + 控制台选择器 + 修复保存清空 rules（#224、#234、#242）
部署与日志容器 stdout 改结构化 JSON（json-logs，#211）；Kustomize K8s 制品 + compose 端口/探活/数据卷修正 + 优雅停机（#165）；WebClient 与 tracing 调度器参数外部化（#182）
文档治理ReviewedAt 人工评审机制（#101）；逐条核对并修正 tracing / api-reference / 入口页与代码不符的事实，含英文 monitoring-api 的整段虚构端点与约 20 个不存在的错误码（#159、#231、#235）

✅ v3.2.2（补丁：用户上报问题修复 + 管理面 HTTP 状态码语义，已发布 2026-09-22）

状态: 已发布（Git tag / GitHub Release v3.2.2；Docker 镜像随 Release 由 CI 重建） 范围: 用户上报的 #83 / #84 修复，并连带收口相邻缺陷（#92 / #94 / #95 / #96 / #98）；纯缺陷修复，无新功能（PR #90 / #91 / #93 / #97 / #99）

领域交付
API Key 配额创建/编辑 API Key 补全配额字段提交，修复创建时设置的配额在前端回显异常（#84）；配额更新/重置接口去掉 Reactor 非阻塞线程上的 block()（原本 100% 失败，#92）；告警阈值三处口径统一为 [0.05,1] 闭区间，新增 QuotaLimits 单一事实来源并为创建路径补上校验（#96）
负载均衡与路由监控一条请求内实例重复选择 3 次收敛为 1 次（请求级 SelectedInstanceHolder + 适配器复用已选实例），修复「实例分布」数字跳变 +3（#83）；连带修复适配器侧未透传请求头致 header 规则/标签路由失效、负载均衡 recordCall 每请求推进 2 次
管理面 HTTP 状态码新增 ApiException / ApiExceptions，138 处「失败伪装为 200」站点全部迁移为正确 4xx/5xx（响应体逐字兼容，#94）；前端拦截器透出后端错误消息；e2e 断言收紧（#95）；MonitoringController 客户端校验错误码统一为 400 并补自动模式测试（#98）
工程与工具新增 OpenAI 兼容 mock 模型服务；.gitignore 忽略本地 docker-ctx

✅ v3.2.1（审计整改补丁，已发布 2026-09-21）

状态: 已发布（Git tag / GitHub Release v3.2.1；Docker 镜像随 Release 由 CI 重建） 范围: v3.2.0 发布后合入的审计整改批次（Reactor / SSE / 配额 / 鉴权 / SSRF）+ 用户正则 ReDoS 收口

领域交付
并发与流式健康 SSE 与请求主链同步段移出 EventLoop；流式完成回调与指标/调用历史去掉 block(5s)；SSE/WS Sink 加背压上限；冷路径 block 统一超时（5s / 启动 30s）
配额与限流单机「判定 + 预留」串行化（消除 TOCTOU）；分布式跨实例竞态改为 Redis 原子 Lua CAS（HINCRBY + 上限检查 + 超限回滚）
认证与授权修复认证过滤器伪 401（JWT 登录态下控制台 AI 面与 /v1/** 曾全不可用）；控制台 JWT 登录态放行；追踪过滤器不再重复执行过滤器链；JWT 黑名单存储不可用降级收敛（首次告警 + 30s 短路 + 启动探测）；/ws/** 与健康 SSE 需认证（前端改带 query token）；RBAC 缺口补齐；调试端点默认关闭并脱敏；Swagger 默认需认证
启动与配置拒绝出厂默认 JWT 密钥；生产环境缺密钥或使用默认值启动即失败（StartupSecurityGate）
SSRF实例 URL SsrfGuard：覆盖实例创建/更新、配置同步、出站 WebClient、适配器连通性测试
用户正则新增 SafeRegexValidator 统一闸门（长度上限 512、嵌套量词、被量词包裹的交替分支、反向引用、量词上限），两个脱敏引擎三条编译路径与配置面校验全部收口；检测器自身改为 O(n) 字符扫描（不对用户输入跑正则）

✅ v3.2.0（已发布 2026-09-19）

状态: 已发布（GitHub Release v3.2.0；PR #60/#64/#65） 范围: PII 脱敏管理闭环 + 配额观测操作闭环 + TDD 测试地基

领域交付
PII 记录链路sanitizeForStorage 与网关响应脱敏开关解耦；调用历史 SUMMARY / 追踪使用该路径
管理 APIGET/PUT /api/config/sanitization、规则列表、试脱敏（全链路响应式；非 JSON 样例按文本掩码）
控制台安全 → PII 脱敏管理；权限 security:sanitization:manage
排除路径管理台 /api/** 与 AI 实时路径排除网关响应脱敏
配额 UX监控页限额/进度对照 + 与 API Key 页交叉链接；文档：0=不限制，阈值 0.0–1.0
质量Redis TTL flaky 断言修复；vitest 单测/API/组件；页面冒烟 10/10

✅ v3.1.2（上一稳定补丁）

发布状态: 已发布（2026-09-18） 说明: Docker 启动 / JWT_SECRET / 镜像前端 static/admin 等补丁

✅ v3.1.1（上一稳定版）

发布状态: 已发布（2026-09-15） Git 标签: v3.1.1

主要功能（v3.0.2 → v3.1.1 演进）

版本日期核心内容
v3.0.22026-09-07API 清理与权限收口：删除 4 废弃控制器 + DTO 弃用项清理 + 权限 URL 规则渐进登记（累计 47 条）+ PermissionClosureTest 35 断言 + 前端死函数清理
v3.0.32026-09-09端到端旅程验收（10/10 PASS）+ README 素材重拍（32 张 = 8 页 × 中/英 × 亮/暗）+ 冷启动深链修复 + i18n/图标告警清理
v3.1.02026-09-14配额账本与多协议入口：多维多窗配额账本（MINUTE/HOUR/DAY/MONTH + JPA 持久化 + Redis 分布式计数与断连降级，默认关闭）+ 配额运行时配置面与观测面（控制台 3 页）+ 权限码增至 48 + OpenAI /v1/models + Anthropic /v1/messages（非流式/流式/count_tokens/工具调用）+ 网关错误体协议化 + 错误体 UTF-8 修复
v3.1.12026-09-15补丁修复：401 形状按协议输出 + count_tokens 计入 tools/tool_use/tool_result + /v1/** 错误消息去噪 + 控制台 SSE 路由切换误报告警修复
v3.1.22026-09-18Docker/启动补丁：JWT_SECRET 统一、--generate-key 修复、镜像前端 static/admin 路径、Redis 健康探针条件化
v3.2.02026-09-19PII 脱敏管理（控制台 + /api/config/sanitization/** + sanitizeForStorage）+ 配额监控限额/进度 UX + vitest/页面冒烟 TDD 地基 + 排除路径对齐（PR #60/#64/#65）
v3.2.12026-09-21审计整改补丁：Reactor/SSE 去阻塞 + 配额 TOCTOU 与 Redis Lua CAS + 伪 401 修复 + 追踪链重复执行修复 + JWT 黑名单降级收敛 + 生产 fail-fast + SSRF 防护 + RBAC/调试端点收紧 + 用户正则 ReDoS 收口（PR #67–#72、#78–#81）
v3.3.22026-10-14补丁（随 v3.3.5 发布）：/v1 正常流 0 字节修复（#356，去掉 exchangeToMono 的响应体提前释放；error 帧改为仅首块后补发；夹具改为同时驱动两个面）+ 告警跨副本冷却（#306）+ 审计事件类型一律枚举名（#309）+ 配置诚实性第三批（#319/#322/#323）+ 脱敏失败只终止（#329）+ 启动校验文案（#331）+ 死代码与形状（#311/#328/#332/#333/#316）+ 文档与门闩（#315/#325/#326/#330/#337/#341/#348/#349/#351/#353/#355/#362）+ 工程质量（#336/#338/#347/#359/#360/#364）
v3.3.12026-10-14审计整改补丁（回切发版，切片点 ea2b7bc2）：API Key 用量统计（#267）与错误上报落库（#268）移出事件循环 + JWT 黑名单锁外批量同步（#273）+ TRACING_APPENDER 异步挂载（#279）+ SSRF 解析结果与建连绑定（#282）+ 出站客户端收归连接池（#284）+ 用量写入属主收敛（#280）+ SecurityAlertService 接线（#277）+ 告警判据/出口/配置面收口（#286/#293/#294/#296）+ 控制台与 tracing 去占位数据（#269–#274）+ 死代码删除（#275/#278）+ 4 项前端依赖更新
v3.3.02026-10-07PostgreSQL 与版本化迁移（PG 切 validate、H2 也接上、删两个启动期补丁组件）+ 多副本集群（跨副本事件广播与限流计数、共享态自检、定时任务分类处置）+ RBAC 收口到 GET 也 fail-closed + tracing 配置诚实性四批收口 + Kustomize/json-logs 部署制品 + 文档事实修正（#160–#248）
v3.2.22026-09-22用户上报问题补丁：API Key 配额回显（#84）与路由监控计数 +3（#83）修复 + 配额接口 block 失败（#92）+ 管理面业务失败由 HTTP 200 改为 4xx/5xx（#94，响应体兼容）+ e2e 断言收紧（#95）+ 告警阈值统一 [0.05,1]（#96）+ 监控接口错误码统一（#98）（PR #90/#91/#93/#97/#99）

统计数据

  • 测试数量: 3,517（全绿）
  • Java 源文件: 750+
  • 代码规模: ~140k LOC

✅ v2.10.x - Web 管理台重构系列（已完成，2026-09-06）

前端功能已齐但未形成完整系统流程，按每版一主题拆分重构： - v2.10.0 前端地基 ✅（2026-09-05 已发布）：死代码清理（13 .vue + common ≈13.5k 行）+ PageSkeleton/StatCard/useChartTheme + Dashboard·Service·Rule 试点 + ~20 页令牌化 + Element Plus 暗色修复 + Layout/console 清理 - v2.10.1 治理指挥台 ✅（2026-09-06 已发布）：Dashboard v2 治理链路面板 + 异常摘要 + Cross-link 跨页导航 + 7 页 PageSkeleton 迁移 + 令牌化收尾 - v2.10.2 配置接入与能力补页 ✅（2026-09-06 已发布）：响应缓存管理页（状态/失效 + B 档运行时开关 + 命中观测）+ 慢查询分析页 + CB 重置/配额告警 + Onboarding 接入引导 + 后端缓存状态与废弃标注 + 权限码 45 - v2.10.3 Web 双语版 ✅（2026-09-06 已发布）：全量 zh/en i18n + 语言切换器 + Element Plus locale + 日期/数字本地化 + 暗色对比收口 - v2.10.4 Web 体验收尾 ✅（2026-09-06 已发布）：服务类型显示名统一 + ECharts 图表语言/主题热切换 + 死代码清理（utils/errorHandler、validators/* 等）+ 暗色对比审计门禁（36 页 ≥4.5）+ 后端 message 文档注记 + 代码块暗色语法高亮

🎯 v3.0.x - Web 完整流程系列 (进行中)

v3.0 为 Web 完整流程里程碑（对外 /api/v1 保持兼容，无 breaking）： - v3.0.1 流程串联 ✅（2026-09-06 已发布）：Onboarding 预选闭环（useRoutePreselect + 5 容器 query 预选）+ Dashboard 治理入口补全 + CB/LB 反向跳转 + 版本页入站 + 旧 redirect 清理 + PageSkeleton 覆盖 18 页 - v3.0.2 API 清理与权限收口 ✅（2026-09-07 已完成）：删除 4 废弃控制器（ServiceConfigController/ServiceInstanceController/InstanceConfigController/SecurityAuditController）与 TokenUsageController 5 个死方法 + DTO 弃用项清理 + PermissionRuleRegistry 清理废弃绑定 + 权限 URL 规则渐进登记 15 条（共 47 条）+ PermissionClosureTest 35 断言 + 前端死函数清理；mvn 3202 用例全绿 - v3.0.3 验收与发布 ✅（2026-09-13 已发布）：端到端旅程验收（10/10 PASS，0 pageerror/0 个 5xx）+ README 素材重拍（32 张 = 8 页 × 中/英 × 亮/暗）+ 文档/计划同步 + 双远端 tag/Release/Docker；另修复冷启动深链（/security/*、/system/* 角色守卫）与 i18n/图标告警 - v3.1.0 配额账本与多协议入口 ✅（2026-09-14 已发布）：多维多窗配额账本（MINUTE/HOUR/DAY/MONTH + JPA 持久化 + Redis 分布式计数与断连降级）+ 配额运行时配置面与观测面（控制台 3 页）+ OpenAI 原生面 /v1/models + Anthropic /v1/messages（非流式/流式/count_tokens/工具调用）+ 网关错误体协议化 + 错误体字符集 UTF-8 修复 + 流式路径实例级 headers 修复 - 语义缓存评估（向量相似度复用，另立项）；高可用地基（多节点/Redis 分布式/配置回滚）于 v3.1.x 后评估；微服务化另行

✅ v2.6.11（已发布的长期支持版，LTS 政策已终止）

发布状态: 已发布 (2026-04-17) 维护周期: 已终止（原计划至 2028-05，见下方"LTS 政策调整说明"）

已完成功能

  • ✅ 多租户支持
  • ✅ API Key 认证机制
  • ✅ JWT Token 支持
  • ✅ OAuth 2.0 集成
  • ✅ 基于角色的访问控制 (RBAC)
  • ✅ 响应数据脱敏（含记录侧脱敏）
  • ✅ 安全审计日志
  • ✅ H2 嵌入式数据库（当前唯一受支持的持久化数据库）
  • 📋 PostgreSQL/MySQL 支持（规划中；当前 pom.xml 仅引入 H2 驱动，配置与方言均硬编码为 H2，尚无外部数据库适配）
  • ✅ Redis 缓存集成
  • ✅ Prometheus 指标收集
  • ✅ Grafana 仪表板模板
  • ✅ 分布式链路追踪 (Zipkin/OpenTelemetry)
  • ✅ 完整的 Docker 部署方案
  • 🟡 Kubernetes 部署支持（部分：deploy/k8s/base 及 dev/prod overlay 已随仓库提供，并已在真实集群验证「迁移 Job 完成 + 3 副本就绪」；横向扩展仍受单文件 H2 限制——每副本独立卷、副本间状态不共享，详见 deployment/kubernetes.md 的「多副本现状」）

代码质量

  • ✅ Checkstyle 代码规范检查
  • ✅ SpotBugs 静态分析
  • ✅ JaCoCo 测试覆盖率报告
  • ✅ 700+ 单元测试
  • ✅ E2E 集成测试

🎯 v2.7.x - 性能优化系列 (2026年Q2-Q3)

已完成

版本日期主要内容
v2.7.02026-04-20Package 结构重组，6个服务模块
v2.7.12026-04-21auth 模块独立 (116 文件)
v2.7.22026-04-22config 模块独立 (~50 文件)
v2.7.32026-04-23router 模块上 (adapter/loadbalancer)
v2.7.42026-04-24router 模块下 (熔断/限流)
v2.7.52026-04-25monitor 模块独立 (98 文件)
v2.7.62026-04-26persistence 模块独立 (49 文件)
v2.7.72026-04-27common 模块独立 (96 文件)
v2.7.82026-04-28controller 分组优化
v2.7.92026-04-29包结构优化完成
v2.7.102026-07-13技术债务清理 - 大文件拆分+废弃代码清理
v2.7.112026-07-14RBAC权限控制 + UI优化

性能提升

  • 路由流程优化 20-50%
  • 内存占用降低 15%
  • 启动时间减少 30%

⏸️ v3.0 - 微服务架构 (无限期推迟)

状态: ⏸️ 推迟

由于当前单体架构已满足需求，v3.0 微服务架构转型已无限期推迟。

功能特性规划

适配器扩展

已支持 ✅

适配器类型状态
GPUStackChat/Embedding/Rerank✅
OllamaChat/Embedding✅
vLLMChat✅
XinferenceChat/Embedding/Rerank✅
LocalAIChat/Embedding✅
OpenAIChat/Embedding✅
Azure OpenAIChat/Embedding✅
Anthropic ClaudeChat✅
阿里云百炼Chat/Embedding✅
腾讯云混元Chat✅
百度智能云Chat✅
Google GeminiChat/Embedding✅

计划支持 📋

  • 📋 Cohere API（版本待定）
  • 📋 AWS Bedrock（版本待定）

2026-10-16 审计更正：Google Gemini 已实现 —— AdapterRegistry 里注册为 adapters.put("gemini", …)，GeminiAdapter.supportCapability() = chat + embedding ⇒ 已移入「已支持」；另两项原先写的 v2.8.x / v2.9.x 版本号早已过期，改为「版本待定」。

负载均衡策略

已实现 ✅

  • ✅ Random (随机)
  • ✅ Round Robin (轮询)
  • ✅ Weighted Round Robin (加权轮询)
  • ✅ Least Connections (最少连接)
  • ✅ IP Hash (IP哈希)
  • ✅ Consistent Hash (一致性哈希)

已实现 ✅（续）

  • ✅ Latency-Aware（延迟感知，LatencyAwareLoadBalancer）
  • ✅ Sticky（会话粘滞，StickyLoadBalancer）

计划实现 📋

  • 📋 Cost-based (成本优先)
  • 📋 Model Capability-based (能力匹配)

2026-10-16 审计更正：延迟优先其实已实现（LatencyAwareLoadBalancer），原先被列在「计划实现」里； 会话粘滞此前未列出，一并补上。

限流算法

已实现 ✅

  • ✅ Token Bucket (令牌桶)
  • ✅ Leaky Bucket (漏桶)
  • ✅ Sliding Window (滑动窗口)
  • ✅ Warm Up (预热限流)

已实现 ✅（续）

  • ✅ API Key 级限流（每键 rateLimitPerMinute + 令牌桶；超限返回 429 与 RATE_LIMITED_API_KEY，#404）
  • ✅ 分布式限流（Redis 滑动窗口 RedisSlidingWindowRateLimiter，由 RateLimitManager 装配；依赖 Redis）

计划实现 📋

  • 📋 User-based Rate Limiting (用户级限流)

2026-10-16 审计更正：「API Key 级别的限流」与「分布式限流」原先都列在计划里，实际都已实现 （前者见 ApiKeyValidator.validateRateLimit，后者见 RateLimitManager 对 RedisSlidingWindowRateLimiter 的装配）。

2026-10-16 审计更正（第二轮）：「Adaptive Rate Limiting（自适应限流）」原先列在「已实现」里， 但全仓没有该实现（router/ratelimit/** 下没有这个算法，其余文档也只列了 token-bucket / leaky-bucket / sliding-window / warm-up 四种）⇒ 该行已删除。

监控和可观测性

已实现 ✅

  • ✅ Prometheus 指标
  • ✅ Grafana 仪表板
  • ✅ 健康检查端点
  • ✅ 基础告警规则
  • ✅ 分布式链路追踪 (Zipkin/OpenTelemetry)
  • ✅ 结构化日志

计划实现 📋

  • 📋 业务指标分析
  • 📋 成本分析
  • 📋 自定义告警规则

技术架构

当前架构 (v3.3.5)

单体应用 → 模块化设计 → 响应式编程

架构演进

阶段版本状态
基础架构v0.1 - v0.3✅ 已完成
安全认证v0.4✅ 已完成
监控追踪v0.5✅ 已完成
性能优化v2.7.x✅ 已完成
配置管理v2.8.x✅ 已完成（模块化配置 + 三批配置诚实性收口）
可维护性提升v2.9.x✅ 已完成（重构记录 / 门闩体系 / 错误码注册表）
微服务探索v3.0⏸️ 推迟（当前单体架构已满足需求）

技术栈

核心技术

  • 后端: Spring Boot 3.5.5 + WebFlux (响应式)
  • 前端: Vue 3 + TypeScript + Element Plus
  • 数据库: H2 (嵌入式) + R2DBC
  • 缓存: Redis (可选)
  • 监控: Prometheus + Grafana
  • 追踪: OpenTelemetry + Zipkin

数据存储

  • 默认: H2 嵌入式数据库（单文件；不可跨副本共享）
  • 现已支持: PostgreSQL —— 显式设置 DATABASE_URL=jdbc:postgresql://… 即走 PostgreSQL（多副本横向扩展需要外部共享库）； 两条路径都有版本化 schema 迁移（PostgreSQL 走 Flyway 并把 ddl-auto 覆盖为 validate，H2 走启动期兼容补丁）
  • 规划中: MySQL（无驱动与方言脚本，未支持）
  • 缓存: Redis (可选)

2026-10-16 审计更正：原文写「当前唯一支持 H2，PostgreSQL / MySQL 规划中」——PostgreSQL 自 v3.0.0 起已支持 （pom.xml 的 org.postgresql:postgresql + flyway-database-postgresql、application-migrate.yml 的迁移模式、 FlywayDialectEnvironmentPostProcessor 的方言覆盖）。MySQL 仍未支持。

性能目标

⚠️ 下表是设计目标，不是实测值（本仓未做基准压测）；引用前请自行实测。

版本RPS延迟 (P95)可用性并发连接
v2.6.x5k< 50ms99.95%5k
v2.7.x10k< 30ms99.95%10k
v2.8.x20k< 20ms99.99%20k
目标100k+< 10ms99.99%100k+

社区发展

当前状态

  • GitHub / Gitee 双平台托管
  • 完整的用户文档和 API 文档
  • 中英文文档支持
  • MkDocs 静态网站

发展目标

  • 活跃的开发者社区
  • 定期的版本发布
  • 更多适配器支持
  • 完善的插件系统

LTS 政策调整说明（2026-09）

决定：终止 LTS（长期支持）版本策略。

背景：项目迭代节奏明显加快（v2.9 → v3.1 期间发布约 20 个版本）。维护一条独立的 LTS 线意味着对旧分支持续做回归测试、安全补丁与文档双轨维护，投入产出已不匹配，因此不再对外承诺 LTS 维护周期。

事项说明
既有发布物v2.6.11 的 Git 标签、Docker 镜像与 Release 仍可下载、可用于回滚，但不再有专门的维护承诺（不保证提供安全补丁或兼容性修复）
后续维护线只维护当前版本（latest）一条线
升级建议跟随最新版本；破坏性变更会在更新日志 中标注
需要长期稳定请固定到具体版本标签（如 v3.1.1）并自建回归测试，拉取镜像时使用对应版本 tag 而非 latest

本页「版本发布周期」表中的 LTS 行已随本政策一并移除。

版本发布周期

版本类型周期说明
功能版1-2个月新功能迭代
补丁版按需Bug 修复和安全更新

参与方式

开发贡献

代码贡献

  • 功能开发和 Bug 修复
  • 性能优化和重构
  • 测试用例编写
  • 代码审查

文档贡献

  • 用户文档完善
  • API 文档更新
  • 教程和示例编写
  • 多语言翻译

反馈渠道

风险和挑战

技术风险

  • 性能瓶颈: 大规模部署下的性能挑战
  • 兼容性: 多版本 API 兼容性维护
  • 安全性: 安全漏洞和攻击防护
  • 横向扩展受限: 当前唯一支持 H2 嵌入式单文件数据库，多副本无法共享同一数据文件，replicas 必须为 1；限流、配额、JWT 黑名单、API-Key 缓存等状态默认均为进程内语义。落地顺序见 issue #160（共享数据库适配）、#161（限流跨实例化）、#162（共享态接线）、#163（调度锁）、#164（实时事件广播）、#165（K8s 制品）

市场风险

  • 竞争加剧: 类似产品的竞争
  • 技术变化: AI 技术快速发展带来的挑战
  • 用户需求: 用户需求的快速变化

应对策略

  • 持续的技术创新和优化
  • 活跃的社区建设和维护
  • 灵活的产品策略调整
  • 完善的质量保证体系

总结

JAiRouter 项目将继续秉承开源精神，致力于为用户提供最优秀的 AI 模型服务路由解决方案。我们欢迎社区的参与和贡献，共同推动项目的发展和进步。

近期重点 (2026年)

  1. ✅ 完成 v2.7.x 性能优化系列 + RBAC权限控制
  2. ✅ 推进 v2.8.x 配置管理优化 + 新适配器 + 插件系统/规则引擎/资源池
  3. ✅ v2.9.x 智能路由深化系列（故障转移/标签路由/响应缓存 P0）
  4. ✅ v2.9.10 响应缓存 P1（流式缓存 + 失效 API + 限流短路）
  5. ✅ v2.9.11 README/截图更新 + hallmark 管理台设计审计 + 前端修复
  6. ✅ v2.10.x Web 管理台重构系列全部完成（v2.10.0 前端地基 ✅ 2026-09-05；v2.10.1 治理指挥台 ✅ / v2.10.2 配置接入与能力补页 ✅ / v2.10.3 Web 双语版 ✅ / v2.10.4 Web 体验收尾 ✅ 2026-09-06）
  7. ✅ v3.0.x Web 完整流程系列（v3.0.1 流程串联 ✅ 2026-09-06；v3.0.2 API 清理与权限收口 ✅ 2026-09-07；v3.0.3 验收与发布 ✅ 2026-09-13）
  8. ✅ v3.1.0 配额账本与多协议入口 ✅ 2026-09-14（多维多窗配额 + Anthropic 入口 + 工具调用 + 运行时配置面/观测面）
  9. ✅ v3.2.0 PII 治理与配额操作闭环（2026-09-19 发布）
  10. ✅ v3.2.1 审计整改补丁（2026-09-21 发布）：Reactor/SSE 去阻塞、配额 TOCTOU 与 Redis Lua CAS、伪 401 修复、追踪链重复执行修复、JWT 黑名单降级收敛、生产 fail-fast、SSRF 防护、RBAC/调试端点收紧、用户正则 ReDoS 收口。已知剩余（P2）：QuotaLedgerService 分布式路径同步 block、前端临时 ID 使用 Math.random
  11. ✅ v3.2.2 补丁（2026-09-22 发布）：用户上报的 API Key 配额回显（#84）与路由监控计数 +3（#83）修复；管理面业务失败由 HTTP 200 改为 4xx/5xx（#94，响应体兼容），并收口配额接口 block 失败（#92）、e2e 断言假通过（#95）、告警阈值口径（#96）、监控接口错误码（#98）。已知剩余（P2）：QuotaLedgerService 分布式路径同步 block、前端临时 ID 使用 Math.random
  12. ✅ v3.3.0 次版本（2026-10-07 发布）：PostgreSQL 与版本化迁移（PG 切 ddl-auto: validate、H2 也接上、删两个启动期补丁组件）；多副本集群（跨副本事件广播与滑动窗口计数、共享态自检、定时任务按类处置）；RBAC 收口到 GET 也 fail-closed；tracing 配置诚实性四批收口（删 57 个零消费方字段、接 3 个）；容器 stdout 结构化 JSON 与 Kustomize 制品；文档事实逐条核对修正（#160–#248）
  13. ✅ v3.4.0 功能版（2026-10-21 发布）：控制台重构（7 组 28 项导航、可折叠侧栏、暗色层级、窄屏卡片化、33 页去彩虹化、全局搜索与状态条）、权限语义化（8 个只读码，55 → 63）、脱敏配置持久化（Flyway V4）、配额小时/月限额。顺延：记录级 FULL 加密策略 UI 随前端轨道（v3.5.0 系列）落地
  14. ✅ v3.5.0 功能版（2026-10-24 发布）：响应脱敏覆盖面收口（/v1/** 非流式 JSON、response.scope 可配置、缓冲上限、SSE 逐帧）、默认 PII 规则与 JSON 键豁免修正、请求侧配置面移除（Flyway V5）、熔断器三项治理、控制台验收修正
  15. 📋 语义缓存评估（向量相似度复用，独立项目）；高可用地基（多节点/Redis）在 v3.2.x 后再评估

长期愿景

  1. 成为 AI 模型路由领域的标准
  2. 建立完整的生态系统
  3. 实现企业级商业化成功
  4. 推动行业技术发展

更新时间: 2026年9月22日

如有任何建议或想法，欢迎通过 GitHub Discussions 与我们交流。