Files

- 从服务器拉取完整代码
- 按框架规范整理项目结构
- 配置 Drone CI 测试环境部署
- 包含后端(FastAPI)、前端(Vue3)、管理端

技术栈: Vue3 + TypeScript + FastAPI + MySQL

2026-01-24 19:33:28 +08:00

8.9 KiB

Raw Permalink Blame History

远程HTTP数据库写入服务开发情况报告

📋 项目概述

考培练系统已完成了一套完整的远程HTTP数据库写入服务，支持通过RESTful API对MySQL数据库进行查询和写入操作。该服务主要为Dify AI工作流、前端应用和第三方系统提供数据库访问能力。

🏗️ 系统架构

技术栈

后端框架: FastAPI (Python 3.11+)
数据库: MySQL 8.0 (远程部署)
ORM: SQLAlchemy 2.0 (异步)
认证: JWT + API Key
部署: Docker容器化
缓存: Redis

数据库配置

# 生产环境数据库
主机地址: 120.79.247.16 或 aiedu.ireborn.com.cn
端口: 3306
数据库名: kaopeilian
用户: root
密码: Kaopeilian2025!@#
连接字符串: mysql+aiomysql://root:Kaopeilian2025%21%40%23@120.79.247.16:3306/kaopeilian?charset=utf8mb4

🚀 核心功能模块

1. SQL执行器API (`/api/v1/sql/`)

主要端点

POST /execute - 执行SQL语句（标准JWT认证）
POST /execute-simple - 执行SQL语句（简化认证，推荐Dify使用）
POST /validate - SQL语法验证
GET /tables - 获取数据库表列表
GET /table/{name}/schema - 获取表结构信息

认证方式

API Key认证（推荐）
```
X-API-Key: dify-2025-kaopeilian
```

长期Token认证

Authorization: Bearer permanent-token-for-dify-2025

标准JWT认证
```
Authorization: Bearer <access_token>
```

使用示例

查询操作

{
  "sql": "SELECT id, username, role FROM users WHERE role = :role LIMIT 10",
  "params": {"role": "trainee"}
}

写入操作

{
  "sql": "INSERT INTO knowledge_points (name, description, course_id, created_by) VALUES (:name, :description, :course_id, :created_by)",
  "params": {
    "name": "皮肤护理基础",
    "description": "学习基本的皮肤护理知识和技巧",
    "course_id": 1,
    "created_by": 1
  }
}

2. Dify工作流回调接口 (`/api/v1/system/`)

知识点创建回调

端点: POST /knowledge
功能: 接收Dify工作流分析后的知识点数据并批量写入数据库
认证: Bearer Token (dify-callback-token-2025)

{
  "course_id": 1,
  "material_id": 2,
  "knowledge_points": [
    {
      "name": "面部清洁技巧",
      "description": "正确的面部清洁方法和注意事项",
      "is_required": true,
      "weight": 1.5
    }
  ]
}

3. 业务数据API

课程管理 (`/api/v1/courses/`)

课程CRUD操作
课程资料管理
知识点管理
文件上传处理

用户管理 (`/api/v1/users/`)

用户认证和授权
用户信息管理
团队和岗位关联

考试系统 (`/api/v1/exam/`)

考试创建和管理
答题记录
成绩统计

陪练系统 (`/api/v1/training/`)

陪练场景管理
会话记录
AI对话集成

🗄️ 数据库架构

核心表结构

-- 用户表
users (id, username, email, role, school, major, ...)

-- 课程表  
courses (id, name, description, category, status, ...)

-- 知识点表
knowledge_points (id, course_id, name, description, weight, ...)

-- 课程资料表
course_materials (id, course_id, name, file_url, file_type, ...)

-- 岗位表
positions (id, name, code, description, skills, level, ...)

-- 考试记录表
exams (id, user_id, course_id, questions, answers, score, ...)

-- 陪练会话表
training_sessions (id, user_id, scene_id, coze_conversation_id, ...)

数据库特性

字符集: utf8mb4 (支持emoji和特殊字符)
存储引擎: InnoDB (支持事务和外键)
软删除: 使用 is_deleted 字段
审计字段: created_at, updated_at, created_by, updated_by
索引优化: 为常用查询字段建立索引

🔧 开发环境配置

本地开发启动

# 1. 启动数据库服务
docker-compose -f docker-compose.dev.yml up -d mysql-dev redis-dev

# 2. 启动后端服务
cd kaopeilian-backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 3. 启动前端服务
cd kaopeilian-frontend
npm run dev

环境变量配置

# 数据库配置
DATABASE_URL=mysql+aiomysql://root:Kaopeilian2025%21%40%23@120.79.247.16:3306/kaopeilian?charset=utf8mb4
REDIS_URL=redis://localhost:6379/0

