1. 从一堆“重复造轮子”的痛说起QuickBlue 到底想解决什么问题做过几年企业级项目的人大概都有类似的经历新项目立项架构评审会上大家一致决定“上微服务”然后团队花了两三个月搭框架——注册中心选型、网关鉴权、链路追踪、分布式事务、多租户隔离、代码生成器、权限模型、日志审计、灰度发布……等这套底座跑通业务需求已经堆了一屏。更尴尬的是下一个项目来了这套东西又要重新搭一遍改改包名、换换配置本质上还是在做重复劳动。QuickBlue 就是冲着这个场景来的。它本质上是一个“AI 应用底座”你可以把它理解成一套已经搭好骨架、通好水电、装好门窗的微服务基座开发者进来之后主要精力放在业务逻辑和 AI 能力集成上而不是再去纠结 Spring Cloud 版本兼容、Sentinel 规则怎么持久化到 Redis 集群、JDK 21 的虚拟线程要不要开这些底层问题。它面向的是企业内部的平台团队、中台研发、以及那些想快速把 AI 能力落到业务系统里的技术负责人。为什么现在特别强调“AI 应用底座”这个概念因为过去一年我接触到的项目里十个有八个都在做“AI 加业务”的尝试——智能客服、文档问答、流程自动化、代码辅助、数据分析助手。但真正卡住他们的往往不是模型本身而是模型怎么和现有的用户体系、权限体系、数据权限、审计日志、限流熔断对接起来。一个 AI 接口调用要经过网关鉴权、租户隔离、Token 计费、敏感词过滤、结果缓存、异步任务队列这些全是传统微服务里已经解决过的问题。QuickBlue 的思路就是把这些通用能力沉淀到底座里AI 应用只需要关注 Prompt 编排、模型路由和业务语义。所以这篇文章我会从架构设计、核心模块、实操落地、踩坑排查几个角度把 QuickBlue 这类 AI 应用底座拆开讲清楚。不管你是正在选型的技术负责人还是准备基于它做二次开发的工程师都能拿到可以直接参考的东西。2. 架构设计拆解为什么是微服务而不是单体2.1 单体先行还是底座先行这是个路线问题很多团队一上来就问“我就做个 AI 问答有必要上微服务吗”这个问题没有标准答案但我的经验是看你的 AI 应用会不会长成企业级系统。如果只是一个内部工具几十个人用单体加个模块化分包完全够。但一旦涉及到多部门、多租户、多模型供应商、多业务线复用单体就会变成一坨——改一个限流规则要全量发版加一个模型供应商要动核心代码权限模型和业务逻辑耦合在一起测试环境永远和线上不一致。QuickBlue 选择微服务路线核心考量有三点。第一是能力复用AI 应用底座里的用户中心、权限中心、网关、文件服务、消息服务、任务调度这些模块在不同业务线之间是高度复用的拆成独立服务后可以独立演进、独立扩容。第二是故障隔离AI 调用本身是不稳定的模型响应慢、超时、限流是常态如果和核心业务在同一个进程里一个慢调用可能拖垮整个应用。第三是技术异构AI 相关的组件迭代非常快Python 生态、向量数据库、推理框架和 Java 业务系统的技术栈差异很大微服务边界天然适合做技术栈隔离。但我要泼一盆冷水微服务不是免费的。服务拆分带来的分布式事务、链路追踪、配置管理、服务发现、网络延迟这些都是实打实的成本。QuickBlue 的价值就在于它把这些成本提前消化掉了你拿到的是一个已经处理好这些问题的底座而不是一堆需要你自己组装的零件。2.2 分层架构与模块边界怎么划QuickBlue 的整体分层我习惯用四层来理解。最底层是基础设施层包括注册中心、配置中心、网关、缓存、消息队列、数据库连接池这些。往上一层是通用能力层也就是用户、权限、租户、字典、日志、文件、定时任务、代码生成这些每个系统都要用的东西。再往上是AI 能力层包括模型路由、Prompt 管理、向量检索、会话管理、Token 计量、内容安全。最上面是业务应用层也就是你真正要交付给用户的那部分。这个分层的关键在于依赖方向单一业务应用层依赖 AI 能力层和通用能力层AI 能力层依赖通用能力层通用能力层依赖基础设施层反向依赖是严格禁止的。我见过太多项目因为业务代码直接调用了基础设施层的 Redis 客户端导致后面想换缓存实现时牵一发动全身。QuickBlue 在模块边界上做了强约束每个服务只暴露 Feign 接口和 DTO内部实现对外不可见。模块拆分上我建议重点关注这几个边界认证授权独立成服务因为所有请求都要过它网关独立部署承担路由、限流、鉴权前置、日志采集AI 编排独立成服务因为它的扩缩容策略和普通业务服务完全不同文件与向量存储独立因为 AI 场景下文件处理和向量检索的 IO 特征很特殊。其他的像字典、日志、消息可以按团队规模决定是合并还是拆分小团队合并成“系统服务”也完全可行。2.3 JDK 21 与 Spring Cloud 版本选型的现实考量QuickBlue 基于 JDK 21这个选择在当下是合理的。JDK 21 是 LTS 版本虚拟线程Virtual Threads正式转正对于 AI 应用这种大量 IO 等待的场景虚拟线程能显著提升吞吐量。我实测过一个场景同样的模型调用接口用传统线程池在 200 并发时线程池打满开始排队换成虚拟线程后 2000 并发下响应时间依然平稳。当然虚拟线程不是银弹CPU 密集型任务用它反而可能因为调度开销略慢但在 AI 应用底座这种 IO 密集为主的场景里收益是明显的。Spring Cloud 版本上JDK 21 对应的比较稳的组合是 Spring Boot 3.2.x 加 Spring Cloud 2023.0.x。这里有个坑要提醒Spring Cloud Alibaba 的版本跟进往往比 Spring Cloud 官方慢半拍如果你要用 Nacos、Sentinel 这些组件一定要去官方版本对应表里核对不要凭感觉升级。我踩过一次坑Spring Boot 升到 3.2 之后 Sentinel 的适配包没跟上启动直接报类找不到排查了半天。提示版本选型不要追新要追“社区验证过的组合”。QuickBlue 这类底座项目稳定性优先级高于尝鲜。3. 核心模块实操从网关到 AI 编排的落地细节3.1 网关层鉴权、限流、日志一个都不能少网关是整个底座的入口QuickBlue 的网关承担了路由转发、JWT 校验、租户识别、接口限流、访问日志采集这几件事。实操上我建议把网关的职责控制在“横切关注点”不要往里塞业务逻辑。具体配置上路由规则建议走配置中心动态下发而不是写死在配置文件里这样新增服务时不用重启网关。限流这块Sentinel 是常见选择但规则持久化到 Redis 集群这一步很多人会漏。默认情况下 Sentinel 规则存在内存里服务重启就丢了生产环境必须做持久化。QuickBlue 的做法是规则写入 Redis网关启动时拉取同时监听配置变更事件实时刷新。这里有个细节Redis 集群模式下Sentinel 的规则 key 要设计好命名空间避免多环境互相覆盖。我一般用sentinel:{env}:{app}:{resource}这种格式。鉴权方面JWT 校验放在网关做前置拦截解析出用户 ID 和租户 ID 后通过请求头透传给下游服务。下游服务不再重复解析 Token只信任网关注入的请求头。但这里有个安全前提下游服务必须只允许网关访问不能直接暴露公网否则请求头可以被伪造。内网部署时用安全组或服务网格做隔离这是底线。3.2 认证授权与多租户隔离的实现要点多租户是 AI 应用底座里绕不开的话题。QuickBlue 采用的是共享数据库、共享表、租户字段隔离的方案也就是每张业务表都带一个tenant_id所有查询自动拼接租户条件。这个方案的好处是成本低、运维简单缺点是隔离性弱一旦代码里漏了租户条件就会串数据。实现上我推荐用 MyBatis 的拦截器做统一处理在 SQL 执行前自动注入tenant_id条件。但要注意几个例外场景系统表、字典表、全局配置表不应该被租户隔离需要在拦截器里做白名单排除。另外跨租户的统计查询要显式声明忽略租户条件不能靠拦截器猜。权限模型上QuickBlue 用的是 RBAC 加数据权限的组合。RBAC 管“能不能访问这个菜单/接口”数据权限管“能看到哪些数据”。数据权限的实现我见过很多种比较稳的是在 SQL 层面做行级过滤比如按部门、按创建人、按自定义范围。这里有个经验数据权限规则不要做得太灵活越灵活越容易出 bug覆盖 80% 的常见场景就够了剩下的特殊需求用自定义 SQL 解决。3.3 AI 编排服务模型路由与 Prompt 管理这是 QuickBlue 区别于传统微服务底座的核心模块。AI 编排服务要解决几个问题多个模型供应商怎么统一调用、Prompt 怎么版本化管理、会话上下文怎么维护、Token 怎么计量、结果怎么缓存。模型路由上我建议抽象一层统一的ModelClient接口不同供应商各家大模型 API实现各自的适配器。路由策略支持按模型名、按租户、按场景、按成本优先级来选。这里的关键是降级策略主模型超时或限流时自动切到备用模型保证业务不中断。降级要记录日志方便后续分析。Prompt 管理我强烈建议做成配置化而不是硬编码在代码里。每个 Prompt 有唯一标识、版本号、模板内容、变量定义、适用模型。业务代码只引用 Prompt 标识具体内容从配置中心或数据库读取。这样做的好处是运营人员可以调 Prompt 而不用发版A/B 测试也方便。我见过一个团队把 Prompt 写死在 Java 代码里改一个标点都要走完整发布流程效率极低。会话管理上短期上下文放 Redis设置合理的过期时间长期会话历史落库支持按用户、按会话查询。Token 计量要在每次模型调用后累加按租户和用户维度统计这是后续计费和配额控制的基础。3.4 数据通信与缓存Redis 集群在底座里的角色Redis 在 QuickBlue 里承担了缓存、会话、限流计数、分布式锁、规则存储等多重角色。集群模式下有几个实操要点。第一是key 设计要带业务前缀避免不同模块互相干扰比如auth:token:*、ai:session:*、sentinel:rule:*。第二是大 key 和热 key 要提前预防会话数据如果单个 key 存了几百 KB集群迁移时会很痛苦建议拆分存储。第三是分布式锁要用 Redisson 这类成熟组件不要自己用 SETNX 手搓锁续期、可重入、锁释放这些细节自己实现很容易出问题。缓存一致性上我一般用“先更新数据库再删除缓存”的策略配合延迟双删处理并发场景。但说实话强一致性在分布式缓存里很难做到完美业务上要能接受短暂不一致。如果某个场景绝对不能容忍脏读那就别用缓存直接查库。4. 从零搭建到跑通一个可复现的落地流程4.1 环境准备与依赖清单假设你要基于 QuickBlue 的思路搭一套自己的底座环境上我建议这样准备。JDK 21 装好Maven 3.9 以上MySQL 8.0Redis 7.x集群模式至少 3 主 3 从Nacos 2.x 做注册和配置中心Sentinel 做限流。如果要用消息队列RocketMQ 或 Kafka 都行看团队熟悉度。依赖版本上Spring Boot 3.2.x、Spring Cloud 2023.0.x、Spring Cloud Alibaba 2023.0.x.x这几个要对齐。MyBatis-Plus 用 3.5.xRedisson 用 3.2x.x。这些版本组合我实测过兼容性没问题。注意Nacos 2.x 默认开启了 gRPC 通信如果服务器有防火墙策略要提前放行 9848 和 9849 端口否则服务注册会失败而且报错信息很不直观容易误判为网络问题。4.2 服务拆分与启动顺序服务拆分我建议按这个顺序落地先起注册中心和配置中心再起网关然后是认证授权服务接着是通用能力服务用户、权限、字典、日志最后是 AI 编排服务和业务服务。启动顺序有依赖关系认证服务依赖用户服务网关依赖认证服务做 Token 校验所以不能乱。每个服务的配置文件建议分三份application.yml放通用配置application-{env}.yml放环境相关配置敏感信息数据库密码、模型 API Key走配置中心的加密配置或环境变量不要明文写在文件里。我见过把 API Key 提交到代码仓库的这是大忌。4.3 关键配置示例与参数说明网关的 Sentinel 规则持久化配置核心是配置数据源指向 Redis。大致思路是定义一个RedisDataSource实现ReadableDataSource接口启动时从 Redis 读取规则同时注册监听器。规则内容用 JSON 存储结构包含资源名、限流阈值、流控模式、流控效果。虚拟线程的开启很简单Spring Boot 3.2 里加一行配置spring.threads.virtual.enabledtrue即可。但要注意虚拟线程和某些依赖 ThreadLocal 的组件可能不兼容比如老版本的分布式追踪 SDK。开启后要重点观察日志和链路追踪是否正常。数据库连接池用 HikariCP连接数不是越大越好。我一般按CPU 核数 * 2 磁盘数估算再结合压测调整。AI 编排服务因为大量等待模型响应连接数可以适当调大但要注意数据库本身的连接上限。4.4 跑通第一个 AI 接口的完整链路从请求进来到模型返回完整链路是这样的客户端请求打到网关网关校验 JWT、识别租户、限流检查通过后转发到 AI 编排服务。编排服务根据请求参数选择 Prompt 模板组装上下文调用模型适配器。适配器根据路由策略选择模型供应商发起调用拿到结果后做内容安全过滤、Token 计量、结果缓存最后返回给网关网关记录访问日志后返回客户端。这条链路上每个环节都可能出问题所以全链路追踪是必须的。我建议用 TraceId 贯穿整个请求网关生成通过请求头透传每个服务在日志里打印 TraceId。排查问题时一个 TraceId 就能串起所有服务的日志效率提升非常明显。5. 常见问题与排查技巧实录5.1 服务注册与配置拉取失败这是新手最常遇到的问题。现象是服务启动后注册不上或者配置拉取超时。排查顺序我一般这样走先确认 Nacos 服务本身是否正常浏览器访问控制台能不能打开再确认网络连通性telnet 端口通不通然后看应用日志里的具体报错是连接超时还是认证失败最后检查命名空间和分组配置是否匹配。有个隐蔽的坑Nacos 2.x 的 gRPC 端口如果没放行HTTP 端口能通但注册会失败报错信息可能是“连接被拒绝”或“超时”很容易误判。解决办法就是提前确认 9848、9849 端口开放。5.2 限流规则不生效或重启丢失Sentinel 规则不生效先确认规则有没有成功推送到客户端。可以在 Sentinel 控制台看规则列表也可以看应用日志里有没有规则加载记录。如果规则在控制台有但应用不生效多半是数据源配置有问题或者规则格式不对。重启丢失就是持久化没做。默认内存存储重启必丢。解决办法就是接 Redis 或 Nacos 做持久化数据源。这里要注意持久化数据源的优先级要高于本地配置否则会被覆盖。5.3 多租户数据串读的排查思路数据串读是最危险的问题一旦发生就是数据泄露。排查时先看 SQL 日志确认租户条件有没有拼上。如果没拼上检查 MyBatis 拦截器是否生效是不是被其他拦截器覆盖了或者该表在排除名单里。如果拼上了还串读检查租户 ID 的来源是否正确是不是从请求头取的时候取错了。预防上我建议在测试环境专门造多租户数据做交叉验证每个接口都要测。另外代码评审时重点看手写 SQL 的地方自动生成的 SQL 一般没问题手写的最容易漏。5.4 模型调用超时与降级处理模型调用超时是 AI 应用的常态。处理上分三层第一层是超时设置不同模型响应时间差异很大超时时间要按模型配置不能一刀切第二层是重试但重试要谨慎非幂等操作不能重试而且重试次数不宜多否则会放大下游压力第三层是降级主模型不可用时切备用模型或者返回缓存结果或者给用户友好提示。我踩过的坑是重试没有做退避失败后立刻重试结果把下游打得更惨。正确做法是加指数退避比如 1 秒、2 秒、4 秒这样递增。5.5 常见问题速查表问题现象可能原因排查方向解决建议服务注册不上端口未放行、命名空间错误检查 gRPC 端口、控制台配置放行 9848/9849核对命名空间限流不生效规则未推送、数据源未配置看控制台规则、应用日志配置持久化数据源数据串读租户条件未拼接看 SQL 日志、拦截器配置检查拦截器白名单和租户来源模型超时超时设置过短、下游限流看调用日志、监控指标按模型配置超时加退避重试虚拟线程异常组件不兼容 ThreadLocal看启动日志、追踪链路升级组件或关闭虚拟线程6. 我在这类底座项目上的一些实操体会做 AI 应用底座这几年我最大的体会是底座的复杂度要匹配团队的成熟度。QuickBlue 这类项目功能很全但如果团队只有三五个人硬上全套微服务反而是负担。我的建议是分阶段来第一阶段先把网关、认证、AI 编排这三个核心跑通其他模块按需引入第二阶段再补全监控、链路追踪、灰度发布第三阶段才考虑多租户、数据权限这些高级特性。另一个体会是配置管理比代码管理更重要。底座项目里配置项非常多环境差异、租户差异、模型差异都体现在配置上。我见过因为配置写错导致生产事故的案例比代码 bug 还多。所以配置要有版本管理、要有变更审计、要有回滚机制重要配置变更要走审批。最后分享一个小技巧底座项目一定要有健康检查接口和就绪探针K8s 部署时这两个配置不对会导致流量打到还没准备好的实例上。健康检查返回应用状态就绪探针确认依赖数据库、Redis、注册中心都连通了再返回成功。这个细节看起来小但能避免很多启动期的诡异问题。后续如果要把这套底座往 AI 原生方向再推一步可以考虑把向量检索、RAG 编排、Agent 调度这些能力也沉淀进去让业务方接入 AI 的门槛进一步降低。不过那是另一个话题了先把当前这套跑稳再说。
QuickBlue AI应用底座：微服务架构设计与落地实践
1. 从一堆“重复造轮子”的痛说起QuickBlue 到底想解决什么问题做过几年企业级项目的人大概都有类似的经历新项目立项架构评审会上大家一致决定“上微服务”然后团队花了两三个月搭框架——注册中心选型、网关鉴权、链路追踪、分布式事务、多租户隔离、代码生成器、权限模型、日志审计、灰度发布……等这套底座跑通业务需求已经堆了一屏。更尴尬的是下一个项目来了这套东西又要重新搭一遍改改包名、换换配置本质上还是在做重复劳动。QuickBlue 就是冲着这个场景来的。它本质上是一个“AI 应用底座”你可以把它理解成一套已经搭好骨架、通好水电、装好门窗的微服务基座开发者进来之后主要精力放在业务逻辑和 AI 能力集成上而不是再去纠结 Spring Cloud 版本兼容、Sentinel 规则怎么持久化到 Redis 集群、JDK 21 的虚拟线程要不要开这些底层问题。它面向的是企业内部的平台团队、中台研发、以及那些想快速把 AI 能力落到业务系统里的技术负责人。为什么现在特别强调“AI 应用底座”这个概念因为过去一年我接触到的项目里十个有八个都在做“AI 加业务”的尝试——智能客服、文档问答、流程自动化、代码辅助、数据分析助手。但真正卡住他们的往往不是模型本身而是模型怎么和现有的用户体系、权限体系、数据权限、审计日志、限流熔断对接起来。一个 AI 接口调用要经过网关鉴权、租户隔离、Token 计费、敏感词过滤、结果缓存、异步任务队列这些全是传统微服务里已经解决过的问题。QuickBlue 的思路就是把这些通用能力沉淀到底座里AI 应用只需要关注 Prompt 编排、模型路由和业务语义。所以这篇文章我会从架构设计、核心模块、实操落地、踩坑排查几个角度把 QuickBlue 这类 AI 应用底座拆开讲清楚。不管你是正在选型的技术负责人还是准备基于它做二次开发的工程师都能拿到可以直接参考的东西。2. 架构设计拆解为什么是微服务而不是单体2.1 单体先行还是底座先行这是个路线问题很多团队一上来就问“我就做个 AI 问答有必要上微服务吗”这个问题没有标准答案但我的经验是看你的 AI 应用会不会长成企业级系统。如果只是一个内部工具几十个人用单体加个模块化分包完全够。但一旦涉及到多部门、多租户、多模型供应商、多业务线复用单体就会变成一坨——改一个限流规则要全量发版加一个模型供应商要动核心代码权限模型和业务逻辑耦合在一起测试环境永远和线上不一致。QuickBlue 选择微服务路线核心考量有三点。第一是能力复用AI 应用底座里的用户中心、权限中心、网关、文件服务、消息服务、任务调度这些模块在不同业务线之间是高度复用的拆成独立服务后可以独立演进、独立扩容。第二是故障隔离AI 调用本身是不稳定的模型响应慢、超时、限流是常态如果和核心业务在同一个进程里一个慢调用可能拖垮整个应用。第三是技术异构AI 相关的组件迭代非常快Python 生态、向量数据库、推理框架和 Java 业务系统的技术栈差异很大微服务边界天然适合做技术栈隔离。但我要泼一盆冷水微服务不是免费的。服务拆分带来的分布式事务、链路追踪、配置管理、服务发现、网络延迟这些都是实打实的成本。QuickBlue 的价值就在于它把这些成本提前消化掉了你拿到的是一个已经处理好这些问题的底座而不是一堆需要你自己组装的零件。2.2 分层架构与模块边界怎么划QuickBlue 的整体分层我习惯用四层来理解。最底层是基础设施层包括注册中心、配置中心、网关、缓存、消息队列、数据库连接池这些。往上一层是通用能力层也就是用户、权限、租户、字典、日志、文件、定时任务、代码生成这些每个系统都要用的东西。再往上是AI 能力层包括模型路由、Prompt 管理、向量检索、会话管理、Token 计量、内容安全。最上面是业务应用层也就是你真正要交付给用户的那部分。这个分层的关键在于依赖方向单一业务应用层依赖 AI 能力层和通用能力层AI 能力层依赖通用能力层通用能力层依赖基础设施层反向依赖是严格禁止的。我见过太多项目因为业务代码直接调用了基础设施层的 Redis 客户端导致后面想换缓存实现时牵一发动全身。QuickBlue 在模块边界上做了强约束每个服务只暴露 Feign 接口和 DTO内部实现对外不可见。模块拆分上我建议重点关注这几个边界认证授权独立成服务因为所有请求都要过它网关独立部署承担路由、限流、鉴权前置、日志采集AI 编排独立成服务因为它的扩缩容策略和普通业务服务完全不同文件与向量存储独立因为 AI 场景下文件处理和向量检索的 IO 特征很特殊。其他的像字典、日志、消息可以按团队规模决定是合并还是拆分小团队合并成“系统服务”也完全可行。2.3 JDK 21 与 Spring Cloud 版本选型的现实考量QuickBlue 基于 JDK 21这个选择在当下是合理的。JDK 21 是 LTS 版本虚拟线程Virtual Threads正式转正对于 AI 应用这种大量 IO 等待的场景虚拟线程能显著提升吞吐量。我实测过一个场景同样的模型调用接口用传统线程池在 200 并发时线程池打满开始排队换成虚拟线程后 2000 并发下响应时间依然平稳。当然虚拟线程不是银弹CPU 密集型任务用它反而可能因为调度开销略慢但在 AI 应用底座这种 IO 密集为主的场景里收益是明显的。Spring Cloud 版本上JDK 21 对应的比较稳的组合是 Spring Boot 3.2.x 加 Spring Cloud 2023.0.x。这里有个坑要提醒Spring Cloud Alibaba 的版本跟进往往比 Spring Cloud 官方慢半拍如果你要用 Nacos、Sentinel 这些组件一定要去官方版本对应表里核对不要凭感觉升级。我踩过一次坑Spring Boot 升到 3.2 之后 Sentinel 的适配包没跟上启动直接报类找不到排查了半天。提示版本选型不要追新要追“社区验证过的组合”。QuickBlue 这类底座项目稳定性优先级高于尝鲜。3. 核心模块实操从网关到 AI 编排的落地细节3.1 网关层鉴权、限流、日志一个都不能少网关是整个底座的入口QuickBlue 的网关承担了路由转发、JWT 校验、租户识别、接口限流、访问日志采集这几件事。实操上我建议把网关的职责控制在“横切关注点”不要往里塞业务逻辑。具体配置上路由规则建议走配置中心动态下发而不是写死在配置文件里这样新增服务时不用重启网关。限流这块Sentinel 是常见选择但规则持久化到 Redis 集群这一步很多人会漏。默认情况下 Sentinel 规则存在内存里服务重启就丢了生产环境必须做持久化。QuickBlue 的做法是规则写入 Redis网关启动时拉取同时监听配置变更事件实时刷新。这里有个细节Redis 集群模式下Sentinel 的规则 key 要设计好命名空间避免多环境互相覆盖。我一般用sentinel:{env}:{app}:{resource}这种格式。鉴权方面JWT 校验放在网关做前置拦截解析出用户 ID 和租户 ID 后通过请求头透传给下游服务。下游服务不再重复解析 Token只信任网关注入的请求头。但这里有个安全前提下游服务必须只允许网关访问不能直接暴露公网否则请求头可以被伪造。内网部署时用安全组或服务网格做隔离这是底线。3.2 认证授权与多租户隔离的实现要点多租户是 AI 应用底座里绕不开的话题。QuickBlue 采用的是共享数据库、共享表、租户字段隔离的方案也就是每张业务表都带一个tenant_id所有查询自动拼接租户条件。这个方案的好处是成本低、运维简单缺点是隔离性弱一旦代码里漏了租户条件就会串数据。实现上我推荐用 MyBatis 的拦截器做统一处理在 SQL 执行前自动注入tenant_id条件。但要注意几个例外场景系统表、字典表、全局配置表不应该被租户隔离需要在拦截器里做白名单排除。另外跨租户的统计查询要显式声明忽略租户条件不能靠拦截器猜。权限模型上QuickBlue 用的是 RBAC 加数据权限的组合。RBAC 管“能不能访问这个菜单/接口”数据权限管“能看到哪些数据”。数据权限的实现我见过很多种比较稳的是在 SQL 层面做行级过滤比如按部门、按创建人、按自定义范围。这里有个经验数据权限规则不要做得太灵活越灵活越容易出 bug覆盖 80% 的常见场景就够了剩下的特殊需求用自定义 SQL 解决。3.3 AI 编排服务模型路由与 Prompt 管理这是 QuickBlue 区别于传统微服务底座的核心模块。AI 编排服务要解决几个问题多个模型供应商怎么统一调用、Prompt 怎么版本化管理、会话上下文怎么维护、Token 怎么计量、结果怎么缓存。模型路由上我建议抽象一层统一的ModelClient接口不同供应商各家大模型 API实现各自的适配器。路由策略支持按模型名、按租户、按场景、按成本优先级来选。这里的关键是降级策略主模型超时或限流时自动切到备用模型保证业务不中断。降级要记录日志方便后续分析。Prompt 管理我强烈建议做成配置化而不是硬编码在代码里。每个 Prompt 有唯一标识、版本号、模板内容、变量定义、适用模型。业务代码只引用 Prompt 标识具体内容从配置中心或数据库读取。这样做的好处是运营人员可以调 Prompt 而不用发版A/B 测试也方便。我见过一个团队把 Prompt 写死在 Java 代码里改一个标点都要走完整发布流程效率极低。会话管理上短期上下文放 Redis设置合理的过期时间长期会话历史落库支持按用户、按会话查询。Token 计量要在每次模型调用后累加按租户和用户维度统计这是后续计费和配额控制的基础。3.4 数据通信与缓存Redis 集群在底座里的角色Redis 在 QuickBlue 里承担了缓存、会话、限流计数、分布式锁、规则存储等多重角色。集群模式下有几个实操要点。第一是key 设计要带业务前缀避免不同模块互相干扰比如auth:token:*、ai:session:*、sentinel:rule:*。第二是大 key 和热 key 要提前预防会话数据如果单个 key 存了几百 KB集群迁移时会很痛苦建议拆分存储。第三是分布式锁要用 Redisson 这类成熟组件不要自己用 SETNX 手搓锁续期、可重入、锁释放这些细节自己实现很容易出问题。缓存一致性上我一般用“先更新数据库再删除缓存”的策略配合延迟双删处理并发场景。但说实话强一致性在分布式缓存里很难做到完美业务上要能接受短暂不一致。如果某个场景绝对不能容忍脏读那就别用缓存直接查库。4. 从零搭建到跑通一个可复现的落地流程4.1 环境准备与依赖清单假设你要基于 QuickBlue 的思路搭一套自己的底座环境上我建议这样准备。JDK 21 装好Maven 3.9 以上MySQL 8.0Redis 7.x集群模式至少 3 主 3 从Nacos 2.x 做注册和配置中心Sentinel 做限流。如果要用消息队列RocketMQ 或 Kafka 都行看团队熟悉度。依赖版本上Spring Boot 3.2.x、Spring Cloud 2023.0.x、Spring Cloud Alibaba 2023.0.x.x这几个要对齐。MyBatis-Plus 用 3.5.xRedisson 用 3.2x.x。这些版本组合我实测过兼容性没问题。注意Nacos 2.x 默认开启了 gRPC 通信如果服务器有防火墙策略要提前放行 9848 和 9849 端口否则服务注册会失败而且报错信息很不直观容易误判为网络问题。4.2 服务拆分与启动顺序服务拆分我建议按这个顺序落地先起注册中心和配置中心再起网关然后是认证授权服务接着是通用能力服务用户、权限、字典、日志最后是 AI 编排服务和业务服务。启动顺序有依赖关系认证服务依赖用户服务网关依赖认证服务做 Token 校验所以不能乱。每个服务的配置文件建议分三份application.yml放通用配置application-{env}.yml放环境相关配置敏感信息数据库密码、模型 API Key走配置中心的加密配置或环境变量不要明文写在文件里。我见过把 API Key 提交到代码仓库的这是大忌。4.3 关键配置示例与参数说明网关的 Sentinel 规则持久化配置核心是配置数据源指向 Redis。大致思路是定义一个RedisDataSource实现ReadableDataSource接口启动时从 Redis 读取规则同时注册监听器。规则内容用 JSON 存储结构包含资源名、限流阈值、流控模式、流控效果。虚拟线程的开启很简单Spring Boot 3.2 里加一行配置spring.threads.virtual.enabledtrue即可。但要注意虚拟线程和某些依赖 ThreadLocal 的组件可能不兼容比如老版本的分布式追踪 SDK。开启后要重点观察日志和链路追踪是否正常。数据库连接池用 HikariCP连接数不是越大越好。我一般按CPU 核数 * 2 磁盘数估算再结合压测调整。AI 编排服务因为大量等待模型响应连接数可以适当调大但要注意数据库本身的连接上限。4.4 跑通第一个 AI 接口的完整链路从请求进来到模型返回完整链路是这样的客户端请求打到网关网关校验 JWT、识别租户、限流检查通过后转发到 AI 编排服务。编排服务根据请求参数选择 Prompt 模板组装上下文调用模型适配器。适配器根据路由策略选择模型供应商发起调用拿到结果后做内容安全过滤、Token 计量、结果缓存最后返回给网关网关记录访问日志后返回客户端。这条链路上每个环节都可能出问题所以全链路追踪是必须的。我建议用 TraceId 贯穿整个请求网关生成通过请求头透传每个服务在日志里打印 TraceId。排查问题时一个 TraceId 就能串起所有服务的日志效率提升非常明显。5. 常见问题与排查技巧实录5.1 服务注册与配置拉取失败这是新手最常遇到的问题。现象是服务启动后注册不上或者配置拉取超时。排查顺序我一般这样走先确认 Nacos 服务本身是否正常浏览器访问控制台能不能打开再确认网络连通性telnet 端口通不通然后看应用日志里的具体报错是连接超时还是认证失败最后检查命名空间和分组配置是否匹配。有个隐蔽的坑Nacos 2.x 的 gRPC 端口如果没放行HTTP 端口能通但注册会失败报错信息可能是“连接被拒绝”或“超时”很容易误判。解决办法就是提前确认 9848、9849 端口开放。5.2 限流规则不生效或重启丢失Sentinel 规则不生效先确认规则有没有成功推送到客户端。可以在 Sentinel 控制台看规则列表也可以看应用日志里有没有规则加载记录。如果规则在控制台有但应用不生效多半是数据源配置有问题或者规则格式不对。重启丢失就是持久化没做。默认内存存储重启必丢。解决办法就是接 Redis 或 Nacos 做持久化数据源。这里要注意持久化数据源的优先级要高于本地配置否则会被覆盖。5.3 多租户数据串读的排查思路数据串读是最危险的问题一旦发生就是数据泄露。排查时先看 SQL 日志确认租户条件有没有拼上。如果没拼上检查 MyBatis 拦截器是否生效是不是被其他拦截器覆盖了或者该表在排除名单里。如果拼上了还串读检查租户 ID 的来源是否正确是不是从请求头取的时候取错了。预防上我建议在测试环境专门造多租户数据做交叉验证每个接口都要测。另外代码评审时重点看手写 SQL 的地方自动生成的 SQL 一般没问题手写的最容易漏。5.4 模型调用超时与降级处理模型调用超时是 AI 应用的常态。处理上分三层第一层是超时设置不同模型响应时间差异很大超时时间要按模型配置不能一刀切第二层是重试但重试要谨慎非幂等操作不能重试而且重试次数不宜多否则会放大下游压力第三层是降级主模型不可用时切备用模型或者返回缓存结果或者给用户友好提示。我踩过的坑是重试没有做退避失败后立刻重试结果把下游打得更惨。正确做法是加指数退避比如 1 秒、2 秒、4 秒这样递增。5.5 常见问题速查表问题现象可能原因排查方向解决建议服务注册不上端口未放行、命名空间错误检查 gRPC 端口、控制台配置放行 9848/9849核对命名空间限流不生效规则未推送、数据源未配置看控制台规则、应用日志配置持久化数据源数据串读租户条件未拼接看 SQL 日志、拦截器配置检查拦截器白名单和租户来源模型超时超时设置过短、下游限流看调用日志、监控指标按模型配置超时加退避重试虚拟线程异常组件不兼容 ThreadLocal看启动日志、追踪链路升级组件或关闭虚拟线程6. 我在这类底座项目上的一些实操体会做 AI 应用底座这几年我最大的体会是底座的复杂度要匹配团队的成熟度。QuickBlue 这类项目功能很全但如果团队只有三五个人硬上全套微服务反而是负担。我的建议是分阶段来第一阶段先把网关、认证、AI 编排这三个核心跑通其他模块按需引入第二阶段再补全监控、链路追踪、灰度发布第三阶段才考虑多租户、数据权限这些高级特性。另一个体会是配置管理比代码管理更重要。底座项目里配置项非常多环境差异、租户差异、模型差异都体现在配置上。我见过因为配置写错导致生产事故的案例比代码 bug 还多。所以配置要有版本管理、要有变更审计、要有回滚机制重要配置变更要走审批。最后分享一个小技巧底座项目一定要有健康检查接口和就绪探针K8s 部署时这两个配置不对会导致流量打到还没准备好的实例上。健康检查返回应用状态就绪探针确认依赖数据库、Redis、注册中心都连通了再返回成功。这个细节看起来小但能避免很多启动期的诡异问题。后续如果要把这套底座往 AI 原生方向再推一步可以考虑把向量检索、RAG 编排、Agent 调度这些能力也沉淀进去让业务方接入 AI 的门槛进一步降低。不过那是另一个话题了先把当前这套跑稳再说。