217 lines
5.2 KiB
Markdown
217 lines
5.2 KiB
Markdown
# TangledupAI API 数据库服务
|
||
|
||
这是一个基于 FastAPI 构建的后端 API 服务，为 TangledupAI 提供用户管理、Agent 卡片管理、对话管理和文件存储等功能。
|
||
|
||
## 功能特性
|
||
|
||
- **用户管理**: 用户注册、查询、更新
|
||
- **Agent 管理**: 创建、查询、更新、删除 Agent 卡片
|
||
- **对话管理**: 创建对话、保存消息
|
||
- **短信服务**: 发送验证码短信
|
||
- **文件存储**: 基于阿里云 OSS 的文件上传、删除、查询
|
||
- **API 安全**: 基于 API Key 的身份验证
|
||
|
||
## 技术栈
|
||
|
||
- **后端框架**: FastAPI
|
||
- **数据库**: PostgreSQL
|
||
- **对象存储**: 阿里云 OSS
|
||
- **短信服务**: 阿里云短信服务
|
||
- **部署**: Docker & Docker Compose
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
API_database/
|
||
├── main.py # 主应用程序入口
|
||
├── config.py # 配置管理
|
||
├── models.py # 数据模型
|
||
├── oss_service.py # 阿里云 OSS 服务
|
||
├── sms.py # 短信服务
|
||
├── utils.py # 工具函数
|
||
├── requirements.txt # Python 依赖
|
||
├── Dockerfile # Docker 镜像构建文件
|
||
├── docker-compose.yml # Docker Compose 配置
|
||
└── .env # 环境变量配置
|
||
```
|
||
|
||
## 安装与运行
|
||
|
||
### 环境要求
|
||
|
||
- Python 3.12+
|
||
- PostgreSQL 数据库
|
||
- 阿里云 OSS 账号
|
||
- 阿里云短信服务账号
|
||
|
||
### 本地开发
|
||
|
||
1. 克隆仓库
|
||
```bash
|
||
git clone <repository-url>
|
||
cd API_database
|
||
```
|
||
|
||
2. 安装依赖
|
||
```bash
|
||
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple
|
||
```
|
||
|
||
3. 配置环境变量
|
||
创建 `.env` 文件并配置以下变量：
|
||
```env
|
||
API_KEY=your_api_key
|
||
DB_HOST=your_db_host
|
||
DB_PORT=your_db_port
|
||
DB_NAME=your_db_name
|
||
DB_USER=your_db_user
|
||
DB_PASSWORD=your_db_password
|
||
DB_SSLMODE=disable
|
||
|
||
# 阿里云 OSS 配置
|
||
OSS_ACCESS_KEY_ID=your_oss_access_key_id
|
||
OSS_ACCESS_KEY_SECRET=your_oss_access_key_secret
|
||
OSS_ENDPOINT=https://oss-cn-shanghai.aliyuncs.com
|
||
OSS_BUCKET_NAME=your_bucket_name
|
||
```
|
||
|
||
4. 启动应用
|
||
```bash
|
||
uvicorn main:app --reload --host 0.0.0.0 --port 9090
|
||
```
|
||
|
||
### Docker 部署
|
||
|
||
1. 使用 Docker Compose
|
||
```bash
|
||
# 设置环境变量
|
||
export API_KEY=your_api_key
|
||
export DB_HOST=your_db_host
|
||
export DB_PORT=your_db_port
|
||
export DB_NAME=your_db_name
|
||
export DB_USER=your_db_user
|
||
export DB_PASSWORD=your_db_password
|
||
export DB_SSLMODE=disable
|
||
|
||
# 启动服务
|
||
docker-compose up -d
|
||
```
|
||
|
||
2. 或者直接使用 Docker
|
||
```bash
|
||
docker build -t tangledup-api .
|
||
docker run -d -p 9090:9090 \
|
||
-e API_KEY=your_api_key \
|
||
-e DB_HOST=your_db_host \
|
||
-e DB_PORT=your_db_port \
|
||
-e DB_NAME=your_db_name \
|
||
-e DB_USER=your_db_user \
|
||
-e DB_PASSWORD=your_db_password \
|
||
-e DB_SSLMODE=disable \
|
||
tangledup-api
|
||
```
|
||
|
||
## API 文档
|
||
|
||
启动服务后，可以通过以下地址访问 API 文档：
|
||
|
||
- Swagger UI: http://localhost:9090/docs
|
||
- ReDoc: http://localhost:9090/redoc
|
||
|
||
## API 端点
|
||
|
||
### 用户管理
|
||
|
||
- `POST /register/` - 用户注册
|
||
- `GET /user/{phone}` - 获取用户信息
|
||
- `PUT /user/{phone}` - 更新用户信息
|
||
|
||
### Agent 管理
|
||
|
||
- `POST /new_agent/` - 创建 Agent 卡片
|
||
- `GET /agents/{phone}` - 获取用户的所有 Agent 卡片
|
||
- `GET /agent_id/{agent_id}` - 根据 ID 获取 Agent 卡片
|
||
- `PUT /agent/{phone_number}/{agent_name}` - 更新 Agent 卡片
|
||
- `PUT /agent_id/{agent_id}` - 根据 ID 更新 Agent 卡片
|
||
- `DELETE /agent/{phone_number}/{agent_name}` - 删除 Agent 卡片
|
||
- `DELETE /agent_id/{agent_id}` - 根据 ID 删除 Agent 卡片
|
||
|
||
### 对话管理
|
||
|
||
- `POST /conversations/` - 创建新对话
|
||
- `POST /messages/` - 保存消息
|
||
|
||
### 文件上传
|
||
|
||
- `POST /upload_image/` - 上传图片
|
||
- `POST /upload` - 上传文件到 OSS
|
||
|
||
### 短信服务
|
||
|
||
- `POST /api/send-sms` - 发送验证码
|
||
- `POST /api/send-sms/diy` - 发送定制短信
|
||
- `GET /api/sms-records` - 获取短信记录
|
||
|
||
### OSS 服务
|
||
|
||
- `POST /test/` - 测试 OSS 连接
|
||
|
||
## 身份验证
|
||
|
||
所有 API 端点都需要在请求头中包含有效的 API Key：
|
||
|
||
```
|
||
x-api-key: 123tangledup-ai
|
||
```
|
||
|
||
## 数据库表结构
|
||
|
||
### users 表
|
||
- phone_number: 手机号码 (主键)
|
||
- user_name: 用户名
|
||
- user_details: 用户详情
|
||
- avatar: 头像URL
|
||
- email: 邮箱
|
||
- points: 积分
|
||
- create_date: 创建时间
|
||
|
||
### agent_cards 表
|
||
- card_id: 卡片ID (主键)
|
||
- phone_number: 用户手机号码
|
||
- card_info: 卡片信息
|
||
- agent_avatar_url: Agent头像URL
|
||
- agent_prompt: Agent提示
|
||
- agent_name: Agent名称
|
||
- is_publish: 是否发布
|
||
- create_date: 创建时间
|
||
- voice_type: 语音类型
|
||
- temperature: 温度参数
|
||
|
||
### conversations 表
|
||
- conversation_id: 对话ID (主键)
|
||
- user_phone: 用户手机号码
|
||
- visitor_key: 访客密钥
|
||
- agent_card_id: Agent卡片ID
|
||
|
||
### messages 表
|
||
- message_id: 消息ID (主键)
|
||
- conversation_id: 对话ID
|
||
- sender: 发送者 (user/agent)
|
||
- content: 消息内容
|
||
- order: 消息顺序
|
||
|
||
## 贡献指南
|
||
|
||
1. Fork 本仓库
|
||
2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 打开一个 Pull Request
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
|
||
|
||
## 联系方式
|
||
|
||
如有问题或建议，请联系项目维护者。 |