184 lines
3.6 KiB
Markdown
184 lines
3.6 KiB
Markdown
# 项目设置指南
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装后端依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 初始化数据库
|
||
|
||
```bash
|
||
# 从项目根目录运行
|
||
python -m app.db.init_db
|
||
```
|
||
|
||
如果需要重置数据库（⚠️ 会删除所有数据）：
|
||
|
||
```bash
|
||
python -m app.db.init_db --reset
|
||
```
|
||
|
||
### 3. 配置环境变量
|
||
|
||
复制 `.env.example` 为 `.env`：
|
||
|
||
```bash
|
||
# Windows
|
||
copy .env.example .env
|
||
|
||
# Linux/Mac
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件，修改以下配置：
|
||
|
||
```env
|
||
# 必须修改（生产环境）
|
||
SECRET_KEY=your-secret-key-change-in-production
|
||
|
||
# 可选：如果需要天气功能
|
||
OPENWEATHER_API_KEY=your-api-key
|
||
```
|
||
|
||
### 4. 启动后端服务
|
||
|
||
```bash
|
||
# 方式1：使用项目入口文件
|
||
python main.py
|
||
|
||
# 方式2：使用 uvicorn 直接运行
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
后端服务将在 `http://localhost:8000` 启动。
|
||
|
||
访问 API 文档：`http://localhost:8000/docs`
|
||
|
||
### 5. 安装前端依赖
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
```
|
||
|
||
### 6. 启动前端服务
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
前端服务将在 `http://localhost:5173` 启动。
|
||
|
||
## 项目结构说明
|
||
|
||
详细的项目结构说明请查看 `PROJECT_STRUCTURE.md`。
|
||
|
||
## 重要变更
|
||
|
||
### 数据库初始化脚本位置调整
|
||
|
||
**旧位置**：`backend/init_db.py`
|
||
**新位置**：`backend/app/db/init_db.py`
|
||
|
||
**新的运行方式**：
|
||
```bash
|
||
python -m app.db.init_db # 创建表
|
||
python -m app.db.init_db --reset # 重置数据库
|
||
```
|
||
|
||
### 旧文件清理
|
||
|
||
以下文件可以删除（代码已迁移到新位置）：
|
||
- `backend/database.py` → 已迁移到 `backend/app/db/session.py`
|
||
- `backend/models.py` → 已迁移到 `backend/app/models/`
|
||
- `backend/init_db.py` → 已迁移到 `backend/app/db/init_db.py`
|
||
|
||
## 开发路线图
|
||
|
||
### ✅ 已完成
|
||
|
||
1. **阶段 1**：静态页面 + TodoList（无用户）
|
||
2. **阶段 2**：博客系统（公开）
|
||
3. **阶段 3**：用户系统 + 权限隔离
|
||
|
||
### 🚧 开发中
|
||
|
||
4. **阶段 4**：天气查询 + 个人记账本
|
||
5. **阶段 5**：书影音收藏站
|
||
6. **阶段 6**：聊天室（WebSocket） + 文件上传
|
||
|
||
## 测试 API
|
||
|
||
### 1. 用户注册
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/v1/auth/register" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"username": "testuser",
|
||
"email": "test@example.com",
|
||
"password": "testpass123"
|
||
}'
|
||
```
|
||
|
||
### 2. 用户登录
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/v1/auth/login" \
|
||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||
-d "username=testuser&password=testpass123"
|
||
```
|
||
|
||
返回的 `access_token` 用于后续 API 请求。
|
||
|
||
### 3. 获取当前用户信息
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8000/api/v1/users/me" \
|
||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
||
```
|
||
|
||
### 4. 创建待办事项
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/v1/todos/" \
|
||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"title": "完成项目文档"
|
||
}'
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q: 运行 `python -m app.db.init_db` 报错 "No module named 'app'"
|
||
|
||
**A**: 确保从项目根目录运行，并且 `backend` 目录在 Python 路径中。或者使用：
|
||
|
||
```bash
|
||
cd backend
|
||
python -m app.db.init_db
|
||
```
|
||
|
||
### Q: 前端无法连接到后端 API
|
||
|
||
**A**: 检查：
|
||
1. 后端服务是否在 `http://localhost:8000` 运行
|
||
2. `frontend/vite.config.js` 中的代理配置是否正确
|
||
3. 浏览器控制台是否有 CORS 错误
|
||
|
||
### Q: 数据库文件在哪里？
|
||
|
||
**A**: 数据库文件 `blogweb.db` 在项目根目录下。
|
||
|
||
## 下一步
|
||
|
||
1. 完善前端 UI 设计
|
||
2. 实现剩余功能模块（天气、记账、收藏、聊天、文件上传）
|
||
3. 添加单元测试
|
||
4. 配置生产环境部署
|
||
|