Spring AI Alibaba 1.x 系列【57】SAA Admin 前后端技术栈与分层设计详解

云烟成雨TD2026-05-22 8:42

文章目录

  • [1. 概述](#1. 概述)
  • [2. 前端模块](#2. 前端模块)
    • [2.1 main --- 主工作台应用](#2.1 main — 主工作台应用)
    • [2.2 spark-flow --- 可视化工作流编辑器](#2.2 spark-flow — 可视化工作流编辑器)
    • [2.3 spark-i18n --- 国际化核心库](#2.3 spark-i18n — 国际化核心库)
  • [3. 后端模块](#3. 后端模块)
    • [3.1 server-runtime --- 运行时领域模型](#3.1 server-runtime — 运行时领域模型)
    • [3.2 server-core --- 核心服务层](#3.2 server-core — 核心服务层)
    • [3.3 server-openapi --- 开放 API](#3.3 server-openapi — 开放 API)
    • [3.4 server-start --- 启动模块](#3.4 server-start — 启动模块)
      • [3.4.1 Controller 层](#3.4.1 Controller 层)
      • [3.4.2 Entity 层](#3.4.2 Entity 层)
      • [3.4.3 Service 层](#3.4.3 Service 层)
      • [3.4.4 全局异常处理](#3.4.4 全局异常处理)
      • [3.4.5 可观测性](#3.4.5 可观测性)
    • [3.5 数据表设计](#3.5 数据表设计)
      • [3.5.1 agentscope-schema.sql](#3.5.1 agentscope-schema.sql)
      • [3.5.2 admin-schema.sql](#3.5.2 admin-schema.sql)

1. 概述

spring-ai-alibaba-admin 是 Spring AI Alibaba 项目中的一个子模块：


spring-ai-alibaba-admin 模块下包含了前后端模块：

2. 前端模块

前端采用 Monorepo 架构，由 3 个子包组成，基于 npm workspaces 管理依赖。


技术栈：

技术 版本 用途
React 18 UI 框架
Umi 4 4.x 应用框架（路由、构建、代理）
Ant Design 5.23.2 UI 组件库
TailwindCSS 3.x 原子化样式（main）
@xyflow/react 12.3.5 流程图渲染引擎（spark-flow）
Zustand 5.x 流程图状态管理（spark-flow）
Axios 1.8.4 HTTP 客户端
CodeMirror 4.x 代码编辑器（脚本/JSON）

2.1 main --- 主工作台应用

基于 Umi 4 构建的单页应用，集成所有业务模块。

入口配置 ：.umirc.ts

配置项 说明
title 应用标题 "SAA"
proxy 代理 /api、/console、/oauth2 到后端 WEB_SERVER
alias @ → src/，@spark-ai/flow → ../spark-flow/dist
routes 路由配置（详见第 3 节）
lessLoader 启用 javascriptEnabled，Ant Design 前缀为 ag-ant

环境变量 （.env）：

bash 复制代码 
WEB_SERVER="http://127.0.0.1:8080"   # 后端 API 地址
BACK_END="java"                      # 后端类型（java / python）
DEFAULT_USERNAME=saa                 # 默认账号
DEFAULT_PASSWORD=123456              # 默认密码

2.2 spark-flow --- 可视化工作流编辑器

独立的流程图渲染库，打包后作为 @spark-ai/flow 发布到 npm。

构建方式 ：father build + TailwindCSS 编译。

核心 API （index.ts 导出）：

导出项 类型 说明
Flow Component 流程图主组件，接收 nodeTypes 参数注册自定义节点
ReactFlowProvider Provider XYFlow 状态提供者
useStore Hook 访问流程图全局状态（nodeSchemaMap、interactiveMode 等）
WorkflowContextProvider Provider 工作流业务上下文（getConfigPanel、onDebounceChange 等）
useFlowInteraction Hook 流程交互（autoFitView、onFlowClearState 等）
useNodesInteraction Hook 节点交互（拖拽、连接、点击）
useHistory Hook 撤销/重做
FlowAside Component 左侧节点面板
FlowTools Component 顶部工具栏
FlowPanel Component 右侧配置面板容器
ConfigPanel Component 节点配置面板
TestPanel Component 测试面板

内置组件 ：VariableInput、VariableTreeSelect、ScriptCodeMirror、JudgeForm、OutputParamsTree、TaskStatus、DragPanel、DraggableWithHandle 等。

状态管理 ：使用 Zustand 管理流程图状态（nodes、edges、nodeSchemaMap、history、interactiveMode）。

2.3 spark-i18n --- 国际化核心库

提供多语言支持和自动化翻译工具链。

支持语言 ：中文（zh-cn）、英文（en-us）、日文（ja-jp）。

翻译命令：

bash 复制代码 
# main 应用
npm run translate:main
npm run translate:main:check
npm run translate:main:init

# spark-flow
npm run translate:spark-flow
npm run translate:spark-flow:check
npm run translate:spark-flow:init

使用方式 ：每个子包创建 $i18n 实例，通过 $i18n.get({ id: '...', dm: '默认文本' }) 获取翻译。

3. 后端模块

后端采用 Maven 多模块 架构，由 4 个子模块组成，按职责分离：

模块 职责 依赖
server-runtime 运行时领域模型（纯 POJO） 无
server-core 核心服务层（实体/Manager/Service/Mapper/配置） server-runtime
server-openapi 开放 API（OpenAI 兼容端点） server-core
server-start 启动模块（Spring Boot 入口 + 管理端 Controller） server-core + server-openapi + server-runtime

技术栈：

技术 版本 用途
Spring Boot 3.3.6 应用框架
MyBatis-Plus 3.5.9 ORM（server-core）
JPA/Hibernate 3.3.6 ORM（server-start）
MySQL 8.0.33 主数据库
Druid 1.2.20 数据库连接池
Redisson 3.27.2 Redis 客户端
Elasticsearch 8.13.4 知识库文档检索
RocketMQ 5.0.7 文档索引消息队列
JWT 0.12.6 认证令牌
Argon2 2.11 密码加密
SpringDoc OpenAPI 2.6.0 API 文档
GraalVM 22.3.1/24.2.1 JS/Python 脚本引擎
Spring Initializr 0.22.0 项目脚手架生成

3.1 server-runtime --- 运行时领域模型

职责：定义所有业务领域对象，不依赖数据库、缓存等外部组件，可独立发布。

基础类型：

类 说明
Result<T> 统一响应包装（data + error + requestId）
Error 错误对象（statusCode + message + code）
RequestContext 请求上下文（requestId、accountId、workspaceId、username、callerIp）
PagingList<T> 分页列表
BaseQuery 基础查询参数

领域子包：

子包 核心领域对象 说明
domain/account Account、ApiKey、TokenResponse、LoginRequest、Workspace、Oauth2User 账号体系
domain/app Application、ApplicationVersion、AppConfig、AgentConfig、AppQuery 应用管理
domain/knowledgebase KnowledgeBase、Document、DocumentChunk、ProcessConfig、IndexConfig 知识库
domain/model Model、AddModelRequest、CredentialSpec、UpdateProviderRequest 模型配置
domain/agent AgentRequest、AgentResponse、AgentStatus Agent 执行
domain/workflow Node、Edge、NodeResult、NodeTypeEnum、NodeStatusEnum、WorkflowStatus 工作流
domain/workflow/debug ApiTaskRunRequest、InitRequest、ProcessGetRequest、TaskRunResponse、WorkflowRequest、WorkflowResponse 工作流调试
domain/plugin Plugin、Tool、ToolExecutionRequest、ToolExecutionResult 插件/工具
domain/mcp McpTool、McpServerDeployConfig、McpServerDetail、McpServerCallToolRequest MCP Server
domain/component AppComponent、AppComponentConfig、AppComponentQuery 应用组件
domain/chat ChatMessage、MessageRole、ContentType、ToolCall、Usage 对话消息
domain/file File、UploadPolicy、WebUploadRequest 文件管理
domain/audio Voice、AudioOutput、AudioResponseFormat 语音合成
domain/refer Refer 关联引用
domain/tool ApiParameter、InputSchema、ToolCallSchema 工具参数

异常与错误码

类 说明
ErrorCode 错误码枚举（INVALID_API_KEY、MISSING_PARAMS、WORKFLOW_DEBUG_GET_PROCESS_FAIL 等）
BizException 业务异常
ExceptionUtils 异常转换工具（Exception → Error 对象）

3.2 server-core --- 核心服务层

职责：数据持久化、业务逻辑、中间件集成、配置管理。

Entity（实体层）：

实体 表名 说明
AppEntity application 应用（Agent/Workflow）
AppVersionEntity application_version 应用版本
AppComponentEntity application_component 应用组件
WorkspaceEntity workspace 工作空间
AccountEntity account 用户账号
ModelEntity model 模型配置
ProviderEntity provider 模型提供商
PluginEntity plugin 插件定义
ToolEntity tool 工具定义
KnowledgeBaseEntity knowledge_base 知识库
DocumentEntity document 文档
McpServerEntity mcp_server MCP Server
AgentSchemaEntity agent_schema Agent Schema
ApiKeyEntity api_key API Key
ReferEntity reference 关联引用
LimitEntity --- 限流/配额（内存实体）

Mapper（数据访问层）每个 Entity 对应一个：：

  • AppMapper
  • AppVersionMapper
  • AppComponentMapper
  • WorkspaceMapper
  • AccountMapper
  • ModelMapper
  • ProviderMapper
  • PluginMapper
  • ToolMapper
  • KnowledgeBaseMapper
  • DocumentMapper
  • McpServerMapper
  • AgentSchemaMapper
  • ApiKeyMapper
  • ReferMapper

Service（业务服务层）：

Service 说明
AppService / AppServiceImpl 应用 CRUD、版本管理、发布
WorkflowService / WorkflowServiceImpl 工作流执行（同步/异步/SSE 流式）
AgentService / AgentServiceImpl Agent 执行（同步/流式）
PluginService / PluginServiceImpl 插件 CRUD、Swagger 解析、工具导出
ToolService / ToolServiceImpl 工具 CRUD
ToolExecutionService 工具执行（Plugin/MCP/AppComponent 三种类型）
AccountService / AccountServiceImpl 账号管理、密码加密（Argon2）、OAuth2 登录
WorkspaceService / WorkspaceServiceImpl 工作空间管理
ApiKeyService / ApiKeyServiceImpl API Key 生成/验证/删除
AppComponentService / AppComponentServiceImpl 应用组件管理
McpServerService / McpServerServiceImpl MCP Server CRUD
Oauth2Service / GitHubOAuth2ServiceImpl OAuth2 登录（GitHub）
ReferService / ReferServiceImpl 关联引用管理
AgentSchemaService / AgentSchemaServiceImpl Agent Schema CRUD

Manager（中间件管理层）：

Manager 说明
RedisManager Redis 操作封装（Redisson）
ModelManager 模型注册/查找
ModelExecuteManager 模型执行（ChatModel 调用）
ProviderManager 模型提供商管理
OssManager 阿里云 OSS 文件存储
FileManager 文件上传/下载
DocumentRetrieverManager 文档检索（ES + Spring AI）
HttpClientManager HTTP 客户端管理
MCPManager MCP Server 连接管理
SandboxManager 沙箱执行（脚本节点）
TokenManager Token 计数/限流

Agent（执行引擎）：

类 说明
AgentExecutor 执行器接口
AbstractAgentExecutor 抽象执行器基类
BasicAgentExecutor 基础 Agent 执行器
WorkflowAgentExecutor 工作流执行器
AgentContext 执行上下文
ConversationChatMemory 会话记忆

Agent Tool（工具回调）：

类 说明
AgentToolCallback 通用工具回调
PluginToolCallback 插件工具回调
McpToolCallback MCP 工具回调
AppComponentToolCallback 应用组件工具回调
CompositeToolCallbackProvider 组合工具提供者
ToolArgumentsHelper 工具参数解析助手

MQ（消息队列）：

类 说明
MqConfig MQ 配置
MqConfigProperties MQ 配置属性
MqProducerManager 生产者管理
MqConsumerManager 消费者管理
MqConsumerHandler 消费者处理器
MqMessage 消息体
SendCallback / SendResult 发送回调/结果

配置类：

配置类 说明
MybatisPlusConfig MyBatis-Plus 配置
RedissonConfig Redisson 配置
JwtConfigProperties JWT 配置属性
MqConfigProperties MQ 配置属性
OAuth2Config OAuth2 配置
CommonConfig 公共配置
ScriptEngineConfig 脚本引擎配置（GraalVM JS/Python）
StudioProperties Studio 全局配置属性
ElasticsearchConfig ES 配置
FileStorageConfig 文件存储配置
SwaggerConfig Swagger/OpenAPI 解析配置
AppChannelConfig 应用渠道配置

其他子包：

子包 说明
context/ RequestContextHolder（ThreadLocal 请求上下文）
workflow/ WorkflowContext（工作流执行上下文）
model/ 模型相关工具
rag/ RAG 相关组件
utils/ 通用工具类（IdGenerator、JsonUtils、LogUtils 等）
base/constants/ 常量定义（CacheConstants）

3.3 server-openapi --- 开放 API

职责 ：提供 OpenAI 兼容风格的 API 端点，供外部系统通过 API Key 调用。

ChatController（@RequestMapping("/api/v1/apps")）：

端点 方法 说明
/api/v1/apps/chat/completions POST Agent 对话（支持 SSE 流式）
/api/v1/apps/workflow/completions POST 工作流对话（支持 SSE 流式）
/api/v1/apps/workflow/async-completions POST 异步工作流执行
/api/v1/apps/workflow/stop-completions POST 停止异步任务
/api/v1/apps/workflow/async-results POST 获取异步结果（从 Redis 读取）

ApiKeyAuthInterceptor：

  • 验证 Authorization: Bearer sk-xxx 请求头
  • 从 api_key 表查询 API Key 有效性
  • 设置 RequestContext（accountId、workspaceId 等）
  • 无效 Key 返回 HTTP 401

认证流程：

3.4 server-start --- 启动模块

职责 ：Spring Boot 入口、管理端 Controller、评估/Prompt/可观测性模块、项目脚手架生成。

SaaStudioAdmin.java 入口类：

java 复制代码 
@SpringBootApplication
@MapperScan("com.alibaba.cloud.ai.studio.admin.mapper")
@ComponentScan(basePackages = { "com.alibaba.cloud.ai.studio" })
@EnableConfigurationProperties(StudioProperties.class)
public class SaaStudioAdmin {
    public static void main(String[] args) {
        SpringApplication.run(SaaStudioAdmin.class).registerShutdownHook();
    }
}

包结构：

bash 复制代码 
com.alibaba.cloud.ai.studio.admin/
├── SaaStudioAdmin.java              # 入口类
├── builder/                         # 管理后台业务
│   ├── controller/                  # 业务 Controller（21 个）
│   ├── advice/                      # 全局异常处理
│   ├── annotation/                  # 自定义注解
│   ├── aspect/                      # AOP 切面
│   ├── interceptor/                 # 拦截器（JWT 认证）
│   ├── resolver/                    # 参数解析器
│   ├── utils/                       # 工具类
│   └── generator/                   # 项目代码生成
│       ├── controller/              # Generator Controller（4 个）
│       └── config/
├── controller/                      # 评估/Prompt/可观测性 Controller（6 个）
├── service/                         # 评估/Prompt 相关 Service（13 个）
├── entity/                          # 评估/Prompt 相关实体（12 个，JPA 注解）
├── mapper/                          # 评估/Prompt 相关 Mapper
├── repository/                      # JPA Repository
├── config/                          # 启动模块配置
├── dto/                             # 数据传输对象
├── enums/                           # 枚举类
├── exception/                       # 异常类
├── observation/                     # 可观测性
├── tracing/                         # 链路追踪
└── utils/                           # 工具类

3.4.1 Controller 层

管理后台业务 Controller：

Controller 请求映射 说明
AppController /console/v1/apps 应用 CRUD、发布、版本管理
AppChatController /console/v1/apps Agent SSE 对话（/chat/completions）
WorkflowController /console/v1/apps 工作流调试（/apps/workflow/debug/*）
KnowledgeBaseController /console/v1/knowledge-bases 知识库 CRUD
DocumentController /console/v1/knowledge-bases 文档管理
DocumentChunkController /console/v1/documents 文档切片 CRUD
ModelController /console/v1/models 模型 CRUD
ProviderController /console/v1/providers 模型提供商管理
PluginController /console/v1 插件 CRUD（/plugins/*）
ToolController /console/v1/tools 工具 CRUD
AppComponentController /console/v1/component-servers 应用组件管理
McpServerController /console/v1/mcp-servers MCP Server 管理
ApiKeyController /console/v1/api-keys API Key 管理
AccountController /console/v1/accounts 账号管理
AuthController /console/v1/auth 登录/注册
Oauth2Controller /oauth2 OAuth2 回调
WorkspaceController /console/v1/workspaces 工作空间
FileController /console/v1/files 文件上传/下载
SystemController /console/v1/system 系统信息
AgentSchemaController /console/v1/agent-schemas Agent Schema
ApiExampleController /test/api/example API 示例

项目脚手架生成 Controller：

Controller 说明
ApplicationController Spring Initializr 应用元数据
DSLController DSL 转换/导出
GeneratorController 项目代码生成
RunnerController 生成项目运行

评估/Prompt/可观测性 Controller ：

Controller 请求映射 说明
PromptController /api Prompt 模板管理
DatasetController /api/dataset 评测集管理
EvaluatorController /api/evaluator 评估器管理
ExperimentController /api 实验管理
ModelConfigController /api 模型配置
ObservabilityController /api/observability 可观测性（Tracing）

3.4.2 Entity 层

使用 JPA 注解（@Table），区别于 server-core 的 MyBatis-Plus（@TableName）。

实体 表名 说明
PromptDO prompt Prompt 模板
PromptVersionDO prompt_version Prompt 版本
PromptTemplateDO prompt_build_template Prompt 构建模板
ModelConfigDO model_config 模型配置
DatasetDO dataset 评测集
DatasetVersionDO dataset_version 评测集版本
DatasetItemDO dataset_item 评测数据项
EvaluatorDO evaluator 评估器
EvaluatorVersionDO evaluator_version 评估器版本
EvaluatorTemplateDO evaluator_template 评估器模板
ExperimentDO experiment 实验
ExperimentResultDO experiment_result 实验结果

3.4.3 Service 层

Service 说明
PromptService / PromptServiceImpl Prompt CRUD
PromptVersionService Prompt 版本管理
PromptTemplateService Prompt 模板管理
PromptRunService Prompt 试玩/运行
DatasetService 评测集管理
DatasetVersionService 评测集版本
DatasetItemService 数据项管理
EvaluatorService 评估器管理
EvaluatorVersionService 评估器版本
EvaluatorTemplateService 评估器模板
ExperimentService 实验管理
ModelConfigService 模型配置
ModelConfigBridgeService 模型配置桥接
TracingService 链路追踪查询
ChatSessionService 对话会话管理
NacosClientService Nacos 配置中心客户端

3.4.4 全局异常处理

类 说明
GlobalExceptionHandler @ControllerAdvice 统一异常拦截
RestExceptionHandler Generator 模块异常处理
GlobalResponseBodyAdvice 统一响应体包装

3.4.5 可观测性

组件 说明
Micrometer 指标收集
OpenTelemetry 链路追踪
OTLP Exporter OTLP 协议上报
Arms Observation 阿里云 ARMS 集成
Actuator 健康检查端点

3.5 数据表设计

后端共 27 张表 ，分布在两个 SQL 脚本中，使用不同的 ORM 框架。

3.5.1 agentscope-schema.sql

server-core 模块使用 MyBatis-Plus ，共计 15 张表：

表名 说明 关联关系 预置数据
account 用户账号 workspace.N 默认账号 saa
workspace 工作空间 account.N 默认空间 ID=1
api_key API Key account.N ---
application 应用（Agent/Workflow） workspace.N ---
application_version 应用版本（含工作流节点配置 JSON） application.N ---
application_component 应用组件 workspace.N ---
plugin 插件 workspace.N ---
tool 工具（含 API Schema） plugin.N ---
agent_schema Agent Schema（类型/指令/子Agent配置） workspace.N ---
provider 模型提供商 workspace.N Tongyi
model 模型配置（类型/模式/标签） provider.N 20+ Qwen 模型
knowledge_base 知识库 workspace.N ---
document 文档（含解析路径/切片配置） knowledge_base.N ---
mcp_server MCP Server（部署配置/安装方式） workspace.N ---
reference 多态关联表（跨实体引用） --- ---

3.5.2 admin-schema.sql

server-start 模块使用 JPA ，共计 12 张表：

表名 说明 关联关系 预置数据
prompt Prompt 模板主表 prompt_version.N ---
prompt_version Prompt 版本（模版内容+变量+模型配置） prompt.N ---
prompt_build_template Prompt 构建模板库 独立 8 个模板
model_config 评测模型配置（JSON 参数定义） 独立 ---
dataset 评测集主表 dataset_version.N、dataset_item.N ---
dataset_version 评测集版本 dataset.N ---
dataset_item 评测数据项 dataset.N ---
evaluator 评估器主表 evaluator_version.N ---
evaluator_version 评估器版本（Prompt+模型配置） evaluator.N ---
evaluator_template 评估器模板库 独立 3 个模板
experiment 实验（关联数据集版本+评估器版本） 关联 dataset_version、evaluator_version ---
experiment_result 实验结果（评分+评估原因） experiment.N ---
相关推荐
快乐的哈士奇5 小时前
对话框打字机效果：Vur + Java/Python 实现
java·开发语言·python
智慧景区与市集主理人5 小时前
商户摊位规范经营！巨有科技助力优化景区商业管控体系
大数据·人工智能·科技
@蔓蔓喜欢你5 小时前
前端状态管理方案：从简单到复杂的演进
人工智能·ai
九皇叔叔5 小时前
Spring-Ai-Alibaba [02] chatclient-demo
java·人工智能·spring·ai
山西茄子5 小时前
DeepStream9.0 inference_builder
人工智能·deepstream
@蔓蔓喜欢你5 小时前
Docker 部署实战：前端应用容器化指南
人工智能·ai
Dicky-_-zhang5 小时前
服务网格Istio mTLS配置实战
java·jvm
鲸采云SRM采购管理系统5 小时前
供应链高效管控：依托鲸采云 SRM AI+飞书 精准筛选优质供应商
人工智能·飞书
@蔓蔓喜欢你5 小时前
前端架构演进：从单体到微前端
人工智能·ai
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03CC-Switch & Claude 基于 Linux 服务器安装使用指南04【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法05【AI】2026 年具身智能模型和世界模型总结06几个好用的ip纯净度检测网站07装上就回不去了：CodeGraph 让 AI 编程效率飙升 92%，它到底做了什么？08裂开！ChatGPT 居然开始要手机号验证，附详细解决方法09用了半年 OpenRouter，我换到了 Ofox.ai — 两个 AI API 聚合平台的真实对比10codex app每次打开重连5次Reconnecting问题解决