基于Python+Django的在线学习系统：核心模块拆解与部署实战-AI智能范式网

基于Python+Django的在线学习系统：核心模块拆解与部署实战

大雄行为锻炼·2026-10-09·阅读 21 GEO检测（免费）

PythonDjango在线学习系统

|难度：普通|阅读约 40 分钟

这类标题在技术交流平台里实在太常见了：基于Python+Django的自主在线学习系统，后面跟着源码、lw、部署文档、讲解视频几个关键词。很多同学拿到完整资源包之后，第一反应不是“终于可以学习了”，而是“这个项目我到底该从哪里看起”。我帮人排查过不少这样的Django项目，发现这类在线学习系统是一个很标准的Web开发练手场景，它把用户认证、课程内容、学习进度、测验评分、后台管理这些常见模块串在了一条业务链上。如果你正在做课设或者毕设，或者想通过一个完整项目掌握Django从开发到部署的全流程，这篇文章可以帮你把这个项目拆明白、跑起来，并且知道哪些地方值得重点讲给面试官听。

1. 项目认知与整体设计思路

1.1 一套完整资源包到底包含了什么

先从交付物的角度理解这个标题。源码指的是整个Django工程，一般包含了用户端、教师端和管理后台三个部分；lw指的项目文档，常见的写法包括需求分析、系统设计、数据库设计、核心功能实现和测试报告；部署文档负责解决“怎么跑起来”的问题，包括环境依赖、数据库迁移、静态文件收集、服务器上线步骤；讲解视频则是把上述内容用口述方式过一遍。

理解这四块之间的关系很重要。源码是骨架，lw是解释骨架为什么这样搭，部署文档是让骨架真正站起来，讲解视频则是加速理解的过程。对初学者来说，最容易犯的错误是直接打开源码读models.py，然后被各种关联字段绕晕。正确的顺序应该是先看lw中的需求分析和数据库设计部分，把角色和业务闭环弄清楚，再回到代码里去对应。

1.2 三类用户与核心业务闭环

自主在线学习系统的主角是学生、教师和管理员。学生选课、看章节内容、标记学习完成、参加章节测验、查看成绩和统计；教师创建课程、维护章节、设置测验题目、查看学生完成情况；管理员管理用户、处理违规内容、维护整体数据。

这个闭环的核心不是“展示课程列表”，而是“学习进度追踪”。一个没有进度记录的系统，本质上就是个内容发布站，谈不上“自主在线学习”。所以项目里最值得研究的业务逻辑是：学生完成一个章节之后，系统如何记住这个行为？下次登录如何继续？测验成绩如何影响课程完成度？把这些想明白，项目才算真正理解透了。

基于业务需求，数据库可以从五个核心表出发扩展：User用户表、Course课程表、Chapter章节表、StudyRecord学习记录表、Quiz测验相关表。后续增加的消息通知、课程评论、积分排行等，都是在这个骨架上做加法。

1.3 为什么这类系统普遍选择Django

自主在线学习系统用Django实现，几乎是最稳妥的选择。Django自带Admin后台，教师和管理员可以直接在后台维护课程内容，不用额外开发一套管理前端；自带ORM，数据库操作以模型类为主，学习成本比直接写SQL低；自带认证系统，登录、登出、会话管理、密码加密开箱即用；自带模板引擎，配合Bootstrap这类前端框架，可以快速做出能看的前端页面。

相比Flask，Django的“全家桶”特性对课程设计和初学者更友好，因为它把项目结构定下来了，不用你自己纠结该装什么扩展。相比Spring Boot，Django的部署和学习曲线更平滑，一个普通配置的服务器就能跑起来。如果项目还要考虑后续扩展，比如加一个移动端接口或者数据分析面板，Django的生态也足够支撑。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 核心功能模块与关键技术实现

2.1 用户模型扩展与权限控制

Django自带的User模型已经包含用户名、密码、邮箱等字段，但还缺少“角色”的概念。最常用的做法是继承AbstractUser，再增加role字段。

python复制from django.contrib.auth.models import AbstractUser
from django.db import models

