Personal Blog - 个人博客项目

现代化的前后端分离博客系统，采用最新技术栈：

• 前端：Vite + React 18 + TanStack Query（JavaScript）
• 后端：FastAPI + SQLAlchemy 2.0（Python 异步）
• 数据库：PostgreSQL 16
• 部署：Docker Compose 一键启动

🚀 快速启动

方式一：Docker Compose（推荐）

最简单的方式，一键启动数据库和后端：

# 1. 启动数据库和后端服务
docker compose up -d --build

# 2. 查看服务状态
docker compose ps

# 3. 查看后端日志
docker compose logs -f backend

后端将在 http://localhost:8000 运行，数据库在 localhost:5432。

然后启动前端（需要单独运行）：

cd frontend
npm install
npm run dev

前端将在 http://localhost:5173 运行。

方式二：本地开发（手动启动）

1. 启动数据库

选项 A：使用 Docker 启动 PostgreSQL

docker run -d \
  --name personal-blog-db \
  -e POSTGRES_USER=blog \
  -e POSTGRES_PASSWORD=blog \
  -e POSTGRES_DB=personal_blog \
  -p 5432:5432 \
  postgres:16

选项 B：使用本地已安装的 PostgreSQL 确保 PostgreSQL 已安装并运行，创建数据库：

CREATE DATABASE personal_blog;
CREATE USER blog WITH PASSWORD 'blog';
GRANT ALL PRIVILEGES ON DATABASE personal_blog TO blog;

2. 启动后端

# 进入后端目录
cd backend

# 创建虚拟环境（Windows）
python -m venv .venv
.\.venv\Scripts\activate

# 或 Linux/Mac
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
copy env.example .env  # Windows
# 或
cp env.example .env    # Linux/Mac

# 编辑 .env 文件，确保 DATABASE_URL 正确
# DATABASE_URL=postgresql+asyncpg://blog:blog@localhost:5432/personal_blog

# 启动后端服务
uvicorn app.main:app --reload

后端将在 http://localhost:8000 运行，访问 http://localhost:8000/docs 查看 API 文档。

3. 启动前端

# 进入前端目录
cd frontend

# 安装依赖
npm install

# 配置环境变量（可选）
copy env.example .env  # Windows
# 或
cp env.example .env    # Linux/Mac

# 编辑 .env 文件，设置后端 API 地址（如果后端不在默认端口）
# VITE_API_BASE_URL=http://localhost:8000

# 启动开发服务器
npm run dev

前端将在 http://localhost:5173 运行。

📋 环境变量配置

后端环境变量（backend/.env）

APP_NAME=Personal Blog API
DEBUG=true
DATABASE_URL=postgresql+asyncpg://blog:blog@localhost:5432/personal_blog
CORS_ORIGINS=["http://localhost:5173"]

前端环境变量（frontend/.env）

VITE_API_BASE_URL=http://localhost:8000

🔍 验证服务

1. 后端健康检查：访问 http://localhost:8000/health，应返回 {"status": "ok"}
2. API 文档：访问 http://localhost:8000/docs 查看 Swagger UI
3. 前端页面：访问 http://localhost:5173 查看博客首页

📁 目录结构

personal-blog/
├── backend/              # Python 后端
│   ├── app/
│   │   ├── api/         # API 路由
│   │   ├── core/        # 核心配置
│   │   ├── db/          # 数据库模型和会话
│   │   └── services/    # 业务逻辑层
│   ├── requirements.txt # Python 依赖
│   └── Dockerfile       # 后端 Docker 镜像
├── frontend/            # React 前端
│   ├── src/
│   │   ├── api/         # API 客户端
│   │   ├── components/  # React 组件
│   │   ├── pages/       # 页面组件
│   │   └── hooks/       # 自定义 Hooks
│   └── package.json     # Node.js 依赖
├── database/            # 数据库相关
│   └── sql/            # SQL 脚本和种子数据
├── nginx/              # Nginx 配置（可选）
└── docker-compose.yml  # Docker Compose 配置

🛠️ 常用命令

Docker Compose

# 启动所有服务
docker compose up -d

# 停止所有服务
docker compose down

# 查看日志
docker compose logs -f backend

# 重建并启动
docker compose up -d --build

# 清理数据卷（⚠️ 会删除数据库数据）
docker compose down -v

后端

# 开发模式（热重载）
uvicorn app.main:app --reload

# 生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8000

# 运行数据库初始化（如果需要）
python -m app.db.init_db

前端

# 开发模式
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

❓ 常见问题

1. 后端无法连接数据库

• 检查 PostgreSQL 是否正在运行
• 确认 DATABASE_URL 环境变量配置正确
• 检查数据库用户权限

2. 前端无法访问后端 API

• 确认后端服务已启动（访问 http://localhost:8000/health）
• 检查 VITE_API_BASE_URL 环境变量
• 查看浏览器控制台的 CORS 错误

3. Docker 容器启动失败

• 检查端口是否被占用（8000, 5432）
• 查看容器日志：docker compose logs backend
• 尝试重建镜像：docker compose build --no-cache

📝 下一步

• 添加用户认证和授权
• 实现文章创建和编辑功能
• 添加评论系统
• 配置 Nginx 反向代理
• 部署到生产环境