企业官网建设流程全解析

1. 从一堆“重复造轮子”的痛说起：QuickBlue 到底想解决什么

如果你带过三五个企业级项目，大概率经历过这样的场景：新项目立项，架构评审会上大家拍板用 Spring Cloud 全家桶，注册中心、配置中心、网关、鉴权、限流、日志、监控、文件服务、消息队列……一张微服务架构图铺满整块白板。然后团队开始分工，有人搭 Nacos，有人写网关过滤器，有人封装统一返回体，有人对接 Redis 集群，有人折腾 Sentinel 的规则持久化。三个月过去，业务代码没写几行，基础设施倒是攒了一大堆。

更麻烦的是，下一个项目来了，这套东西又要重来一遍。上一个项目里踩过的坑——比如 Sentinel 规则重启就丢、网关鉴权漏了白名单、Redis 集群模式下序列化踩雷——新团队大概率还要再踩一次。这就是典型的“每个团队都在重复造轮子，而且造出来的轮子质量参差不齐”。

QuickBlue 这个项目，本质上就是冲着这个痛点去的。它想做的事情，用一句话概括：把企业做 AI 应用时反复要用到的那套底层能力，提前沉淀成一个开箱即用的“AI 应用底座”。你不需要从零搭微服务骨架，不需要重新设计权限模型，不需要再纠结大模型调用怎么统一管理、会话上下文怎么存、多租户怎么隔离，底座里已经有了，你只管往上写业务。

这里要先厘清一个概念，很多人一听“AI 应用底座”就以为是某个大模型或者某个 Agent 框架，其实不是。它更像是一栋楼的地基和承重结构，而不是装修风格。地基决定了你这栋楼能盖多高、能住多少人、能不能加层。QuickBlue 提供的正是这套承重结构：微服务治理、统一认证鉴权、数据访问层、缓存层、AI 能力接入层、可观测性等等。至于你在这上面盖的是智能客服、知识库问答、还是业务流程自动化，那是业务层的事。

那为什么偏偏是现在，企业开始需要一个专门的“AI 应用底座”？我的观察是三个因素叠加。第一，AI 应用从 Demo 走向生产，Demo 阶段一个 Flask 脚本加个 API Key 就能跑，生产阶段要考虑并发、限流、降级、审计、成本核算，这些全是工程问题。第二，企业内部往往不止一个 AI 应用，多个应用之间要共享用户体系、共享知识库、共享模型配额，没有统一底座就会变成一堆孤岛。第三，微服务这套东西本身已经足够成熟，Spring Cloud、Nacos、Sentinel、Redis 这些组件经过多年验证，把它们和 AI 能力做一次工程化整合，时机到了。

QuickBlue 面向的读者，我判断主要是三类人：一是企业里的架构师和技术负责人，需要评估要不要引入这么一套底座；二是中高级后端开发，想理解一个成熟微服务底座是怎么组织的；三是正在做 AI 应用落地、被基础设施拖慢节奏的团队。不管你是哪一类，接下来的内容我都会尽量把“为什么这么设计”讲透，而不是只丢一堆配置。

2. 拆开看骨架：QuickBlue 的核心模块与选型逻辑

2.1 为什么是 Spring Cloud 而不是别的

先回答一个被问得最多的问题：都 2025 年了，为什么还选 Spring Cloud，不用 Service Mesh 或者更轻量的方案？

我的判断很直接：企业级落地的第一约束从来不是技术先进性，而是团队能不能 hold 住、招不招得到人、出问题能不能快速定位。Service Mesh 确实优雅，把服务治理下沉到 Sidecar，业务代码零侵入。但它带来的运维复杂度是实打实的——你得维护一套控制面，得懂 Envoy 的配置，出了问题排查链路比 Spring Cloud 长得多。对于一个几十人规模、以业务交付为主的团队，这套东西的投入产出比并不划算。

Spring Cloud 的优势在于生态完整、资料丰富、人才储备厚。Nacos 做注册和配置，Sentinel 做流量防护，Gateway 做统一入口，OpenFeign 做服务调用，这套组合在国内的落地案例多到数不清。QuickBlue 选择它，本质上是选择了一条“确定性最高”的路。你团队里随便一个三年经验的 Java 开发，给他一周时间就能上手，这在企业环境里是巨大的优势。