class User(AbstractUser):
    ROLE_CHOICES = (
        ('student', '学生'),
        ('teacher', '教师'),
        ('admin', '管理员'),
    )
    role = models.CharField('角色', max_length=16, choices=ROLE_CHOICES, default='student')
    avatar = models.ImageField('头像', upload_to='avatars/', blank=True, null=True)

要注意的是，改完User模型之后，必须在settings.py里告诉Django使用自定义用户类：

python复制AUTH_USER_MODEL = 'myapp.User'

这个配置如果不写，Django还是会使用默认的auth.User，导致之后makemigrations时出现外键冲突或者模型关联错误。权限控制可以分成两层：视图层的登录保护用Django内置的login_required装饰器；角色判断用自定义方法或者UserPassesTestMixin。

python复制from django.contrib.auth.decorators import login_required
from django.shortcuts import redirect

def teacher_required(view_func):
    @login_required
    def wrapper(request, *args, **kwargs):
        if request.user.role != 'teacher' and not request.user.is_superuser:
            return redirect('index')
        return view_func(request, *args, **kwargs)
    return wrapper

2.2 课程、章节与学习进度的数据设计

课程和章节的关系是一对多，章节与学习记录的关系是一对一（针对同一学生）。代码设计上使用外键和unique_together来保证数据不重复写入。

python复制class Course(models.Model):
    title = models.CharField('课程名称', max_length=200)
    description = models.TextField('课程简介', blank=True)
    cover = models.ImageField('封面图', upload_to='course_covers/', blank=True)
    teacher = models.ForeignKey(User, on_delete=models.CASCADE, verbose_name='授课教师', related_name='courses')
    created_at = models.DateTimeField(auto_now_add=True)

class Chapter(models.Model):
    course = models.ForeignKey(Course, on_delete=models.CASCADE, verbose_name='所属课程', related_name='chapters')
    title = models.CharField('章节名称', max_length=200)
    order = models.PositiveIntegerField('排序', default=0)
    content = models.TextField('章节内容', blank=True)
    video_url = models.URLField('视频地址', blank=True)
    attachment = models.FileField('附件', upload_to='attachments/', blank=True)

class StudyRecord(models.Model):
    student = models.ForeignKey(User, on_delete=models.CASCADE, verbose_name='学生')
    chapter = models.ForeignKey(Chapter, on_delete=models.CASCADE, verbose_name='章节')
    finished = models.BooleanField('是否完成', default=False)
    finished_at = models.DateTimeField('完成时间', null=True, blank=True)

    class Meta:
        unique_together = ('student', 'chapter')

学习进度的核心操作是“标记完成”。这里推荐使用update_or_create而不是先get再create，避免并发情况下重复记录。

python复制from django.utils import timezone

@login_required
def mark_chapter_done(request, chapter_id):
    if request.method != 'POST':
        return JsonResponse({'status': 'error', 'message': '仅支持POST请求'})
    chapter = get_object_or_404(Chapter, pk=chapter_id)
    record, created = StudyRecord.objects.update_or_create(
        student=request.user,
        chapter=chapter,
        defaults={'finished': True, 'finished_at': timezone.now()}
    )
    return JsonResponse({'status': 'ok', 'created': created})

这样设计的好处是：无论学生点多少次“完成学习”，数据库里始终只有一条记录，状态始终是完成的。计算课程完成度时，用已完成章节数除以总章节数就可以。

2.3 测验模块与自动判分

测验模块是最能体现“在线学习”特色的功能。基本逻辑是每个章节关联一个测验，测验下有若干选择题，学生提交答案后，后端逐题比对。

python复制class Quiz(models.Model):
    chapter = models.ForeignKey(Chapter, on_delete=models.CASCADE, verbose_name='关联章节', related_name='quizzes')
    title = models.CharField('测验名称', max_length=200)

class Question(models.Model):
    quiz = models.ForeignKey(Quiz, on_delete=models.CASCADE, verbose_name='测验', related_name='questions')
    content = models.TextField('题干')
    option_a = models.CharField('选项A', max_length=200)
    option_b = models.CharField('选项B', max_length=200)
    option_c = models.CharField('选项C', max_length=200)
    option_d = models.CharField('选项D', max_length=200)
    answer = models.CharField('正确答案', max_length=1, choices=(('A', 'A'), ('B', 'B'), ('C', 'C'), ('D', 'D')))

