企业官网建设流程全解析

1. 从一次深夜救火说起：为什么“AI 应用底座”不是伪命题

去年冬天，一个做智能客服的朋友半夜给我打电话，说他们的 AI 问答服务又挂了。不是模型挂了，是模型前面那层业务系统挂了——用户会话状态丢了，知识库检索接口超时，限流规则没生效导致一个爬虫把整个问答集群打满。他原话是：“我们花了三个月调模型，结果死在了一堆 CRUD 接口上。”

这个场景我太熟了。过去两年，几乎每一家说自己“在做 AI 应用”的团队，都会经历这个阶段：模型能力很强，Demo 很惊艳，但一旦要接入真实业务、真实用户、真实并发，整个系统就开始露怯。问题从来不在模型本身，而在于模型下面那层“地基”没人认真搭。

QuickBlue 就是冲着这层地基来的。你可以把它理解成一个AI 应用底座——它不训练模型，也不做具体的业务功能，它解决的是“当你要把 AI 能力塞进一个真实的企业系统时，那些绕不开的脏活累活”。比如统一鉴权、会话管理、多模型路由、限流熔断、知识库检索编排、日志追踪、灰度发布。这些东西单拎出来都不难，但要把它们组合成一个稳定、可扩展、能扛住生产流量的底座，工作量远超大多数团队的预期。

这篇文章适合三类人看：第一类是在企业里负责 AI 落地、被各种“模型接进去就完事”的说法坑过的技术负责人；第二类是想了解 AI 应用后端架构到底长什么样的后端工程师；第三类是做微服务架构、正在考虑怎么把 AI 能力作为一类标准服务纳入现有体系的架构师。我会从 QuickBlue 的设计思路讲起，拆到微服务拆分、Spring Cloud 组件选型、JDK 21 的适配细节，再给出一套可参考的实操路径和踩坑记录。不吹概念，只讲我实际验证过的东西。

2. QuickBlue 到底解决了什么问题：AI 应用底座的定位拆解

2.1 先搞清楚“底座”和“平台”的区别

很多人一听到“底座”就联想到“平台”，觉得又是一个大而全的东西。这两个词在企业软件语境里差别很大。平台通常面向最终用户，提供可视化界面、开箱即用的功能，比如一个低代码平台、一个数据分析平台。底座面向的是开发者和系统本身，它不直接产生业务价值，但没有它，上面的业务就搭不稳。

打个比方：平台像是商场里已经装修好的店铺，你拎包入驻就能卖货；底座像是商场的地基、水电、消防、承重结构。QuickBlue 属于后者。它提供的是一组标准化的基础能力，让 AI 应用开发者不用每次都从零实现鉴权、限流、会话、路由这些东西。

这个定位决定了 QuickBlue 的几个特征：第一，它是无业务侵入的，不会规定你的 AI 应用必须长什么样；第二，它是可组合的，你需要哪个能力就接哪个；第三，它是面向生产的，所有设计都以稳定性和可观测性为优先，而不是 Demo 跑通就行。

2.2 AI 应用相比传统应用，多了哪些“底座级”需求

传统微服务该有的东西，AI 应用一样都不能少：服务注册发现、配置中心、网关、熔断限流、链路追踪。但 AI 应用额外多了几类需求，这些是普通业务系统不会重点考虑的。

第一类是模型调用的不确定性。传统接口的响应时间基本可控，但大模型推理的延迟波动极大，同一个请求可能 800ms 返回，也可能 8 秒才返回。这就要求底座在超时控制、重试策略、降级方案上做特殊处理——不能简单套用传统的固定超时。

第二类是会话与上下文管理。AI 对话是有状态的，多轮对话需要维护上下文窗口。这个状态存在哪里、怎么过期、怎么在多实例之间共享，都是底座要解决的问题。用本地内存存？多实例部署就废了。用 Redis 存？那序列化格式、过期策略、并发读写又得设计。