再说 JDK 21。这个选择我觉得挺关键。JDK 21 是 LTS 版本，虚拟线程（Virtual Threads）正式转正，这对 AI 应用特别有意义。AI 应用的一个典型特征是大量 IO 等待——等模型返回、等向量库检索、等外部 API。传统线程池模式下，一个请求占一个线程，高并发时线程池很快被打满。虚拟线程让“一个请求一个线程”的编程模型重新变得可行，吞吐量上去了，代码还不用改成响应式那种反人类的写法。QuickBlue 基于 JDK 21，等于把这个红利直接吃进来了。

2.2 微服务拆分：拆到什么粒度才算合适

微服务拆分是个老生常谈但又永远吵不出结果的话题。QuickBlue 作为底座，它自己是怎么拆的，其实很有参考价值。

底座的拆分原则和业务系统不太一样。业务系统拆分看领域边界，底座拆分看能力复用度和变更频率。变更频率低、被所有服务依赖的能力，适合独立成服务；变更频繁、和具体业务强绑定的，不该塞进底座。

按这个原则，QuickBlue 的模块大致可以分成这么几层：

这里有个经验：底座里最忌讳的是把“公共依赖包”也做成服务。有些团队喜欢搞一个 common-service，所有工具方法都通过 RPC 调用，结果就是每次调个字符串工具都要走一次网络，延迟上去了，故障点也多了。QuickBlue 把这类东西做成 Jar 包直接依赖，是对的。判断标准很简单：无状态、无外部依赖、纯计算的东西，做成 Jar 包；有状态、要独立扩缩容、要独立发布的，做成服务。

2.3 AI 能力接入层：底座和普通微服务框架的分水岭

如果说前面那些模块和普通的 Spring Cloud 脚手架差别不大，那 AI 能力接入层就是 QuickBlue 真正区别于“若依微服务 Plus”这类通用脚手架的地方。

通用脚手架解决的是“怎么把微服务跑起来”，QuickBlue 额外解决了“怎么把 AI 能力管起来”。具体来说，它要处理几个通用脚手架不会碰的问题：

模型调用的统一抽象。企业里往往同时用多个模型——有的场景用便宜的小模型，有的场景用能力强的大模型，有的走公有云 API，有的走本地部署。如果每个业务代码里都硬编码某个厂商的 SDK，换模型时就是灾难。底座需要提供一层统一抽象，业务只面向接口编程，底层换模型对业务透明。

会话上下文的存储。多轮对话是有状态的，这个状态存哪、存多久、怎么和用户绑定、多实例部署时怎么共享，都是问题。底座通常会用 Redis 来存会话，配合合理的过期策略。

Token 与成本核算。AI 调用是要花钱的，企业需要知道每个租户、每个应用、每个用户消耗了多少 Token。这要求底座在调用链路上埋点，把用量统计出来。

Prompt 模板管理。Prompt 是 AI 应用的“业务逻辑”之一，散落在代码里没法维护。底座一般会提供模板的集中管理和版本控制。

这几件事，通用微服务脚手架一件都不管，但对 AI 应用来说件件要命。这也是为什么我说“AI 应用底座”不是营销概念，而是有实打实的技术内涵。

3. 关键细节深挖：那些决定成败的工程点

3.1 Sentinel 规则持久化：别让限流规则重启就丢

Sentinel 是 Spring Cloud 体系里做流量防护的主力，但它的默认行为有个大坑：规则默认存在内存里，应用一重启就全没了。这在生产环境是不可接受的——你半夜发个版，第二天早上流量高峰来了，发现限流规则没了，服务直接被冲垮。

QuickBlue 这类底座必须解决这个问题。标准做法是把规则持久化到 Nacos 或 Redis。我倾向于用 Nacos，因为规则本身是配置，Nacos 天然适合管配置，而且支持监听推送，规则改了不用重启。

具体实现上，需要做两件事。一是引入sentinel-datasource-nacos依赖，二是在配置里声明数据源：