class QuizResult(models.Model):
    student = models.ForeignKey(User, on_delete=models.CASCADE, verbose_name='学生')
    quiz = models.ForeignKey(Quiz, on_delete=models.CASCADE, verbose_name='测验')
    score = models.PositiveIntegerField('得分')
    total = models.PositiveIntegerField('总分')
    submit_time = models.DateTimeField(auto_now_add=True)

视图层读取POST数据时，要拿每一个Question的主键作为表单name属性，这样才能在提交后遍历比对。

python复制@login_required
def submit_quiz(request, quiz_id):
    quiz = get_object_or_404(Quiz, pk=quiz_id)
    questions = quiz.questions.all()
    score = 0
    for q in questions:
        selected = request.POST.get(str(q.id))
        if selected and selected.upper() == q.answer:
            score += 1
    total = questions.count()
    QuizResult.objects.create(student=request.user, quiz=quiz, score=score, total=total)
    percent = round(score / total * 100, 2) if total else 0
    return render(request, 'quiz_result.html', {
        'score': score,
        'total': total,
        'percent': percent,
        'passed': percent >= 60,
    })

判断是否通过可以用60分作为阈值，具体阈值可以在lw中定义为通过分数，尽量做成设置项而不是写死在视图里。

2.4 个人学习统计与仪表盘

统计功能是项目展示时的加分项。学生端仪表盘可以展示“已完成章节数”“课程完成度百分比”“测验平均分”“最近学习的课程”等。实现方式并不复杂，主要是ORM聚合查询的运用。

python复制from django.db.models import Count, Avg

@login_required
def dashboard(request):
    done_count = StudyRecord.objects.filter(student=request.user, finished=True).count()
    quiz_results = QuizResult.objects.filter(student=request.user)
    avg_score = quiz_results.aggregate(Avg('score'))['score__avg'] or 0
    course_progress = {}
    courses = Course.objects.filter(chapters_relation__isnull=False).distinct()
    for course in courses:
        total_chapters = course.chapters.count()
        done_chapters = StudyRecord.objects.filter(
            student=request.user,
            finished=True,
            chapter__course=course
        ).count()
        if total_chapters > 0:
            course_progress[course.id] = round(done_chapters / total_chapters * 100, 2)
    return render(request, 'dashboard.html', {
        'done_count': done_count,
        'avg_score': avg_score,
        'course_progress': course_progress,
    })

这里需要注意关联查询的字段名，related_name定义的是什么就写什么，不然会报AttributeError。仪表盘只做基础统计并不难，难点在于前端展示。建议用进度条组件，配合Bootstrap的progress类，一行CSS就能让完成度变得直观。

3. 本地开发环境到服务器部署

3.1 在本地把项目跑起来

拿到源码之后，第一步不是双击运行，而是先确认目录结构。一个正常的Django项目应该有manage.py、项目包（比如learning_system/）、应用包（比如myapp/）、requirements.txt、readme文档。

操作流程可以分为六步：

创建虚拟环境：python -m venv venv
激活环境：Windows下执行venv\Scripts\activate，Linux/Mac下执行source venv/bin/activate
安装依赖：pip install -r requirements.txt
配置数据库：如果没有MySQL，先用默认的SQLite
执行迁移：python manage.py makemigrations && python manage.py migrate
创建管理员：python manage.py createsuperuser
启动开发服务器：python manage.py runserver

如果迁移过程中报错，优先检查Python版本和Django版本是否搭配合适。Django 4.x对Python版本有明确要求，Python 3.8以下大概率跑不起来。

3.2 从SQLite切换到MySQL

很多部署文档会建议生产环境使用MySQL。切换时不仅要在settings.py修改数据库连接，还需要安装驱动，mysqlclient在Windows上安装经常失败，但可以通过预编译的wheel包解决。

python复制DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'learn_system',
        'USER': 'root',
        'PASSWORD': 'your_password',
        'HOST': '127.0.0.1',
        'PORT': '3306',
        'OPTIONS': {'charset': 'utf8mb4'},
    }
}

