DjangoBlog 个人博客项目架构文档
基于 liangliangyy/DjangoBlog 定制
项目路径: /home/devil/projects/djangoblog
一、项目概述
DjangoBlog 是一个基于 Django 5.2 的现代化个人博客系统，支持后台管理（Admin）全功能内容管理，可直接在网页上完成文章、分类、标签、友链、侧边栏等内容的新增、编辑和删除。
核心能力矩阵
| 功能 |
说明 |
| 文章管理 |
增删改查、Markdown编辑器、草稿/发布、排序 |
| 分类管理 |
支持无限父子分类 |
| 标签管理 |
多对多关联 |
| 评论系统 |
支持 GitHub 风格 emoji 反应、嵌套回复 |
| 友链管理 |
支持首页/列表/文章页等位置展示 |
| 侧边栏 |
可自定义 HTML 内容 |
| 站点配置 |
标题、SEO、底部信息、评论审核等 |
| 搜索 |
Elasticsearch / Whoosh 双引擎 |
| 多语言 |
中文简体/繁体/英文 |
| 深色模式 |
支持系统跟随、手动切换、localStorage 持久化 |
| OAuth 登录 |
GitHub / Google 等第三方登录 |
| RSS/Atom 订阅 |
文章订阅输出 |
二、项目目录结构
djangoblog/ # 项目根目录
├── manage.py # Django 项目管理入口
├── requirements.txt # Python 依赖
├── Dockerfile # Docker 部署
│
├── djangoblog/ # Django 项目配置目录（主配置）
│ ├── settings.py # 全局配置（数据库、中间件、APP）
│ ├── urls.py # 根 URL 路由
│ ├── wsgi.py # WSGI 部署入口
│ ├── admin_site.py # 自定义 Admin 站点
│ ├── mixins.py # 通用 Mixin（缓存、查询优化、分页）
│ ├── feeds.py # RSS/Atom 订阅
│ ├── sitemap.py # 站点地图
│ ├── utils.py # 工具函数（缓存、设置）
│ ├── constants.py # 常量定义
│ └── blog_signals.py # 信号处理
│
├── blog/ # 博客核心 APP
│ ├── models.py # 数据模型（Article/Category/Tag/Links/SideBar）
│ ├── views.py # 视图（首页/文章详情/分类/标签/归档）
│ ├── urls.py # 博客 URL 路由
│ ├── admin.py # Admin 管理配置
│ ├── forms.py # 表单
│ ├── middleware.py # 中间件
│ ├── context_processors.py # 上下文处理器
│ ├── documents.py # ES 文档映射
│ ├── search_indexes.py # 搜索索引
│ ├── templatetags/ # 自定义模板标签
│ │ └── blog_tags.py
│ ├── management/commands/ # 管理命令
│ │ ├── build_index.py # 重建搜索索引
│ │ ├── clear_cache.py # 清除缓存
│ │ └── create_testdata.py # 创建测试数据
│ └── static/blog/ # 博客静态资源
│
├── accounts/ # 用户认证 APP
│ ├── models.py # BlogUser 模型（继承 AbstractUser）
│ ├── views.py # 登录/注册/密码重置等视图
│ ├── forms.py # 用户表单
│ └── user_login_backend.py # 自定义登录后端（邮箱/用户名）
│
├── comments/ # 评论 APP
│ ├── models.py # Comment / CommentReaction 模型
│ ├── views.py # 评论提交/展示视图
│ └── utils.py # 评论工具（IP获取、UA解析）
│
├── oauth/ # OAuth 第三方登录 APP
│ ├── models.py # OAuthConfig / OAuthUser
│ ├── oauthmanager.py # OAuth 管理器（GitHub/Google/微信）
│ └── views.py # 认证回调处理
│
├── servermanager/ # 服务器管理 APP
│ ├── api/ # API 接口
│ │ ├── blogapi.py # 博客 API（搜索/分类/最近文章）
│ │ └── commonapi.py # 通用 API
│ ├── robot.py # 微信机器人
│ └── models.py # Commands / EmailSendLog
│
├── owntracks/ # 位置追踪 APP
│ └── models.py # OwnTrackLog
│
├── plugins/ # 插件系统
│ ├── article_copyright/ # 文章版权声明
│ ├── article_recommendation/ # 文章推荐
│ ├── external_links/ # 外部链接处理
│ ├── image_lazy_loading/ # 图片懒加载
│ ├── reading_time/ # 阅读时间估算
│ ├── seo_optimizer/ # SEO 优化
│ ├── view_count/ # 阅读计数
│ └── cloudflare_cache/ # Cloudflare 缓存刷新
│
├── djangoblog/plugin_manage/ # 插件管理框架
│ ├── hook_constants.py # 钩子常量
│ ├── hooks.py # 钩子注册/触发
│ └── loader.py # 插件加载器
│
├── frontend/ # 前端资源（Vite + Tailwind + Alpine.js）
│ ├── package.json # Node.js 依赖
│ ├── vite.config.js # Vite 构建配置
│ ├── tailwind.config.js # Tailwind CSS 配置
│ ├── src/ # 前端源码
│ │ ├── main.js # 入口文件
│ │ ├── styles/main.css # 全局样式
│ │ └── components/ # 组件
│ │ ├── navigation.js # 导航栏
│ │ ├── darkMode.js # 深色模式
│ │ ├── backToTop.js # 回到顶部
│ │ ├── codeCopy.js # 代码复制
│ │ ├── imageLightbox.js # 图片灯箱
│ │ ├── commentSystem.js # 评论系统
│ │ └── reactionPicker.js # emoji 反应选择器
│
├── templates/ # Django 模板
│ ├── share_layout/ # 全局布局
│ │ ├── base.html # 基础模板
│ │ ├── nav.html # 导航栏
│ │ └── footer.html # 页脚
│ ├── blog/ # 博客页面模板
│ │ ├── article_index.html # 首页文章列表
│ │ ├── article_detail.html # 文章详情页
│ │ └── article_archives.html # 归档页面
│ ├── account/ # 账户模板
│ ├── comments/ # 评论模板
│ ├── oauth/ # OAuth 模板
│ └── search/ # 搜索模板
│
├── uploads/ # 上传文件目录（媒体）
└── locale/ # 国际化翻译文件
├── zh_Hans/ # 简体中文
├── zh_Hant/ # 繁体中文
└── en/ # 英文
三、核心数据模型
3.1 文章 (Article)
| 字段 |
类型 |
说明 |
title |
CharField(200) |
文章标题，唯一 |
body |
MDTextField |
Markdown 正文 |
pub_time |
DateTimeField |
发布时间 |
status |
CharField(1) |
d=草稿, p=已发布 |
comment_status |
CharField(1) |
o=开放, c=关闭 |
type |
CharField(1) |
a=文章, p=页面 |
views |
PositiveIntegerField |
阅读数 |
author |
ForeignKey(BlogUser) |
作者 |
category |
ForeignKey(Category) |
分类 |
tags |
ManyToManyField(Tag) |
标签 |
article_order |
IntegerField |
排序权重 |
show_toc |
BooleanField |
是否显示目录 |
3.2 分类 (Category)
| 字段 |
类型 |
说明 |
name |
CharField(30) |
分类名称 |
parent_category |
ForeignKey(self) |
父分类（支持无限级） |
slug |
SlugField |
URL 友好标识 |
3.3 标签 (Tag)
| 字段 |
类型 |
说明 |
name |
CharField(30) |
标签名称 |
slug |
SlugField |
URL 友好标识 |
| 字段 |
类型 |
说明 |
body |
TextField |
评论内容 |
author |
ForeignKey(BlogUser) |
评论者 |
article |
ForeignKey(Article) |
所属文章 |
parent_comment |
ForeignKey(self) |
父评论（嵌套回复） |
is_enable |
BooleanField |
是否显示（审核） |
3.5 站点配置 (BlogSettings) — 单例模型
| 字段 |
类型 |
说明 |
title |
CharField |
站点标题 |
description |
CharField |
站点描述 |
keywords |
CharField |
SEO 关键词 |
footer |
TextField |
页脚 HTML |
beian |
CharField |
备案号 |
analytics_code |
TextField |
统计代码 |
color_scheme |
CharField |
主题配色 |
article_sub_max_length |
IntegerField |
摘要截断长度 |
comment_need_review |
BooleanField |
评论需审核 |
四、URL 路由设计
前端路由（用户可见）
/ → 首页（文章列表）
/page/<int:page>/ → 首页分页
/article/<Y>/<M>/<D>/<id>.html → 文章详情
/category/<slug>.html → 分类文章列表
/tag/<slug>.html → 标签文章列表
/author/<name>.html → 作者文章列表
/archives.html → 文章归档
/links.html → 友情链接
/search → 全文搜索
/feed/ /rss/ → RSS 订阅
/sitemap.xml → 站点地图
后台管理路由（管理员可见）
/admin/ → Admin 后台首页
/admin/blog/article/ → 文章列表 + 增删改
/admin/blog/category/ → 分类管理
/admin/blog/tag/ → 标签管理
/admin/blog/links/ → 友链管理
/admin/blog/sidebar/ → 侧边栏管理
/admin/blog/blogsettings/ → 站点配置
/admin/comments/comment/ → 评论管理
/admin/account/bloguser/ → 用户管理
五、请求处理流程
用户请求 → Nginx (静态文件) / Gunicorn (动态)
↓
Django WSGI
↓
URL 路由 (urls.py)
↓
中间件链 (Security → Session → Locale → GZip → Common → CSRF → Auth → Message)
↓
View 视图 (ListView / DetailView)
↓
Mixin 层 (缓存 → 查询优化 → 分页)
↓
Model 查询 (select_related + prefetch_related)
↓
模板渲染 (base.html + 页面模板 + 插件钩子)
↓
返回 HTML 响应
六、缓存策略
| 缓存目标 |
策略 |
Key 模式 |
| 文章列表页 |
数据库缓存 + 文件缓存 |
index_{page} |
| 分类列表 |
数据库缓存 |
category_{slug}_{page} |
| 标签列表 |
数据库缓存 |
tag_{slug}_{page} |
| 文章详情 |
数据库缓存 |
article_{id} |
| 站点设置 |
数据库缓存 |
blog_settings |
| 侧边栏 |
数据库缓存 |
sidebar_{name} |
七、插件系统
插件通过「钩子（Hook）」机制在模板渲染时介入：
| 钩子 |
触发位置 |
已实现插件 |
article_content_hook |
文章内容渲染后 |
版权声明、阅读时间、图片懒加载、SEO、文章推荐 |
article_detail_bottom_hook |
文章详情页底部 |
文章推荐 |
sidebar_hook |
侧边栏渲染 |
文章推荐 |
css_includes_hook |
页面头部 CSS |
各插件样式 |
js_includes_hook |
页面底部 JS |
各插件脚本 |
插件结构示例 (plugins/article_copyright/plugin.py):
class ArticleCopyrightPlugin(BasePlugin):
def get_hooks(self):
return {
'article_content_hook': self.add_copyright
}
def add_copyright(self, context):
# 在文章末尾添加版权声明
...
八、部署架构
┌─────────────┐
│ Nginx │ ← 反向代理 + 静态文件
│ (80/443) │
└──────┬──────┘
│ proxy_pass
┌──────┴──────┐
│ Gunicorn │ ← Python WSGI 服务器
│ + gevent │
└──────┬──────┘
│
┌────────────┼────────────┐
│ │ │
┌──────┴─────┐ ┌───┴────┐ ┌────┴────┐
│ MySQL 8 │ │ Redis │ │ Elastic │
│ (主存储) │ │ (缓存) │ │ (搜索) │
└────────────┘ └────────┘ └─────────┘
开发环境（当前使用）
| 组件 |
方案 |
| 数据库 |
SQLite（开发）/ MySQL（生产） |
| 缓存 |
本地内存缓存（开发）/ Redis（生产） |
| 搜索 |
Whoosh（开发）/ Elasticsearch（生产） |
| 前端构建 |
Vite + ESBuild |
| CSS 框架 |
Tailwind CSS + Alpine.js |
| WSGI 服务器 |
Uvicorn（开发）/ Gunicorn（生产） |
九、网页内容管理流程
通过 Django Admin 后台实现网页端的完整内容管理：
1. 管理员登录 → /admin/
2. 进入「文章」列表页 → 查看/搜索/过滤所有文章
3. 点击「新增文章」→ 使用 Markdown 编辑器 (mdEditor) 编写
- 支持实时预览
- 支持图片上传
- 支持代码高亮
4. 设置分类、标签、排序权重、发布状态
5. 保存 → 自动生成 slug → 缓存清除 → 前端立即可见
6. 已有文章可随时编辑 / 删除 / 切换草稿/发布
同样流程适用于：分类、标签、友链、侧边栏、站点配置、评论审核。
十、自定义计划（后续迭代）
| 优先级 |
改造项 |
说明 |
| P0 |
内容个性化 |
替换示例数据为个人博客内容（文章、分类、标签） |
| P0 |
主题定制 |
修改配色、Logo、导航文案、页脚信息 |
| P1 |
多数据库支持 |
SQLite 开发 ↔ MySQL 生产环境切换 |
| P1 |
前端页面美化 |
进一步定制 Tailwind 样式 |
| P2 |
自定义域名 |
配置站点域名和 HTTPS |
| P2 |
评论开放 |
配置第三方 OAuth 登录 |
本文由 admin 原创，转载请注明出处。
评论
0