DJCMS 内容管理系统 - 产品说明文档

一、产品概述

1.1 产品简介

DJCMS 是一款基于 Django 6.0 框架开发的全功能内容管理系统（CMS），面向个人博客、企业官网、技术社区等内容驱动型网站场景。系统采用前后端一体化架构，提供完整的后台管理、前台展示和 RESTful API 接口，开箱即用。

1.2 核心价值

📦 开箱即用

内置完整的文章、页面、分类、标签、评论、媒体库等功能模块，无需二次开发即可上线

🎨 专业管理后台

自定义深色主题侧边栏布局，配备数据仪表盘、媒体库网格视图、站点设置可视化面板

🔍 SEO 友好

全站支持独立 SEO 配置、站点地图、URL 别名、自定义 Head/Footer 代码注入

🔌 RESTful API

完整的 CRUD 接口，支持第三方集成和移动端开发

📱 响应式设计

前台全站适配移动端，后台支持侧边栏收缩

1.3 技术栈

类别	技术	版本
后端框架	Django	6.0.5
编程语言	Python	3.15
数据库	SQLite（开发）/ 可扩展至 MySQL/PostgreSQL	-
前端框架	Bootstrap	5.3.2
图标库	Font Awesome	6.5.1
图表库	Chart.js	4.4.1
富文本编辑器	CKEditor（含上传）	4.22.1
REST API	Django REST Framework	-
标签系统	django-taggit	-
用户认证	django-allauth	-
跨域支持	django-cors-headers	-

二、系统架构

2.1 应用模块

DJCMS
├── cms_core      核心数据层 — 12个数据模型、表单、上下文处理器、站点地图
├── cms_admin     管理后台 — 仪表盘、媒体库、站点设置
├── cms_front     前台展示 — 首页、文章、搜索、评论、订阅
├── cms_api       API接口 — RESTful CRUD、搜索、统计
└── djcms         项目配置 — 设置、中间件、路由

2.2 数据流

用户请求 → URL路由 → 中间件（URL重定向/CSRF/认证） → 视图 → 模型 → 模板/序列化器 → 响应

2.3 中间件栈

顺序	中间件	职责
1	CorsMiddleware	跨域请求处理
2	SecurityMiddleware	安全防护
3	SessionMiddleware	会话管理
4	CommonMiddleware	通用处理
5	CsrfViewMiddleware	CSRF 防护
6	AuthenticationMiddleware	用户认证
7	MessageMiddleware	消息提示
8	XFrameOptionsMiddleware	点击劫持防护
9	AccountMiddleware	AllAuth 账户
10	URLRedirectMiddleware	自定义 URL 重定向

三、功能模块详细说明

3.1 内容管理

3.1.1 文章管理

文章是系统的核心内容单元，支持以下功能：

功能	说明
富文本编辑	CKEditor 全功能编辑器，支持图片上传、代码高亮、表格
分类归属	每篇文章归属一个分类
标签系统	支持多标签，使用 django-taggit
三种状态	草稿(draft)、已发布(published)、已归档(archived)
推荐标记	可标记为推荐文章，首页优先展示
自动摘要	未填写摘要时自动截取内容前200字符
浏览计数	自动记录浏览次数
SEO 配置	独立的 SEO 标题、描述、关键词
批量操作	批量发布、批量推荐、导出 JSON/CSV
特色图片	支持上传文章封面图

文章数据模型：

字段	类型	说明
title	CharField(200)	文章标题
slug	SlugField(250)	URL 别名，唯一
content	RichTextUploadingField	富文本内容
excerpt	TextField	摘要
featured_image	ImageField	特色图片
category	ForeignKey(Category)	所属分类
tags	TaggableManager	标签
author	ForeignKey(User)	作者
status	CharField(20)	状态
is_active	BooleanField	是否启用
is_featured	BooleanField	是否推荐
allow_comments	BooleanField	允许评论
publish_date	DateTimeField	发布时间
view_count	PositiveIntegerField	浏览次数
seo_title / seo_description / seo_keywords	-	SEO 字段