这里要注意charset参数，很多项目出现中文乱码，都是因为建库时没有指定utf8mb4编码。切换到MySQL之后，所有表的字符集都要保持一致，否则后续插入中文内容时会出现Incorrect string value错误。从SQLite迁移到MySQL不能直接拷贝数据库文件，需要重新执行makemigrations和migrate，再通过后台重新录入数据。

3.3 用Gunicorn配合Nginx上线

开发环境的runserver只适合调试，上线必须用独立的WSGI服务器。比较常见的组合是Gunicorn加Nginx。Gunicorn负责跑Python应用，Nginx负责接收用户请求、代理转发、托管静态文件和媒体文件。

bash复制pip install gunicorn
gunicorn learning_system.wsgi:application --bind 127.0.0.1:8000 --workers 3

Nginx配置可以写成：

nginx复制server {
    listen 80;
    server_name example.com;

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

    location /media/ {
        alias /path/to/project/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;
    }
}

部署时最容易被忽略的一步是collectstatic。关闭DEBUG后，Django不会再为你提供静态文件服务，必须先执行python manage.py collectstatic把所有静态资源集中到STATIC_ROOT目录，再交给Nginx处理。

3.4 生产环境必须改的几个配置

settings.py里有三个关键配置直接影响上线成败。DEBUG必须设为False，否则一旦服务器暴露到公网，报错页面会把项目路径、数据库配置全部泄露出去。ALLOWED_HOSTS要填服务器域名或IP，否则会出现DisallowedHost报错。SECRET_KEY不能使用仓库里默认的明文值，建议通过环境变量读取。

python复制import os

DEBUG = os.environ.get('DJANGO_DEBUG', 'False') == 'True'
ALLOWED_HOSTS = os.environ.get('DJANGO_ALLOWED_HOSTS', 'example.com').split(',')
SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'change-me')

时区和语言设置同样建议改一下，默认的UTC时区和英文界面会让很多用户困惑。

python复制LANGUAGE_CODE = 'zh-hans'
TIME_ZONE = 'Asia/Shanghai'
USE_TZ = True

我还遇到过很奇怪的现象：本地运行一切正常，部署上服务器之后，凡是涉及文件上传的模块都报错。后来排查发现是Nginx运行用户没有media目录的写权限。解决方案是给media目录设置合适的属主和权限，比如chown -R www-data:www-data media。

4. 高频问题与排查记录

4.1 让人反复踩坑的问题速查表

现象	常见原因	解决办法
makemigrations检测不到模型变化	应用没有注册到INSTALLED_APPS，或者模型在别的应用里	检查settings配置和应用目录下的apps.py
登录后跳转回登录页	LOGIN_URL配置错误，或者request.user没有正确传递到模板	检查装饰器顺序，确认模板中使用{{ request.user }}
后台访问样式全乱	DEBUG关闭后静态文件没有收集	执行collectstatic，确认Nginx静态目录配置
图片上传后访问404	MEDIA_ROOT和MEDIA_URL没有在URL配置中暴露	本地开发用static()辅助函数，生产环境交给Nginx
表单提交提示CSRF校验失败	模板form标签里缺少csrf_token	在form内部添加
中文内容变成问号	数据库连接字符集不是utf8mb4	修改DATABASES配置，重新创建数据库

这些坑的共同特点是：报错信息不直观，可能表现为404、500或者页面渲染异常，只有结合配置逐项排查才能定位。

4.2 拿到源码包之后如何快速排查

先读项目根目录的requirements.txt，了解当前项目的依赖版本。再用python manage.py check命令做一次系统自检，它能帮你发现settings中的明显错误。之后跑一次migrate，如果有未执行的迁移，系统会列出pending migration列表。

如果迁移全部正常，但访问首页还是报错，把runserver的终端日志贴出来，90%的问题集中在URL路径写错、模板文件找不到、模型字段名对不上这三种情况。URL问题最直观，看到NoReverseMatch就是在反向解析时出了问题；模板问题会报TemplateDoesNotExist；字段名错误几乎都会抛FieldError。

4.3 学习进度统计不准的排查思路

