DJCMS 技术文档

一、技术架构

1.1 架构概述

DJCMS 采用 Django MVT（Model-View-Template）架构，分为四个独立应用模块：

1.2 应用职责划分

1.3 请求处理流程

二、数据模型

2.1 模型继承体系

所有业务模型继承自 TimeStampedModel 抽象基类，自动包含 created_at 和 updated_at 时间戳字段。

class TimeStampedModel(models.Model):
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)
    class Meta:
        abstract = True

继承关系：

2.2 模型关系图

2.3 模型详细定义

Category（分类）

关键方法：

• save() — slug为空时自动从name生成
• total_articles — 属性，返回已发布文章数
• get_absolute_url() — 返回 /category/<slug>/

Meta配置：ordering = ['sort_order', 'name']

Article（文章）

数据库索引：

• (status, is_active, publish_date) — 列表查询优化
• (slug) — URL查找优化

关键方法：

• save() — excerpt为空时自动从content中去除HTML标签后截取前200字符
• get_absolute_url() — 返回 /articles/<year>/<month>/<day>/<slug>/

Page（页面）

关键方法：

• save() — is_home=True时，自动将其他页面的is_home设为False（确保唯一）
• get_absolute_url() — 首页返回 /，其他返回 /<slug>/

Media（媒体）

属性方法：

• url — 返回文件URL
• size_display — 自动格式化为 B/KB/MB

SiteSettings（站点设置）— 单例模式

实现原理：

class SiteSettings(models.Model):
    # ... 30+ 字段 ...

    def save(self, *args, **kwargs):
        SiteSettings.objects.exclude(pk=self.pk).delete()
        super().save(*args, **kwargs)

    @classmethod
    def get_settings(cls):
        obj, created = cls.objects.get_or_create(pk=1)
        return obj

• save() 时删除除自身外的所有记录，确保数据库中只有一条记录
• get_settings() 类方法始终返回 pk=1 的实例，不存在则创建
• Admin 中 has_add_permission() 在已有记录时返回 False，has_delete_permission() 始终返回 False

字段分组：

Comment（评论）

Menu / MenuItem（导航菜单）

Menu：name, slug, description

MenuItem：

get_url() 方法：根据 link_type 智能返回URL：

• page → page.get_absolute_url()
• article → article.get_absolute_url()
• category → category.get_absolute_url()
• custom → link_url

NewsletterSubscriber（邮件订阅者）

save() 方法：token为空时自动生成 uuid.uuid4().hex

URLRedirect（URL重定向）

ContentBlock（内容块）

Notification（通知）

AuthorProfile（作者档案）

属性方法：

• article_count — 该作者已发布文章数
• total_views — 该作者文章总浏览量

三、URL路由

3.1 根路由配置

文件：djcms/urls.py

urlpatterns = [
    path('admin/', admin.site.urls),           # Django默认Admin
    path('cms-admin/', include('cms_admin.urls')),  # 自定义管理后台
    path('ckeditor/', include('ckeditor_uploader.urls')),  # CKEditor上传
    path('api/', include('cms_api.urls')),      # REST API
    path('accounts/', include('allauth.urls')), # 用户认证
    path('sitemap.xml', sitemap, {...}),        # 站点地图
    path('', include('cms_front.urls')),        # 前台（catch-all，必须在最后）
]

3.2 前台路由

文件：cms_front/urls.py，命名空间：cms_front

查询参数：

3.3 管理后台路由

文件：cms_admin/urls.py，命名空间：cms_admin

3.4 API路由

文件：cms_api/urls.py，命名空间：cms_api

四、视图层

4.1 前台视图

home(request)

首页视图。优先检查是否设置了自定义首页（Page.is_home=True），有则渲染该页面；否则展示默认首页，包含推荐文章、最新文章、分类探索、标签云、站点统计。

数据查询：

featured_articles = Article.objects.filter(
    status='published', is_active=True, is_featured=True
).select_related('author', 'category')[:6]

latest_articles = Article.objects.filter(
    status='published', is_active=True
).select_related('author', 'category')[:9]

categories = Category.objects.filter(
    is_active=True, articles__status='published'
).annotate(article_count=Count('articles')).order_by('-article_count')[:8]

tag_cloud = Article.tags.most_common()[:15]

article_detail(request, year, month, day, slug)

文章详情视图。通过年月日+slug精确定位文章，自动递增浏览量，展示评论、相关文章、上下篇导航。

