WordMaster Backend

WordMaster 智能背单词系统后端 API

🚀 快速开始

选项1：使用预构建的Docker镜像

如果您只想快速运行WordMaster后端，可以直接使用预构建的Docker镜像：

# 拉取最新镜像
docker pull ghcr.io/wordmastersoftware/core:latest

# 启动服务（需要先配置.env文件）
cp .env.example .env  # 配置您的环境变量
docker-compose up -d

服务将在 http://localhost:8000 启动

1. 环境要求

• Python 3.10+
• PostgreSQL 14+
• pip

2. 安装依赖

cd backend
pip install -r requirements.txt

3. 配置环境变量

复制 .env.example 为 .env 并修改配置：

cp .env.example .env

编辑 .env 文件，配置数据库连接和系统默认的 LLM 配置：

DATABASE_URL=postgresql://wordmaster:password@localhost:5432/postgres

# 系统默认的 LLM 配置（用户可以选择使用或自定义）
DEFAULT_LLM_API_KEY=your-api-key-here
DEFAULT_LLM_BASE_URL=https://api.openai.com/v1
DEFAULT_LLM_MODEL=gpt-4

4. 初始化数据库

确保 PostgreSQL 已安装并运行，然后执行：

# 连接到 PostgreSQL
psql -U wordmaster -d postgres

# 在 psql 中执行初始化脚本
\i init_db.sql

或者直接使用命令行：

psql -U wordmaster -d postgres -f init_db.sql

5. 运行服务

# 开发模式（自动重载）
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 或者使用 Python 直接运行
python -m app.main

服务将在 http://localhost:8000 启动

6. 访问 API 文档

启动服务后，访问以下地址查看 API 文档：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🎯 核心特性

用户级别的 LLM 配置

每个用户可以选择：

• ✅ 使用系统默认配置 - 使用 .env 中配置的 LLM API
• ✅ 使用自定义配置 - 配置自己的 API Key、Endpoint 和 Model

优势：

• 灵活性高：不同用户可以使用不同的 LLM 服务
• 成本控制：用户可以使用自己的 API Key
• 隐私保护：API Key 加密存储，不会在响应中返回

📁 项目结构

backend/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI 主应用
│   ├── config.py            # 配置管理
│   ├── database.py          # 数据库连接
│   ├── models/              # 数据模型
│   │   ├── __init__.py
│   │   ├── user.py          # 用户模型（包含LLM配置）
│   │   ├── user_session.py
│   │   ├── wordbook.py
│   │   ├── word_collection.py
│   │   └── user_word_item.py
│   ├── schemas/             # Pydantic 模式
│   │   ├── __init__.py
│   │   ├── auth.py          # 包含LLM配置Schema
│   │   ├── word.py
│   │   ├── study.py
│   │   ├── exam.py
│   │   └── collection.py
│   ├── api/                 # API 路由
│   │   ├── __init__.py
│   │   ├── auth.py          # 认证 + LLM配置管理
│   │   ├── words.py
│   │   ├── study.py
│   │   ├── exam.py
│   │   ├── tts.py
│   │   ├── collections.py
│   │   └── messages.py
│   ├── services/            # 业务逻辑
│   │   ├── __init__.py
│   │   ├── auth_service.py
│   │   ├── word_service.py
│   │   ├── study_service.py
│   │   ├── exam_service.py
│   │   ├── llm_service.py   # 支持用户级别配置
│   │   ├── tts_service.py
│   │   ├── collection_service.py
│   │   ├── message_service.py
│   │   └── tts_service.py
│   └── utils/
│       ├── __init__.py
│       ├── auth.py
│       ├── dependencies.py
│       └── prompt_templates.py
├── init_db.sql              # 数据库初始化脚本
├── requirements.txt
├── .env.example
└── README.md

🔌 API 接口

认证模块 (/api/auth)

基础认证

• POST /api/auth/register - 用户注册
• POST /api/auth/login - 用户登录
• POST /api/auth/logout - 退出登录
• GET /api/auth/me - 获取当前用户信息
• PUT /api/auth/profile - 更新用户资料
• PUT /api/auth/password - 修改密码

LLM 配置管理

• GET /api/auth/llm-config - 获取当前用户的 LLM 配置
• PUT /api/auth/llm-config - 更新用户的 LLM 配置

LLM 配置示例：

// 使用系统默认配置
PUT /api/auth/llm-config
{
  "use_default_llm": true
}