第三类是多模型路由与成本控制。企业往往同时接入了多个模型供应商，不同模型的成本、能力、可用性都不一样。底座需要提供统一的路由层，支持按业务场景、按成本预算、按可用性动态选择模型，还要能统计每个业务线消耗了多少 token。

第四类是知识库检索编排。RAG 架构里，检索环节涉及向量库查询、关键词召回、重排序等多个步骤，这些步骤的编排、超时控制、结果合并，都是底座层面的工作。

QuickBlue 的价值就在于，它把这四类需求都抽象成了标准组件，你不用每个项目重新造一遍轮子。

2.3 为什么企业自研底座往往失败

我见过不少团队尝试自研 AI 应用底座，最后要么半途而废，要么做出来没人用。原因通常有三个。

一是低估了非功能性需求的复杂度。写一个能跑的鉴权拦截器可能只要半天，但要写出能扛住每秒几千次并发、支持动态规则更新、有完整审计日志的鉴权组件，工作量是前者的几十倍。很多团队按“能跑就行”的标准做底座，结果上线后到处是坑。

二是没有考虑多团队协作。底座是给多个业务团队用的，接口设计、版本管理、向后兼容、文档维护，这些“软”工作往往被忽略。等三个业务团队都接进来之后，改一个接口就要协调三方，底座反而成了瓶颈。

三是缺乏生产验证。底座的问题往往在高并发、异常场景下才暴露。自研底座如果没有经过真实流量打磨，很容易在关键时刻掉链子。QuickBlue 这类经过多个项目验证的底座，价值就在于它已经踩过大部分坑。

3. 微服务拆分：QuickBlue 的骨架是怎么搭的

3.1 拆分原则：按“能力边界”而不是“技术分层”

很多团队做微服务拆分时习惯按技术分层拆：网关一层、业务一层、数据一层。这种拆法在 AI 应用场景下会出问题，因为 AI 应用的很多能力是横跨多层的。比如“模型调用”这个能力，它既涉及网络通信，又涉及业务路由，还涉及数据统计，硬按技术层拆会导致一个完整能力被切碎在多个服务里。

QuickBlue 的拆分思路是按能力边界拆。我把它核心的服务划分整理成下面这张表，你可以对照自己的项目看看是否合理。

这个拆法的好处是，每个服务的边界清晰，团队可以并行开发。比如模型路由服务由算法工程团队维护，会话管理服务由后端团队维护，互不干扰。

3.2 服务间通信：同步还是异步，这是个问题

AI 应用的通信模式比传统业务复杂。传统业务大多是“请求-响应”同步模式，但 AI 应用里，一次用户请求可能触发多个异步任务：模型推理、知识检索、日志上报、计费统计。如果全部用同步调用，一个环节慢就拖垮整条链路。

QuickBlue 的做法是核心链路同步、辅助链路异步。用户请求进来后，鉴权、会话读取、模型路由这几个环节是同步的，因为后续步骤依赖它们的结果。而日志上报、计费统计、质量评估这些环节走异步消息，不阻塞主流程。

具体实现上，同步通信用 Spring Cloud OpenFeign，异步通信用消息队列。这里有个细节值得说：Feign 的默认超时时间在 AI 场景下往往不够用，因为模型推理可能耗时较长。我的经验是把连接超时设为 2 秒，读取超时根据业务场景单独配置，对话类接口设 30 秒，批处理类接口设 120 秒，并且一定要配合熔断器使用，避免线程池被慢请求占满。

3.3 配置管理：为什么 AI 应用的配置比普通应用更“活”

AI 应用的配置变化频率远高于传统应用。模型版本会更新、路由权重会调整、限流阈值会随业务波动、提示词模板会迭代。如果每次改配置都要重启服务，运维成本会很高。

QuickBlue 用配置中心统一管理这些动态配置，并且做了配置分级：全局配置（如模型供应商列表）、服务级配置（如本服务的限流阈值）、实例级配置（如本实例的灰度标记）。分级的好处是，改全局配置影响所有服务，改服务级配置只影响特定服务，避免误操作扩大影响面。