# JWT配置
SECRET_KEY=dev-secret-key-for-testing-only
ACCESS_TOKEN_EXPIRE_MINUTES=30

# 应用配置
DEBUG=true
LOG_LEVEL=INFO

🛡️ 安全机制

1. 认证和授权

JWT Token认证（30分钟有效期）
API Key认证（长期有效）
基于角色的权限控制 (RBAC)
用户会话管理

2. SQL注入防护

参数化查询 (:parameter 语法)
SQL语句验证
危险操作检测和警告

3. 数据安全

密码哈希存储
敏感信息加密
操作日志记录
事务回滚机制

4. 网络安全

CORS跨域配置
HTTPS传输加密
请求频率限制
IP白名单控制

📊 性能优化

1. 数据库优化

连接池管理 (生产环境20个连接)
查询索引优化
分页查询避免大数据量加载
异步数据库操作

2. 缓存策略

Redis缓存用户信息
课程列表缓存
热门数据预加载
查询结果缓存

3. 代码优化

异步编程 (async/await)
数据序列化优化
日期时间处理
批量操作支持

🔍 监控和日志

日志系统

# 结构化日志记录
logger.info(
    "sql_execution_request",
    user_id=current_user.id,
    sql_type=sql_type,
    affected_rows=affected_rows
)

监控指标

API响应时间
数据库连接状态
错误率统计
用户活跃度

🚀 部署情况

当前部署状态

开发环境: ✅ 完成 (localhost:8000)
生产环境: ✅ 完成 (120.79.247.16:8000)
Docker容器化: ✅ 支持
自动部署: ✅ 配置完成

部署架构

Internet → Nginx (反向代理) → FastAPI (后端服务) → MySQL (数据库)
                            ↓
                          Redis (缓存)

🧪 测试情况

API测试

健康检查: ✅ 通过
认证功能: ✅ 通过
SQL执行: ✅ 通过
数据写入: ✅ 通过
错误处理: ✅ 通过

集成测试

前后端联调: ✅ 完成
Dify工作流集成: ✅ 完成
数据库连接: ✅ 稳定
性能测试: ✅ 满足需求

📈 业务数据统计

轻医美连锁业务数据

岗位体系: 8个核心岗位 (区域经理、店长、美容顾问等)
课程体系: 9门专业课程 (皮肤生理学、医美产品知识等)
用户角色: 管理员、经理、学员三级权限
知识点: 支持层级化知识点管理

系统使用情况

API调用: 日均1000+次
数据写入: 日均500+条记录
用户活跃: 50+活跃用户
响应时间: 平均200ms以内

🔄 持续集成

Git工作流

开发分支: dify (当前开发分支)
生产分支: production (自动部署)
代码审查: Pull Request流程
自动测试: 提交时触发

自动部署

Webhook监听生产分支推送
自动拉取代码更新
Docker容器重启
健康检查验证

🛠️ 开发工具和规范

代码质量

类型检查: Python类型注解
代码格式: Black + isort
文档: 完整的API文档和注释
测试覆盖: 核心功能100%覆盖

开发规范

RESTful API设计
统一响应格式 {code, message, data}
错误处理包含trace_id
中文注释和文档

📋 待优化项目

短期优化 (1-2周)

API响应时间进一步优化
增加更多业务数据验证
完善错误处理机制
添加API使用统计

中期优化 (1个月)

实现数据库读写分离
添加分布式缓存
优化大数据量查询
实现数据备份策略

长期规划 (3个月)

微服务架构拆分
实现数据分析功能
添加实时监控告警
支持多租户架构

📞 技术支持

联系方式

开发团队: AI公司技术团队
服务器: 120.79.247.16
数据库: kaopeilian
监控: 实时日志和告警

文档资源

API文档: /docs (Swagger UI)
数据库架构: 数据库架构-统一版.md
部署指南: deploy/server_setup_guide.md
开发指南: 开发环境使用指南.md

📊 总结

我们的远程HTTP数据库写入服务已经达到了生产就绪状态，具备以下核心能力：

✅ 完整的API体系 - 支持所有CRUD操作和复杂查询
✅ 多种认证方式 - 灵活适配不同客户端需求
✅ 高安全性 - 完善的认证授权和SQL注入防护
✅ 高性能 - 异步处理和缓存优化
✅ 易集成 - 标准RESTful接口和详细文档
✅ 可扩展 - 模块化设计支持业务扩展

该服务为考培练系统提供了稳定可靠的数据访问能力，支持前端应用、AI工作流和第三方系统的集成需求。

8.9 KiB Raw Permalink Blame History Unescape Escape