3.1.2 页面管理

页面用于创建"关于我们"、"隐私政策"等静态内容页面：

功能	说明
富文本编辑	同文章编辑器
首页设置	可将页面设为网站首页（全局唯一）
自定义模板	支持指定不同的模板文件
SEO 配置	独立的 SEO 字段
浏览计数	自动记录浏览次数
动态导航	已发布页面自动出现在前台导航栏和底部链接

3.1.3 分类管理

功能	说明
无限级嵌套	支持父子分类，可无限层级
图标配置	支持 Font Awesome 图标类名
排序权重	自定义排序顺序
SEO 配置	独立的 SEO 字段
文章统计	自动统计已发布文章数
URL 别名	自动生成 slug

3.1.4 标签系统

基于 django-taggit 实现：

文章可添加多个标签
标签云自动展示热门标签
支持按标签筛选文章
前台标签详情页展示相关文章

3.2 媒体管理

功能	说明
多类型支持	图片、文档、视频、音频、其他
网格视图	后台媒体库以卡片网格展示
图片预览	列表和详情页均显示图片缩略图
文件信息	自动记录文件大小、图片尺寸
文件大小格式化	自动转换为 B/KB/MB 显示
按月归档	上传文件按年月目录存储

3.3 评论系统

功能	说明
嵌套回复	支持多级评论回复
审核机制	评论需审核后才能展示
批量审核	后台支持批量审核/取消审核
IP 记录	自动记录评论者 IP 地址
访客评论	无需注册即可评论
评论表单	昵称、邮箱、网站（可选）、评论内容

3.4 导航菜单

功能	说明
多级菜单	支持父子级菜单项
四种链接类型	页面、文章、分类、自定义链接
智能URL	根据链接类型自动计算URL
排序权重	自定义菜单项顺序
打开方式	支持当前窗口/新窗口
图标配置	每个菜单项可配置图标
启用/禁用	可单独控制菜单项显示

3.5 SEO 优化

功能	说明
独立 SEO 字段	文章/页面/分类均可独立配置 SEO 标题、描述、关键词
站点地图	自动生成 sitemap.xml，包含文章/页面/分类/静态页面
URL 别名	所有内容均支持自定义 slug
自定义 Head HTML	可在 `</head>` 前注入自定义代码
自定义 Footer HTML	可在 `</body>` 前注入自定义代码
Google Analytics	内置 GA 追踪 ID 配置
Open Graph	自动生成 OG 标签
Canonical URL	自动设置规范链接

3.6 邮件订阅

功能	说明
前台订阅表单	底部区域嵌入订阅入口
AJAX 提交	无刷新订阅体验
令牌验证	每个订阅者自动生成唯一令牌
退订功能	通过令牌链接安全退订
重复检测	自动检查邮箱是否已订阅
Toast 反馈	订阅成功/失败即时提示
订阅说明	可自定义订阅说明文字

3.7 URL 重定向

功能	说明
301/302 重定向	支持永久和临时重定向
中间件自动处理	请求自动匹配重定向规则
命中计数	记录每条规则被触发的次数
路径排除	自动跳过 /admin/、/api/、/ckeditor/ 路径
启用/禁用	可单独控制规则生效

3.8 内容块

可复用的内容片段，用于侧边栏、横幅、页脚等区域：

类型	说明
html	自定义 HTML 内容
text	纯文本内容
banner	横幅广告（含图片和链接）
sidebar	侧边栏内容块
footer	页脚内容块

3.9 通知系统

功能	说明
四种类型	信息(info)、成功(success)、警告(warning)、错误(danger)
未读计数	导航栏实时显示未读通知数
批量操作	批量标记已读/未读
关联链接	通知可关联相关 URL
全局通知	不绑定用户时为全局通知