关键逻辑：

# 精确日期范围查询
target_date = datetime(year, month, day, tzinfo=get_current_timezone())
next_date = target_date + timedelta(days=1)
article = get_object_or_404(Article, slug=slug, publish_date__gte=target_date, publish_date__lt=next_date)

# 浏览量递增（使用update避免竞态条件）
Article.objects.filter(pk=article.pk).update(view_count=article.view_count + 1)

# 评论处理（POST提交，需审核）
if request.method == 'POST':
    form = CommentForm(request.POST)
    if form.is_valid():
        comment = form.save(commit=False)
        comment.article = article
        comment.ip_address = request.META.get('REMOTE_ADDR', '')
        comment.save()

article_list(request)

文章列表视图。支持多维度筛选（分类/标签/搜索/日期），使用 Django Paginator 分页，右侧栏展示分类、近期文章、归档、标签云。

筛选逻辑：

if category_slug:
    articles_list = articles_list.filter(category__slug=category_slug)
if tag:
    articles_list = articles_list.filter(tags__name__iexact=tag)
if search_query:
    articles_list = articles_list.filter(
        Q(title__icontains=search_query) |
        Q(content__icontains=search_query) |
        Q(excerpt__icontains=search_query)
    )

contact(request)

联系表单视图。POST提交时发送邮件至站点配置的通知邮箱，使用 Django send_mail。

newsletter_subscribe(request)

AJAX订阅端点。仅接受POST请求，返回JSON响应。

@require_POST
def newsletter_subscribe(request):
    form = NewsletterForm(request.POST)
    if form.is_valid():
        form.save()
        return JsonResponse({'success': True, 'message': '订阅成功！'})
    else:
        return JsonResponse({'success': False, 'message': errors[0]})

subscribe_api(request)

API订阅端点。支持JSON body和表单数据两种格式，豁免CSRF（@csrf_exempt）。

4.2 管理后台视图

dashboard(request)

控制台仪表盘。装饰器 @staff_member_required 限制仅管理员访问。

统计数据：文章数/发布数/草稿数/归档数、页面数、分类数、媒体数、评论数/待审核数、订阅数、重定向数、总浏览量、未读通知数。

图表数据（JSON序列化传给 Chart.js）：

• daily_chart — 30天发布趋势（逐日查询）
• status_chart — 文章状态分布
• category_chart — 分类文章分布
• media_chart — 媒体类型分布

site_settings_view(request)

站点设置视图。POST时手动处理各类型字段：

# 字符串/文本字段
for field in fields:
    setattr(settings, field, request.POST.get(field, ''))

# 布尔字段（checkbox未选中时不出现在POST中）
for field in bool_fields:
    setattr(settings, field, field in request.POST)

# 整数字段
for field in int_fields:
    setattr(settings, field, int(request.POST[field]))

# 文件字段
for field in fields:
    if field in request.FILES:
        setattr(settings, field, request.FILES[field])

4.3 API视图

自定义权限类

class IsAdminOrReadOnly(permissions.BasePermission):
    """管理员可写，所有人可读"""
    def has_permission(self, request, view):
        if request.method in permissions.SAFE_METHODS:
            return True
        return request.user and request.user.is_staff

ArticleViewSet

class ArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.filter(is_active=True)
    serializer_class = ArticleSerializer
    lookup_field = 'slug'
    permission_classes = [IsAdminOrReadOnly]
    filterset_fields = ['category', 'author', 'status']

    @action(detail=True, methods=['post'])
    def increment_view(self, request, slug=None):
        """浏览量递增"""
        article = self.get_object()
        article.view_count += 1
        article.save(update_fields=['view_count'])
        return Response({'view_count': article.view_count})

    @action(detail=False, methods=['get'])
    def archive(self, request):
        """文章归档（按年月分组）"""
        ...

CommentListCreateView

class CommentListCreateView(generics.ListCreateAPIView):
    queryset = Comment.objects.all()

    def get_serializer_class(self):
        if self.request.method == 'POST':
            return CommentCreateSerializer  # 不含is_approved
        return CommentSerializer  # is_approved只读

site_stats(request)

公开统计接口，返回站点核心数据。

search_api(request)

全局搜索接口，同时搜索文章和页面，返回合并结果。

五、序列化器

文件：cms_api/serializers.py

5.1 序列化器列表

5.2 标签序列化

