系统架构总览
整体架构
Snail AI 采用 Server-Agent 分布式架构，前端通过 HTTP 与 Server 交互，Server 通过 gRPC 双向流将大模型调用分发至 Agent Client 执行。整体架构如下：
端口规划
| 端口 | 协议 | 用途 | 说明 |
|---|---|---|---|
| 8080 | HTTP | Web 服务端口 | Admin REST API + OpenAPI 外部接口 + SSE 流式响应 |
| 18888 | gRPC | Server 端 gRPC 监听 | 接收 Client 节点注册、心跳，向 Client 分发模型调用任务 |
| 18889 | gRPC | Client 端 gRPC 监听 | Client 节点启动后监听此端口，接收 Server 下发的调用请求 |
Maven 模块结构
Snail AI 后端采用 7 个 Maven 模块 的分层架构，职责清晰，依赖关系自底向上：
模块详细说明
| 模块 | 定位 | 核心内容 |
|---|---|---|
| snail-ai-commons | 共享基础层 | DTO/VO 定义、gRPC Proto 文件、枚举常量、通用工具类、异常定义 |
| snail-ai-persistence | 数据访问层 | MyBatis-Plus Mapper、向量存储适配器（PgVector/Milvus/ES）、搜索引擎适配器、MinIO 文件操作 |
| snail-ai-features | 核心业务层 | Agent 责任链引擎、模型管理、RAG 流水线、记忆系统、技能加载、MCP 集成、资源管理 |
| snail-ai-agent | 客户端 SDK | 拦截器链（Interceptor）、Advisor 流水线、工具注册、gRPC Handler、客户端启动配置 |
| snail-ai-admin | 管理 API 层 | 后台管理 REST Controller（Agent/RAG/Model/MCP/Skill/Memory/App/User/Resource 等） |
| snail-ai-openapi | 外部 API 层 | 面向第三方系统的 API 接口（认证、对话、RAG 查询），使用独立的认证体系 |
| snail-ai-starter | 启动模块 | Spring Boot 主入口、自动配置、配置文件（application.yml）、启动脚本 |
依赖关系说明
snail-ai-starter
├── snail-ai-admin → 管理后台 Controller
│ └── snail-ai-features → 核心业务 Service
│ ├── snail-ai-persistence → 数据访问
│ │ └── snail-ai-commons → 共享基础
│ └── snail-ai-commons
├── snail-ai-openapi → 外部接口 Controller
│ └── snail-ai-features
└── snail-ai-agent → 客户端 SDK（可选引入）
└── snail-ai-commons技术选型决策
为什么选择 Spring AI 2.0
核心理由：
- 生态亲和性 -- 企业 Java 团队普遍使用 Spring 技术栈，Spring AI 无缝融合现有技术体系
- 模型抽象统一 --
ChatModel、EmbeddingModel接口屏蔽了不同供应商的差异，切换模型零成本 - Advisor 流水线 -- 天然支持请求/响应的前后处理，与 Snail AI 的责任链设计完美对齐
- 生产级能力 -- 内置重试、限流、可观测性等企业级特性
为什么选择 gRPC 双向流
| 对比维度 | gRPC 双向流 | HTTP 长轮询 | WebSocket |
|---|---|---|---|
| 流式传输 | 原生支持双向流 | 需轮询模拟 | 支持 |
| 序列化效率 | Protobuf（高效二进制） | JSON（文本） | JSON/Binary |
| 服务治理 | 原生负载均衡、拦截器 | 需额外网关 | 需额外治理 |
| 类型安全 | Proto 强类型 | 无 | 无 |
| 跨语言 | 原生多语言支持 | 通用 | 通用 |
| 适用场景 | 微服务内部通信 | 简单前后端交互 | 实时前端交互 |
选型结论： Server 与 Client 之间是内部服务通信，gRPC 双向流在性能、类型安全和服务治理方面均优于其他方案。前端与 Server 之间则使用 HTTP + SSE，兼顾兼容性和实时性。
为什么支持多数据库
设计原则： 同一份代码、同一份配置，通过切换数据库连接和方言即可适配不同的数据库。这对满足不同企业的数据库选型偏好和国产化信创合规要求至关重要。
请求生命周期
一次完整的用户对话请求经历以下阶段：
安全架构
| 安全层面 | 实现方式 |
|---|---|
| 会话认证 | Sa-Token（Admin API），支持 Token 刷新和登出 |
| 外部认证 | App Token（OpenAPI），一个 App 一个 Token |
| 角色管理 | 管理员 / 普通用户两级角色，管理员可管理所有资源 |
| 配额控制 | 按用户维度限制 Token 消耗量和调用次数，到期自动失效 |
| 数据隔离 | 用户数据按 userId 隔离，智能体市场通过订阅机制授权访问 |
| 密钥安全 | 模型 API Key 加密存储，前端不返回明文 |