注意：动态配置一定要有回滚机制和变更审计。我踩过的坑是，某次调整路由权重时手滑多打了一个零，导致所有流量打到最贵的模型上，半小时烧掉了一笔不小的费用。后来我们强制要求所有配置变更必须走审批流，并且支持一键回滚。

4. Spring Cloud 组件选型：哪些是刚需，哪些可以省

4.1 注册中心与配置中心：Nacos 还是 Consul

Spring Cloud 生态里，注册中心和配置中心的可选项不少。QuickBlue 选的是 Nacos，理由有三个：一是它同时提供注册和配置两个功能，减少组件数量；二是它对 Spring Cloud Alibaba 生态支持成熟，文档和社区案例多；三是它的控制台对运维友好，排查问题方便。

Consul 也是不错的选择，尤其在多数据中心场景下更有优势。但如果你的部署环境相对单一，Nacos 的性价比更高。这里的关键不是选哪个，而是不要同时用两套注册中心。我见过有的项目历史遗留，一部分服务注册在 Eureka，一部分在 Nacos，结果服务发现经常出问题，排查起来极其痛苦。

4.2 网关选型：Spring Cloud Gateway 的实战配置

网关是 AI 应用底座的咽喉。QuickBlue 用的是 Spring Cloud Gateway，核心原因是它基于响应式编程模型，在高并发场景下资源利用率比传统的 Servlet 网关更好。

