在系统性地学习了FastAPI框架的核心特性后，本教程将通过一个完整的项目，带你动手开发一个基于FastAPI的前后端一体化企业级知识库博客平台，实现学以致用。
先看看效果
首页文章页显示
文章详情页
后台登录系统：
文章管理列表
创建分类，管理分类页
数据看板页
评论管理页
通知中心
用户管理页面
更多详细的功能，可在部署后亲自体验。
企业博客论坛平台
这是一个基于 FastAPI + MySQL + SQLAlchemy 构建的前后端一体化博客系统，专为企业内部知识分享与团队协作设计。
📁 项目结构
project/
├── backend/ # 后端代码
│ ├── main.py # FastAPI应用入口 ✅
│ ├── api/ # 接口层 (API Layer)
│ │ ├── auth.py # 认证API ✅
│ │ ├── users.py # 用户管理API ✅
│ │ ├── articles.py # 文章管理API ✅
│ │ ├── categories.py # 分类管理API ✅
│ │ ├── comments.py # 评论管理API ✅
│ │ └── stats.py # 统计API ✅
│ ├── services/ # 业务层 (Business Layer)
│ │ ├── auth_service.py # 认证业务逻辑 ✅
│ │ ├── user_service.py # 用户业务逻辑 ✅
│ │ ├── article_service.py # 文章业务逻辑 ✅
│ │ └── email_service.py # 邮件服务 ✅
│ ├── models/ # 模型层 (Model Layer)
│ │ ├── base.py # 基础模型 ✅
│ │ ├── user.py # 用户模型 ✅
│ │ ├── article.py # 文章模型 ✅
│ │ └── comment.py # 评论模型 ✅
│ ├── schemas/ # 数据模式 (Schema Layer)
│ │ ├── user.py # 用户模式 ✅
│ │ ├── article.py # 文章模式 ✅
│ │ └── comment.py # 评论模式 ✅
│ ├── utils/ # 工具层 (Utils Layer)
│ │ ├── database.py # 数据库工具 ✅
│ │ ├── auth.py # 认证工具 ✅
│ │ ├── document_utils.py # 文档处理工具 ✅
│ │ └── spam_filter.py # 垃圾过滤工具 ✅
│ └── core/ # 核心配置 (Core Layer)
│ ├── config.py # 应用配置 ✅
│ └── dependencies.py # 依赖注入 ✅
├── frontend/ # 前端代码
│ ├── templates/ # HTML模板 ✅
│ └── static/ # 静态资源 ✅
│ └── css/ # CSS文件 ✅
├── uploads/ # 上传文件 ✅
└── run_server.py # 启动脚本 ✅
✨ 功能特性
核心功能
- 🔐 权限管理: 管理员/后端用户/访客三级权限体系
- ✍️ 文章管理: 支持Markdown格式，发布/编辑/删除文章
- 📖 内容浏览: 现代化UI，响应式设计，优秀的阅读体验
- 💬 互动功能: 评论、点赞、阅读统计
- 🎨 美观界面: TailwindCSS设计，现代化UI风格
技术特性
- ⚡ FastAPI高性能异步框架
- 🔒 JWT身份认证
- 📝 Markdown内容渲染
- 🗄️ SQLAlchemy ORM
- 📊 RESTful API设计
- 📱 响应式布局
🚀 快速开始
方式一：使用启动脚本（推荐 - Windows）
- 创建数据库
CREATE DATABASE blog_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
- 配置环境编辑
.env 文件，修改数据库密码：
DATABASE_URL=mysql+pymysql://root:你的密码@localhost:3306/blog_db
- 运行启动脚本
start.bat & python run_server.py
方式二：手动启动
- 安装依赖
pip install -r requirements.txt
- 创建数据库
# 使用SQL脚本
mysql -u root -p < create_database.sql
# 或手动创建
mysql -u root -p
CREATE DATABASE blog_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
- 配置环境变量
# 复制配置文件
cp .env.example .env
# 编辑 .env 文件，修改数据库连接信息
- 初始化数据库
python init_db.py
项目提供了SQL初始化脚本，可直接在数据库管理工具中执行。
- 启动服务
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
访问系统
| 功能 |
地址 |
说明 |
| 前端首页 |
http://localhost:8000 |
浏览文章 |
| 文章详情 |
http://localhost:8000/article/{id} |
查看文章详情 |
| 后台登录 |
http://localhost:8000/admin/login |
管理员/用户登录 |
| 后台管理 |
http://localhost:8000/admin/dashboard |
文章和用户管理 |
| API文档 |
http://localhost:8000/docs |
Swagger交互式文档 |
默认账号
管理员账号
⚠️ 重要: 请妥善保管超级管理员密码！
📖 文档导航
| 文档 |
说明 |
| 快速开始 |
5分钟快速部署指南 |
| 配置指南 |
配置管理详细说明 |
| 用户指南 |
详细的功能使用说明 |
| 部署指南 |
生产环境部署文档 |
| 项目总览 |
架构设计和技术细节 |
⚙️ 配置管理
项目采用统一的配置管理方式，所有配置集中在 config.py 中：
主要配置项
# 数据库配置
DATABASE_URL=mysql+pymysql://root:password@localhost:3306/blog_db
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10
# JWT认证配置
SECRET_KEY=your-secret-key-change-this
ACCESS_TOKEN_EXPIRE_MINUTES=30
# 应用配置
DEBUG=False
HOST=0.0.0.0
PORT=8000
详细配置说明请查看 CONFIG_GUIDE.md。
🎯 核心功能说明
管理员功能
- 创建后端用户账号
- 管理所有用户
- 发布/编辑/删除任何文章
- 查看系统统计
- 下载文章
后端用户功能
- 登录后台系统
- 发布新文章（支持Markdown）
- 编辑自己的文章
- 删除自己的文章
- 查看文章统计数据
前端访客功能
- 浏览所有文章
- 查看文章详情
- 发表评论
- 点赞文章
- 无需登录即可访问
🔧 技术栈
后端
- 框架: FastAPI
- 数据库: MySQL 8.0+
- ORM: SQLAlchemy 2.0
- 认证: JWT (python-jose)
- 密码加密: bcrypt
前端
- UI框架: TailwindCSS 3.x
- 图标: Font Awesome 6.4
- Markdown渲染: marked.js
- 模板引擎: Jinja2
📊 数据库设计
核心表结构
- users (用户表)
- articles (文章表)
- comments (评论表)
- likes (点赞表)
🔒 安全特性
- ✅ 密码bcrypt加密存储
- ✅ JWT Token身份验证
- ✅ 三级权限控制
- ✅ SQL注入防护（ORM）
- ✅ XSS攻击防护
- ✅ IP限制点赞
🚀 生产环境部署
详细部署步骤请参考 DEPLOYMENT.md。
快速部署要点
- 使用Nginx反向代理
- 配置HTTPS证书
- 使用Supervisor管理进程
- 配置数据库备份
- 启用日志监控
📝 API接口
完整API文档访问: http://localhost:8000/docs
主要接口
| 方法 |
路径 |
说明 |
权限 |
| POST |
/api/auth/login |
用户登录 |
公开 |
| GET |
/api/articles |
获取文章列表 |
公开 |
| GET |
/api/articles/{id} |
获取文章详情 |
公开 |
| POST |
/api/articles |
创建文章 |
需登录 |
| PUT |
/api/articles/{id} |
更新文章 |
需登录 |
| DELETE |
/api/articles/{id} |
删除文章 |
需登录 |
| POST |
/api/articles/{id}/comments |
发表评论 |
公开 |
| POST |
/api/articles/{id}/like |
点赞文章 |
公开 |
| POST |
/api/users |
创建用户 |
需管理员 |
| GET |
/api/users |
获取用户列表 |
需管理员 |
🛠️ 常见问题
数据库连接失败
检查MySQL服务是否启动，数据库配置是否正确。
端口被占用
修改启动命令中的端口号，如果不改，默认是8000：
python -m uvicorn backend.main:app --reload --host 0.0.0.0 --port 8001
依赖安装失败
使用国内镜像源：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
更多问题请查看 USER_GUIDE.md 的常见问题部分。
用户使用指南
系统概述
企业博客论坛平台是一个前后端一体化的知识分享系统，支持文章发布、浏览、评论和点赞功能。
角色说明
1. 超级管理员&管理员
- 创建后端用户账号
- 发布、编辑、删除，下载文章，管理所有内容
- 管理所有用户和内容
2. 后端用户
- 登录后台系统
- 发布、编辑、删除自己的文章
- 查看文章统计数据
3. 前端访客
- 浏览所有已发布的文章
- 查看文章详情
- 评论文章
- 点赞文章
功能使用
超级管理员操作
1. 首次登录
访问 http://localhost:8000/admin/login
默认账号：
重要：超级管理员密码请不要随意给出
2. 创建用户
- 登录后台管理系统
- 点击"用户管理"标签
- 填写用户信息：
- 用户名（必填）
- 邮箱（可选）
- 密码（必填）
- 是否为管理员（勾选框）
- 点击"创建用户"按钮
3. 查看用户列表
在"用户管理"标签下可以看到：
- 所有用户列表
- 用户角色（管理员/普通用户）
- 注册时间
后端用户操作
1. 登录系统
访问 http://localhost:8000/admin/login，使用管理员分配的账号密码登录。
2. 发布文章
- 登录后台管理系统
- 在"文章管理"标签下
- 填写文章标题和内容
- 内容支持Markdown格式：
# 一级标题
## 二级标题
**粗体文字**
*斜体文字*
- 列表项1
- 列表项2
```代码块```
> 引用文字
- 点击"发布文章"按钮
3. 编辑文章
- 在"我的文章"列表中找到要编辑的文章
- 点击"编辑"按钮
- 修改标题或内容
- 点击"更新文章"按钮
4. 删除文章
- 在"我的文章"列表中找到要删除的文章
- 点击"删除"按钮
- 确认删除操作
5. 查看文章统计
在文章列表中可以看到：
前端访客操作
1. 浏览文章
访问 http://localhost:8000，可以看到所有已发布的文章列表。
每篇文章显示：
- 文章标题
- 作者名称
- 发布时间
- 内容摘要
- 阅读数、点赞数、评论数
2. 阅读文章
点击文章标题或"阅读全文"按钮，进入文章详情页。
文章详情页显示：
- 完整的文章内容（Markdown渲染）
- 作者信息
- 发布时间
- 统计数据
3. 点赞文章
在文章详情页，点击红色的爱心图标即可点赞。
注意：
4. 评论文章
在文章详情页底部：
- 输入您的昵称（可选，默认为"访客"）
- 输入评论内容
- 点击"发表评论"按钮
评论会立即显示在评论列表中。
Markdown语法快速参考
标题
# 一级标题
## 二级标题
### 三级标题
文字样式
**粗体**
*斜体*
~~删除线~~
`代码`
列表
- 无序列表项1
- 无序列表项2
1. 有序列表项1
2. 有序列表项2
链接和图片
[链接文字](https://example.com)
引用
> 这是一段引用文字
代码块
<pre>
def hello():
print("Hello World")
</pre>
表格
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容1 | 内容2 | 内容3 |
常见问题
Q: 忘记密码怎么办？
A: 请联系超级管理员重置密码。超级管理员可以通过后台直接修改新密码。
Q: 文章可以插入图片吗？
A: 可以，使用Markdown语法插入图片链接。建议先将图片上传到图床服务，或者直接使用富文本编写，支持在线粘贴图片。
Q: 可以删除别人的评论吗？
A: 目前系统只有超级管理员支持删除别人评论功能。
Q: 文章内容有字数限制吗？
A: 没有硬性限制，但建议单篇文章不超过10000字，以保证阅读体验。
Q: 可以导出文章吗？
A: 可以通过API接口获取文章内容，管理员和超级管理员可以登录后台下载，或直接从数据库导出。
Q: 支持文章分类和标签吗？
A: 支持。
技术支持
如遇到问题，请：
- 查看系统日志
- 检查网络连接
- 联系系统管理员
API文档地址：http://localhost:8000/docs
📄 许可证
本项目仅供企业内部使用。
版本: v1.0.0
最后更新: 2025-11-24
发表于 2025-12-25 07:52:52
|
查看: 27|
回复: 0
