124 lines
2.7 KiB
Markdown
124 lines
2.7 KiB
Markdown
# Keyborad Backend
|
||
|
||
基于 Spring Boot 3.5.5 的后端服务，集成了 AI 能力、向量搜索、Apple 登录等功能。
|
||
|
||
## 技术栈
|
||
|
||
- **Java 17** + **Spring Boot 3.5.5**
|
||
- **Spring AI** - LLM 对话和文本嵌入（OpenAI 兼容 API）
|
||
- **Qdrant** - 向量数据库，支持语义搜索
|
||
- **PostgreSQL** - 关系型数据库
|
||
- **MyBatis Plus** - ORM 框架
|
||
- **Redis** - 会话存储和缓存
|
||
- **Sa-Token** - 认证授权框架
|
||
- **Knife4j** - API 文档
|
||
- **X-File-Storage** - 文件上传（Cloudflare R2）
|
||
- **MailerSend** - 邮件服务
|
||
|
||
## 核心功能
|
||
|
||
### 认证系统
|
||
- Apple Sign-In JWT 验证
|
||
- Sa-Token 会话管理
|
||
- 请求签名校验（防篡改/防重放）
|
||
|
||
### AI 能力
|
||
- LLM 对话（支持流式响应）
|
||
- 文本嵌入（1536 维向量）
|
||
- 语义搜索（Qdrant 向量检索）
|
||
|
||
### 通用功能
|
||
- 统一响应格式
|
||
- 全局异常处理
|
||
- 国际化支持（i18n）
|
||
- 请求日志记录
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- JDK 17+
|
||
- Maven 3.8+
|
||
- PostgreSQL 14+
|
||
- Redis 6+
|
||
|
||
### 本地运行
|
||
|
||
1. 克隆项目
|
||
```bash
|
||
git clone <repository-url>
|
||
cd keyborad-backend
|
||
```
|
||
|
||
2. 配置数据库和 Redis
|
||
```yaml
|
||
# 修改 src/main/resources/application-dev.yml
|
||
spring:
|
||
datasource:
|
||
url: jdbc:postgresql://localhost:5432/keyborad_db
|
||
username: your_username
|
||
password: your_password
|
||
redis:
|
||
host: localhost
|
||
port: 6379
|
||
```
|
||
|
||
3. 启动应用
|
||
```bash
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
4. 访问 API 文档
|
||
```
|
||
http://localhost:7529/api/doc.html
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/main/java/com/yolo/keyborad/
|
||
├── controller/ # REST API 端点
|
||
├── service/ # 业务逻辑层
|
||
│ └── impl/ # 服务实现
|
||
├── mapper/ # MyBatis 数据库映射
|
||
├── model/
|
||
│ ├── entity/ # 数据库实体
|
||
│ ├── dto/ # 请求数据传输对象
|
||
│ └── vo/ # 响应视图对象
|
||
├── config/ # Spring 配置类
|
||
├── aop/ # AOP 拦截器
|
||
├── Interceptor/ # 请求拦截器
|
||
├── filter/ # Servlet 过滤器
|
||
├── exception/ # 异常处理
|
||
├── common/ # 通用工具类
|
||
└── utils/ # 工具类
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
| 配置项 | 说明 | 默认值 |
|
||
|-------|------|-------|
|
||
| `server.port` | 服务端口 | 7529 |
|
||
| `server.servlet.context-path` | 上下文路径 | /api |
|
||
| `spring.profiles.active` | 激活配置文件 | dev |
|
||
|
||
## API 认证
|
||
|
||
### Sa-Token 认证
|
||
需要在请求头中携带 `satoken` 字段。
|
||
|
||
### 请求签名
|
||
部分接口需要签名校验，请求头需包含：
|
||
- `X-App-Id` - 应用 ID
|
||
- `X-Timestamp` - 时间戳
|
||
- `X-Nonce` - 随机数
|
||
- `X-Sign` - 签名
|
||
|
||
## 开发指南
|
||
|
||
详细的开发指南请参考 [CLAUDE.md](./CLAUDE.md)。
|
||
|
||
## License
|
||
|
||
MIT License
|