这个项目并不是什么宏大工程它源于一个特别具体的问题县里每年都要组织农业技术培训但靠电话通知、线下集中授课的模式越来越跑不动了。乡镇学员分布散、农忙时间不固定、讲师来回跑成本高一场培训经常到场人数不到通知的一半。于是就有了这个基于Python和Django搭建的“某县农业技术在线培训平台”——本质是一个面向乡村场景的轻量在线教学系统。它能承载视频课程、文档资料、在线考核、学习进度追踪也兼容手机浏览器访问让学员在地里干活休息的空档也能掏出手机把一节课程看完。这套系统的技术栈不复杂Python 3.10 Django 4.2 MySQL Nginx Gunicorn前端用服务端渲染加少量JavaScript。但真正把一个“看起来不难”的Django项目做到能在基层环境稳定跑起来里面还是有不少值得记录的门道。下面我把整个项目从需求拆解到部署上线的过程完整写出来给要做类似在线教育、培训类系统的朋友一个参考。1. 需求倒推技术选型为什么这种系统选Django最省心1.1 先想清楚谁会打开这个系统做任何系统之前先把用户画像摸清楚。这个培训平台的使用者分为三类需求差异非常明显角色使用场景核心需求学员手机端为主农闲或碎片时间学习打开快、看得清、能记住学习进度讲师后台发布课程、上传资料偶尔查看学员学习情况操作简单、支持批量导入管理员汇总学时、导出考核数据、管理用户和课程数据统计清晰、权限分层这里面最要紧的是“学员用手机访问”。乡下的网络状况参差不齐手机型号跨度很大不能默认每个学员都有最新款智能手机和稳定宽带。所以前端页面必须轻避免引入重型框架保持服务端渲染的兼容性。1.2 为什么不是前后端分离也不上微服务技术选型那阵子我身边有朋友推荐用Vue Django REST Framework做前后端分离理由是“以后扩展方便”。但对于这个项目来说前后端分离是个伪需求。前后端分离的好处是交互体验好、前后端并行开发代价是至少多一层Node构建流程、多一套接口联调工作部署时还得处理跨域和静态资源托管。对于一个只有几千名学员、业务逻辑以“课程—学习—考核—统计”为主线的平台Django自带的模板引擎完全够用。而且模板渲染天然对SEO友好页面首屏快开发效率也高。微服务就更不必要了。业务规模没到那个量级强行拆分只会增加运维复杂度。一个Django项目加一个MySQL实例部署在一台4核8G的云服务器上初期完全够用单机架构排查问题还方便。1.3 框架选型上的几个现实考量选Django而不是Flask或FastAPI主要是这几点自带Admin后台Django内置的admin管理界面能极大降低讲师录入课程的负担稍微配置一下list_display、search_fields就能直接交付不用从零写管理端。用户认证体系完整Django自带的User模型和auth模块覆盖了登录、登出、权限分组、密码重置等常规需求不需要自己实现用户系统。ORM成熟稳定农业培训系统涉及大量数据筛选比如按村、按乡镇查学习记录用Django ORM写起来很直观生成的SQL性能也能接受。迁移机制方便迭代后续每次加字段、改表结构跑一遍makemigrations和migrate就能同步到生产库对单人开发来说省了太多事。提示版本建议直接用Django 4.2 LTS长期支持版本安全更新能持续到2026年左右。Python用3.10或3.11别用最新的Python 3.12或3.13部分第三方库的二进制包可能还没跟上。2. 数据模型设计核心就是“人—课—进度”三件套2.1 用户模型怎么扩别直接改Profile字段Django自带的User模型有username、password、email这些基础字段但培训系统需要记录学员的所属乡镇、村组、身份角色还有讲师和管理员的区分。常见的做法有两种一是继承AbstractUser重写User模型二是用OneToOneField扩展用户档案。我这次选择了第一种方式因为项目一开始就确定不要换用户模型扩展字段和业务绑定紧密直接在项目初始化阶段就用自定义User模型后续迁移更省心。# users/models.py from django.contrib.auth.models import AbstractUser from django.db import models class User(AbstractUser): ROLE_CHOICES ( (student, 学员), (teacher, 讲师), (admin, 管理员), ) role models.CharField(max_length16, choicesROLE_CHOICES, defaultstudent, verbose_name角色) region models.CharField(max_length64, blankTrue, verbose_name所属乡镇/村) phone models.CharField(max_length20, blankTrue, verbose_name手机号) id_card models.CharField(max_length18, blankTrue, verbose_name身份证号) created_at models.DateTimeField(auto_now_addTrue, verbose_name注册时间) class Meta: verbose_name 用户 verbose_name_plural 用户这里有个很实用的细节为每个角色建一个分组但不强制用Django的Group表而是直接靠role字段区分。因为业务逻辑里判断角色只需要一个if user.role teacher比查权限表轻量得多。Django的Group和Permission机制留给后期需要细粒度权限时再用。2.2 课程、章节、资料逻辑分层要清晰课程结构我从一开始就定成“培训计划—课程—章节”三层而不是扁平的一堆课程列表。原因是乡村培训系统天然有批次概念比如“2025年春季果树修剪培训班”下面有若干门课程每门课程里又有几个视频章节。# courses/models.py class TrainingPlan(models.Model): name models.CharField(max_length128, verbose_name培训计划名称) start_date models.DateField(verbose_name开始日期) end_date models.DateField(verbose_name结束日期) description models.TextField(blankTrue, verbose_name计划说明) is_active models.BooleanField(defaultTrue, verbose_name是否启用) class Course(models.Model): plan models.ForeignKey(TrainingPlan, on_deletemodels.CASCADE, related_namecourses, verbose_name所属培训计划) title models.CharField(max_length128, verbose_name课程名称) teacher models.ForeignKey(settings.AUTH_USER_MODEL, on_deletemodels.SET_NULL, nullTrue, related_namecourses, verbose_name授课讲师) cover models.ImageField(upload_tocovers/, blankTrue, verbose_name封面图) created_at models.DateTimeField(auto_now_addTrue, verbose_name创建时间) class Lesson(models.Model): course models.ForeignKey(Course, on_deletemodels.CASCADE, related_namelessons, verbose_name所属课程) title models.CharField(max_length128, verbose_name章节标题) video_url models.URLField(blankTrue, verbose_name视频地址) attachment models.FileField(upload_toattachments/, blankTrue, verbose_name附件资料) order models.PositiveIntegerField(default0, verbose_name排序) duration models.PositiveIntegerField(default0, verbose_name视频时长/秒)很多初学者容易忽略order字段。没有它删除一个章节后再添加章节顺序就会乱套。加上order字段查询时用order_by(order)就能稳定排序。注意视频文件先不要自己存本地。早期我们试过把视频直接传到Django的MEDIA_ROOT后来发现服务器带宽和存储都是大麻烦。一个1080P的课程视频随便就是几百MB一台8G内存的服务器兼做文件服务器很快就吃不消。后面改成传对象存储或者直接把视频托管到第三方视频平台Django只存一个video_url字段省了太多事。2.3 学习进度和考核用一张记录表解决所有统计问题学习记录是整个系统的数据核心。每次学员打开一个章节前端就向后端发一条上报请求后端记录“学到了哪里、看了多久、是否完成”。这样管理员随时能查出“某某乡镇有多少人完成了春季培训”。# records/models.py class LearningRecord(models.Model): user models.ForeignKey(settings.AUTH_USER_MODEL, on_deletemodels.CASCADE, related_namelearning_records, verbose_name学员) lesson models.ForeignKey(Lesson, on_deletemodels.CASCADE, related_namelearning_records, verbose_name章节) watch_seconds models.PositiveIntegerField(default0, verbose_name已观看时长/秒) is_completed models.BooleanField(defaultFalse, verbose_name是否完成) last_position models.PositiveIntegerField(default0, verbose_name最后播放位置/秒) updated_at models.DateTimeField(auto_nowTrue, verbose_name更新时间) class Meta: unique_together (user, lesson) class ExamResult(models.Model): user models.ForeignKey(settings.AUTH_USER_MODEL, on_deletemodels.CASCADE, verbose_name学员) course models.ForeignKey(Course, on_deletemodels.CASCADE, verbose_name课程) score models.FloatField(verbose_name考试得分) passed models.BooleanField(defaultFalse, verbose_name是否合格) submitted_at models.DateTimeField(auto_now_addTrue, verbose_name提交时间)LearningRecord表加了unique_together(user, lesson)保证同一个学员对同一章节只会有一条进度记录。更新进度时直接update_or_create既避免重复数据代码也简洁。一张记录表再配合Django的聚合查询就能满足绝大多数统计需求完成人数、平均学时、各村完成率一条ORM语句的事。3. 核心功能模块实现模板渲染为主接口为辅3.1 用户注册登录Django自带认证的“半定制”改造登录功能直接用Django的LoginView省掉手写表单校验和session管理的麻烦。但培训平台的学员注册有个特殊需求——需要管理员预绑定比如导入某乡镇学员名单后学员凭身份证号和初始密码登录。这就不能做成完全开放注册。# users/views.py from django.contrib.auth.views import LoginView, LogoutView class CustomLoginView(LoginView): template_name users/login.html redirect_authenticated_user True def get_success_url(self): user self.request.user if user.role student: return reverse(courses:student_home) elif user.role teacher: return reverse(courses:teacher_dashboard) return reverse(admin:index)这里有个坑redirect_authenticated_user True虽然在用户已登录时会直接跳过登录页但如果你没有定义get_success_url它会默认跳到Django的LOGIN_REDIRECT_URL。不同角色的跳转目标不同必须自己重写这个方法。注册方面我们用的是“名单导入首登改密”模式管理员在后台按模板Excel导入学员名单姓名、身份证号、手机号、所属村组系统自动生成用户名和初始密码学员首次登录后强制修改密码。这就绕开了手机验证码这类在乡村场景下经常收不到短信的麻烦。3.2 课程列表和学习页ListAPI 详情页的组合课程首页要让学员一眼看到当前正在进行的培训计划和每门课的完成状态。Django的ListView配合annotate就能把“每门课总章节数、已完成章节数”一并算出来。# courses/views.py from django.views.generic import ListView from django.db.models import Count, Q class CourseListView(ListView): template_name courses/course_list.html context_object_name courses paginate_by 12 def get_queryset(self): plan TrainingPlan.objects.filter(is_activeTrue).first() courses Course.objects.filter(planplan) user self.request.user for course in courses: total_lessons course.lessons.count() completed_lessons LearningRecord.objects.filter( useruser, lesson__coursecourse, is_completedTrue ).count() course.progress int(completed_lessons / total_lessons * 100) if total_lessons else 0 return courses直接在get_queryset里循环查数据库数据量小的时候没问题。如果课程数量涨上来建议改成annotate Count加条件聚合一条SQL搞定但初期这样写最简单直接业务跑起来以后再做性能优化也不迟。3.3 学习进度上报一个轻量POST接口前端播放页嵌入了一个简易的HTML5视频播放器每隔15秒向后端上报当前播放位置。之所以用接口而不是表单提交是为了让上报动作变成异步的不影响视频播放。# records/views.py import json from django.http import JsonResponse from django.views.decorators.http import require_POST from django.contrib.auth.decorators import login_required require_POST login_required def report_progress(request): data json.loads(request.body) lesson_id data.get(lesson_id) position int(data.get(position, 0)) watch_seconds int(data.get(watch_seconds, 0)) duration int(data.get(duration, 0)) try: lesson Lesson.objects.get(idlesson_id) except Lesson.DoesNotExist: return JsonResponse({code: 1, msg: 章节不存在}) record, created LearningRecord.objects.update_or_create( userrequest.user, lessonlesson, defaults{ last_position: position, watch_seconds: watch_seconds, } ) # 如果观看时长超过视频时长的85%判定为完成 if duration 0 and watch_seconds duration * 0.85: record.is_completed True record.save() return JsonResponse({code: 0, msg: ok})判断完成的标准是“观看时长超过视频时长的85%”这是故意的。不让学员拖动进度条到底就算完成也不要求100%看完——85%既保证有效学习又容忍了网络卡顿导致的最后几秒没播完的情况。前端用一个简单的setInterval每15秒调用一次这个接口同时把参数localStorage存一份避免切换页面导致进度丢失// schoolrecord.js let lastReported 0; video.addEventListener(timeupdate, function () { const pos Math.floor(video.currentTime); const dur Math.floor(video.duration); if (pos - lastReported 15) { lastReported pos; fetch(/records/report/, { method: POST, headers: { Content-Type: application/json, X-CSRFToken: getCookie(csrftoken) }, body: JSON.stringify({ lesson_id: LESSON_ID, position: pos, watch_seconds: pos, duration: dur }) }).catch(e { // 上报失败先存本地下次打开再补报 localStorage.setItem(pending_report_ LESSON_ID, JSON.stringify({ position: pos, watch_seconds: pos })); }); } });提示fetch请求里的X-CSRFToken一定要加上否则Django的CSRF中间件会直接返回403。getCookie函数可以放在全局公共JS里网上有很多现成写法这里不再贴完整代码。3.4 权限控制装饰器和Mixin的混合使用Django的权限体系很好用但默认的login_required只解决了“登录了没有”解决不了“登录了但角色不对”。我给不同角色写了独立的入口判断# common/decorators.py from functools import wraps from django.core.exceptions import PermissionDenied def role_required(roles): def decorator(view_func): wraps(view_func) def _wrapped(request, *args, **kwargs): if not request.user.is_authenticated: return redirect(users:login) if request.user.role not in roles: raise PermissionDenied return view_func(request, *args, **kwargs) return _wrapped return decorator role_required([teacher, admin]) def course_create(request): ...视图函数用装饰器类视图用UserPassesTestMixin或自定义LoginRequiredMixin两种风格统一起来用即可。注意一点PermissionDenied异常要在settings里配一个403的模板否则默认页面太难看也不友好。4. 踩坑实录从SQLite换到MySQL从页面白屏到强制刷新4.1 第一个坑SQLite不背锅但乡村场景并发真的会写锁Django项目默认数据库是SQLite开发时跑起来特别爽零配置、免维护。前期学员量小也没人刻意做压力测试直到有一次集中培训报名某村网格员在同一时间帮二十多个学员批量注册SQLite直接报database is locked。SQLite对“单写入者”的支持是有保障的但它不支持并发写。多个请求同时写入时后面的请求会等待等待超时就直接报错。培训系统里相关写入场景其实挺多上报进度、提交考核、批量导入用户任何一个请求密集的节点都可能把SQLite点爆。解决方案不复杂——换MySQL。在项目初期就换代价极低等项目跑起来数据多了再换光迁移数据就够折腾的。# settings.py 数据库配置片段 DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: training_db, USER: training_user, PASSWORD: your_password_here, HOST: 127.0.0.1, PORT: 3306, OPTIONS: { charset: utf8mb4, }, CONN_MAX_AGE: 60, } }CONN_MAX_AGE 60意思是数据库连接在60秒内复用避免每个请求都重新建连接。这个参数在高并发时能显著减少握手开销但要注意MySQL的wait_timeout默认是8小时如果连接空闲超过MySQL的超时阈值Django会复用失效连接报错。Django 4.1已经内置了连接健康检查配合CONN_MAX_AGE就基本不需要额外处理。4.2 第二个坑数据库字符集没配好用户名直接变问号学员姓名里带生僻字的导入进去之后页面上显示一串问号。这问题几乎每个做中文应用的人都会遇到根源是库、表、连接三个层面的字符集不一致。MySQL安装时默认编码可能是latin1也可能是utf8mb3就是utf8但utf8mb3存不下emoji和部分生僻字。正确做法是建库时指定utf8mb4CREATE DATABASE training_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;Django连接时再指定charsetutf8mb4双保险。库建好之后再改编码很麻烦建议项目初始化时就确认。除了数据库层面的编码问题Django的settings里也要设置FILE_CHARSET和DEFAULT_CHARSET默认就是utf-8一般不用动。比较隐蔽的是Excel导入用户名单时如果Excel文件本身是GBK编码用pandas读取时没指定encodinggbk中文全部变成乱码入库。这个坑我踩了两次才记住pandas读取Excel默认会把字符串列按单元格类型推断字符串里若有中文编码在原文件里就可能已经乱了最稳妥的流程是先转到CSV再逐行清洗。4.3 第三个坑admin站点里ImageField和FileField的MEDIA路径Django的admin虽然强大但文件上传的路径配置很容易被新手忽略。settings.py里如果没有配置MEDIA_URL和MEDIA_ROOT上传的文件会跑到项目根目录而且在admin列表里点击链接无法查看图片。MEDIA_URL /media/ MEDIA_ROOT BASE_DIR / media主urls.py里还要加一句from django.conf import settings from django.conf.urls.static import static urlpatterns [ ... ] static(settings.MEDIA_URL, document_rootsettings.MEDIA_ROOT)这句只会在DEBUGTrue时生效生产环境下Nginx会直接托管/media/路径。如果在生产环境忘记配置Nginx的location上传的文件能存但访问不了页面就是一片空。当时排查这个问题花了一下午。4.4 第四个坑前端页面缓存导致更新后学员仍看到旧课程Django模板渲染默认不会做浏览器缓存控制但如果你用Nginx做反向代理没配置add_header Cache-Control的话Nginx的默认行为会让浏览器对静态资源做很激进的缓存。结果就是讲师在后台更新了课程封面学员刷新页面还是旧图。Nginx配置加一行即可location /static/ { alias /path/to/static/; expires 7d; add_header Cache-Control public, max-age604800, immutable; } location /media/ { alias /path/to/media/; expires 1h; add_header Cache-Control public, max-age3600; }静态文件可以缓存7天media文件课程图片、附件缓存1小时。这样既保证性能又不会让学员长期看不到更新内容。4.5 第五个坑手机端页面宽度没处理布局直接乱很多讲师喜欢在后台把课程简介写一大段文字学员在手机上打开如果没有viewport meta标签页面会以PC宽度渲染字小得看不清布局全乱需要手动缩放才能阅读。解决方式很简单base.html里加一行meta nameviewport contentwidthdevice-width, initial-scale1.0同时所有CSS建议直接用rem而不是px做字体单位。用rem的一个好处是老款手机或者视力不好的学员可以自己在系统设置里调大字体页面布局不会被撑破。这个细节对乡村用户特别重要他们有相当比例是老年人默认字体偏小的话根本没法看。5. 部署和优化一台4G服务器也能跑得稳5.1 部署方案Gunicorn Nginx 就够了我用的是腾讯云轻量服务器4核4GCentOS系统。部署方式选的是Gunicorn Nginx的组合。没选uWSGI因为它配置复杂、踩坑成本高没选Daphne因为它面向ASGI我们的项目是纯WSGI。Gunicorn的配置要点是worker数。4核服务器建议worker数 2 * CPU核心数 1也就是9个。但考虑到项目内存占用和MySQL也要内存我实际配了5个worker每个worker处理一个请求。内存有限时宁可减少worker数也要保证每个worker稳定worker太多反而会因为内存交换把系统拖垮。# gunicorn启动脚本示例 gunicorn config.wsgi:application \ --workers 5 \ --threads 2 \ --bind 127.0.0.1:8000 \ --timeout 60 \ --max-requests 1000 \ --access-logfile /var/log/training/gunicorn_access.log \ --error-logfile /var/log/training/gunicorn_error.log--max-requests 1000的作用是每个worker处理1000个请求后自动重启这样即使有内存泄漏也会周期性释放不至于跑几天就OOM。这是实际运维中一个很有用的“防呆”参数。Nginx这边主要做静态文件托管和反向代理配置不复杂但有几个细节别忘了client_max_body_size要调大否则学员提交考核时如果带了图片附件会直接413proxy_read_timeout也要适当加大防止视频进度上报这类接口偶尔处理慢时被Nginx提前掐断。server { listen 80; server_name your_domain; client_max_body_size 20m; location /static/ { alias /var/www/training/static/; expires 7d; } location /media/ { alias /var/www/training/media/; expires 1h; } 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_read_timeout 60s; } }5.2 安全加固DDos防御做不了但基础安全必须有基层项目不太会招来专业黑客但不设防等于裸奔。以下几个环节是必须做的settings.py里DEBUG设为False并在ALLOWED_HOSTS里把自己域名加上否则会有Host头攻击风险。给admin路径改成一个不规则的URL比如/admin/改成/manage-panel/能挡掉绝大多数扫描器的自动探测。数据库密码不要用弱密码至少16位混合字符。定期执行collectstatic并且把静态文件目录放在与项目代码分离的路径下避免源码泄露。Django版本保持更新订阅GitHub的Release通知安全修复第一时间跟进。注意HTTPS是必要的但现在申请SSL证书很便宜甚至免费直接通过云厂商的免费证书功能搞定即可。部署HTTP/2能明显改善移动端加载速度。5.3 性能优化从“够用”到“好用”系统跑通后下一步要考虑体验。这个项目做过的几项优化值得记录数据库索引。学习进度上报接口频繁按user和lesson查询这两个字段的联合索引建好之后查询耗时从平均80ms降到5ms以内效果立竿见影。class LearningRecord(models.Model): ... class Meta: indexes [ models.Index(fields[user, lesson]), ]静态文件压缩。项目里的CSS和JS文件加起来有好几百KBNginx开启gzip后能压到原来的四分之一移动端加载速度提升非常明显。gzip on; gzip_types text/css application/javascript application/json image/svgxml; gzip_min_length 1k;慢请求日志。给Django加上django-axes防暴力破解和简易的慢查询日志定期看Nginx的access.log里哪些接口响应时间超过500ms有针对性地优化。有一次就发现Excel导入接口因为同步处理耗时太长改成异步任务后体验才顺畅起来。5.4 数据备份这是很多人会忽视的致命环节用Django的dumpdata命令做逻辑备份很容易但对这种有大量学习记录数据的系统推荐用物理备份mysqldump -u training_user -p training_db /backup/training_db_$(date %F).sql每天凌晨3点执行一次保留最近30天的备份文件再用rsync同步到另一台存储服务器。我吃了没备份的亏有一次服务器磁盘故障数据库直接跑不起来了靠备份才救了回来。那之后我再也没有心存侥幸过。另外记得定期清理media目录里失效的附件和视频不然存储空间会被无用文件慢慢占满。写一个定时任务扫描attachment字段对应的文件超过一定时间的过期培训资料自动归档到冷存储。6. 项目复盘这套系统的扩展空间比你想的大乡村在线培训平台上线后实际使用效果超出了预期。第一批试点有12个乡镇约4000名学员注册每周活跃率保持在60%左右。但更重要的是这个项目验证了一件事技术选型不追求时髦贴合实际场景和团队能力才是关键。系统后续的扩展方向我从项目规划的角度简单分享几个考核证书打印培训合格后自动生成电子证书后台支持批量导出PDF方便乡镇统计学时。数据大屏接入一个大屏展示页面实时显示各乡镇的参训人数、完成率、热门课程排行对汇报工作有实际价值。微信小程序端H5在微信里打开已经能实现大部分功能但小程序的消息订阅提醒、订阅号模板消息推送对提升学员粘性帮助很大。AI问答助手在课程详情页挂一个基于课程资料的智能问答学员看完视频后可以直接问问题比翻讲稿高效得多。从我个人的实际感受来说这类项目最需要注意的不是技术本身而是对“用户到底怎么用”的预判。做乡村场景的项目永远不要假设用户有流畅的4G网络、有最新款手机、有足够耐心去研究复杂的交互。简洁、稳定、低门槛比炫技重要一百倍。如果你现在正打算做类似培训系统我的建议是先用Django的admin把课程管理跑起来再花一周时间把学员端的学习页面打磨到好用的程度最后再考虑报表、证书这些锦上添花的功能。不要贪多先跑通核心闭环再慢慢加料。
这个项目并不是什么宏大工程它源于一个特别具体的问题县里每年都要组织农业技术培训但靠电话通知、线下集中授课的模式越来越跑不动了。乡镇学员分布散、农忙时间不固定、讲师来回跑成本高一场培训经常到场人数不到通知的一半。于是就有了这个基于Python和Django搭建的“某县农业技术在线培训平台”——本质是一个面向乡村场景的轻量在线教学系统。它能承载视频课程、文档资料、在线考核、学习进度追踪也兼容手机浏览器访问让学员在地里干活休息的空档也能掏出手机把一节课程看完。这套系统的技术栈不复杂Python 3.10 Django 4.2 MySQL Nginx Gunicorn前端用服务端渲染加少量JavaScript。但真正把一个“看起来不难”的Django项目做到能在基层环境稳定跑起来里面还是有不少值得记录的门道。下面我把整个项目从需求拆解到部署上线的过程完整写出来给要做类似在线教育、培训类系统的朋友一个参考。1. 需求倒推技术选型为什么这种系统选Django最省心1.1 先想清楚谁会打开这个系统做任何系统之前先把用户画像摸清楚。这个培训平台的使用者分为三类需求差异非常明显角色使用场景核心需求学员手机端为主农闲或碎片时间学习打开快、看得清、能记住学习进度讲师后台发布课程、上传资料偶尔查看学员学习情况操作简单、支持批量导入管理员汇总学时、导出考核数据、管理用户和课程数据统计清晰、权限分层这里面最要紧的是“学员用手机访问”。乡下的网络状况参差不齐手机型号跨度很大不能默认每个学员都有最新款智能手机和稳定宽带。所以前端页面必须轻避免引入重型框架保持服务端渲染的兼容性。1.2 为什么不是前后端分离也不上微服务技术选型那阵子我身边有朋友推荐用Vue Django REST Framework做前后端分离理由是“以后扩展方便”。但对于这个项目来说前后端分离是个伪需求。前后端分离的好处是交互体验好、前后端并行开发代价是至少多一层Node构建流程、多一套接口联调工作部署时还得处理跨域和静态资源托管。对于一个只有几千名学员、业务逻辑以“课程—学习—考核—统计”为主线的平台Django自带的模板引擎完全够用。而且模板渲染天然对SEO友好页面首屏快开发效率也高。微服务就更不必要了。业务规模没到那个量级强行拆分只会增加运维复杂度。一个Django项目加一个MySQL实例部署在一台4核8G的云服务器上初期完全够用单机架构排查问题还方便。1.3 框架选型上的几个现实考量选Django而不是Flask或FastAPI主要是这几点自带Admin后台Django内置的admin管理界面能极大降低讲师录入课程的负担稍微配置一下list_display、search_fields就能直接交付不用从零写管理端。用户认证体系完整Django自带的User模型和auth模块覆盖了登录、登出、权限分组、密码重置等常规需求不需要自己实现用户系统。ORM成熟稳定农业培训系统涉及大量数据筛选比如按村、按乡镇查学习记录用Django ORM写起来很直观生成的SQL性能也能接受。迁移机制方便迭代后续每次加字段、改表结构跑一遍makemigrations和migrate就能同步到生产库对单人开发来说省了太多事。提示版本建议直接用Django 4.2 LTS长期支持版本安全更新能持续到2026年左右。Python用3.10或3.11别用最新的Python 3.12或3.13部分第三方库的二进制包可能还没跟上。2. 数据模型设计核心就是“人—课—进度”三件套2.1 用户模型怎么扩别直接改Profile字段Django自带的User模型有username、password、email这些基础字段但培训系统需要记录学员的所属乡镇、村组、身份角色还有讲师和管理员的区分。常见的做法有两种一是继承AbstractUser重写User模型二是用OneToOneField扩展用户档案。我这次选择了第一种方式因为项目一开始就确定不要换用户模型扩展字段和业务绑定紧密直接在项目初始化阶段就用自定义User模型后续迁移更省心。# users/models.py from django.contrib.auth.models import AbstractUser from django.db import models class User(AbstractUser): ROLE_CHOICES ( (student, 学员), (teacher, 讲师), (admin, 管理员), ) role models.CharField(max_length16, choicesROLE_CHOICES, defaultstudent, verbose_name角色) region models.CharField(max_length64, blankTrue, verbose_name所属乡镇/村) phone models.CharField(max_length20, blankTrue, verbose_name手机号) id_card models.CharField(max_length18, blankTrue, verbose_name身份证号) created_at models.DateTimeField(auto_now_addTrue, verbose_name注册时间) class Meta: verbose_name 用户 verbose_name_plural 用户这里有个很实用的细节为每个角色建一个分组但不强制用Django的Group表而是直接靠role字段区分。因为业务逻辑里判断角色只需要一个if user.role teacher比查权限表轻量得多。Django的Group和Permission机制留给后期需要细粒度权限时再用。2.2 课程、章节、资料逻辑分层要清晰课程结构我从一开始就定成“培训计划—课程—章节”三层而不是扁平的一堆课程列表。原因是乡村培训系统天然有批次概念比如“2025年春季果树修剪培训班”下面有若干门课程每门课程里又有几个视频章节。# courses/models.py class TrainingPlan(models.Model): name models.CharField(max_length128, verbose_name培训计划名称) start_date models.DateField(verbose_name开始日期) end_date models.DateField(verbose_name结束日期) description models.TextField(blankTrue, verbose_name计划说明) is_active models.BooleanField(defaultTrue, verbose_name是否启用) class Course(models.Model): plan models.ForeignKey(TrainingPlan, on_deletemodels.CASCADE, related_namecourses, verbose_name所属培训计划) title models.CharField(max_length128, verbose_name课程名称) teacher models.ForeignKey(settings.AUTH_USER_MODEL, on_deletemodels.SET_NULL, nullTrue, related_namecourses, verbose_name授课讲师) cover models.ImageField(upload_tocovers/, blankTrue, verbose_name封面图) created_at models.DateTimeField(auto_now_addTrue, verbose_name创建时间) class Lesson(models.Model): course models.ForeignKey(Course, on_deletemodels.CASCADE, related_namelessons, verbose_name所属课程) title models.CharField(max_length128, verbose_name章节标题) video_url models.URLField(blankTrue, verbose_name视频地址) attachment models.FileField(upload_toattachments/, blankTrue, verbose_name附件资料) order models.PositiveIntegerField(default0, verbose_name排序) duration models.PositiveIntegerField(default0, verbose_name视频时长/秒)很多初学者容易忽略order字段。没有它删除一个章节后再添加章节顺序就会乱套。加上order字段查询时用order_by(order)就能稳定排序。注意视频文件先不要自己存本地。早期我们试过把视频直接传到Django的MEDIA_ROOT后来发现服务器带宽和存储都是大麻烦。一个1080P的课程视频随便就是几百MB一台8G内存的服务器兼做文件服务器很快就吃不消。后面改成传对象存储或者直接把视频托管到第三方视频平台Django只存一个video_url字段省了太多事。2.3 学习进度和考核用一张记录表解决所有统计问题学习记录是整个系统的数据核心。每次学员打开一个章节前端就向后端发一条上报请求后端记录“学到了哪里、看了多久、是否完成”。这样管理员随时能查出“某某乡镇有多少人完成了春季培训”。# records/models.py class LearningRecord(models.Model): user models.ForeignKey(settings.AUTH_USER_MODEL, on_deletemodels.CASCADE, related_namelearning_records, verbose_name学员) lesson models.ForeignKey(Lesson, on_deletemodels.CASCADE, related_namelearning_records, verbose_name章节) watch_seconds models.PositiveIntegerField(default0, verbose_name已观看时长/秒) is_completed models.BooleanField(defaultFalse, verbose_name是否完成) last_position models.PositiveIntegerField(default0, verbose_name最后播放位置/秒) updated_at models.DateTimeField(auto_nowTrue, verbose_name更新时间) class Meta: unique_together (user, lesson) class ExamResult(models.Model): user models.ForeignKey(settings.AUTH_USER_MODEL, on_deletemodels.CASCADE, verbose_name学员) course models.ForeignKey(Course, on_deletemodels.CASCADE, verbose_name课程) score models.FloatField(verbose_name考试得分) passed models.BooleanField(defaultFalse, verbose_name是否合格) submitted_at models.DateTimeField(auto_now_addTrue, verbose_name提交时间)LearningRecord表加了unique_together(user, lesson)保证同一个学员对同一章节只会有一条进度记录。更新进度时直接update_or_create既避免重复数据代码也简洁。一张记录表再配合Django的聚合查询就能满足绝大多数统计需求完成人数、平均学时、各村完成率一条ORM语句的事。3. 核心功能模块实现模板渲染为主接口为辅3.1 用户注册登录Django自带认证的“半定制”改造登录功能直接用Django的LoginView省掉手写表单校验和session管理的麻烦。但培训平台的学员注册有个特殊需求——需要管理员预绑定比如导入某乡镇学员名单后学员凭身份证号和初始密码登录。这就不能做成完全开放注册。# users/views.py from django.contrib.auth.views import LoginView, LogoutView class CustomLoginView(LoginView): template_name users/login.html redirect_authenticated_user True def get_success_url(self): user self.request.user if user.role student: return reverse(courses:student_home) elif user.role teacher: return reverse(courses:teacher_dashboard) return reverse(admin:index)这里有个坑redirect_authenticated_user True虽然在用户已登录时会直接跳过登录页但如果你没有定义get_success_url它会默认跳到Django的LOGIN_REDIRECT_URL。不同角色的跳转目标不同必须自己重写这个方法。注册方面我们用的是“名单导入首登改密”模式管理员在后台按模板Excel导入学员名单姓名、身份证号、手机号、所属村组系统自动生成用户名和初始密码学员首次登录后强制修改密码。这就绕开了手机验证码这类在乡村场景下经常收不到短信的麻烦。3.2 课程列表和学习页ListAPI 详情页的组合课程首页要让学员一眼看到当前正在进行的培训计划和每门课的完成状态。Django的ListView配合annotate就能把“每门课总章节数、已完成章节数”一并算出来。# courses/views.py from django.views.generic import ListView from django.db.models import Count, Q class CourseListView(ListView): template_name courses/course_list.html context_object_name courses paginate_by 12 def get_queryset(self): plan TrainingPlan.objects.filter(is_activeTrue).first() courses Course.objects.filter(planplan) user self.request.user for course in courses: total_lessons course.lessons.count() completed_lessons LearningRecord.objects.filter( useruser, lesson__coursecourse, is_completedTrue ).count() course.progress int(completed_lessons / total_lessons * 100) if total_lessons else 0 return courses直接在get_queryset里循环查数据库数据量小的时候没问题。如果课程数量涨上来建议改成annotate Count加条件聚合一条SQL搞定但初期这样写最简单直接业务跑起来以后再做性能优化也不迟。3.3 学习进度上报一个轻量POST接口前端播放页嵌入了一个简易的HTML5视频播放器每隔15秒向后端上报当前播放位置。之所以用接口而不是表单提交是为了让上报动作变成异步的不影响视频播放。# records/views.py import json from django.http import JsonResponse from django.views.decorators.http import require_POST from django.contrib.auth.decorators import login_required require_POST login_required def report_progress(request): data json.loads(request.body) lesson_id data.get(lesson_id) position int(data.get(position, 0)) watch_seconds int(data.get(watch_seconds, 0)) duration int(data.get(duration, 0)) try: lesson Lesson.objects.get(idlesson_id) except Lesson.DoesNotExist: return JsonResponse({code: 1, msg: 章节不存在}) record, created LearningRecord.objects.update_or_create( userrequest.user, lessonlesson, defaults{ last_position: position, watch_seconds: watch_seconds, } ) # 如果观看时长超过视频时长的85%判定为完成 if duration 0 and watch_seconds duration * 0.85: record.is_completed True record.save() return JsonResponse({code: 0, msg: ok})判断完成的标准是“观看时长超过视频时长的85%”这是故意的。不让学员拖动进度条到底就算完成也不要求100%看完——85%既保证有效学习又容忍了网络卡顿导致的最后几秒没播完的情况。前端用一个简单的setInterval每15秒调用一次这个接口同时把参数localStorage存一份避免切换页面导致进度丢失// schoolrecord.js let lastReported 0; video.addEventListener(timeupdate, function () { const pos Math.floor(video.currentTime); const dur Math.floor(video.duration); if (pos - lastReported 15) { lastReported pos; fetch(/records/report/, { method: POST, headers: { Content-Type: application/json, X-CSRFToken: getCookie(csrftoken) }, body: JSON.stringify({ lesson_id: LESSON_ID, position: pos, watch_seconds: pos, duration: dur }) }).catch(e { // 上报失败先存本地下次打开再补报 localStorage.setItem(pending_report_ LESSON_ID, JSON.stringify({ position: pos, watch_seconds: pos })); }); } });提示fetch请求里的X-CSRFToken一定要加上否则Django的CSRF中间件会直接返回403。getCookie函数可以放在全局公共JS里网上有很多现成写法这里不再贴完整代码。3.4 权限控制装饰器和Mixin的混合使用Django的权限体系很好用但默认的login_required只解决了“登录了没有”解决不了“登录了但角色不对”。我给不同角色写了独立的入口判断# common/decorators.py from functools import wraps from django.core.exceptions import PermissionDenied def role_required(roles): def decorator(view_func): wraps(view_func) def _wrapped(request, *args, **kwargs): if not request.user.is_authenticated: return redirect(users:login) if request.user.role not in roles: raise PermissionDenied return view_func(request, *args, **kwargs) return _wrapped return decorator role_required([teacher, admin]) def course_create(request): ...视图函数用装饰器类视图用UserPassesTestMixin或自定义LoginRequiredMixin两种风格统一起来用即可。注意一点PermissionDenied异常要在settings里配一个403的模板否则默认页面太难看也不友好。4. 踩坑实录从SQLite换到MySQL从页面白屏到强制刷新4.1 第一个坑SQLite不背锅但乡村场景并发真的会写锁Django项目默认数据库是SQLite开发时跑起来特别爽零配置、免维护。前期学员量小也没人刻意做压力测试直到有一次集中培训报名某村网格员在同一时间帮二十多个学员批量注册SQLite直接报database is locked。SQLite对“单写入者”的支持是有保障的但它不支持并发写。多个请求同时写入时后面的请求会等待等待超时就直接报错。培训系统里相关写入场景其实挺多上报进度、提交考核、批量导入用户任何一个请求密集的节点都可能把SQLite点爆。解决方案不复杂——换MySQL。在项目初期就换代价极低等项目跑起来数据多了再换光迁移数据就够折腾的。# settings.py 数据库配置片段 DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: training_db, USER: training_user, PASSWORD: your_password_here, HOST: 127.0.0.1, PORT: 3306, OPTIONS: { charset: utf8mb4, }, CONN_MAX_AGE: 60, } }CONN_MAX_AGE 60意思是数据库连接在60秒内复用避免每个请求都重新建连接。这个参数在高并发时能显著减少握手开销但要注意MySQL的wait_timeout默认是8小时如果连接空闲超过MySQL的超时阈值Django会复用失效连接报错。Django 4.1已经内置了连接健康检查配合CONN_MAX_AGE就基本不需要额外处理。4.2 第二个坑数据库字符集没配好用户名直接变问号学员姓名里带生僻字的导入进去之后页面上显示一串问号。这问题几乎每个做中文应用的人都会遇到根源是库、表、连接三个层面的字符集不一致。MySQL安装时默认编码可能是latin1也可能是utf8mb3就是utf8但utf8mb3存不下emoji和部分生僻字。正确做法是建库时指定utf8mb4CREATE DATABASE training_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;Django连接时再指定charsetutf8mb4双保险。库建好之后再改编码很麻烦建议项目初始化时就确认。除了数据库层面的编码问题Django的settings里也要设置FILE_CHARSET和DEFAULT_CHARSET默认就是utf-8一般不用动。比较隐蔽的是Excel导入用户名单时如果Excel文件本身是GBK编码用pandas读取时没指定encodinggbk中文全部变成乱码入库。这个坑我踩了两次才记住pandas读取Excel默认会把字符串列按单元格类型推断字符串里若有中文编码在原文件里就可能已经乱了最稳妥的流程是先转到CSV再逐行清洗。4.3 第三个坑admin站点里ImageField和FileField的MEDIA路径Django的admin虽然强大但文件上传的路径配置很容易被新手忽略。settings.py里如果没有配置MEDIA_URL和MEDIA_ROOT上传的文件会跑到项目根目录而且在admin列表里点击链接无法查看图片。MEDIA_URL /media/ MEDIA_ROOT BASE_DIR / media主urls.py里还要加一句from django.conf import settings from django.conf.urls.static import static urlpatterns [ ... ] static(settings.MEDIA_URL, document_rootsettings.MEDIA_ROOT)这句只会在DEBUGTrue时生效生产环境下Nginx会直接托管/media/路径。如果在生产环境忘记配置Nginx的location上传的文件能存但访问不了页面就是一片空。当时排查这个问题花了一下午。4.4 第四个坑前端页面缓存导致更新后学员仍看到旧课程Django模板渲染默认不会做浏览器缓存控制但如果你用Nginx做反向代理没配置add_header Cache-Control的话Nginx的默认行为会让浏览器对静态资源做很激进的缓存。结果就是讲师在后台更新了课程封面学员刷新页面还是旧图。Nginx配置加一行即可location /static/ { alias /path/to/static/; expires 7d; add_header Cache-Control public, max-age604800, immutable; } location /media/ { alias /path/to/media/; expires 1h; add_header Cache-Control public, max-age3600; }静态文件可以缓存7天media文件课程图片、附件缓存1小时。这样既保证性能又不会让学员长期看不到更新内容。4.5 第五个坑手机端页面宽度没处理布局直接乱很多讲师喜欢在后台把课程简介写一大段文字学员在手机上打开如果没有viewport meta标签页面会以PC宽度渲染字小得看不清布局全乱需要手动缩放才能阅读。解决方式很简单base.html里加一行meta nameviewport contentwidthdevice-width, initial-scale1.0同时所有CSS建议直接用rem而不是px做字体单位。用rem的一个好处是老款手机或者视力不好的学员可以自己在系统设置里调大字体页面布局不会被撑破。这个细节对乡村用户特别重要他们有相当比例是老年人默认字体偏小的话根本没法看。5. 部署和优化一台4G服务器也能跑得稳5.1 部署方案Gunicorn Nginx 就够了我用的是腾讯云轻量服务器4核4GCentOS系统。部署方式选的是Gunicorn Nginx的组合。没选uWSGI因为它配置复杂、踩坑成本高没选Daphne因为它面向ASGI我们的项目是纯WSGI。Gunicorn的配置要点是worker数。4核服务器建议worker数 2 * CPU核心数 1也就是9个。但考虑到项目内存占用和MySQL也要内存我实际配了5个worker每个worker处理一个请求。内存有限时宁可减少worker数也要保证每个worker稳定worker太多反而会因为内存交换把系统拖垮。# gunicorn启动脚本示例 gunicorn config.wsgi:application \ --workers 5 \ --threads 2 \ --bind 127.0.0.1:8000 \ --timeout 60 \ --max-requests 1000 \ --access-logfile /var/log/training/gunicorn_access.log \ --error-logfile /var/log/training/gunicorn_error.log--max-requests 1000的作用是每个worker处理1000个请求后自动重启这样即使有内存泄漏也会周期性释放不至于跑几天就OOM。这是实际运维中一个很有用的“防呆”参数。Nginx这边主要做静态文件托管和反向代理配置不复杂但有几个细节别忘了client_max_body_size要调大否则学员提交考核时如果带了图片附件会直接413proxy_read_timeout也要适当加大防止视频进度上报这类接口偶尔处理慢时被Nginx提前掐断。server { listen 80; server_name your_domain; client_max_body_size 20m; location /static/ { alias /var/www/training/static/; expires 7d; } location /media/ { alias /var/www/training/media/; expires 1h; } 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_read_timeout 60s; } }5.2 安全加固DDos防御做不了但基础安全必须有基层项目不太会招来专业黑客但不设防等于裸奔。以下几个环节是必须做的settings.py里DEBUG设为False并在ALLOWED_HOSTS里把自己域名加上否则会有Host头攻击风险。给admin路径改成一个不规则的URL比如/admin/改成/manage-panel/能挡掉绝大多数扫描器的自动探测。数据库密码不要用弱密码至少16位混合字符。定期执行collectstatic并且把静态文件目录放在与项目代码分离的路径下避免源码泄露。Django版本保持更新订阅GitHub的Release通知安全修复第一时间跟进。注意HTTPS是必要的但现在申请SSL证书很便宜甚至免费直接通过云厂商的免费证书功能搞定即可。部署HTTP/2能明显改善移动端加载速度。5.3 性能优化从“够用”到“好用”系统跑通后下一步要考虑体验。这个项目做过的几项优化值得记录数据库索引。学习进度上报接口频繁按user和lesson查询这两个字段的联合索引建好之后查询耗时从平均80ms降到5ms以内效果立竿见影。class LearningRecord(models.Model): ... class Meta: indexes [ models.Index(fields[user, lesson]), ]静态文件压缩。项目里的CSS和JS文件加起来有好几百KBNginx开启gzip后能压到原来的四分之一移动端加载速度提升非常明显。gzip on; gzip_types text/css application/javascript application/json image/svgxml; gzip_min_length 1k;慢请求日志。给Django加上django-axes防暴力破解和简易的慢查询日志定期看Nginx的access.log里哪些接口响应时间超过500ms有针对性地优化。有一次就发现Excel导入接口因为同步处理耗时太长改成异步任务后体验才顺畅起来。5.4 数据备份这是很多人会忽视的致命环节用Django的dumpdata命令做逻辑备份很容易但对这种有大量学习记录数据的系统推荐用物理备份mysqldump -u training_user -p training_db /backup/training_db_$(date %F).sql每天凌晨3点执行一次保留最近30天的备份文件再用rsync同步到另一台存储服务器。我吃了没备份的亏有一次服务器磁盘故障数据库直接跑不起来了靠备份才救了回来。那之后我再也没有心存侥幸过。另外记得定期清理media目录里失效的附件和视频不然存储空间会被无用文件慢慢占满。写一个定时任务扫描attachment字段对应的文件超过一定时间的过期培训资料自动归档到冷存储。6. 项目复盘这套系统的扩展空间比你想的大乡村在线培训平台上线后实际使用效果超出了预期。第一批试点有12个乡镇约4000名学员注册每周活跃率保持在60%左右。但更重要的是这个项目验证了一件事技术选型不追求时髦贴合实际场景和团队能力才是关键。系统后续的扩展方向我从项目规划的角度简单分享几个考核证书打印培训合格后自动生成电子证书后台支持批量导出PDF方便乡镇统计学时。数据大屏接入一个大屏展示页面实时显示各乡镇的参训人数、完成率、热门课程排行对汇报工作有实际价值。微信小程序端H5在微信里打开已经能实现大部分功能但小程序的消息订阅提醒、订阅号模板消息推送对提升学员粘性帮助很大。AI问答助手在课程详情页挂一个基于课程资料的智能问答学员看完视频后可以直接问问题比翻讲稿高效得多。从我个人的实际感受来说这类项目最需要注意的不是技术本身而是对“用户到底怎么用”的预判。做乡村场景的项目永远不要假设用户有流畅的4G网络、有最新款手机、有足够耐心去研究复杂的交互。简洁、稳定、低门槛比炫技重要一百倍。如果你现在正打算做类似培训系统我的建议是先用Django的admin把课程管理跑起来再花一周时间把学员端的学习页面打磨到好用的程度最后再考虑报表、证书这些锦上添花的功能。不要贪多先跑通核心闭环再慢慢加料。
空间解法精讲)
