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. 克隆项目

git clone <repository-url>
cd keyborad-backend

2. 配置数据库和 Redis

# 修改 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. 启动应用

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。

License

MIT License