ArticleSerializer 使用 TaggitSerializer 混入处理 django-taggit 标签：

class ArticleSerializer(TaggitSerializer, serializers.ModelSerializer):
    tags = TagListSerializerField()
    author_name = serializers.CharField(source='author.username', read_only=True)
    category_name = serializers.CharField(source='category.name', read_only=True)
    url = serializers.SerializerMethodField()

    def get_url(self, obj):
        return obj.get_absolute_url()

六、表单

文件：cms_core/forms.py

6.1 CommentForm

class CommentForm(forms.ModelForm):
    class Meta:
        model = Comment
        fields = ['author_name', 'author_email', 'author_website', 'content']

    # 验证规则
    clean_author_name(): len >= 2
    clean_content(): len >= 5

6.2 NewsletterForm

class NewsletterForm(forms.ModelForm):
    class Meta:
        model = NewsletterSubscriber
        fields = ['email']

    # 验证规则
    clean_email(): 检查 NewsletterSubscriber.objects.filter(email=email, is_active=True).exists()

6.3 ContactForm

class ContactForm(forms.Form):
    name = CharField(max_length=100)      # len >= 2
    email = EmailField()
    subject = CharField(max_length=200)
    message = CharField(widget=Textarea)   # len >= 10

七、中间件

7.1 URLRedirectMiddleware

文件：djcms/middleware.py

功能：在请求处理前检查自定义URL重定向规则。

处理逻辑：

class URLRedirectMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        path = request.path

        # 跳过管理后台、API、CKEditor路径
        skip_prefixes = ['/admin/', '/cms-admin/', '/api/', '/ckeditor/', '/static/', '/media/']
        if any(path.startswith(prefix) for prefix in skip_prefixes):
            return self.get_response(request)

        # 查询匹配的重定向规则
        try:
            redirect = URLRedirect.objects.get(old_path=path, is_active=True)
            redirect.hit_count += 1
            redirect.save(update_fields=['hit_count'])
            return HttpResponsePermanentRedirect if redirect.redirect_type == '301' else HttpResponseRedirect
        except URLRedirect.DoesNotExist:
            pass

        return self.get_response(request)

八、上下文处理器

文件：cms_core/context_processors.py

函数 site_settings(request) 向所有模板注入全局变量：

calculate_reading_time(html_content)：去除HTML标签后按500字/分钟计算阅读时间，最少1分钟。

九、Admin后台配置

文件：cms_core/admin.py

9.1 全局配置

admin.site.site_header = 'DJCMS 内容管理系统'
admin.site.site_title = 'DJCMS 管理后台'
admin.site.index_title = '仪表盘'

9.2 各模型Admin配置

9.3 批量操作

ArticleAdmin：

CommentAdmin：approve_comments、disapprove_comments

NotificationAdmin：mark_as_read、mark_as_unread

NewsletterSubscriberAdmin：export_subscribers（CSV）

十、模板系统

10.1 模板继承结构

前台：

后台：

10.2 前台基础模板 block 结构

base.html 定义的 block：

10.3 后台基础模板结构

admin/base.html 采用左侧边栏 + 右侧内容区布局：

<div id="container">
    <aside class="sidebar">...</aside>     <!-- 固定侧边栏 -->
    <div class="content-wrapper">
        <nav class="content-topbar">...</nav>  <!-- 面包屑导航 -->
        <main class="main">
            <div class="main-content">
                {% block content %}{% endblock %}
            </div>
        </main>
    </div>
</div>

十一、静态资源

11.1 CSS架构

style.css（前台，863行）

CSS变量体系：

:root {
    --primary: #4361ee;
    --primary-dark: #3a56d4;
    --secondary: #6c757d;
    --success: #06d6a0;
    --danger: #ef476f;
    --warning: #ffd166;
    --info: #118ab2;
    --dark: #1a1a2e;
    --light: #f8f9fa;
    --gray-50: #f9fafb;
    --gray-100: #f3f4f6;
    --sidebar-width: 260px;
    --transition: all 0.3s ease;
}

核心样式模块：

• 导航栏（毛玻璃效果 backdrop-filter: blur(10px)）
• 推荐文章大图展示区
• 文章卡片（悬浮动画 transform: translateY(-4px)）
• 分类卡片（悬浮变色边框）
• 标签云
• CTA区域
• 文章内容排版（标题/代码/引用/表格）
• 分页器
• 表单样式
• 阅读进度条
• 返回顶部按钮
• TOC目录
• 骨架屏加载动画

