WordMaster Pro 部署指南

这是一个基于 FastAPI + Vue3 的智能单词学习系统，支持远程访问和初中英语单词导入。

🚀 快速启动

后端启动

1. 进入后端目录：

cd backend

2. 安装依赖：

pip install -r requirements.txt

3. 启动后端服务：

python main.py

后端将在 http://0.0.0.0:8888 启动

前端启动

1. 进入前端目录：

cd frontend

2. 安装依赖：

npm install

3. 启动开发服务器：

npm run dev

前端将在 http://localhost:3000 启动 (如端口被占用会自动选择其他端口)

📦 生产环境部署

方法1：使用 Docker (推荐)

创建 docker-compose.yml：

version: '3.8'
services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
    environment:
      - DATABASE_URL=sqlite:///./data/wordmaster.db
  
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    depends_on:
      - backend

启动：

docker-compose up -d

方法2：使用 PM2

1. 安装 PM2：

npm install -g pm2

2. 启动后端：

pm2 start "uvicorn main:app --host 0.0.0.0 --port 8000" --name wordmaster-backend

3. 构建并启动前端：

cd frontend
npm run build
pm2 serve dist 3000 --name wordmaster-frontend

方法3：使用 Nginx 反向代理

Nginx 配置示例：

server {
    listen 80;
    server_name your-domain.com;

    # 前端静态文件
    location / {
        root /path/to/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理
    location /api {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

🌐 远程访问配置

云服务器部署

1. 阿里云/腾讯云/AWS：

   • 创建云服务器实例
   • 配置安全组，开放 8000 和 3000 端口
   • 使用上述部署方法

2. 域名配置：

   • 购买域名并解析到服务器IP
   • 配置 HTTPS (使用 Let's Encrypt)

内网穿透 (开发测试)

使用 ngrok 进行内网穿透：

# 安装 ngrok
npm install -g ngrok

# 穿透后端
ngrok http 8000

# 穿透前端
ngrok http 3000

📚 初中英语单词导入

系统已内置初中英语单词，启动后会自动导入。也可以手动导入：

1. 使用 API 导入

curl -X POST "http://localhost:8000/api/words/import" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@initial_words.csv"

2. 使用前端界面导入

1. 登录系统
2. 进入"词库管理"页面
3. 点击"导入单词"按钮
4. 选择 CSV 或 JSON 文件

3. CSV 格式示例

word,meaning,example,phrases,level
abandon,放弃,He decided to abandon the project,abandon hope;abandon ship,middle_school
ability,能力,She has the ability to learn quickly,have ability;ability to do,middle_school

4. JSON 格式示例

[
  {
    "word": "abandon",
    "meaning": "放弃",
    "example": "He decided to abandon the project",
    "phrases": ["abandon hope", "abandon ship"],
    "level": "middle_school"
  }
]

🔧 环境变量配置

后端环境变量 (可选)：

# .env 文件
SECRET_KEY=your-super-secret-key-here
DATABASE_URL=sqlite:///./wordmaster.db
ACCESS_TOKEN_EXPIRE_MINUTES=30

📊 功能特性

🧠 学习算法

• SM-2 间隔重复算法：个性化复习间隔
• 主动回忆模式：输入答案，模糊匹配
• 多种学习模式：抽认卡、选择题、完形填空
• 双向练习：英→中、中→英自动切换

📈 智能分析

• 学习统计：准确率、连续天数、学习进度
• 顽固词检测：自动标记难记单词
• 记忆曲线：可视化复习预测

🎯 用户体验

• 响应式设计：支持电脑、平板、手机
• 语音朗读：TTS 发音功能
• 快捷键支持：键盘操作更高效
• 离线缓存：渐进式 Web 应用

🛠️ 技术栈

后端

• FastAPI：高性能 Python Web 框架
• SQLAlchemy：ORM 数据库操作
• JWT：用户认证
• Pydantic：数据验证

前端

• Vue 3：组合式 API
• Element Plus：UI 组件库
• Pinia：状态管理
• Vite：构建工具

数据库

• SQLite：轻量级数据库（可升级到 PostgreSQL/MySQL）

🔒 安全建议

1. 修改默认密钥：

SECRET_KEY = "your-production-secret-key-very-long-and-random"

2. CORS 配置：

allow_origins=["https://your-domain.com"]  # 限制具体域名

3. HTTPS 部署：使用 SSL 证书

4. 数据库安全：定期备份，访问控制

📱 移动端适配

系统已完全适配移动端，支持：

• 触摸手势操作
• 响应式布局
• PWA 渐进式应用
• 离线使用

🤝 技术支持

如遇问题，请检查：

1. 端口是否被占用
2. 防火墙设置
3. Node.js 和 Python 版本
4. 网络连接状态

祝您学习愉快！🎉