1. 项目缘起与整体架构思路1.1 为什么选择 SpringBoot Vue 这套组合做企业级平台技术选型永远是第一道分水岭。我前后参与过七八个中后台项目的从零搭建踩过不少坑之后最终沉淀下来的主力方案就是SpringBoot 做后端 Vue 做前端。这套组合不是最时髦的但它是目前企业级场景里综合成本最低、招人最容易、生态最成熟的方案没有之一。先说说后端为什么是 SpringBoot。企业级平台最怕什么怕的是业务逻辑复杂、模块多、集成第三方组件频繁。SpringBoot 的自动装配机制把大量样板配置干掉了一个starter依赖引进来数据源、连接池、事务、序列化基本就绪。更关键的是它的生态你要接 Redis、接 Kafka、接 MinIO、接消息队列、接定时任务几乎每个中间件都有官方或社区维护的 starter版本兼容性有保障。我之前试过用别的框架搭类似平台光是中间件集成就耗掉两周换成 SpringBoot 之后同样的活儿两天搞定。再说前端为什么是 Vue。企业级可视化平台的前端有两个硬需求一是组件化程度高二是上手门槛低。Vue 的模板语法对后端转全栈的同事非常友好v-if、v-for、v-model这套东西看一遍就能写。而且 Vue 生态里有 Element Plus 这种企业级 UI 库表格、表单、弹窗、树形控件开箱即用省掉大量造轮子的时间。Vue3 加 TypeScript 之后大型项目的类型安全也有了保障重构的时候心里有底。提示如果你的团队里前端人手紧张Vue 的学习曲线明显比 React 平缓这是很多中小团队选它的真实原因不用不好意思承认。1.2 智能体平台的核心定位这个项目叫“企业级可视化智能体平台”关键词拆开看是三层意思。企业级意味着它不是玩具要考虑权限、审计、多租户、高可用可视化意味着它得有数据大屏、图表、流程编排这些看得见的东西智能体平台意味着它的核心能力是管理和调度 AI 智能体包括模型接入、对话编排、知识库、工具调用等。我理解的智能体平台本质上是一个“AI 能力的中台”。它把大模型的调用、提示词管理、上下文维护、工具注册这些脏活累活统一封装起来业务方只需要关心“我要做一个什么智能体”而不用关心底层模型怎么调、会话怎么存、工具怎么接。这跟当年微服务中台解决“服务治理”问题的思路是一模一样的。架构上我采用的是前后端分离 模块化单体的路线。为什么不上微服务因为企业级平台在早期阶段业务边界还没完全清晰强行拆微服务只会带来分布式事务、链路追踪、服务发现一堆额外复杂度。模块化单体先把业务跑通等某个模块真的成为瓶颈了再单独拆出去这才是务实的做法。1.3 整体分层设计整个平台我分成四层来设计从下往上依次是基础设施层MySQL 存业务数据Redis 做缓存和会话MinIO 做对象存储存知识库文档、模型文件、导出报表Kafka 做异步消息。核心服务层SpringBoot 主应用内部按模块划分——用户权限模块、智能体管理模块、模型接入模块、知识库模块、可视化模块。接口网关层统一用 SpringBoot 的 Controller 暴露 RESTful 接口配合 JWT 做鉴权Swagger 做文档。前端展示层Vue3 Element Plus ECharts负责所有可视化交互。这样分层的好处是职责清晰。比如知识库模块要换向量数据库只动核心服务层的一个子模块前端完全无感。可视化模块要加新图表类型只动前端后端接口不用改。2. 后端核心模块拆解与实操要点2.1 SpringBoot 项目骨架搭建项目骨架我用的是 Maven 多模块结构这是企业级项目的标配。单模块项目写到后面必然是一坨多模块能强制你做职责隔离。我的模块划分是这样的agent-platform ├── agent-common // 通用工具、常量、异常 ├── agent-model // 实体、DTO、VO ├── agent-dao // 数据访问层 ├── agent-service // 业务逻辑层 ├── agent-web // 控制器、启动类 └── agent-job // 定时任务、异步任务pom.xml里 SpringBoot 版本我选的是3.2.x。这里有个坑要提醒网上很多教程还在用 2.x但 3.x 已经全面转向 Jakarta EEjavax.*包名全部变成jakarta.*。如果你从老项目迁移这一步会改到怀疑人生。新项目直接上 3.x别犹豫。核心依赖清单如下依赖用途版本建议spring-boot-starter-webWeb 框架随主版本spring-boot-starter-data-redisRedis 集成随主版本mybatis-plus-boot-starterORM 增强3.5.xminio对象存储8.5.xspring-kafka消息队列随主版本hutool-all工具集5.8.xsa-token权限认证1.37.x注意MyBatis-Plus 和 SpringBoot 3.x 的兼容性要特别确认早期版本有反射相关的坑务必用 3.5.3 以上。2.2 智能体管理模块设计智能体管理是整个平台的心脏。一个智能体在我的设计里包含这些核心字段名称、描述、绑定的模型、系统提示词、温度参数、最大 token 数、关联知识库、可用工具列表、状态。数据库表设计我用了主表加关联表的方式agent_info智能体主信息agent_model_rel智能体与模型的关联agent_kb_rel智能体与知识库的关联agent_tool_rel智能体与工具的关联为什么不用 JSON 字段一把梭因为关联查询、权限过滤、统计报表都需要用到这些关系。JSON 字段查询性能差而且没法建索引。我见过有团队图省事全塞 JSON后期做“查所有用了某个知识库的智能体”这种需求时直接傻眼。智能体执行的核心逻辑我封装成一个AgentExecutor服务流程是这样的接收用户输入加载智能体配置根据配置拼接系统提示词和上下文如果绑定了知识库先做向量检索把相关片段塞进上下文调用大模型接口流式返回结果如果模型返回了工具调用指令执行对应工具把结果再喂回模型保存会话记录这里第 5 步的工具调用是智能体的灵魂。我设计了一个ToolRegistry所有工具实现统一的Tool接口包含name、description、parameters、execute四个方法。注册进去之后模型就能通过 function calling 的方式调用它们。2.3 模型接入与统一抽象企业级平台不可能只接一个模型。今天用这个明天老板说换那个所以必须做统一抽象。我定义了一个LlmClient接口public interface LlmClient { String chat(ListMessage messages, LlmConfig config); void chatStream(ListMessage messages, LlmConfig config, StreamCallback callback); ListString listModels(); }然后针对不同模型厂商做实现类。这样上层业务代码只依赖LlmClient接口换模型只需要加一个实现类改一下配置业务代码一行不动。配置我放在数据库里而不是配置文件里因为运营人员需要能动态切换。llm_config表存厂商、baseUrl、apiKey加密存储、默认模型、超时时间这些。apiKey 我用 AES 加密后存读取时解密避免数据库被拖库后密钥泄露。提示apiKey 千万别明文存数据库也别硬编码在代码里。我见过有项目把 key 写在application.yml里然后提交到代码仓库这是重大安全事故。2.4 知识库与向量检索知识库模块是企业级智能体平台的刚需。客户经常说“我要让 AI 回答我们公司内部文档的问题”这就是 RAG检索增强生成的典型场景。我的实现流程是文档上传到 MinIO然后异步做解析和分块调用 embedding 模型把每块转成向量存到向量数据库。用户提问时把问题也转成向量做相似度检索取 top-k 个片段拼进提示词。文档解析这块要支持多种格式PDF、Word、Markdown、TXT。PDF 解析我用 Apache PDFBoxWord 用 POI。这里有个经验PDF 解析出来的文本经常有换行错乱的问题需要做后处理把孤立的单字行合并。不然分块之后语义是断的检索效果很差。分块策略我默认用固定长度加重叠chunk size 设 500 字符overlap 设 50 字符。为什么不按段落分因为有些文档段落特别长超过模型上下文限制。固定长度加重叠是工程上最稳的方案虽然不完美但够用。向量数据库我选的是 Milvus 的轻量替代方案早期用内存版数据量大了再换集群版。这里不展开具体产品核心是选一个支持 ANN 检索、有 Java SDK 的就行。2.5 Redis 与 MinIO 的集成细节Redis 在这个平台里承担三个角色缓存、会话存储、分布式锁。缓存主要缓存模型列表、智能体配置这些读多写少的数据。会话存储用 Redis 的 Hash 结构key 是 sessionIdfield 是消息序号value 是消息内容。分布式锁用在智能体执行这种可能并发的场景防止同一个会话被重复处理。MinIO 的集成要注意 bucket 的权限策略。我建了两个 bucket一个public存前端可直接访问的静态资源一个private存知识库文档这种敏感数据。private bucket 的访问必须走后端签名 URL不能直接暴露。// 生成预签名URL示例 String url minioClient.getPresignedObjectUrl( GetPresignedObjectUrlArgs.builder() .method(Method.GET) .bucket(private) .object(objectName) .expiry(1, TimeUnit.HOURS) .build() );预签名 URL 的有效期我设 1 小时太短用户体验差太长有安全风险。3. 前端可视化与交互实现3.1 Vue3 项目结构与工程化配置前端我用的是 Vue3 Vite TypeScript Pinia Vue Router 这套组合。Vite 的冷启动速度比 Webpack 快一个数量级开发体验提升明显。目录结构按功能划分src ├── api // 接口封装 ├── assets // 静态资源 ├── components // 通用组件 ├── views // 页面 ├── store // Pinia状态 ├── router // 路由 ├── utils // 工具函数 └── types // TS类型定义路由我用的是动态路由方案。登录后根据后端返回的权限菜单动态生成路由表这样不同角色的用户看到的菜单不一样。实现上是在路由守卫里判断如果路由表还没加载就先请求菜单接口用router.addRoute动态添加。// 动态路由核心逻辑 const loadRoutes async () { const menus await getMenuList() menus.forEach(menu { const route { path: menu.path, name: menu.name, component: () import(/views/${menu.component}.vue), meta: { title: menu.title, icon: menu.icon } } router.addRoute(Layout, route) }) }注意动态 import 的路径不能是完全变量Vite 需要能静态分析。用模板字符串拼接时要保证/views/前缀是固定的否则打包会失败。3.2 可视化大屏与 ECharts 实战可视化大屏是这个平台的门面。我用 ECharts 做图表配合 CSS Grid 做布局。大屏的核心诉求是“自适应”因为客户的大屏分辨率五花八门有 1920x1080 的也有 3840x2160 的。我的方案是用transform: scale()做整体缩放。设计稿按 1920x1080 做运行时计算实际宽高比取最小值作为缩放比例然后整体缩放。这样不管什么分辨率布局都不会乱。const resize () { const scaleX window.innerWidth / 1920 const scaleY window.innerHeight / 1080 const scale Math.min(scaleX, scaleY) container.style.transform scale(${scale}) }ECharts 实例要记得在组件卸载时dispose不然会内存泄漏。我踩过这个坑大屏开一整天内存涨到几个 G最后浏览器卡死。正确做法是在onUnmounted里调用chart.dispose()。图表类型上企业级大屏常用的有折线图趋势、柱状图对比、饼图占比、地图地域分布、雷达图多维评估。ECharts 都支持配置项比较多建议封装成通用组件传数据和配置进去就行。3.3 智能体对话界面实现对话界面是用户接触最多的页面。核心功能是消息列表、输入框、流式输出。流式输出我用的是 SSEServer-Sent Events后端用 SpringBoot 的SseEmitter推送前端用EventSource接收。const eventSource new EventSource(/api/agent/chat?sessionId${id}) eventSource.onmessage (e) { const chunk JSON.parse(e.data) appendToLastMessage(chunk.content) }这里有个细节SSE 默认不支持 POST只能 GET。但对话内容可能很长放 URL 里不合适。我的做法是先 POST 创建会话拿到 sessionId再用 GET 建立 SSE 连接通过 sessionId 关联。消息渲染要支持 Markdown因为模型返回的内容经常有代码块、列表、表格。我用markdown-it做解析配合highlight.js做代码高亮。注意要做 XSS 防护markdown-it默认是安全的但如果你开了html: true就要自己过滤。3.4 前端打包与后端集成部署前端打包后要放进 SpringBoot 里一起部署这是企业级项目常见的做法省得单独维护一个 Nginx。具体操作是把dist目录复制到 SpringBoot 的src/main/resources/static下然后配置一个转发规则Configuration public class WebConfig implements WebMvcConfigurer { Override public void addViewControllers(ViewControllerRegistry registry) { registry.addViewController(/{path:[^\\.]*}) .setViewName(forward:/index.html); } }这段配置的作用是所有非静态资源的请求都转发到index.html交给 Vue Router 处理。不然用户刷新页面会 404。提示打包顺序很重要先npm run build生成 dist再mvn package打 jar 包。可以配一个 Maven 插件自动执行前端构建但我不推荐因为前端构建慢每次后端打包都等一遍很痛苦。分开执行更灵活。4. 部署上线与常见问题排查4.1 生产环境部署方案生产部署我推荐 Docker Compose 方案比裸机部署省心太多。一个docker-compose.yml把 MySQL、Redis、MinIO、Kafka、应用全部编排起来一条命令启动。version: 3.8 services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: ${DB_PASSWORD} volumes: - ./data/mysql:/var/lib/mysql redis: image: redis:7-alpine command: redis-server --requirepass ${REDIS_PASSWORD} minio: image: minio/minio command: server /data --console-address :9001 app: build: . depends_on: - mysql - redis - minio ports: - 8080:8080密码全部用环境变量注入不写死在文件里。docker-compose.yml可以提交到仓库.env文件加到.gitignore。JVM 参数我设的是-Xms2g -Xmx2g -XX:UseG1GC。企业级应用内存给足G1 垃圾回收器在 2G 到 8G 堆内存区间表现最稳。别用默认的默认的堆太小跑一会儿就 OOM。4.2 常见问题速查表问题现象可能原因排查方向解决方案启动报数据源错误数据库未就绪检查 MySQL 容器状态加 healthcheck 和 depends_on前端刷新 404路由未配置转发检查 WebConfig添加 forward 规则SSE 连接断开网关超时检查 Nginx/网关超时配置调大 proxy_read_timeout文件上传失败MinIO 权限检查 bucket 策略配置正确的 accessKey模型调用超时网络或模型慢看日志中的耗时调大超时时间加降级内存持续增长资源未释放看堆内存曲线检查 ECharts dispose、连接池中文乱码编码不一致检查数据库和连接串统一 utf8mb4定时任务重复执行多实例部署检查是否有分布式锁加 Redis 锁4.3 性能优化经验企业级平台上线后性能问题会逐渐暴露。我总结几个最有效的优化点。数据库层面慢查询是万恶之源。开启慢查询日志把超过 1 秒的 SQL 都揪出来。常见的优化是加索引、避免select *、避免在 where 里用函数。我遇到过一个查询因为 where 条件里对时间字段用了DATE()函数导致索引失效全表扫描 200 万行加了函数索引后从 8 秒降到 50 毫秒。缓存层面热点数据必须缓存。智能体配置、模型列表、用户权限这些读的频率远高于写。我用 Spring Cache 加 Redis 做二级缓存Cacheable注解一加代码侵入性很小。但要注意缓存穿透和雪崩空值也要缓存过期时间加随机值。接口层面大列表接口必须分页这是铁律。我见过有接口一次返回几万条数据前端直接卡死。分页用 MyBatis-Plus 的Page对象配合前端的分页组件体验和性能兼顾。前端层面路由懒加载、组件按需引入、图片压缩、开启 gzip。Vite 打包默认就做了 tree-shaking但 Element Plus 这种大库还是要配按需引入不然打包体积轻松上 2M。4.4 踩过的坑与独家心得说几个文档里不会写、但实际一定会遇到的坑。第一个坑时区问题。服务器是 UTC数据库存的是 UTC但用户在东八区。如果不处理用户看到的时间差 8 小时。我的做法是数据库统一存 UTC返回给前端时转成用户时区。SpringBoot 里配spring.jackson.time-zoneGMT8MySQL 连接串加serverTimezoneAsia/Shanghai。第二个坑大文件上传。知识库文档可能几百兆默认的上传配置会失败。要同时改三处SpringBoot 的spring.servlet.multipart.max-file-size、Nginx 的client_max_body_size、前端的超时时间。少改一处都不行。第三个坑并发写会话。同一个会话如果用户快速发两条消息可能后一条先返回导致消息顺序错乱。我的解法是给会话加锁用 Redis 的setnx实现处理完释放。虽然牺牲了一点并发但保证了正确性。第四个坑模型返回格式不稳定。不同模型返回的 JSON 结构不一样有的包在choices[0].message.content有的在output.text。统一抽象层要做好适配别让上层业务感知到差异。第五个坑前端环境变量。开发环境和生产环境的接口地址不一样用.env.development和.env.production区分。Vite 里只有VITE_开头的变量才会暴露给前端别把密钥写进去。5. 平台扩展方向与个人体会5.1 后续可扩展的能力这个平台目前是 MVP 版本跑通了核心链路。后续可以扩展的方向很多我列几个优先级高的。多租户隔离现在所有数据在一个库里如果要做 SaaS需要按租户隔离。方案有两种一种是共享库加 tenant_id 字段一种是独立库。前者成本低后者隔离彻底。我倾向于先做前者等大客户有要求了再升级。工作流编排现在的智能体是单轮的复杂场景需要多智能体协作。可以引入工作流引擎把多个智能体串起来前一个的输出作为后一个的输入。这块可以参考 DAG 的思路用有向无环图描述执行顺序。可观测性企业级平台必须能监控。接入 Prometheus 采集指标Grafana 做看板把接口耗时、模型调用次数、token 消耗都监控起来。出了问题能快速定位这是运维的基本要求。审计日志谁在什么时候调用了哪个智能体输入输出是什么都要记录。合规场景下这是硬需求。日志量大建议存到独立的表或者用 ELK 做集中管理。5.2 我个人的一些体会做企业级平台和做个人项目最大的区别是对稳定性的要求完全不同。个人项目挂了重启就行企业级平台挂了可能影响几百人的工作。所以我在设计时永远留一手接口要有降级方案数据库要有备份关键操作要有日志。另一个体会是别过度设计。我早期特别喜欢上微服务、上消息队列、上各种中间件觉得这样才“企业级”。后来发现很多项目根本用不上反而增加了运维负担。技术选型要跟着业务走业务没到那个量级就别上那个量级的架构。还有一点是文档和注释。企业级项目是团队协作你写的代码别人要维护。关键逻辑一定要写注释接口一定要有文档。我现在养成习惯写完一个模块就顺手把 Swagger 注解补上把复杂逻辑的注释写了。当时多花十分钟后面省别人十小时。最后说个心态问题。企业级平台不是一次性能做完的它是迭代出来的。第一版能跑通核心流程就是胜利别想着一步到位。我见过太多项目因为追求完美做了半年还没上线最后不了了之。先上线再优化让用户用起来根据反馈迭代这才是正道。这个平台我从零搭到现在前后迭代了十几个版本踩的坑能写一本书。但每次解决一个问题看到平台更稳一点、更好用一点那种成就感是实打实的。如果你也在做类似的项目希望这些经验能帮你少走点弯路。有问题欢迎交流我踩过的坑能帮你避开一个是一个。