admin.css（后台，556行）

完整设计系统，包含：

• CSS变量（颜色/阴影/圆角/过渡）
• 侧边栏深色渐变（#0f172a → #1a2332）
• 内容区布局
• 数据表格样式
• 变更列表/表单覆盖
• 仪表盘统计卡片/图表/快捷操作
• 响应式（@media (max-width: 992px) 侧边栏收缩）

dark-mode.css（暗色模式，145行）

深蓝紫色调（#1a1a2e / #16213e），覆盖所有组件。

ckeditor.css（编辑器内容样式，82行）

CKEditor内容区域排版，确保编辑器内显示效果与前台一致。

11.2 JavaScript

文件：static/js/main.js（170行）

十二、SEO站点地图

文件：cms_core/sitemaps.py

URL配置：

path('sitemap.xml', sitemap, {
    'sitemaps': {
        'pages': PageSitemap,
        'articles': ArticleSitemap,
        'categories': CategorySitemap,
        'static': StaticViewSitemap,
    }
}),

十三、管理命令

13.1 generate_articles

文件：cms_core/management/commands/generate_articles.py

用途：批量生成测试文章数据。

用法：

python manage.py generate_articles

特点：

• 内置约150篇预定义文章数据
• 涵盖 Python/JavaScript/Web/DevOps/设计/生活/教程 分类
• 随机分配作者、发布日期、浏览量
• 15%概率设为推荐文章
• 90%概率为已发布状态
• 自动处理slug冲突
• 幂等操作（已存在的slug会自动追加后缀）

十四、种子数据

文件：seed_data.py

用途：初始化项目基础数据。

用法：

python seed_data.py

创建内容：

• 8个分类（含父子关系）
• 12篇精选文章（含完整HTML内容和标签）
• 2个页面（关于我们、隐私政策）
• 作者档案
• 主导航菜单（含菜单项）
• 站点设置
• 侧边栏内容块

十五、配置参考

15.1 Django设置

文件：djcms/settings.py

15.2 CKEditor配置

15.3 REST Framework配置

15.4 CORS配置

15.5 日志配置

LOGGING = {
    'handlers': {
        'file': {
            'level': 'ERROR',
            'class': 'logging.FileHandler',
            'filename': BASE_DIR / 'logs' / 'django.log',
        }
    },
    'loggers': {
        'django': {
            'handlers': ['file'],
            'level': 'ERROR',
        }
    }
}

十六、数据库迁移

16.1 迁移历史

16.2 数据库切换

从 SQLite 切换到 PostgreSQL/MySQL：

# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'djcms',
        'USER': 'djcms_user',
        'PASSWORD': 'your_password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

十七、第三方依赖

一键安装：

pip install django django-ckeditor django-ckeditor-uploader django-taggit djangorestframework django-cors-headers django-allauth Pillow

十八、开发指南

18.1 开发环境搭建

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

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# 3. 安装依赖
pip install django django-ckeditor django-ckeditor-uploader django-taggit \
    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

18.2 访问地址

18.3 新增功能模块

1. 在 cms_core/models.py 中定义模型
2. 运行 python manage.py makemigrations 和 python manage.py migrate
3. 在 cms_core/admin.py 中注册Admin
4. 在 cms_front/views.py 中创建视图
5. 在 cms_front/urls.py 中添加路由
6. 在 templates/cms_front/ 中创建模板
7. 如需API，在 cms_api/serializers.py 和 cms_api/views.py 中添加

18.4 代码规范

• 模型字段使用中文 verbose_name
• 模型 Meta 使用中文 verbose_name 和 verbose_name_plural
• 视图函数使用 docstring 注释
• Admin 类使用 format_html 和 mark_safe 渲染 HTML
• 表单使用 Bootstrap form-control 样式
• CSS 使用变量体系保持一致性
• 查询使用 select_related / prefetch_related 优化

十九、生产部署

19.1 部署架构

19.2 Gunicorn配置

pip install gunicorn
gunicorn djcms.wsgi:application --bind 0.0.0.0:8000 --workers 4

19.3 Nginx配置示例

server {
    listen 80;
    server_name example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /static/ {
        alias /path/to/djcms/staticfiles/;
    }

    location /media/ {
        alias /path/to/djcms/media/;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

19.4 生产环境检查清单

二十、性能优化建议