// 使用自定义配置
PUT /api/auth/llm-config
{
  "use_default_llm": false,
  "llm_api_key": "sk-your-api-key",
  "llm_base_url": "https://api.openai.com/v1",
  "llm_model": "gpt-4"
}

单词管理 (/api/words)

• POST /api/words/import - 导入单词列表（自动使用用户的 LLM 配置）
• GET /api/words/list - 获取用户单词本
• DELETE /api/words/{word_id} - 删除单词

学习模块 (/api/study)

• GET /api/study/session - 获取学习会话
• [更多学习相关接口...]

考试模块 (/api/exam)

• POST /api/exam/generate - 生成考试（自动使用用户的 LLM 配置）
• POST /api/exam/submit - 提交考试答案

TTS 语音 (/api/tts)

• GET /api/tts/{word} - 获取单词发音

单词本模块 (/api/collections)

• GET /api/collections - 获取用户单词本
• POST /api/collections - 创建新的单词本
• PUT /api/collections/{id} - 更新单词本
• DELETE /api/collections/{id} - 删除单词本

消息模块 (/api/messages)

• GET /api/messages - 获取消息历史
• [更多消息相关接口...]

🗄️ 数据库设计

用户表 (users)

新增字段：

• use_default_llm - 是否使用系统默认 LLM 配置
• llm_api_key - 用户自定义的 API Key（加密存储）
• llm_base_url - 用户自定义的 API Endpoint
• llm_model - 用户自定义的 Model

其他表

• user_sessions - 用户登录会话
• wordbook - 单词库（JSONB 存储翻译、音标、例句）
• word_collections - 单词本分类管理
• user_word_items - 用户学习进度（四ID设计：collection_id, user_id, word_id, item_item）（5种状态：0-4）
• messages - 消息历史记录

🔐 LLM 配置工作流程

┌─────────────────────────────────────────┐
│  用户注册/登录                           │
│  默认：use_default_llm = true            │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  用户可以选择：                          │
│  1️⃣ 使用系统默认配置（.env）             │
│  2️⃣ 配置自己的 LLM API                  │
│     - API Key                           │
│     - Base URL                          │
│     - Model                             │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  导入单词 / 生成考试时                   │
│  自动使用用户配置的 LLM                  │
│  - use_default_llm=true → 系统配置      │
│  - use_default_llm=false → 用户配置     │
└─────────────────────────────────────────┘

📦 部署

Docker 部署 (推荐)

我们提供了 docker-compose.yml 以便快速启动完整的应用环境（包含数据库）。

选项1：使用预构建的镜像（推荐）

您可以直接拉取并使用预构建的镜像，而无需本地构建：

# 拉取最新镜像
docker pull ghcr.io/wordmastersoftware/core:latest

# 启动服务（使用预构建镜像）
docker-compose up -d

选项2：从源码构建

如果您想从源码构建镜像：

1. 准备配置文件

   复制示例配置并根据需要修改（如 LLM API Key）：

   cp .env.example .env

2. 构建并启动

   docker-compose up -d --build

   这将自动：

   • 启动 PostgreSQL 数据库并初始化数据
   • 构建后端镜像
   • 启动后端服务

3. 访问服务

   后端 API 将在 http://localhost:8000 上可用。

4. 查看日志

   docker-compose logs -f

5. 停止服务

   docker-compose down

使用预构建镜像的优势

• 更快的部署速度：无需本地构建时间
• 一致的运行环境：使用官方发布的镜像
• 减少本地依赖：不需要安装Python等依赖项

传统 Docker 运行

如果你只想单独运行后端容器：

# 1. 构建镜像 (注意：.dockerignore 会排除 .env 文件以保证安全)
docker build -t wordmaster-backend .

# 2. 运行容器 (运行时挂载 .env)
docker run -p 8000:8000 --env-file .env wordmaster-backend

🔧 故障排除

LLM 配置问题

问题：用户使用自定义配置后，大模型调用失败

解决：

1. 检查用户配置的 API Key 是否有效
2. 检查 Base URL 是否正确
3. 查看日志获取详细错误信息

数据库连接失败

检查 PostgreSQL 是否运行：

sudo systemctl status postgresql

🤝 贡献

欢迎提交 Issue 和 Pull Request 来帮助改进这个项目！

📄 许可证

GNU GENERAL PUBLIC LICENSE Version 3