3.10 作者档案

扩展 Django 用户模型，为作者提供更丰富的个人资料：

字段	说明
bio	个人简介
avatar	头像
website	个人网站
twitter	Twitter 账号
github	GitHub 账号
job_title	职位
display_email	是否公开邮箱
article_count	已发布文章数（自动统计）
total_views	总浏览量（自动统计）

3.11 站点设置

采用单例模式，全局唯一配置实例，分为 7 大设置分区：

分区	包含设置项
基本信息	站点名称、描述、Logo、Favicon、页脚文本
SEO	默认 SEO 标题、描述、关键词
联系方式	邮箱、电话、地址
社交媒体	Facebook、Twitter/X、Instagram、LinkedIn、YouTube、GitHub
分析代码	Google Analytics ID、自定义 Head/Footer HTML
邮件服务	SMTP 服务器、端口、用户、密码、TLS、通知邮箱
系统设置	每页文章数、评论开关、维护模式、缓存时间、暗色模式、延迟加载

四、管理后台

4.1 界面设计

布局：左侧固定深色渐变侧边栏 + 右侧内容区
侧边栏：品牌 Logo、分组导航菜单、用户信息
配色：深蓝渐变侧边栏(#0f172a → #1a2332)、浅灰内容区、蓝色主色调(#4361ee)
响应式：移动端侧边栏自动收缩

4.2 控制台仪表盘

组件	说明
统计卡片	文章数、分类数、媒体数、浏览量、评论数、订阅数、页面数、通知数
快捷操作	写文章、添加分类、上传媒体、新建页面、系统设置
发布趋势图	30天文章发布趋势折线图
状态分布图	文章状态饼图
分类分布图	分类文章分布饼图
媒体类型图	媒体文件类型柱状图
最近文章	最新5篇文章列表
最新评论	最新5条评论列表

4.3 侧边栏菜单

分组	菜单项
概览	控制台
内容管理	文章管理、页面管理、分类管理、评论管理、媒体库
系统	邮件订阅、通知管理、内容块、URL 重定向、作者档案、用户管理、用户组、站点设置

4.4 批量操作

模型	支持的批量操作
文章	发布、取消发布、推荐、取消推荐、导出 JSON、导出 CSV
评论	审核通过、取消审核
通知	标记已读、标记未读

五、前台展示

5.1 页面列表

页面	URL	说明
首页	`/`	推荐文章大图展示、最新文章网格、分类探索、标签云
文章列表	`/articles/`	支持分类/标签/搜索/日期筛选，右侧栏含分类/近期/归档/标签
文章详情	`/articles/<年>/<月>/<日>/<slug>/`	TOC 目录、社交分享、作者卡、上下篇、相关文章、评论
分类详情	`/category/<slug>/`	分类信息 + 文章列表
标签详情	`/tag/<tag>/`	标签文章列表
搜索	`/search/?q=`	全文搜索结果
联系我们	`/contact/`	联系信息 + 表单
作者详情	`/author/<username>/`	作者资料 + 文章列表
静态页面	`/<slug>/`	自定义页面内容

5.2 前台特色功能

功能	说明
阅读进度条	顶部显示文章阅读进度
返回顶部	滚动超过 300px 显示返回顶部按钮
TOC 目录	自动从文章 h2/h3 生成目录导航
社交分享	Twitter、Facebook、LinkedIn、WhatsApp、Telegram、复制链接
图片懒加载	IntersectionObserver 实现，自动降级
消息提示	Bootstrap Alert 自动 5 秒关闭
表单防重复	提交时按钮禁用 + loading 状态
面包屑导航	多级面包屑路径
暗色模式	全站暗色主题支持
动态导航	已发布页面自动出现在导航栏和底部

5.3 前台导航栏

项目	说明
Logo/站点名	链接至首页
首页	固定导航项
文章	链接至文章列表
分类	下拉菜单展示所有分类
动态页面	自动显示所有已发布的非首页页面
联系我们	固定导航项
管理入口	仅管理员可见，显示未读通知 badge
搜索框	右侧搜索框

5.4 前台页脚

四栏布局：

栏目	内容
站点信息	站点名称、描述、联系邮箱、联系电话
快速链接	首页、文章列表、动态页面、联系我们
热门分类	前5个分类链接
关注我们	社交媒体按钮、邮件订阅表单

六、RESTful API

6.1 接口列表

接口	方法	权限	说明
`/api/articles/`	GET/POST	读取公开/创建需认证	文章列表与创建
`/api/articles/<slug>/`	GET/PUT/PATCH/DELETE	读取公开/修改需认证	文章详情与修改
`/api/articles/archive/`	GET	公开	文章归档（按年月分组）
`/api/articles/<slug>/increment_view/`	POST	公开	浏览量递增
`/api/categories/`	GET/POST	读取公开/创建需认证	分类列表与创建
`/api/categories/<slug>/`	GET/PUT/PATCH/DELETE	读取公开/修改需认证	分类详情与修改
`/api/pages/`	GET/POST	读取公开/创建需认证	页面列表与创建
`/api/pages/<slug>/`	GET/PUT/PATCH/DELETE	读取公开/修改需认证	页面详情与修改
`/api/pages/<slug>/increment_view/`	POST	公开	浏览量递增
`/api/media/`	GET/POST	仅管理员	媒体列表与上传
`/api/media/<pk>/`	GET/PUT/PATCH/DELETE	仅管理员	媒体详情与修改
`/api/comments/`	GET/POST	读取公开/创建公开	评论列表与创建
`/api/settings/`	GET/PUT/PATCH	仅管理员	站点设置读写
`/api/stats/`	GET	公开	站点统计数据
`/api/search/?q=`	GET	公开	全局搜索（文章+页面）

6.2 API 查询参数

资源	参数	说明
文章	`?category=&tag=&author=&search=&featured=true`	多维度筛选
分类	`?parent=null`	获取顶级分类
媒体	`?type=image`	按类型筛选
分页	`?page=1`	页码（默认每页20条）

6.3 站点统计接口

GET /api/stats/ 返回：

{
    "total_articles": 158,
    "published_articles": 145,
    "total_categories": 8,
    "total_comments": 10,
    "total_views": 50000,
    "total_subscribers": 25,
    "total_pages": 2,
    "total_media": 15
}

七、数据模型总览

系统共包含 12 个核心数据模型：

模型	说明	关键特性
Category	分类	无限级嵌套、SEO、图标
Page	页面	首页设置、自定义模板、SEO
Article	文章	富文本、标签、推荐、SEO、批量操作
Media	媒体	多类型、缩略图、文件信息
SiteSettings	站点设置	单例模式、7大分区
Comment	评论	嵌套回复、审核机制
Menu	菜单	导航菜单容器
MenuItem	菜单项	四种链接类型、多级
NewsletterSubscriber	订阅者	令牌验证、退订
URLRedirect	URL重定向	301/302、命中计数
ContentBlock	内容块	五种类型、可复用
Notification	通知	四种类型、已读/未读
AuthorProfile	作者档案	扩展用户、统计

八、安全机制

机制	说明
CSRF 防护	全站 CSRF Token 验证
XSS 防护	Django 模板自动转义、CKEditor 内容过滤
SQL 注入防护	Django ORM 参数化查询
点击劫持防护	X-Frame-Options 中间件
CORS 控制	django-cors-headers 可配置跨域策略
认证授权	Django Auth + django-allauth
API 权限	DRF IsAuthenticatedOrReadOnly / IsAdminUser
评论审核	评论默认需审核后展示
密码安全	Django 内置密码哈希

九、部署说明

9.1 环境要求

Python 3.11+
Django 6.0+
SQLite（开发）/ MySQL 8.0+ / PostgreSQL 14+（生产）

9.2 快速启动

# 1. 克隆项目
git clone <repository_url>
cd djcms

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate

# 3. 安装依赖
pip install django django-ckeditor django-ckeditor-uploader django-taggit
pip install djangorestframework django-cors-headers django-allauth Pillow

# 4. 初始化数据库
python manage.py migrate

# 5. 加载种子数据
python seed_data.py

# 6. 生成测试文章（可选）
python manage.py generate_articles

# 7. 创建超级管理员
python manage.py createsuperuser

# 8. 启动开发服务器
python manage.py runserver 0.0.0.0:8000

9.3 生产部署建议

组件	推荐方案
WSGI 服务器	Gunicorn
反向代理	Nginx
数据库	PostgreSQL / MySQL
静态文件	Nginx 直接服务 / CDN
媒体文件	对象存储（OSS/S3）
HTTPS	Let's Encrypt + Nginx
进程管理	systemd / Supervisor

9.4 关键配置项

配置	生产环境建议
DEBUG	False
ALLOWED_HOSTS	设置具体域名
SECRET_KEY	使用环境变量
DATABASE	切换至 PostgreSQL/MySQL
EMAIL_BACKEND	切换至 SMTP
CORS_ALLOW_ALL_ORIGINS	False，设置具体域名

十、项目目录结构

djcms/
├── cms_core/                     # 核心数据层
│   ├── management/commands/      # 管理命令
│   │   └── generate_articles.py  # 批量生成文章
│   ├── migrations/               # 数据库迁移
│   ├── admin.py                  # Admin 后台注册
│   ├── context_processors.py     # 全局上下文处理器
│   ├── forms.py                  # 表单定义
│   ├── models.py                 # 数据模型（12个）
│   └── sitemaps.py               # SEO 站点地图
│
├── cms_admin/                    # 管理后台
│   ├── urls.py                   # 后台路由
│   └── views.py                  # 仪表盘/媒体库/设置
│
├── cms_front/                    # 前台展示
│   ├── urls.py                   # 前台路由
│   └── views.py                  # 所有前台视图
│
├── cms_api/                      # REST API
│   ├── serializers.py            # DRF 序列化器
│   ├── urls.py                   # API 路由
│   └── views.py                  # API 视图集
│
├── djcms/                        # 项目配置
│   ├── middleware.py             # URL 重定向中间件
│   ├── settings.py               # 全局配置
│   └── urls.py                   # 根路由
│
├── static/                       # 静态资源
│   ├── css/
│   │   ├── style.css             # 前台样式（863行）
│   │   ├── admin.css             # 后台样式（556行）
│   │   ├── dark-mode.css         # 暗色模式（145行）
│   │   └── ckeditor.css          # 编辑器样式（82行）
│   └── js/
│       └── main.js               # 前台脚本（170行）
│
├── templates/                    # 模板文件
│   ├── base.html                 # 前台基础模板
│   ├── admin/                    # 后台模板（15+个）
│   └── cms_front/                # 前台页面模板（9个）
│
├── media/                        # 媒体上传目录
├── logs/                         # 日志目录
├── db.sqlite3                    # SQLite 数据库
├── manage.py                     # Django 管理脚本
└── seed_data.py                  # 种子数据脚本

十一、版本信息

项目	版本
系统版本	DJCMS v2.0
框架版本	Django 6.0.5
Python 版本	3.15
数据库	SQLite 3

十二、未来规划

方向	计划功能
多语言	支持中英文切换
主题系统	可视化主题切换
插件机制	支持第三方插件安装
全文搜索	Elasticsearch 集成
缓存优化	Redis 缓存层
实时通信	WebSocket 通知推送
移动端 API	完善的移动端接口
自动化测试	完整的单元测试和集成测试
Docker 部署	一键 Docker Compose 部署
CI/CD	GitHub Actions 自动化流水线