spring: cloud: sentinel: datasource: flow: nacos: server-addr: ${NACOS_ADDR} >@Bean public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) { RedisTemplate<String, Object> template = new RedisTemplate<>(); template.setConnectionFactory(factory); ObjectMapper mapper = new ObjectMapper(); mapper.activateDefaultTyping( LaissezFaireSubTypeValidator.instance, ObjectMapper.DefaultTyping.NON_FINAL, JsonTypeInfo.As.PROPERTY); GenericJackson2JsonRedisSerializer serializer = new GenericJackson2JsonRedisSerializer(mapper); template.setKeySerializer(new StringRedisSerializer()); template.setValueSerializer(serializer); template.setHashKeySerializer(new StringRedisSerializer()); template.setHashValueSerializer(serializer); template.afterPropertiesSet(); return template; }

activateDefaultTyping会在 JSON 里额外写入@class字段，反序列化时就能还原成正确的类型。代价是存的内容稍微大一点，但换来的是类型安全，值。

还有一个集群特有的坑：Redis 集群模式下，涉及多个 key 的操作必须保证这些 key 在同一个 slot。比如你用MGET一次取多个 key，如果这些 key 分散在不同节点，会直接报错。解决办法是用 hash tag，把相关的 key 用{}包起来，比如user:{1001}:name和user:{1001}:age，花括号里的内容相同，就会被分到同一个 slot。

3.3 网关鉴权：白名单漏配是高频事故

网关是流量的第一道关口，鉴权逻辑放这里最合适。但网关鉴权有个经典事故模式：新增了一个不需要登录的接口，忘了加白名单，导致前端一直 401；或者反过来，某个敏感接口本该鉴权，结果被通配符白名单误放行。

QuickBlue 这类底座通常会把白名单做成配置项，支持从 Nacos 动态刷新。配置大概长这样：