网关层我重点配置了三块：路由规则、过滤器链、限流。路由规则按业务线划分，比如/api/chat/**走对话服务，/api/knowledge/**走知识检索服务。过滤器链里，鉴权过滤器排在最前面，然后是日志过滤器、限流过滤器。限流用的是 Redis 加令牌桶算法，因为网关是多实例部署，必须用分布式限流。

spring: cloud: gateway: routes: - id: chat-service uri: lb://chat-service predicates: - Path=/api/chat/** filters: - name: RequestRateLimiter args: redis-rate-limiter.replenishRate: 100 redis-rate-limiter.burstCapacity: 200 key-resolver: "#{@userKeyResolver}"

上面这段配置的意思是：对话服务每秒补充 100 个令牌，桶容量 200，按用户维度限流。replenishRate和burstCapacity这两个参数需要根据实际压测结果调整，不能拍脑袋定。我的经验是先设一个保守值，上线后观察 Redis 里的令牌消耗曲线，再逐步调优。

4.3 熔断限流：Sentinel 的规则持久化是个坑

Sentinel 是 Spring Cloud Alibaba 体系里做熔断限流的标配。但很多人用 Sentinel 时忽略了一个问题：默认规则存在内存里，服务重启就丢了。生产环境必须做规则持久化。

QuickBlue 的做法是把 Sentinel 规则持久化到 Nacos，服务启动时从 Nacos 拉取规则，规则变更时通过 Nacos 推送。这样规则不会因为重启丢失，也支持动态调整。配置上需要引入sentinel-datasource-nacos依赖，然后在配置文件里指定 Nacos 的数据源。

spring: cloud: sentinel: datasource: flow: nacos: server-addr: ${NACOS_ADDR} dataId: ${spring.application.name}-flow-rules groupId: SENTINEL_GROUP rule-type: flow

提示：Sentinel 的流控规则和熔断规则要分开配置。流控是限制入口流量，熔断是当依赖服务异常时快速失败。两者作用点不同，不要混在一起调。

4.4 链路追踪：AI 应用的追踪比普通应用更难

普通微服务的链路追踪相对简单，一个请求经过几个服务，串起来就行。但 AI 应用的链路里多了模型调用这个“黑盒”，模型内部的耗时、token 消耗、返回质量，都需要额外埋点。

QuickBlue 在标准链路追踪的基础上，增加了模型调用维度的埋点：每次模型调用记录模型名称、输入 token 数、输出 token 数、首 token 延迟、总延迟。这些数据汇总后，可以分析出哪个模型在哪个场景下性价比最高。这个能力在成本优化阶段非常有用，我靠它发现某个业务线用了一个贵三倍的模型，但效果提升不到 5%，换掉之后成本直接降了一半。

5. JDK 21 适配：新特性用得好是红利，用不好是坑

5.1 为什么 AI 应用底座值得升级到 JDK 21

JDK 21 是 LTS 版本，对 AI 应用底座来说有几个实打实的收益。虚拟线程是最值得关注的一个。AI 应用里大量操作是 IO 密集型的——调模型、查向量库、读写 Redis，这些操作在传统线程模型下会阻塞平台线程。虚拟线程让每个请求可以用一个虚拟线程处理，阻塞时自动让出底层载体线程，吞吐量提升明显。

我做过一个对比测试：同样的模型调用接口，用传统线程池，200 并发时响应时间开始明显上升；换成虚拟线程后，500 并发下响应时间仍然平稳。当然，虚拟线程不是银弹，它解决的是 IO 阻塞问题，CPU 密集型任务该用线程池还是用线程池。

另一个收益是记录模式（Record Patterns）和模式匹配，让处理复杂的请求响应结构时代码更简洁。AI 应用的请求体往往嵌套很深，用模式匹配解构比一层层 get 清爽很多。

5.2 虚拟线程在网关和业务服务里的正确用法

虚拟线程用起来很简单，但用对不容易。最常见的错误是把虚拟线程和线程池混用。虚拟线程的设计初衷是“一个任务一个虚拟线程”，不需要池化。如果你把虚拟线程放进线程池，就失去了它的意义。

在 Spring Boot 3.2 及以上版本里，开启虚拟线程只需要一个配置：

spring: threads: virtual: enabled: true

开启后，Tomcat 的请求处理会自动使用虚拟线程。但要注意，如果你在代码里手动创建了线程池，那些任务还是跑在平台线程上。我的做法是，把业务代码里的Executors.newFixedThreadPool逐步替换成Executors.newVirtualThreadPerTaskExecutor，让所有 IO 密集型任务都享受虚拟线程的红利。

注意：虚拟线程下，ThreadLocal的使用要格外小心。虚拟线程数量可能非常多，如果每个线程都存一份 ThreadLocal 数据，内存占用会飙升。AI 应用里常见的用户上下文、追踪 ID，建议改用ScopedValue（JDK 21 预览特性）或者显式传参。

5.3 升级 JDK 21 时容易忽略的兼容性问题

从 JDK 8 或 11 升到 21，大部分代码不用改，但有几个地方容易出问题。一是反射相关的库，一些老版本的序列化库、代理库在 JDK 21 下会报模块访问错误，需要升级到新版本。二是GC 行为变化，JDK 21 默认的 G1 在参数调优上和旧版本有差异，升级后要重新观察 GC 日志，必要时调整MaxGCPauseMillis。三是依赖的 Spring Cloud 版本，JDK 21 需要 Spring Boot 3.2 及以上，Spring Cloud 2023.0 及以上，版本不匹配会出现各种奇怪的启动错误。

我的建议是，升级前先在测试环境跑一轮完整的回归测试，重点观察启动日志里的警告信息和运行时的 GC 表现。不要直接在生产环境升级，哪怕你觉得“只是换个 JDK 而已”。

6. 实操路径：从零搭一个最小可用的 AI 应用底座

6.1 环境准备与依赖版本锁定

搭底座最怕版本冲突。我建议在动手之前，先把版本矩阵定下来，并且写进父 POM 的dependencyManagement里，所有子模块统一继承。下面是我验证过的一套组合：

版本锁定之后，创建一个父工程，把公共依赖、插件配置、编码规范都放在父 POM 里。子模块只声明自己需要的依赖，不写版本号。这样做的好处是，将来升级某个组件时，只改父 POM 一处。

6.2 网关服务的核心配置与启动验证

网关是第一个要跑起来的服务。创建gateway-service模块，引入spring-cloud-starter-gateway和spring-cloud-starter-alibaba-nacos-discovery。启动类上加@EnableDiscoveryClient。

配置文件里重点配三块：Nacos 地址、路由规则、跨域。跨域这块 AI 应用经常遇到，因为前端可能部署在不同域名下。Spring Cloud Gateway 的跨域配置和传统 Spring MVC 不一样，要用CorsWebFilter或者配置文件里的globalcors。

启动后，先验证网关能否从 Nacos 拉到服务列表，再验证路由规则是否生效。我的习惯是用curl直接打网关端口，看请求有没有被正确转发。这一步看起来简单，但很多问题（比如路由不生效、过滤器顺序错乱）都是在这一步暴露的。

6.3 会话管理服务的存储设计

会话管理服务的核心是存储设计。我选的是 Redis 加本地缓存的二级结构：热点会话放本地缓存，减少 Redis 访问；全量会话放 Redis，保证多实例共享。

Redis 的 key 设计要包含租户 ID 和会话 ID，比如session:{tenantId}:{sessionId}。value 用 Hash 结构存，字段包括上下文消息列表、最后活跃时间、模型偏好等。过期时间设 30 分钟，每次读写时刷新。这里有个细节：上下文消息列表不能无限增长，要设一个上限，超过后按时间淘汰最老的消息。我设的上限是 20 轮对话，超过后把最早的两轮压缩成摘要。

public void appendMessage(String tenantId, String sessionId, Message message) { String key = "session:" + tenantId + ":" + sessionId; redisTemplate.opsForHash().put(key, "lastActive", System.currentTimeMillis()); redisTemplate.opsForList().rightPush(key + ":messages", message); Long size = redisTemplate.opsForList().size(key + ":messages"); if (size != null && size > MAX_MESSAGES) { redisTemplate.opsForList().trim(key + ":messages", size - MAX_MESSAGES, -1); } redisTemplate.expire(key, Duration.ofMinutes(30)); }

上面这段代码是简化版，实际生产里还要考虑并发写入的原子性，建议用 Lua 脚本把多个操作打包。

6.4 模型路由服务的策略实现

模型路由服务是 QuickBlue 里最能体现“AI 应用底座”特色的部分。它的核心是一个策略链：先按业务场景过滤可用模型，再按成本预算排序，最后按当前负载做负载均衡。

策略链的每个环节都可以配置。比如某个业务场景要求“必须用支持长上下文的模型”，那就在过滤环节加上上下文长度条件。某个业务线有成本上限，那就在排序环节按单价升序排。负载均衡环节我用了加权轮询，权重根据模型的实时健康度动态调整——连续失败的模型权重降低，恢复后逐步回升。

public ModelRoute selectRoute(RouteContext context) { List<ModelCandidate> candidates = filterByScene(context.getScene()); candidates = filterByCapability(candidates, context.getRequiredCapabilities()); candidates = sortByCost(candidates, context.getCostBudget()); return loadBalance(candidates); }

这个策略链的好处是，每个环节职责单一，新增策略时不用改其他环节。比如后来要加一个“按地域就近选择模型”的策略，只需要在过滤环节加一个条件，不影响排序和负载均衡。

7. 常见问题与排查技巧实录

7.1 服务注册上了但调不通，先查这三处

这是最高频的问题。服务在 Nacos 控制台能看到，但 Feign 调用报“无可用实例”。排查顺序是：第一，看调用方和服务提供方是否在同一个命名空间和分组，Nacos 默认按命名空间隔离，跨命名空间发现不了；第二，看服务提供方的健康检查是否通过，有时候服务注册了但健康检查失败，Nacos 会把它标记为不健康；第三，看网络是否互通，尤其是容器化部署时，Pod 之间的网络策略可能挡住了端口。

我踩过最坑的一次是，服务提供方注册的是容器内网 IP，但调用方在另一个网络里，根本访问不到。后来统一改成注册宿主机 IP 才解决。这个问题的根因是 Nacos 客户端默认取的是网卡 IP，多网卡环境下可能取错，需要在配置里显式指定。

7.2 限流规则不生效的几种典型原因

Sentinel 限流不生效，常见原因有四个。一是规则没持久化，服务重启后规则丢了；二是资源名写错了，Sentinel 是按资源名匹配的，资源名对不上规则就不生效；三是规则类型选错了，流控规则和熔断规则的作用点不同；四是 Sentinel 的切面没生效，比如用了异步调用，Sentinel 的默认切面拦不住。

排查时我习惯先看 Sentinel 控制台的“簇点链路”，确认资源有没有被识别到。如果资源列表是空的，说明切面没生效，检查依赖和配置。如果资源有但规则不生效，检查规则配置的资源名和实际资源名是否一致。

7.3 虚拟线程下 ThreadLocal 丢失的排查

开启虚拟线程后，如果发现用户上下文丢失，大概率是 ThreadLocal 的问题。虚拟线程在阻塞时会让出载体线程，如果代码里依赖 ThreadLocal 传递上下文，切换载体线程后上下文就丢了。

解决办法有两个：一是改用ScopedValue，它是 JDK 21 引入的不可变上下文传递机制，天然支持虚拟线程；二是显式传参，把上下文作为方法参数传递，不依赖 ThreadLocal。我倾向于第二种，虽然代码稍微啰嗦，但最不容易出问题。

7.4 常见问题速查表

8. 我在实际项目里踩过的几个坑

第一个坑是过度拆分。一开始我把模型路由拆成了“路由决策”和“路由执行”两个服务，结果发现两者耦合太紧，每次改路由策略都要同时改两个服务，反而降低了效率。后来合并成一个服务，边界反而更清晰。微服务拆分不是越细越好，拆到“一个服务对应一个完整能力”就够了。

第二个坑是忽略冷启动。AI 应用底座的服务启动时，要连接 Nacos、Redis、消息队列，还要预热模型路由的缓存。如果没做预热，服务刚启动那几分钟响应特别慢。后来我在启动类里加了预热逻辑，服务就绪前先把常用配置和路由规则加载到本地缓存。

第三个坑是日志量失控。AI 应用的日志比普通应用多得多，每次模型调用都要记录输入输出。如果不做采样和分级，日志文件几天就撑爆磁盘。我的做法是：错误日志全量记录，正常调用按 1% 采样，调试日志只在特定条件下开启。这样既保留了排查问题的能力，又控制了存储成本。

第四个坑是成本监控缺失。前面提过，我因为配置错误烧了一笔钱。后来我在模型路由服务里加了实时成本统计，每个业务线、每个模型的 token 消耗和费用都实时上报，超过阈值就告警。这个功能后来成了我们优化成本的主要依据。

9. 这套底座后续还能怎么扩展

QuickBlue 作为 AI 应用底座，本身是一个持续演进的东西。我目前在做的一个扩展方向是多模态能力的统一接入。现在底座主要处理文本模型，但图片生成、语音识别这些能力也在快速进入企业场景。思路是把多模态能力也抽象成“模型”的一种，复用现有的路由、限流、计费体系，只是请求和响应的数据结构不同。

另一个方向是提示词版本管理。提示词是 AI 应用的核心资产之一，但很多团队还在用硬编码或者配置文件管理，改一次要发一次版。我在尝试把提示词也纳入配置中心，支持版本管理、灰度发布、A/B 测试。这样产品经理改提示词不用等开发排期，效率提升明显。

还有一个方向是质量评估的自动化。现在模型返回质量主要靠人工抽检，成本高且覆盖不全。我在探索用一个小模型做自动评估，对每次返回打分，低分样本自动进入人工复核队列。这个能力如果做成了，对业务方的价值会很大。

最后分享一个小技巧：搭底座的时候，不要想着一次做全。先把最核心的鉴权、会话、路由三个能力做扎实，让业务能跑起来，然后再根据实际需求逐步扩展。我见过太多团队想一口气把底座做完美，结果半年过去了业务还没上线。底座的迭代节奏应该跟着业务走，业务需要什么就补什么，这样每一步都有验证，不会做无用功。