feat: 初始化考培练系统项目
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
111
0
backend/docs/__init__.py
Normal file
0
backend/docs/__init__.py
Normal file
0
backend/docs/api/__init__.py
Normal file
0
backend/docs/api/__init__.py
Normal file
227
backend/docs/database_rollback_guide.md
Normal file
227
backend/docs/database_rollback_guide.md
Normal file
@@ -0,0 +1,227 @@
|
||||
# 考培练系统数据库回滚指南
|
||||
|
||||
## 概述
|
||||
|
||||
考培练系统支持基于MySQL Binlog的数据库回滚功能，可以快速恢复误操作导致的数据变更。本指南提供了完整的回滚操作流程和最佳实践。
|
||||
|
||||
## 回滚方案对比
|
||||
|
||||
| 方案 | 适用场景 | 优点 | 缺点 | 推荐度 |
|
||||
|------|----------|------|------|--------|
|
||||
| **Binlog回滚** | 精确时间点回滚 | 精确、完整 | 需要技术知识 | ⭐⭐⭐⭐⭐ |
|
||||
| **软删除恢复** | 删除操作回滚 | 简单、安全 | 仅限软删除 | ⭐⭐⭐⭐ |
|
||||
| **备份恢复** | 大规模回滚 | 完整恢复 | 可能丢失新数据 | ⭐⭐⭐ |
|
||||
| **手动修复** | 小范围修复 | 灵活 | 容易出错 | ⭐⭐ |
|
||||
|
||||
## 一、Binlog回滚（推荐）
|
||||
|
||||
### 1.1 前提条件检查
|
||||
|
||||
```bash
|
||||
# 检查Binlog是否启用
|
||||
docker exec kaopeilian-mysql mysql -uroot -proot -e "SHOW VARIABLES LIKE 'log_bin';"
|
||||
|
||||
# 检查Binlog格式（推荐ROW格式）
|
||||
docker exec kaopeilian-mysql mysql -uroot -proot -e "SHOW VARIABLES LIKE 'binlog_format';"
|
||||
|
||||
# 查看可用的Binlog文件
|
||||
docker exec kaopeilian-mysql mysql -uroot -proot -e "SHOW BINARY LOGS;"
|
||||
```
|
||||
|
||||
### 1.2 使用专用回滚工具
|
||||
|
||||
#### 查看最近变更
|
||||
```bash
|
||||
cd /Users/nongjun/Desktop/Ai公司/本地开发与测试/kaopeilian-backend
|
||||
python scripts/kaopeilian_rollback.py --list --hours 24
|
||||
```
|
||||
|
||||
#### 回滚用户操作
|
||||
```bash
|
||||
# 模拟回滚（查看会执行什么操作）
|
||||
python scripts/kaopeilian_rollback.py --rollback-user 123 --operation-type delete
|
||||
|
||||
# 实际执行回滚
|
||||
python scripts/kaopeilian_rollback.py --rollback-user 123 --operation-type delete --execute
|
||||
```
|
||||
|
||||
#### 回滚课程操作
|
||||
```bash
|
||||
# 回滚课程删除
|
||||
python scripts/kaopeilian_rollback.py --rollback-course 456 --operation-type delete --execute
|
||||
|
||||
# 回滚课程更新（需要手动处理）
|
||||
python scripts/kaopeilian_rollback.py --rollback-course 456 --operation-type update
|
||||
```
|
||||
|
||||
#### 回滚考试操作
|
||||
```bash
|
||||
# 回滚考试记录（会同时删除考试和考试结果）
|
||||
python scripts/kaopeilian_rollback.py --rollback-exam 789 --execute
|
||||
```
|
||||
|
||||
### 1.3 使用简化回滚工具
|
||||
|
||||
#### 查看Binlog文件
|
||||
```bash
|
||||
python scripts/simple_rollback.py --list
|
||||
```
|
||||
|
||||
#### 基于时间点回滚
|
||||
```bash
|
||||
# 模拟回滚到指定时间点
|
||||
python scripts/simple_rollback.py --time "2024-12-20 10:30:00"
|
||||
|
||||
# 实际执行回滚
|
||||
python scripts/simple_rollback.py --time "2024-12-20 10:30:00" --execute
|
||||
```
|
||||
|
||||
### 1.4 使用完整Binlog工具
|
||||
|
||||
```bash
|
||||
# 查看帮助
|
||||
python scripts/binlog_rollback_tool.py --help
|
||||
|
||||
# 列出Binlog文件
|
||||
python scripts/binlog_rollback_tool.py --list-binlogs
|
||||
|
||||
# 回滚到指定时间点
|
||||
python scripts/binlog_rollback_tool.py --time "2024-12-20 10:30:00" --execute
|
||||
```
|
||||
|
||||
## 二、软删除恢复
|
||||
|
||||
### 2.1 恢复用户
|
||||
```sql
|
||||
-- 恢复软删除的用户
|
||||
UPDATE users SET is_deleted = FALSE, deleted_at = NULL WHERE id = 123;
|
||||
```
|
||||
|
||||
### 2.2 恢复课程
|
||||
```sql
|
||||
-- 恢复软删除的课程
|
||||
UPDATE courses SET is_deleted = FALSE, deleted_at = NULL WHERE id = 456;
|
||||
```
|
||||
|
||||
### 2.3 恢复岗位
|
||||
```sql
|
||||
-- 恢复软删除的岗位
|
||||
UPDATE positions SET is_deleted = FALSE, deleted_at = NULL WHERE id = 789;
|
||||
```
|
||||
|
||||
## 三、备份恢复
|
||||
|
||||
### 3.1 创建完整备份
|
||||
```bash
|
||||
# 创建数据库完整备份
|
||||
docker exec kaopeilian-mysql mysqldump -uroot -proot --single-transaction --routines --triggers kaopeilian > backup_$(date +%Y%m%d_%H%M%S).sql
|
||||
```
|
||||
|
||||
### 3.2 恢复备份
|
||||
```bash
|
||||
# 恢复数据库备份
|
||||
docker exec -i kaopeilian-mysql mysql -uroot -proot kaopeilian < backup_20241220_103000.sql
|
||||
```
|
||||
|
||||
## 四、常见回滚场景
|
||||
|
||||
### 4.1 误删用户
|
||||
```bash
|
||||
# 1. 查看最近删除的用户
|
||||
python scripts/kaopeilian_rollback.py --list --hours 1
|
||||
|
||||
# 2. 恢复软删除的用户
|
||||
python scripts/kaopeilian_rollback.py --rollback-user 123 --operation-type delete --execute
|
||||
```
|
||||
|
||||
### 4.2 误删课程
|
||||
```bash
|
||||
# 1. 恢复软删除的课程
|
||||
python scripts/kaopeilian_rollback.py --rollback-course 456 --operation-type delete --execute
|
||||
|
||||
# 2. 恢复课程关联数据（如果需要）
|
||||
# 手动执行SQL恢复课程资料、知识点等
|
||||
```
|
||||
|
||||
### 4.3 误删考试记录
|
||||
```bash
|
||||
# 1. 恢复考试记录（会同时恢复考试结果）
|
||||
python scripts/kaopeilian_rollback.py --rollback-exam 789 --execute
|
||||
```
|
||||
|
||||
### 4.4 批量误操作
|
||||
```bash
|
||||
# 1. 基于时间点回滚
|
||||
python scripts/simple_rollback.py --time "2024-12-20 10:30:00" --execute
|
||||
|
||||
# 2. 或使用完整备份恢复
|
||||
docker exec -i kaopeilian-mysql mysql -uroot -proot kaopeilian < backup_before_operation.sql
|
||||
```
|
||||
|
||||
## 五、最佳实践
|
||||
|
||||
### 5.1 回滚前准备
|
||||
1. **创建备份**：回滚前必须创建当前数据备份
|
||||
2. **确认时间点**：精确确定需要回滚到的时间点
|
||||
3. **评估影响**：评估回滚操作对系统的影响
|
||||
4. **通知用户**：必要时通知相关用户
|
||||
|
||||
### 5.2 回滚操作流程
|
||||
1. **停止服务**：停止可能影响数据的服务
|
||||
2. **创建备份**：备份当前状态
|
||||
3. **执行回滚**：使用合适的回滚工具
|
||||
4. **验证数据**：验证回滚结果
|
||||
5. **重启服务**：恢复服务运行
|
||||
6. **记录日志**：记录回滚操作日志
|
||||
|
||||
### 5.3 安全注意事项
|
||||
- 回滚操作不可逆，务必谨慎
|
||||
- 生产环境回滚前必须在测试环境验证
|
||||
- 重要操作需要多人确认
|
||||
- 保留回滚操作日志
|
||||
|
||||
## 六、故障排除
|
||||
|
||||
### 6.1 Binlog未启用
|
||||
```bash
|
||||
# 检查MySQL配置
|
||||
docker exec kaopeilian-mysql mysql -uroot -proot -e "SHOW VARIABLES LIKE 'log_bin';"
|
||||
|
||||
# 如果未启用，需要修改MySQL配置并重启
|
||||
```
|
||||
|
||||
### 6.2 Binlog文件过大
|
||||
```bash
|
||||
# 清理旧的Binlog文件
|
||||
docker exec kaopeilian-mysql mysql -uroot -proot -e "PURGE BINARY LOGS BEFORE DATE_SUB(NOW(), INTERVAL 7 DAY);"
|
||||
```
|
||||
|
||||
### 6.3 回滚工具执行失败
|
||||
1. 检查数据库连接
|
||||
2. 确认权限设置
|
||||
3. 查看错误日志
|
||||
4. 手动执行SQL语句
|
||||
|
||||
## 七、监控与预防
|
||||
|
||||
### 7.1 设置监控
|
||||
- 监控Binlog文件大小
|
||||
- 监控数据库操作日志
|
||||
- 设置异常操作告警
|
||||
|
||||
### 7.2 预防措施
|
||||
- 定期备份数据库
|
||||
- 设置操作权限控制
|
||||
- 实施操作审计
|
||||
- 提供操作确认机制
|
||||
|
||||
## 八、联系支持
|
||||
|
||||
如遇到回滚问题，请联系技术支持：
|
||||
- 查看系统日志：`docker logs kaopeilian-mysql`
|
||||
- 查看应用日志：`docker logs kaopeilian-backend`
|
||||
- 提交问题报告：包含错误信息、操作步骤、时间点等
|
||||
|
||||
---
|
||||
|
||||
**重要提醒**：数据库回滚是高风险操作，请务必在充分理解操作影响的前提下执行，建议在测试环境先验证回滚方案的有效性。
|
||||
0
backend/docs/deployment/__init__.py
Normal file
0
backend/docs/deployment/__init__.py
Normal file
0
backend/docs/development/__init__.py
Normal file
0
backend/docs/development/__init__.py
Normal file
664
backend/docs/openapi_sql_executor.json
Normal file
664
backend/docs/openapi_sql_executor.json
Normal file
@@ -0,0 +1,664 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "KaoPeiLian SQL Executor API",
|
||||
"description": "SQL 执行器 API，专门为 Dify 平台集成设计，支持对考陪练系统数据库执行查询和写入操作。\n\n## 主要功能\n- 执行 SQL 查询和写入操作\n- 支持参数化查询防止 SQL 注入\n- 获取数据库表列表和表结构\n- SQL 语句验证\n\n## 安全说明\n所有接口都需要 JWT Bearer Token 认证。请先通过登录接口获取访问令牌。",
|
||||
"version": "1.0.0",
|
||||
"contact": {
|
||||
"name": "KaoPeiLian Tech Support",
|
||||
"email": "support@kaopeilian.com"
|
||||
}
|
||||
},
|
||||
"servers": [
|
||||
{
|
||||
"url": "http://120.79.247.16:8000/api/v1",
|
||||
"description": "考陪练系统服务器"
|
||||
},
|
||||
{
|
||||
"url": "http://aiedu.ireborn.com.cn/api/v1",
|
||||
"description": "域名访问"
|
||||
}
|
||||
],
|
||||
"security": [
|
||||
{
|
||||
"bearerAuth": []
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"/auth/login": {
|
||||
"post": {
|
||||
"tags": ["认证"],
|
||||
"summary": "用户登录",
|
||||
"description": "获取访问令牌，用于后续 API 调用",
|
||||
"security": [],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/LoginRequest"
|
||||
},
|
||||
"examples": {
|
||||
"admin": {
|
||||
"summary": "管理员登录",
|
||||
"value": {
|
||||
"username": "admin",
|
||||
"password": "admin123"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "登录成功",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/LoginResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "用户名或密码错误",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/sql/execute": {
|
||||
"post": {
|
||||
"tags": ["SQL执行器"],
|
||||
"summary": "执行 SQL 语句",
|
||||
"description": "执行查询或写入 SQL 语句。\n\n**查询操作**: SELECT, SHOW, DESCRIBE\n**写入操作**: INSERT, UPDATE, DELETE, CREATE, ALTER, DROP\n\n支持参数化查询，使用 `:param_name` 格式定义参数。",
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/SqlExecuteRequest"
|
||||
},
|
||||
"examples": {
|
||||
"simpleQuery": {
|
||||
"summary": "简单查询",
|
||||
"value": {
|
||||
"sql": "SELECT id, username, role FROM users LIMIT 5"
|
||||
}
|
||||
},
|
||||
"parameterizedQuery": {
|
||||
"summary": "参数化查询",
|
||||
"value": {
|
||||
"sql": "SELECT * FROM courses WHERE category = :category AND status = :status",
|
||||
"params": {
|
||||
"category": "护肤",
|
||||
"status": "active"
|
||||
}
|
||||
}
|
||||
},
|
||||
"insertData": {
|
||||
"summary": "插入数据",
|
||||
"value": {
|
||||
"sql": "INSERT INTO knowledge_points (title, content, course_id) VALUES (:title, :content, :course_id)",
|
||||
"params": {
|
||||
"title": "面部护理基础",
|
||||
"content": "面部护理的基本步骤...",
|
||||
"course_id": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "SQL 执行成功",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"oneOf": [
|
||||
{
|
||||
"$ref": "#/components/schemas/QueryResponse"
|
||||
},
|
||||
{
|
||||
"$ref": "#/components/schemas/ExecuteResponse"
|
||||
}
|
||||
]
|
||||
},
|
||||
"examples": {
|
||||
"queryResult": {
|
||||
"summary": "查询结果",
|
||||
"value": {
|
||||
"code": 200,
|
||||
"message": "SQL 执行成功",
|
||||
"data": {
|
||||
"type": "query",
|
||||
"columns": ["id", "username", "role"],
|
||||
"rows": [
|
||||
{
|
||||
"id": 1,
|
||||
"username": "admin",
|
||||
"role": "admin"
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"username": "user1",
|
||||
"role": "trainee"
|
||||
}
|
||||
],
|
||||
"row_count": 2
|
||||
}
|
||||
}
|
||||
},
|
||||
"executeResult": {
|
||||
"summary": "写入结果",
|
||||
"value": {
|
||||
"code": 200,
|
||||
"message": "SQL 执行成功",
|
||||
"data": {
|
||||
"type": "execute",
|
||||
"affected_rows": 1,
|
||||
"success": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "请求参数错误",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未认证或认证失败",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "SQL 执行错误",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/sql/validate": {
|
||||
"post": {
|
||||
"tags": ["SQL执行器"],
|
||||
"summary": "验证 SQL 语法",
|
||||
"description": "验证 SQL 语句的语法正确性，不执行实际操作",
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/SqlValidateRequest"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "验证完成",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ValidateResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/sql/tables": {
|
||||
"get": {
|
||||
"tags": ["SQL执行器"],
|
||||
"summary": "获取表列表",
|
||||
"description": "获取数据库中所有表的列表",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "成功获取表列表",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/TablesResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未认证",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/sql/table/{table_name}/schema": {
|
||||
"get": {
|
||||
"tags": ["SQL执行器"],
|
||||
"summary": "获取表结构",
|
||||
"description": "获取指定表的结构信息，包括字段名、类型、约束等",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "table_name",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"description": "表名",
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
|
||||
},
|
||||
"example": "users"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "成功获取表结构",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/TableSchemaResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "无效的表名",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "未认证",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"securitySchemes": {
|
||||
"bearerAuth": {
|
||||
"type": "http",
|
||||
"scheme": "bearer",
|
||||
"bearerFormat": "JWT",
|
||||
"description": "使用登录接口返回的 access_token。\n格式: Bearer {access_token}"
|
||||
}
|
||||
},
|
||||
"schemas": {
|
||||
"LoginRequest": {
|
||||
"type": "object",
|
||||
"required": ["username", "password"],
|
||||
"properties": {
|
||||
"username": {
|
||||
"type": "string",
|
||||
"description": "用户名",
|
||||
"example": "admin"
|
||||
},
|
||||
"password": {
|
||||
"type": "string",
|
||||
"format": "password",
|
||||
"description": "密码",
|
||||
"example": "admin123"
|
||||
}
|
||||
}
|
||||
},
|
||||
"LoginResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "integer",
|
||||
"example": 200
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"example": "登录成功"
|
||||
},
|
||||
"data": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"user": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "integer",
|
||||
"example": 1
|
||||
},
|
||||
"username": {
|
||||
"type": "string",
|
||||
"example": "admin"
|
||||
},
|
||||
"role": {
|
||||
"type": "string",
|
||||
"example": "admin"
|
||||
}
|
||||
}
|
||||
},
|
||||
"token": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"access_token": {
|
||||
"type": "string",
|
||||
"description": "JWT 访问令牌",
|
||||
"example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
|
||||
},
|
||||
"token_type": {
|
||||
"type": "string",
|
||||
"example": "bearer"
|
||||
},
|
||||
"expires_in": {
|
||||
"type": "integer",
|
||||
"description": "过期时间（秒）",
|
||||
"example": 1800
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"SqlExecuteRequest": {
|
||||
"type": "object",
|
||||
"required": ["sql"],
|
||||
"properties": {
|
||||
"sql": {
|
||||
"type": "string",
|
||||
"description": "要执行的 SQL 语句",
|
||||
"example": "SELECT * FROM users WHERE role = :role"
|
||||
},
|
||||
"params": {
|
||||
"type": "object",
|
||||
"description": "SQL 参数字典，键为参数名，值为参数值",
|
||||
"additionalProperties": true,
|
||||
"example": {
|
||||
"role": "admin"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"SqlValidateRequest": {
|
||||
"type": "object",
|
||||
"required": ["sql"],
|
||||
"properties": {
|
||||
"sql": {
|
||||
"type": "string",
|
||||
"description": "要验证的 SQL 语句",
|
||||
"example": "SELECT * FROM users"
|
||||
}
|
||||
}
|
||||
},
|
||||
"QueryResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "integer",
|
||||
"example": 200
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"example": "SQL 执行成功"
|
||||
},
|
||||
"data": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["query"],
|
||||
"example": "query"
|
||||
},
|
||||
"columns": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "列名数组",
|
||||
"example": ["id", "username", "role"]
|
||||
},
|
||||
"rows": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
},
|
||||
"description": "查询结果行"
|
||||
},
|
||||
"row_count": {
|
||||
"type": "integer",
|
||||
"description": "返回的行数",
|
||||
"example": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"ExecuteResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "integer",
|
||||
"example": 200
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"example": "SQL 执行成功"
|
||||
},
|
||||
"data": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["execute"],
|
||||
"example": "execute"
|
||||
},
|
||||
"affected_rows": {
|
||||
"type": "integer",
|
||||
"description": "影响的行数",
|
||||
"example": 1
|
||||
},
|
||||
"success": {
|
||||
"type": "boolean",
|
||||
"example": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"ValidateResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "integer",
|
||||
"example": 200
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"example": "SQL 验证完成"
|
||||
},
|
||||
"data": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"valid": {
|
||||
"type": "boolean",
|
||||
"description": "SQL 是否有效",
|
||||
"example": true
|
||||
},
|
||||
"warnings": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "警告信息列表",
|
||||
"example": ["包含危险操作: DROP"]
|
||||
},
|
||||
"sql_type": {
|
||||
"type": "string",
|
||||
"description": "SQL 类型",
|
||||
"example": "SELECT"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"TablesResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "integer",
|
||||
"example": 200
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"example": "获取表列表成功"
|
||||
},
|
||||
"data": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"tables": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": "表名列表",
|
||||
"example": ["users", "courses", "exams"]
|
||||
},
|
||||
"count": {
|
||||
"type": "integer",
|
||||
"description": "表的数量",
|
||||
"example": 20
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"TableSchemaResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "integer",
|
||||
"example": 200
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"example": "获取表结构成功"
|
||||
},
|
||||
"data": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"table_name": {
|
||||
"type": "string",
|
||||
"example": "users"
|
||||
},
|
||||
"columns": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"field": {
|
||||
"type": "string",
|
||||
"description": "字段名",
|
||||
"example": "id"
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"description": "字段类型",
|
||||
"example": "int(11)"
|
||||
},
|
||||
"null": {
|
||||
"type": "string",
|
||||
"enum": ["YES", "NO"],
|
||||
"description": "是否可为空",
|
||||
"example": "NO"
|
||||
},
|
||||
"key": {
|
||||
"type": "string",
|
||||
"description": "键类型（PRI, UNI, MUL）",
|
||||
"example": "PRI"
|
||||
},
|
||||
"default": {
|
||||
"type": "string",
|
||||
"nullable": true,
|
||||
"description": "默认值",
|
||||
"example": null
|
||||
},
|
||||
"extra": {
|
||||
"type": "string",
|
||||
"description": "额外信息",
|
||||
"example": "auto_increment"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"column_count": {
|
||||
"type": "integer",
|
||||
"description": "列的数量",
|
||||
"example": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"ErrorResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"detail": {
|
||||
"type": "string",
|
||||
"description": "错误详情",
|
||||
"example": "SQL 执行失败: You have an error in your SQL syntax"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"tags": [
|
||||
{
|
||||
"name": "认证",
|
||||
"description": "用户认证相关接口"
|
||||
},
|
||||
{
|
||||
"name": "SQL执行器",
|
||||
"description": "SQL 执行和管理相关接口"
|
||||
}
|
||||
]
|
||||
}
|
||||
568
backend/docs/openapi_sql_executor.yaml
Normal file
568
backend/docs/openapi_sql_executor.yaml
Normal file
@@ -0,0 +1,568 @@
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: KaoPeiLian SQL Executor API
|
||||
description: |
|
||||
SQL 执行器 API，专门为 Dify 平台集成设计，支持对考陪练系统数据库执行查询和写入操作。
|
||||
|
||||
## 主要功能
|
||||
- 执行 SQL 查询和写入操作
|
||||
- 支持参数化查询防止 SQL 注入
|
||||
- 获取数据库表列表和表结构
|
||||
- SQL 语句验证
|
||||
|
||||
## 安全说明
|
||||
所有接口都需要 JWT Bearer Token 认证。请先通过登录接口获取访问令牌。
|
||||
version: 1.0.0
|
||||
contact:
|
||||
name: KaoPeiLian Tech Support
|
||||
email: support@kaopeilian.com
|
||||
|
||||
servers:
|
||||
- url: http://120.79.247.16:8000/api/v1
|
||||
description: 考陪练系统服务器
|
||||
- url: http://localhost:8000/api/v1
|
||||
description: 本地开发服务器
|
||||
- url: http://aiedu.ireborn.com.cn/api/v1
|
||||
description: 域名访问
|
||||
|
||||
security:
|
||||
- bearerAuth: []
|
||||
|
||||
paths:
|
||||
/auth/login:
|
||||
post:
|
||||
tags:
|
||||
- 认证
|
||||
summary: 用户登录
|
||||
description: 获取访问令牌，用于后续 API 调用
|
||||
security: [] # 登录接口不需要认证
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LoginRequest'
|
||||
examples:
|
||||
admin:
|
||||
summary: 管理员登录
|
||||
value:
|
||||
username: admin
|
||||
password: admin123
|
||||
responses:
|
||||
'200':
|
||||
description: 登录成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LoginResponse'
|
||||
'401':
|
||||
description: 用户名或密码错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/sql/execute-simple:
|
||||
post:
|
||||
tags:
|
||||
- SQL执行器-简化认证
|
||||
summary: 执行 SQL 语句（简化认证版）
|
||||
description: |
|
||||
执行查询或写入 SQL 语句，使用简化的认证方式。
|
||||
|
||||
**认证方式（二选一）**：
|
||||
1. API Key: X-API-Key: dify-2025-kaopeilian
|
||||
2. 长期 Token: Authorization: Bearer permanent-token-for-dify-2025
|
||||
|
||||
**查询操作**: SELECT, SHOW, DESCRIBE
|
||||
**写入操作**: INSERT, UPDATE, DELETE, CREATE, ALTER, DROP
|
||||
|
||||
支持参数化查询，使用 `:param_name` 格式定义参数。
|
||||
security:
|
||||
- apiKey: []
|
||||
- bearerAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SqlExecuteRequest'
|
||||
examples:
|
||||
simpleQuery:
|
||||
summary: 简单查询
|
||||
value:
|
||||
sql: "SELECT id, username, role FROM users LIMIT 5"
|
||||
parameterizedQuery:
|
||||
summary: 参数化查询
|
||||
value:
|
||||
sql: "SELECT * FROM courses WHERE category = :category AND status = :status"
|
||||
params:
|
||||
category: "护肤"
|
||||
status: "active"
|
||||
insertData:
|
||||
summary: 插入数据
|
||||
value:
|
||||
sql: "INSERT INTO knowledge_points (title, content, course_id) VALUES (:title, :content, :course_id)"
|
||||
params:
|
||||
title: "面部护理基础"
|
||||
content: "面部护理的基本步骤..."
|
||||
course_id: 1
|
||||
responses:
|
||||
'200':
|
||||
description: SQL 执行成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/QueryResponse'
|
||||
- $ref: '#/components/schemas/ExecuteResponse'
|
||||
'401':
|
||||
description: 未认证或认证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'500':
|
||||
description: SQL 执行错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/sql/execute:
|
||||
post:
|
||||
tags:
|
||||
- SQL执行器
|
||||
summary: 执行 SQL 语句（标准认证版）
|
||||
description: |
|
||||
执行查询或写入 SQL 语句。
|
||||
|
||||
**查询操作**: SELECT, SHOW, DESCRIBE
|
||||
**写入操作**: INSERT, UPDATE, DELETE, CREATE, ALTER, DROP
|
||||
|
||||
支持参数化查询，使用 `:param_name` 格式定义参数。
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SqlExecuteRequest'
|
||||
examples:
|
||||
simpleQuery:
|
||||
summary: 简单查询
|
||||
value:
|
||||
sql: "SELECT id, username, role FROM users LIMIT 5"
|
||||
parameterizedQuery:
|
||||
summary: 参数化查询
|
||||
value:
|
||||
sql: "SELECT * FROM courses WHERE category = :category AND status = :status"
|
||||
params:
|
||||
category: "护肤"
|
||||
status: "active"
|
||||
insertData:
|
||||
summary: 插入数据
|
||||
value:
|
||||
sql: "INSERT INTO knowledge_points (title, content, course_id) VALUES (:title, :content, :course_id)"
|
||||
params:
|
||||
title: "面部护理基础"
|
||||
content: "面部护理的基本步骤..."
|
||||
course_id: 1
|
||||
responses:
|
||||
'200':
|
||||
description: SQL 执行成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/QueryResponse'
|
||||
- $ref: '#/components/schemas/ExecuteResponse'
|
||||
examples:
|
||||
queryResult:
|
||||
summary: 查询结果
|
||||
value:
|
||||
code: 200
|
||||
message: "SQL 执行成功"
|
||||
data:
|
||||
type: "query"
|
||||
columns: ["id", "username", "role"]
|
||||
rows:
|
||||
- id: 1
|
||||
username: "admin"
|
||||
role: "admin"
|
||||
- id: 2
|
||||
username: "user1"
|
||||
role: "trainee"
|
||||
row_count: 2
|
||||
executeResult:
|
||||
summary: 写入结果
|
||||
value:
|
||||
code: 200
|
||||
message: "SQL 执行成功"
|
||||
data:
|
||||
type: "execute"
|
||||
affected_rows: 1
|
||||
success: true
|
||||
'400':
|
||||
description: 请求参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'401':
|
||||
description: 未认证或认证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'500':
|
||||
description: SQL 执行错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/sql/validate:
|
||||
post:
|
||||
tags:
|
||||
- SQL执行器
|
||||
summary: 验证 SQL 语法
|
||||
description: 验证 SQL 语句的语法正确性，不执行实际操作
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SqlValidateRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: 验证完成
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ValidateResponse'
|
||||
|
||||
/sql/tables:
|
||||
get:
|
||||
tags:
|
||||
- SQL执行器
|
||||
summary: 获取表列表
|
||||
description: 获取数据库中所有表的列表
|
||||
responses:
|
||||
'200':
|
||||
description: 成功获取表列表
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TablesResponse'
|
||||
'401':
|
||||
description: 未认证
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/sql/table/{table_name}/schema:
|
||||
get:
|
||||
tags:
|
||||
- SQL执行器
|
||||
summary: 获取表结构
|
||||
description: 获取指定表的结构信息，包括字段名、类型、约束等
|
||||
parameters:
|
||||
- name: table_name
|
||||
in: path
|
||||
required: true
|
||||
description: 表名
|
||||
schema:
|
||||
type: string
|
||||
pattern: '^[a-zA-Z_][a-zA-Z0-9_]*$'
|
||||
example: users
|
||||
responses:
|
||||
'200':
|
||||
description: 成功获取表结构
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TableSchemaResponse'
|
||||
'400':
|
||||
description: 无效的表名
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'401':
|
||||
description: 未认证
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
使用登录接口返回的 access_token。
|
||||
格式: Bearer {access_token}
|
||||
apiKey:
|
||||
type: apiKey
|
||||
in: header
|
||||
name: X-API-Key
|
||||
description: |
|
||||
API Key 认证，适用于内部服务调用。
|
||||
示例: X-API-Key: dify-2025-kaopeilian
|
||||
|
||||
schemas:
|
||||
LoginRequest:
|
||||
type: object
|
||||
required:
|
||||
- username
|
||||
- password
|
||||
properties:
|
||||
username:
|
||||
type: string
|
||||
description: 用户名
|
||||
example: admin
|
||||
password:
|
||||
type: string
|
||||
format: password
|
||||
description: 密码
|
||||
example: admin123
|
||||
|
||||
LoginResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: integer
|
||||
example: 200
|
||||
message:
|
||||
type: string
|
||||
example: 登录成功
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
user:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
example: 1
|
||||
username:
|
||||
type: string
|
||||
example: admin
|
||||
role:
|
||||
type: string
|
||||
example: admin
|
||||
token:
|
||||
type: object
|
||||
properties:
|
||||
access_token:
|
||||
type: string
|
||||
description: JWT 访问令牌
|
||||
example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
|
||||
token_type:
|
||||
type: string
|
||||
example: bearer
|
||||
expires_in:
|
||||
type: integer
|
||||
description: 过期时间（秒）
|
||||
example: 1800
|
||||
|
||||
SqlExecuteRequest:
|
||||
type: object
|
||||
required:
|
||||
- sql
|
||||
properties:
|
||||
sql:
|
||||
type: string
|
||||
description: 要执行的 SQL 语句
|
||||
example: "SELECT * FROM users WHERE role = :role"
|
||||
params:
|
||||
type: object
|
||||
description: SQL 参数字典，键为参数名，值为参数值
|
||||
additionalProperties: true
|
||||
example:
|
||||
role: admin
|
||||
|
||||
SqlValidateRequest:
|
||||
type: object
|
||||
required:
|
||||
- sql
|
||||
properties:
|
||||
sql:
|
||||
type: string
|
||||
description: 要验证的 SQL 语句
|
||||
example: "SELECT * FROM users"
|
||||
|
||||
QueryResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: integer
|
||||
example: 200
|
||||
message:
|
||||
type: string
|
||||
example: SQL 执行成功
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum: [query]
|
||||
example: query
|
||||
columns:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: 列名数组
|
||||
example: ["id", "username", "role"]
|
||||
rows:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
description: 查询结果行
|
||||
row_count:
|
||||
type: integer
|
||||
description: 返回的行数
|
||||
example: 5
|
||||
|
||||
ExecuteResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: integer
|
||||
example: 200
|
||||
message:
|
||||
type: string
|
||||
example: SQL 执行成功
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum: [execute]
|
||||
example: execute
|
||||
affected_rows:
|
||||
type: integer
|
||||
description: 影响的行数
|
||||
example: 1
|
||||
success:
|
||||
type: boolean
|
||||
example: true
|
||||
|
||||
ValidateResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: integer
|
||||
example: 200
|
||||
message:
|
||||
type: string
|
||||
example: SQL 验证完成
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
valid:
|
||||
type: boolean
|
||||
description: SQL 是否有效
|
||||
example: true
|
||||
warnings:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: 警告信息列表
|
||||
example: ["包含危险操作: DROP"]
|
||||
sql_type:
|
||||
type: string
|
||||
description: SQL 类型
|
||||
example: SELECT
|
||||
|
||||
TablesResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: integer
|
||||
example: 200
|
||||
message:
|
||||
type: string
|
||||
example: 获取表列表成功
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
tables:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: 表名列表
|
||||
example: ["users", "courses", "exams"]
|
||||
count:
|
||||
type: integer
|
||||
description: 表的数量
|
||||
example: 20
|
||||
|
||||
TableSchemaResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: integer
|
||||
example: 200
|
||||
message:
|
||||
type: string
|
||||
example: 获取表结构成功
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
table_name:
|
||||
type: string
|
||||
example: users
|
||||
columns:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
field:
|
||||
type: string
|
||||
description: 字段名
|
||||
example: id
|
||||
type:
|
||||
type: string
|
||||
description: 字段类型
|
||||
example: int(11)
|
||||
null:
|
||||
type: string
|
||||
enum: ["YES", "NO"]
|
||||
description: 是否可为空
|
||||
example: NO
|
||||
key:
|
||||
type: string
|
||||
description: 键类型（PRI, UNI, MUL）
|
||||
example: PRI
|
||||
default:
|
||||
type: string
|
||||
nullable: true
|
||||
description: 默认值
|
||||
example: null
|
||||
extra:
|
||||
type: string
|
||||
description: 额外信息
|
||||
example: auto_increment
|
||||
column_count:
|
||||
type: integer
|
||||
description: 列的数量
|
||||
example: 10
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
properties:
|
||||
detail:
|
||||
type: string
|
||||
description: 错误详情
|
||||
example: SQL 执行失败: You have an error in your SQL syntax
|
||||
|
||||
tags:
|
||||
- name: 认证
|
||||
description: 用户认证相关接口
|
||||
- name: SQL执行器
|
||||
description: SQL 执行和管理相关接口
|
||||
124
backend/docs/sql_executor_checklist.md
Normal file
124
backend/docs/sql_executor_checklist.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# SQL 执行器 API 完成清单
|
||||
|
||||
## ✅ 已完成功能
|
||||
|
||||
### 1. API 开发
|
||||
- [x] 创建 `/api/v1/sql/execute` - 标准认证版本
|
||||
- [x] 创建 `/api/v1/sql/execute-simple` - 简化认证版本
|
||||
- [x] 创建 `/api/v1/sql/validate` - SQL 验证
|
||||
- [x] 创建 `/api/v1/sql/tables` - 获取表列表
|
||||
- [x] 创建 `/api/v1/sql/table/{name}/schema` - 获取表结构
|
||||
|
||||
### 2. 认证方式
|
||||
- [x] JWT Bearer Token（标准版）
|
||||
- [x] API Key 认证（X-API-Key: dify-2025-kaopeilian）
|
||||
- [x] 长期 Token（Bearer permanent-token-for-dify-2025）
|
||||
|
||||
### 3. 安全特性
|
||||
- [x] 参数化查询支持
|
||||
- [x] SQL 操作日志记录
|
||||
- [x] 危险操作警告
|
||||
- [x] 事务自动回滚
|
||||
|
||||
### 4. 文档
|
||||
- [x] OpenAPI 3.1 规范（YAML）
|
||||
- [x] OpenAPI 3.1 规范（JSON）
|
||||
- [x] Dify 使用指南
|
||||
- [x] 服务器部署指南
|
||||
- [x] 快速部署脚本
|
||||
- [x] 集成总结文档
|
||||
|
||||
### 5. 测试
|
||||
- [x] 本地测试脚本
|
||||
- [x] API Key 认证测试通过
|
||||
- [x] 长期 Token 认证测试通过
|
||||
- [x] 查询操作测试通过
|
||||
- [x] 写入操作测试通过
|
||||
|
||||
## 📋 Dify 配置步骤
|
||||
|
||||
### 方式一：导入 OpenAPI（推荐）
|
||||
1. 在 Dify 中选择"导入 OpenAPI"
|
||||
2. 上传 `openapi_sql_executor.yaml` 或 `.json`
|
||||
3. 选择服务器：120.79.247.16:8000
|
||||
4. 配置认证（见下方）
|
||||
|
||||
### 方式二：手动配置
|
||||
1. **URL**: http://120.79.247.16:8000/api/v1/sql/execute-simple
|
||||
2. **方法**: POST
|
||||
3. **认证配置**:
|
||||
- 类型: 请求头
|
||||
- 前缀: Custom
|
||||
- 键: X-API-Key
|
||||
- 值: dify-2025-kaopeilian
|
||||
|
||||
## 🚀 部署检查
|
||||
|
||||
### 本地环境
|
||||
- [x] 服务正常运行
|
||||
- [x] 数据库连接正常
|
||||
- [x] API 响应正常
|
||||
|
||||
### 服务器环境（待部署）
|
||||
- [ ] 上传代码到服务器
|
||||
- [ ] 运行部署脚本
|
||||
- [ ] 配置防火墙
|
||||
- [ ] 测试公网访问
|
||||
|
||||
## 📊 数据库信息
|
||||
|
||||
- **主机**: 120.79.247.16
|
||||
- **端口**: 3306
|
||||
- **数据库**: kaopeilian
|
||||
- **用户**: root
|
||||
- **密码**: Kaopeilian2025!@#
|
||||
|
||||
## 🔧 常用命令
|
||||
|
||||
### 本地测试
|
||||
```bash
|
||||
# 测试 API Key
|
||||
curl -X POST http://localhost:8000/api/v1/sql/execute-simple \
|
||||
-H "X-API-Key: dify-2025-kaopeilian" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"sql": "SELECT COUNT(*) FROM users"}'
|
||||
```
|
||||
|
||||
### 服务器部署
|
||||
```bash
|
||||
# 连接服务器
|
||||
ssh root@120.79.247.16
|
||||
|
||||
# 运行部署脚本
|
||||
bash /opt/kaopeilian/backend/deploy/quick_deploy.sh
|
||||
```
|
||||
|
||||
## 📝 下一步行动
|
||||
|
||||
1. **部署到服务器**
|
||||
- 上传代码
|
||||
- 运行部署脚本
|
||||
- 测试公网访问
|
||||
|
||||
2. **在 Dify 中配置**
|
||||
- 导入 OpenAPI 文档
|
||||
- 配置认证
|
||||
- 创建工作流
|
||||
|
||||
3. **监控和维护**
|
||||
- 设置日志监控
|
||||
- 定期备份
|
||||
- 性能优化
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. API Key 是硬编码的，生产环境建议从环境变量读取
|
||||
2. 确保服务器防火墙开放 8000 端口
|
||||
3. 建议使用 HTTPS 加密传输
|
||||
4. 定期更新 API Key 和 Token
|
||||
|
||||
---
|
||||
|
||||
**状态**: 开发完成，待部署到生产环境
|
||||
|
||||
|
||||
Reference in New Issue
Block a user