security: ignore-urls: - /auth/login - /auth/captcha - /doc/** - /actuator/health

这里的关键是白名单匹配规则要精确。/doc/**这种通配符要慎用，如果哪天有个/doc/delete的接口，就被一起放行了。我的经验是白名单尽量用完整路径，少用通配符，实在要用也要限定到具体目录层级。

另外，网关鉴权还要处理一个细节：Token 校验通过后，用户信息怎么传给下游服务。常见做法是把用户 ID、租户 ID 塞进请求头，下游服务直接从请求头取。但这里有个安全隐患——如果下游服务直接暴露，外部请求可以伪造请求头。所以下游服务要么不对外暴露，要么在网关层把外部传入的同名请求头清掉再重新写入。

3.4 多租户隔离：数据层怎么做才干净

企业级底座基本都要支持多租户，因为一套系统往往要给多个部门或子公司用。多租户的核心是数据隔离，隔离级别从低到高有三种：独立数据库、共享数据库独立 Schema、共享数据库共享表加租户字段。

QuickBlue 这类底座通常采用第三种，成本最低，实现也最灵活。具体做法是在每张业务表加一个tenant_id字段，然后在数据访问层做拦截，查询时自动加上租户条件，插入时自动填充租户 ID。

用 MyBatis-Plus 的话，可以通过TenantLineInnerInterceptor实现：

@Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new TenantLineInnerInterceptor( new TenantLineHandler() { @Override public Expression getTenantId() { Long tenantId = TenantContext.getTenantId(); return new LongValue(tenantId); } @Override public String getTenantIdColumn() { return "tenant_id"; } @Override public boolean ignoreTable(String tableName) { return IGNORE_TABLES.contains(tableName); } })); return interceptor; }

TenantContext用 ThreadLocal 存当前请求的租户 ID，在网关鉴权后解析 Token 得到，通过请求头传到下游，下游在过滤器里塞进 ThreadLocal。

注意：租户拦截器要配置忽略表，比如系统字典、全局配置这类所有租户共享的表，不能加租户条件，否则查不到数据。这个忽略列表要维护好，新增共享表时记得加进去，不然会出现“新表查不到数据”的诡异问题。

4. 从零跑起来：QuickBlue 的实操落地流程

4.1 环境准备与依赖版本对齐

动手之前，版本对齐是第一位的。Spring Cloud 的版本管理是个老大难，Spring Boot、Spring Cloud、Spring Cloud Alibaba 三者版本必须匹配，否则各种莫名其妙的启动报错。

以 JDK 21 为基础，一套经过验证的版本组合是：

版本对不齐的典型症状是启动时报NoSuchMethodError或ClassNotFoundException，看着像代码问题，其实是依赖冲突。排查这类问题，mvn dependency:tree是必备工具，把冲突的依赖排除掉。

环境准备清单：

1. 安装 JDK 21，配置JAVA_HOME
2. 启动 Nacos，单机模式用sh startup.sh -m standalone
3. 启动 Redis，集群模式至少 6 个节点（3 主 3 从）
4. 启动 Sentinel Dashboard，用于查看规则和监控
5. 准备 MySQL，导入底座的基础表结构

4.2 服务启动顺序与依赖关系

微服务启动是有顺序的，顺序错了会报错。QuickBlue 这类底座的启动顺序大致是：

1. Nacos 先起，所有服务都依赖它做注册和配置
2. Redis、MySQL 先起，数据层依赖
3. 认证授权服务，其他服务启动时可能要校验 Token
4. 系统管理服务，提供用户、租户等基础数据
5. 网关服务，最后起，因为它要路由到其他服务
6. 业务服务，按需启动

这个顺序不是绝对的，因为服务之间有容错机制，但按这个顺序起能避免大量启动期的报错日志，排查问题也清爽。

启动后，去 Nacos 控制台看服务列表，确认所有服务都注册上了。如果某个服务没出现，先看它的日志有没有报注册失败，常见原因是 Nacos 地址配错、网络不通、或者命名空间不匹配。

4.3 一个完整的 AI 调用链路走查

光把服务起起来还不够，得验证核心链路是通的。我们走一遍“用户发起一次 AI 对话”的完整链路，看看底座各模块是怎么协作的。

第一步，请求进网关。前端带着 Token 请求/ai/chat，网关先做鉴权，校验 Token 有效性，解析出用户 ID 和租户 ID，塞进请求头，然后路由到 AI 能力服务。

第二步，AI 能力服务处理。服务从请求头取出用户和租户信息，塞进TenantContext。然后根据会话 ID 从 Redis 拉取历史对话上下文。如果没有会话 ID，就新建一个会话。

第三步，组装 Prompt。从 Prompt 模板管理里取出对应场景的模板，把历史上下文和当前问题填充进去。这一步要注意 Token 长度控制，历史对话不能无限拼，超出模型上下文窗口会被截断或报错。常见做法是保留最近 N 轮对话，或者按 Token 数动态裁剪。

第四步，调用模型。通过统一抽象层调用具体模型，这里会经过 Sentinel 的限流和熔断保护。如果模型调用超时或失败，走降级逻辑，返回友好提示而不是一堆堆栈。

第五步，记录用量。调用返回后，从响应里解析出 Token 消耗量，累加到用户的用量统计里。这个统计通常异步写，不阻塞主流程。

第六步，存上下文。把本轮问答追加到会话上下文，写回 Redis，设置合理的过期时间。

第七步，返回响应。把模型返回的内容包装成统一格式返回给前端。

这条链路走通，说明底座的鉴权、路由、缓存、限流、AI 接入都正常工作了。任何一环出问题，都能通过日志快速定位到具体模块。

4.4 虚拟线程的开启与验证

JDK 21 的虚拟线程是个大杀器，但要真正用上，得做点配置。Spring Boot 3.2 开始支持虚拟线程，开启方式很简单：

spring: threads: virtual: enabled: true

这一行配置会让 Spring 的异步任务执行器和 Tomcat 的请求处理都改用虚拟线程。开启后怎么验证生效了？可以在一个接口里打印当前线程：

@GetMapping("/thread-check") public String threadCheck() { return Thread.currentThread().toString(); }

如果输出里带VirtualThread字样，说明生效了。没开启的话，输出是传统的http-nio-8080-exec-1这种。

虚拟线程对 AI 应用的价值，前面提过，主要是应对大量 IO 等待。但要注意，虚拟线程不是银弹。如果代码里有synchronized块包着阻塞操作，虚拟线程会被 pin 住，退化成平台线程，性能反而可能下降。JDK 21 里可以用-Djdk.tracePinnedThreads=full参数来检测 pin 住的情况，排查时很有用。

5. 踩坑实录：那些文档里不会写的问题

5.1 常见问题速查表

5.2 三个我踩过的坑

坑一：Sentinel 规则持久化配了，但规则不生效。当时排查了很久，最后发现是 Nacos 里的规则 JSON 格式不对——rule-type和数据源声明里的类型对不上。Sentinel 对规则格式要求很严，字段名错一个字符就静默失败，不报错。后来我养成了习惯，规则配好后一定去 Sentinel 控制台确认规则加载上了，而不是只看 Nacos 里有没有配置。

坑二：Redis 集群下分布式锁失效。用 Redisson 加锁，单机测试没问题，上了集群偶尔出现两个线程同时拿到锁。原因是 Redisson 的锁 key 和业务 key 不在同一个 slot，集群模式下跨 slot 操作行为异常。解决办法是给锁 key 和业务 key 加相同的 hash tag，保证它们在同一个节点。

坑三：网关转发丢失请求头。下游服务拿不到用户信息，排查发现是网关转发时默认过滤了部分请求头。Spring Cloud Gateway 默认会过滤掉一些 hop-by-hop 的请求头，自定义的请求头如果名字不规范也可能被过滤。解决办法是在网关配置里显式声明要保留的请求头，或者用规范的命名（避免下划线等特殊字符）。

5.3 性能调优的几个实操心得

底座跑起来只是第一步，跑得好是另一回事。分享几个调优心得。

连接池要按并发量算。数据库连接池和 Redis 连接池的大小，不能拍脑袋定。经验公式是：连接数 = 平均 QPS × 平均耗时（秒）× 冗余系数。比如一个接口平均 QPS 200，平均耗时 50ms，那理论并发是 10，冗余系数取 3，连接池设 30 左右就够。设太大反而浪费资源，还可能把数据库压垮。

JVM 参数要针对 AI 场景调。AI 应用内存占用大，尤其是处理长文本时。堆内存建议给足，同时开启 G1 或者 ZGC。JDK 21 上 ZGC 表现不错，停顿时间能控制在毫秒级，适合对延迟敏感的场景。参数大概是-XX:+UseZGC -Xmx4g -Xms4g。

限流阈值要分层设置。网关层做粗粒度限流，保护整个系统；服务层做细粒度限流，保护单个接口；模型调用层单独限流，因为模型 API 通常有配额限制。三层限流配合，才能既保证系统稳定，又不浪费配额。

6. 底座之上：QuickBlue 的扩展方向与选型建议

6.1 什么团队适合引入 AI 应用底座

不是所有团队都需要底座。我的判断标准是：如果你一年内要做两个以上的 AI 应用，或者团队超过十人，底座的价值就体现出来了。单个小应用，一个 Spring Boot 单体加几个工具类就够了，上底座反而是过度设计。

反过来，如果你面临这些情况，底座值得考虑：多个 AI 应用要共享用户和权限体系；模型调用要统一管理和成本核算；团队里新人多，需要一套规范的脚手架降低上手成本；对稳定性和可观测性有明确要求。

6.2 底座后续可以怎么扩展

QuickBlue 这类底座搭好之后，扩展方向其实很多。往深了做，可以接入向量数据库，把知识库检索能力也沉淀到底座里；可以做模型路由，根据问题类型自动选择最合适的模型；可以做 Prompt 的 A/B 测试，让 Prompt 优化有数据支撑。

往广了做，可以把底座和企业的现有系统打通，比如对接统一身份认证、对接监控告警平台、对接成本管理系统。底座的价值在于“一次建设，多次复用”，接入的系统越多，摊薄到每个应用的成本就越低。

6.3 选型时的几个提醒

最后说几个选型提醒。第一，别被“全栈”迷惑，底座不是功能越多越好，而是越稳越好。一个功能齐全但三天两头出问题的底座，不如一个功能精简但稳定的底座。第二，关注社区活跃度，底座依赖的组件如果社区不活跃，出了问题没人解答，升级也没人维护，风险很大。第三，留好退出机制，底座再好的设计也可能不适用你的场景，要保证业务代码和底座之间的耦合度可控，将来换底座时不至于推倒重来。

我自己在评估这类底座时，会先拿一个真实的小需求跑一遍全流程，从建表、写接口、配权限到部署上线，看看整个体验顺不顺。文档写得再漂亮，不如亲手跑一遍来得真实。跑完之后，哪些地方设计得好、哪些地方是坑，心里就有数了。