blogweb/SETUP_GUIDE.md

项目设置指南

快速开始

1. 安装后端依赖

pip install -r requirements.txt

2. 初始化数据库

# 从项目根目录运行
python -m app.db.init_db

如果需要重置数据库（⚠️ 会删除所有数据）：

python -m app.db.init_db --reset

3. 配置环境变量

复制 .env.example 为 .env：

# Windows
copy .env.example .env

# Linux/Mac
cp .env.example .env

编辑 .env 文件，修改以下配置：

# 必须修改（生产环境）
SECRET_KEY=your-secret-key-change-in-production

# 可选：如果需要天气功能
OPENWEATHER_API_KEY=your-api-key

4. 启动后端服务

# 方式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. 安装前端依赖

cd frontend
npm install

6. 启动前端服务

npm run dev

前端服务将在 http://localhost:5173 启动。

项目结构说明

详细的项目结构说明请查看 PROJECT_STRUCTURE.md。

重要变更

数据库初始化脚本位置调整

旧位置：backend/init_db.py
新位置：backend/app/db/init_db.py

新的运行方式：

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. 用户注册

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. 用户登录

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. 获取当前用户信息

curl -X GET "http://localhost:8000/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

4. 创建待办事项

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 路径中。或者使用：

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. 配置生产环境部署