有同学问过：课程完成度明明显示100%，但测验模块却打不开，这种问题通常是业务逻辑中断导致。一个章节应该同时关联学习记录和测验，如果章节里没有创建测验，前端页面就无法正确渲染测验入口。

排查时可以进入Django Admin后台，检查每一条Chapter记录是否关联了Quiz记录。也可以用shell手动创建测验数据：

bash复制python manage.py shell

python复制from myapp.models import Course, Chapter, Quiz

course = Course.objects.first()
chapter = course.chapters.first()
quiz = Quiz.objects.create(chapter=chapter, title='第1章自测题')
print(quiz.id)

这种手工造数据的方式，在调试阶段比写一堆测试代码更直观，可以快速确认问题出在数据层面还是页面逻辑层面。

4.4 调试技巧：从print到日志与路由定位

我调试Django项目的习惯是先加一个日志记录，而不是直接看页面报错。

python复制import logging

logger = logging.getLogger(__name__)

def submit_quiz(request, quiz_id):
    logger.info('quiz_id=%s, user=%s', quiz_id, request.user)

在生产环境日志会写到服务端文件中，配合Nginx的access.log和error.log，能快速定位请求是否到达Django应用。如果Nginx日志里有请求记录，但Gunicorn日志没有响应记录，问题多半在WSGI进程崩溃或连接超时；如果Nginx日志为空，说明请求根本没到达服务器，可能是DNS解析或端口被防火墙拦截。

5. 从基础项目到作品集亮点

5.1 给项目增加明显差异化的功能

一个标准的学习系统做完，只是完成了及格线。想让项目在答辩或者面试时有记忆点，可以从三个方向扩展。第一个方向是内容形式升级，比如在章节中嵌入视频，用HTML5的video标签配合阿里云OSS或腾讯云COS这类对象存储服务，视频走CDN加速。第二个方向是学习反馈升级，比如引入答题后的知识点解析、错题本功能，每次测验结束后记录错题，方便学生集中复习。第三个方向是数据可视化，把学生的学习时长、测验成绩、活跃天数通过图表库展示成图表，这部分做出来非常直观，答辩时一张图胜过十句话。

5.2 如何写出能加分的项目文档

lw部分的结构可以按照这套逻辑来组织：第一章绪论写背景和国内外现状；第二章需求分析画用例图、功能模块图；第三章系统设计画架构图和ER图；第四章实现细节贴核心代码并逐段解释；第五章测试写用例表和结果分析；最后加总结与展望。

关键是每段代码都要有解释，解释不能只写“这段代码实现了什么功能”，而要写“为什么选择这个方法，如果不这样会有什么问题”。比如学习进度记录用unique_together保证唯一约束，如果不加，重复点击按钮会产生多条记录，统计自动乱掉。这种“原因解释”才是项目文档最大的价值。

5.3 二次开发的进一步设想

项目跑通了，后续扩展的空间很大。可以把静态部署改造成Docker部署，写好Dockerfile和docker-compose.yml，环境问题直接隔离。可以把课程订阅改成选课加积分制，学生完成课程获得积分，积分换取更多课程的访问权限，这就是一个简单的运营闭环。也可以把前后端分离，Django只提供RESTful API，前端用Vue或React单独开发，工程能力会体现得更明显。

这些扩展方向不是必须全部做完，根据自己时间和答辩重点选一个方向钻进去，比每个功能都浅尝辄止更有说服力。

5.4 我对这类学习系统项目的一点体会

我在带人复现这类Django项目时，最深的体会是：真正难的不是代码，而是把用户需求翻译成数据模型的能力。很多同学看到“自主在线学习系统”这八个字，第一反应是打开IDE开始写models，这是一种危险的冲动。先画清楚角色和流程，再设计表结构，最后写视图函数和模板，这件事的顺序一旦颠倒，项目大概率会返工。

如果你拿到的是一个已经写好的源码包，也别急着全部看懂，先从一条主链路入手：学生注册、登录、选课、学习章节、做测验、看成绩。把这个闭环跑通，再去看教师端和管理后台，整个系统就会清晰很多。这个主链路其实就是整个项目的骨架，其余功能都是附着在骨架上的肌肉和皮肤。