feat: 添加数据库初始化文档和配置优化
- 添加完整的数据库初始化文档 (docs/DATABASE_SETUP.md) - 添加快速开始指南 (docs/QUICK_START.md) - 更新 requirements.txt 添加缺失的依赖 (requests, python-docx) - 优化 .gitignore 配置，保留 uploads 目录结构 - 创建 uploads 目录结构 (images/, pdfs/) - 支持 PostgreSQL 和 SQLite 两种数据库配置 数据库文档包含： - PostgreSQL 和 SQLite 安装配置指南 - 完整的表结构说明 - 管理员账户初始化步骤 - 数据库迁移说明 - 常见问题排查 - 备份恢复方案 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
+9
-2
@@ -40,8 +40,15 @@ ENV/
|
||||
*.log
|
||||
logs/
|
||||
|
||||
# Uploads
|
||||
uploads/
|
||||
# Uploads (keep directory structure but ignore contents)
|
||||
uploads/*
|
||||
!uploads/.gitkeep
|
||||
!uploads/images/
|
||||
!uploads/pdfs/
|
||||
uploads/images/*
|
||||
uploads/pdfs/*
|
||||
!uploads/images/.gitkeep
|
||||
!uploads/pdfs/.gitkeep
|
||||
temp/
|
||||
*.tmp
|
||||
|
||||
|
||||
@@ -9,4 +9,6 @@ pdfplumber>=0.11.7
|
||||
PyMuPDF>=1.23.0
|
||||
python-dotenv>=1.0.0
|
||||
psycopg2-binary>=2.9.7
|
||||
python-multipart==0.0.6
|
||||
python-multipart==0.0.6
|
||||
requests>=2.31.0
|
||||
python-docx>=0.8.11
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
# Keep this directory in git
|
||||
@@ -0,0 +1 @@
|
||||
# Keep this directory in git
|
||||
@@ -0,0 +1 @@
|
||||
# Keep this directory in git
|
||||
@@ -0,0 +1,486 @@
|
||||
# 数据库初始化指南
|
||||
|
||||
本文档提供完整的数据库初始化和配置指南，包括 PostgreSQL 和 SQLite 两种数据库的设置方法。
|
||||
|
||||
## 目录
|
||||
|
||||
- [1. 环境要求](#1-环境要求)
|
||||
- [2. PostgreSQL 数据库设置（推荐生产环境）](#2-postgresql-数据库设置推荐生产环境)
|
||||
- [3. SQLite 数据库设置（开发环境）](#3-sqlite-数据库设置开发环境)
|
||||
- [4. 数据库表结构说明](#4-数据库表结构说明)
|
||||
- [5. 初始化管理员账户](#5-初始化管理员账户)
|
||||
- [6. 数据库迁移](#6-数据库迁移)
|
||||
- [7. 常见问题](#7-常见问题)
|
||||
|
||||
---
|
||||
|
||||
## 1. 环境要求
|
||||
|
||||
### 基础软件
|
||||
- Python 3.8+
|
||||
- PostgreSQL 14+ (如使用 PostgreSQL)
|
||||
- Node.js 16+ (前端)
|
||||
|
||||
### Python 依赖
|
||||
项目依赖已在 `backend/requirements.txt` 中定义，主要包括：
|
||||
- FastAPI
|
||||
- SQLAlchemy
|
||||
- psycopg2-binary (PostgreSQL 驱动)
|
||||
- python-dotenv
|
||||
|
||||
---
|
||||
|
||||
## 2. PostgreSQL 数据库设置（推荐生产环境）
|
||||
|
||||
### 2.1 安装 PostgreSQL
|
||||
|
||||
**macOS (使用 Homebrew):**
|
||||
```bash
|
||||
brew install postgresql@14
|
||||
brew services start postgresql@14
|
||||
```
|
||||
|
||||
**Ubuntu/Debian:**
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install postgresql postgresql-contrib
|
||||
sudo systemctl start postgresql
|
||||
sudo systemctl enable postgresql
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
从官网下载安装: https://www.postgresql.org/download/windows/
|
||||
|
||||
### 2.2 创建数据库和用户
|
||||
|
||||
使用 PostgreSQL 命令行创建数据库：
|
||||
|
||||
```bash
|
||||
# 连接到 PostgreSQL
|
||||
psql -U postgres
|
||||
|
||||
# 在 psql 命令行中执行以下命令：
|
||||
CREATE DATABASE wordmaster;
|
||||
CREATE USER wordmaster_user WITH PASSWORD 'your_secure_password';
|
||||
GRANT ALL PRIVILEGES ON DATABASE wordmaster TO wordmaster_user;
|
||||
|
||||
# 退出 psql
|
||||
\q
|
||||
```
|
||||
|
||||
**更简单的方式（使用默认 postgres 用户）:**
|
||||
```bash
|
||||
# 创建数据库
|
||||
psql -U postgres -c "CREATE DATABASE wordmaster;"
|
||||
|
||||
# 验证数据库创建
|
||||
psql -U postgres -c "\l" | grep wordmaster
|
||||
```
|
||||
|
||||
### 2.3 配置环境变量
|
||||
|
||||
在项目根目录创建 `.env` 文件：
|
||||
|
||||
```bash
|
||||
# 复制示例配置文件
|
||||
cp backend/.env.example .env
|
||||
```
|
||||
|
||||
编辑 `.env` 文件，配置数据库连接：
|
||||
|
||||
```env
|
||||
# PostgreSQL 配置
|
||||
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/wordmaster
|
||||
|
||||
# 或使用自定义用户
|
||||
# DATABASE_URL=postgresql://wordmaster_user:your_secure_password@localhost:5432/wordmaster
|
||||
|
||||
# 安全配置
|
||||
SECRET_KEY=your-super-secret-key-change-in-production
|
||||
ALGORITHM=HS256
|
||||
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
||||
```
|
||||
|
||||
### 2.4 初始化数据库表
|
||||
|
||||
数据库表会在首次启动后端服务时自动创建：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python3 create_admin.py
|
||||
```
|
||||
|
||||
或者手动启动后端让其自动创建：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate # 激活虚拟环境
|
||||
python main.py
|
||||
```
|
||||
|
||||
### 2.5 验证数据库连接
|
||||
|
||||
```bash
|
||||
# 连接数据库
|
||||
psql -U postgres -d wordmaster
|
||||
|
||||
# 查看所有表
|
||||
\dt
|
||||
|
||||
# 应该看到以下表：
|
||||
# - users
|
||||
# - words
|
||||
# - user_word_progress
|
||||
# - papers
|
||||
# - questions
|
||||
# - question_collections
|
||||
# - mistakes
|
||||
# - review_logs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. SQLite 数据库设置（开发环境）
|
||||
|
||||
SQLite 无需安装，非常适合开发和测试环境。
|
||||
|
||||
### 3.1 配置环境变量
|
||||
|
||||
在 `.env` 文件中配置：
|
||||
|
||||
```env
|
||||
# SQLite 配置（开发环境）
|
||||
DATABASE_URL=sqlite:///./wordmaster.db
|
||||
|
||||
SECRET_KEY=dev-secret-key-change-in-production
|
||||
ALGORITHM=HS256
|
||||
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
||||
```
|
||||
|
||||
### 3.2 初始化数据库
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python3 create_admin.py
|
||||
```
|
||||
|
||||
数据库文件将自动创建在 `backend/wordmaster.db`
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据库表结构说明
|
||||
|
||||
### 4.1 核心表结构
|
||||
|
||||
#### users - 用户表
|
||||
```sql
|
||||
CREATE TABLE users (
|
||||
id SERIAL PRIMARY KEY,
|
||||
username VARCHAR UNIQUE NOT NULL,
|
||||
email VARCHAR UNIQUE NOT NULL,
|
||||
hashed_password VARCHAR NOT NULL,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
#### words - 单词表
|
||||
```sql
|
||||
CREATE TABLE words (
|
||||
id SERIAL PRIMARY KEY,
|
||||
word VARCHAR NOT NULL,
|
||||
translation TEXT,
|
||||
difficulty INTEGER DEFAULT 1,
|
||||
category VARCHAR,
|
||||
example_sentence TEXT,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
#### user_word_progress - 用户单词学习进度
|
||||
```sql
|
||||
CREATE TABLE user_word_progress (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER REFERENCES users(id),
|
||||
word_id INTEGER REFERENCES words(id),
|
||||
ease_factor FLOAT DEFAULT 2.5,
|
||||
interval INTEGER DEFAULT 0,
|
||||
repetitions INTEGER DEFAULT 0,
|
||||
next_review_date TIMESTAMP,
|
||||
last_review_date TIMESTAMP,
|
||||
status VARCHAR DEFAULT 'learning'
|
||||
);
|
||||
```
|
||||
|
||||
#### papers - 试卷表
|
||||
```sql
|
||||
CREATE TABLE papers (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER REFERENCES users(id),
|
||||
title VARCHAR NOT NULL,
|
||||
subject VARCHAR,
|
||||
file_path VARCHAR,
|
||||
upload_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
description TEXT,
|
||||
tags JSON
|
||||
);
|
||||
```
|
||||
|
||||
#### questions - 题目表
|
||||
```sql
|
||||
CREATE TABLE questions (
|
||||
id SERIAL PRIMARY KEY,
|
||||
paper_id INTEGER REFERENCES papers(id),
|
||||
question_text TEXT NOT NULL,
|
||||
question_type VARCHAR,
|
||||
answer TEXT,
|
||||
difficulty INTEGER,
|
||||
page_number INTEGER,
|
||||
page_spans JSON,
|
||||
source_text TEXT,
|
||||
images JSON,
|
||||
formula JSON,
|
||||
score FLOAT,
|
||||
question_number VARCHAR,
|
||||
auto_extracted BOOLEAN DEFAULT FALSE,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
#### mistakes - 错题表
|
||||
```sql
|
||||
CREATE TABLE mistakes (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER REFERENCES users(id),
|
||||
question_id INTEGER REFERENCES questions(id),
|
||||
user_answer TEXT,
|
||||
correct_answer TEXT,
|
||||
notes TEXT,
|
||||
leitner_box INTEGER DEFAULT 1,
|
||||
next_review_date TIMESTAMP,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
#### review_logs - 复习记录表
|
||||
```sql
|
||||
CREATE TABLE review_logs (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER REFERENCES users(id),
|
||||
mistake_id INTEGER REFERENCES mistakes(id),
|
||||
review_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
is_correct BOOLEAN,
|
||||
time_spent INTEGER
|
||||
);
|
||||
```
|
||||
|
||||
#### question_collections - 题目集合
|
||||
```sql
|
||||
CREATE TABLE question_collections (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER REFERENCES users(id),
|
||||
name VARCHAR NOT NULL,
|
||||
description TEXT,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 初始化管理员账户
|
||||
|
||||
### 5.1 使用脚本创建管理员
|
||||
|
||||
项目提供了便捷的管理员创建脚本：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python3 create_admin.py
|
||||
```
|
||||
|
||||
**默认管理员账户：**
|
||||
- 用户名: `admin`
|
||||
- 密码: `admin`
|
||||
- 邮箱: `admin@admin.com`
|
||||
|
||||
### 5.2 修改管理员密码
|
||||
|
||||
如需修改密码，可以再次运行脚本（会更新密码）或通过 API 修改。
|
||||
|
||||
### 5.3 手动创建用户
|
||||
|
||||
也可以通过 PostgreSQL 命令行手动创建：
|
||||
|
||||
```bash
|
||||
psql -U postgres -d wordmaster
|
||||
```
|
||||
|
||||
```sql
|
||||
-- 插入用户（密码需要使用 bcrypt 哈希）
|
||||
-- 这里的哈希值对应密码 "admin"
|
||||
INSERT INTO users (username, email, hashed_password, created_at)
|
||||
VALUES (
|
||||
'admin',
|
||||
'admin@admin.com',
|
||||
'$2b$12$KIX.qh0yRsYQUzH7EqQv1eRWZG5g9V.Lv3mK5yH9rJC.YmMvxhFWK',
|
||||
CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 数据库迁移
|
||||
|
||||
### 6.1 SQLite 迁移脚本
|
||||
|
||||
如果数据库结构发生变化，使用迁移脚本更新：
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python3 migrate_db.py
|
||||
```
|
||||
|
||||
此脚本会为 `questions` 表添加新字段（如果缺失）。
|
||||
|
||||
### 6.2 PostgreSQL 迁移
|
||||
|
||||
PostgreSQL 使用 SQLAlchemy 的自动迁移：
|
||||
|
||||
```python
|
||||
# 在 backend/main.py 中
|
||||
Base.metadata.create_all(bind=engine)
|
||||
```
|
||||
|
||||
首次启动时会自动创建所有表。
|
||||
|
||||
---
|
||||
|
||||
## 7. 常见问题
|
||||
|
||||
### 7.1 数据库连接失败
|
||||
|
||||
**问题**: `psycopg2.OperationalError: could not connect to server`
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 检查 PostgreSQL 是否运行
|
||||
brew services list | grep postgresql
|
||||
# 或
|
||||
sudo systemctl status postgresql
|
||||
|
||||
# 启动 PostgreSQL
|
||||
brew services start postgresql@14
|
||||
# 或
|
||||
sudo systemctl start postgresql
|
||||
```
|
||||
|
||||
### 7.2 数据库不存在
|
||||
|
||||
**问题**: `database "wordmaster" does not exist`
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
psql -U postgres -c "CREATE DATABASE wordmaster;"
|
||||
```
|
||||
|
||||
### 7.3 权限问题
|
||||
|
||||
**问题**: `permission denied for database wordmaster`
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
psql -U postgres
|
||||
GRANT ALL PRIVILEGES ON DATABASE wordmaster TO postgres;
|
||||
# 或授权给特定用户
|
||||
GRANT ALL PRIVILEGES ON DATABASE wordmaster TO wordmaster_user;
|
||||
```
|
||||
|
||||
### 7.4 表已存在错误
|
||||
|
||||
**问题**: `table "users" already exists`
|
||||
|
||||
这不是错误，说明表已经创建。可以忽略或删除数据库重新创建：
|
||||
|
||||
```bash
|
||||
# 删除数据库（警告：会丢失所有数据）
|
||||
psql -U postgres -c "DROP DATABASE wordmaster;"
|
||||
psql -U postgres -c "CREATE DATABASE wordmaster;"
|
||||
```
|
||||
|
||||
### 7.5 虚拟环境依赖问题
|
||||
|
||||
**问题**: `ModuleNotFoundError: No module named 'psycopg2'`
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 备份和恢复
|
||||
|
||||
### 8.1 PostgreSQL 备份
|
||||
|
||||
```bash
|
||||
# 备份数据库
|
||||
pg_dump -U postgres wordmaster > backup_$(date +%Y%m%d).sql
|
||||
|
||||
# 恢复数据库
|
||||
psql -U postgres wordmaster < backup_20241127.sql
|
||||
```
|
||||
|
||||
### 8.2 SQLite 备份
|
||||
|
||||
```bash
|
||||
# 简单复制数据库文件
|
||||
cp backend/wordmaster.db backend/wordmaster.db.backup
|
||||
|
||||
# 恢复
|
||||
cp backend/wordmaster.db.backup backend/wordmaster.db
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 生产环境建议
|
||||
|
||||
1. **更改默认密码**: 修改 `.env` 中的 `SECRET_KEY` 和数据库密码
|
||||
2. **启用 SSL**: 配置 PostgreSQL SSL 连接
|
||||
3. **定期备份**: 设置自动备份计划
|
||||
4. **监控**: 使用 pg_stat_statements 监控数据库性能
|
||||
5. **连接池**: 配置适当的数据库连接池大小
|
||||
|
||||
---
|
||||
|
||||
## 附录：完整初始化流程
|
||||
|
||||
### 一键初始化（PostgreSQL）
|
||||
|
||||
```bash
|
||||
# 1. 安装 PostgreSQL
|
||||
brew install postgresql@14
|
||||
brew services start postgresql@14
|
||||
|
||||
# 2. 创建数据库
|
||||
psql -U postgres -c "CREATE DATABASE wordmaster;"
|
||||
|
||||
# 3. 配置环境变量
|
||||
cp backend/.env.example .env
|
||||
# 编辑 .env 设置 DATABASE_URL
|
||||
|
||||
# 4. 安装 Python 依赖
|
||||
cd backend
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 5. 创建表和管理员
|
||||
python3 create_admin.py
|
||||
|
||||
# 6. 启动服务
|
||||
cd ..
|
||||
./start.sh
|
||||
```
|
||||
|
||||
完成！系统已就绪，访问 http://localhost:3008 开始使用。
|
||||
@@ -0,0 +1,146 @@
|
||||
# 快速开始指南
|
||||
|
||||
5 分钟快速启动学习助手 Pro 系统。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- Python 3.8+
|
||||
- Node.js 16+
|
||||
- PostgreSQL 14+ (或使用 SQLite)
|
||||
|
||||
## 快速启动步骤
|
||||
|
||||
### 1. 克隆项目
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd python-template
|
||||
```
|
||||
|
||||
### 2. 数据库设置
|
||||
|
||||
**选项 A: PostgreSQL (推荐)**
|
||||
```bash
|
||||
# macOS
|
||||
brew install postgresql@14
|
||||
brew services start postgresql@14
|
||||
psql -U postgres -c "CREATE DATABASE wordmaster;"
|
||||
|
||||
# Linux
|
||||
sudo apt install postgresql
|
||||
sudo systemctl start postgresql
|
||||
sudo -u postgres psql -c "CREATE DATABASE wordmaster;"
|
||||
```
|
||||
|
||||
**选项 B: SQLite (简单)**
|
||||
无需额外安装，使用文件数据库。
|
||||
|
||||
### 3. 配置环境变量
|
||||
|
||||
```bash
|
||||
# 创建 .env 文件
|
||||
cat > .env << 'EOF'
|
||||
# PostgreSQL
|
||||
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/wordmaster
|
||||
|
||||
# 或 SQLite
|
||||
# DATABASE_URL=sqlite:///./wordmaster.db
|
||||
|
||||
SECRET_KEY=your-secret-key-change-in-production
|
||||
ALGORITHM=HS256
|
||||
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
||||
EOF
|
||||
```
|
||||
|
||||
### 4. 安装后端依赖
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 5. 初始化数据库
|
||||
|
||||
```bash
|
||||
# 创建表和管理员账户
|
||||
python3 create_admin.py
|
||||
```
|
||||
|
||||
默认管理员账户：
|
||||
- 用户名: `admin`
|
||||
- 密码: `admin`
|
||||
|
||||
### 6. 安装前端依赖
|
||||
|
||||
```bash
|
||||
cd ../frontend
|
||||
npm install
|
||||
```
|
||||
|
||||
### 7. 启动系统
|
||||
|
||||
```bash
|
||||
cd ..
|
||||
./start.sh
|
||||
```
|
||||
|
||||
系统将自动启动：
|
||||
- 后端服务: http://localhost:8888
|
||||
- 前端服务: http://localhost:3008
|
||||
- API 文档: http://localhost:8888/docs
|
||||
|
||||
## 验证安装
|
||||
|
||||
打开浏览器访问 http://localhost:3008，使用管理员账户登录：
|
||||
- 用户名: `admin`
|
||||
- 密码: `admin`
|
||||
|
||||
## 常用命令
|
||||
|
||||
```bash
|
||||
# 启动系统
|
||||
./start.sh
|
||||
|
||||
# 停止系统
|
||||
./stop.sh
|
||||
|
||||
# 查看状态
|
||||
./status.sh
|
||||
|
||||
# 查看日志
|
||||
tail -f backend/backend.log
|
||||
tail -f frontend/frontend.log
|
||||
```
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
python-template/
|
||||
├── backend/ # FastAPI 后端
|
||||
│ ├── main.py # 主应用文件
|
||||
│ ├── requirements.txt
|
||||
│ ├── create_admin.py
|
||||
│ └── venv/ # Python 虚拟环境
|
||||
├── frontend/ # Vue 3 前端
|
||||
│ ├── src/
|
||||
│ └── package.json
|
||||
├── docs/ # 文档
|
||||
│ ├── DATABASE_SETUP.md # 数据库详细配置
|
||||
│ └── QUICK_START.md # 本文件
|
||||
├── .env # 环境变量配置
|
||||
├── start.sh # 启动脚本
|
||||
├── stop.sh # 停止脚本
|
||||
└── status.sh # 状态检查脚本
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- 阅读 [数据库设置指南](./DATABASE_SETUP.md) 了解详细配置
|
||||
- 查看 [CLAUDE.md](../CLAUDE.md) 了解项目架构
|
||||
- 访问 API 文档: http://localhost:8888/docs
|
||||
|
||||
## 遇到问题？
|
||||
|
||||
参考 [DATABASE_SETUP.md](./DATABASE_SETUP.md) 的"常见问题"章节。
|
||||
Reference in New Issue
Block a user