最近把一个Django项目从头到尾啃了一遍叫“同城临期视频平台”源码包编号69305。第一眼以为是个短视频网站結果打开模型一看才发现它是把“视频”和“临期商品”绑在一起的同城交易平台附近的面包房、超市把当天还没卖完、又接近保质期的货拍成十几秒的短视频挂出来用户刷到后直接下单到店自提或者等骑手送。这个点子挺聪明既能帮商家清库存又满足了一大批人“想省钱又怕踩雷”的需求。这个项目最值得看的地方是它把Django里常见但容易讲散的模块全部串起来了用户登录、商家入驻、商品上架、视频上传、定位附近门店、下单核销、后台管理。对想学Django的开发者来说这是一个比“博客系统”更有真实业务感的完整案例对想做本地生活创业的人来说代码本身已经能跑改改前端、接个支付基本就是一个可拿去谈合作的Demo。下面我从业务、架构、代码、排错和二次开发几个角度把这套东西拆开讲清楚。1. 项目整体设计与业务拆解1.1 临期商品平台的商业逻辑临期商品不是“过期食品”而是还在保质期内、但剩余时间不长的商品。很多商超晚间会把当日到期或近几日内到期的熟食、乳品、烘焙糕点打折出售有时候折扣低到三折。这类商品的问题是“信息不透明”顾客不知道店里还剩什么、还剩多少、新不新鲜商家也没法持续吆喝只能被动等客上门。这个平台想解决的就是信息对称问题。商家把临期商品拍成视频挂上原价、折扣价、到期时间用户一看就知道东西长什么样、还剩多少量、能不能在过期前用完。平台赚的是佣金或流量费用商家清掉库存用户省了钱三方都满意。但这里有个容易踩偏的点很多人会把“临期”做成“低价清仓”的简单卖场忽略了临期商品最敏感的信任问题。所以项目里必须有“保质期/到期时间”字段、必须支持按到期时间排序、过期商品必须自动下架这些不是锦上添花而是业务底线。我在源码里看到它给商品加了 expire_time并且查询时默认过滤掉“当前时间已晚于到期时间”的记录这个设计是对的。1.2 “同城”维度决定了技术方案“同城”不是简单存一个城市字段而是要做真实的距离计算。不然用户在北京刷到一个上海的临期面包店根本无法自提配送成本也不现实。项目里的定位方案很务实用户的 Profile 里存了经度、纬度商家/门店也有经纬度字段计算列表时用 Haversine 公式做距离筛选和排序前端再用地理定位API把当前坐标传过来。这样做的好处是避免引入太重的地理信息组件。真实生产环境如果要做“附近3公里”这种高频查询可能要考虑 GeoDjango 或空间索引但在这个学习型项目里直接用经纬度字段加一个小函数就够了。重点在于同城筛选不是“城市字符串相等”而是“坐标点距离小于某个阈值”这个思路一定要转过来。1.3 视频为什么是核心载体如果只是发布文字和图片整个项目就是一个普通的二手交易/本地电商做不出差异化。视频的存在让用户能更直观地看到商品的色泽、包装、生产日期还能让商家用口播解释“为什么打折、剩几天、怎么保存”。相比图片视频的信任度和转化率明显更高。代价就是技术复杂度上来了。视频存储比图片大一个数量级播放时需要处理格式兼容、封面、加载速度后台还要管理视频文件。源码里商品表和视频是一对一/一对多的关系一个商品可以关联多条短视频上传后直接存到 media 目录开发环境用 Django 的 media 服务播放学习阶段完全够用。生产环境可以换成云对象存储这个后面我会专门讲。2. 技术选型与源码结构2.1 选用Django而不是别家框架很合理同城临期平台是个典型的业务型Web应用后端需要管理用户、门店、商品、订单、视频等多个模型还要有后台增删改查。Django在这一点上几乎是“开箱即用”的自带 Admin 后台、ORM、Session、Auth密码加密和CSRF防护也是内置的。用 Flask 的话这些都要自己拼装开发效率和代码规范度都会打折扣用 Java 那套 Spring Boot 当然可以但项目体量这么小没必要为了“高并发”把工程复杂度拉满。我在项目里看到它的 app 分了 accounts、shop、product、order 几个模块目录结构很清晰。虽然部分逻辑还能更抽象但作为学习项目这种“一个模块一个app”的做法非常标准也方便后续拆成独立服务。2.2 核心数据模型一览数据模型是整个项目的骨架我从源码中整理出主要表和字段这些直接决定了业务能不能跑通模型核心字段说明UserDjango自带username, email, password标准用户体系区分用户/商家角色用扩展ProfileProfileuser, longitude, latitude, city, avatar用户地理位置和扩展信息定位就看这里Shopowner, name, address, longitude, latitude门店/商家和User是外键关系Categoryname, parent商品分类可做二级分类Productname, original_price, discount_price, expire_time, stock, shop, video, status核心商品信息关联门店和视频Videoproduct, file, cover, uploaded_at商品的短视频一个商品可多个Orderuser, shop, total_amount, status, pickup_time订单主表OrderItemorder, product, quantity, price订单子表记录每个商品下单时的快照这些字段不是随便设计的。比如 expire_time 和 status 配合能让临期商品“到期即失效”OrderItem 里单独存 price是为了防止商品改价后影响历史订单。数据模型是最值得反复品的地方多一个冗余字段后续可能少很多坑。2.3 源码目录结构源码包解压后核心结构大致是这样django_group_buy/ ├── manage.py ├── requirements.txt ├── config/ │ ├── settings.py │ ├── urls.py │ └── wsgi.py ├── apps/ │ ├── accounts/ │ │ ├── models.py │ │ ├── views.py │ │ └── urls.py │ ├── shop/ │ ├── product/ │ └── order/ ├── static/ │ ├── css/ │ ├── js/ │ └── images/ ├── media/ │ ├── videos/ │ └── covers/ └── templates/ ├── accounts/ ├── product/ ├── order/ └── base.htmltemplates 直接放在根目录static 和 media 分离路径在 settings 里统一管理。媒体文件没有塞进 static说明作者对静态资源和用户上传资源有区分意识这点比很多新手写的好。2.4 依赖与运行环境requirements.txt 里主要包括 Django、Pillow、requests 这类常规库以及少量辅助库。Django 版本在 4.x 左右Python 用 3.9 以上基本没毛病。数据库默认是 SQLite迁移文件已经生成跑起来不需要额外装数据库服务。3. 核心功能实现要点3.1 用户系统与同城定位用户注册登录用的就是 Django 自带 User再写了一个 Profile 扩展模型用 OneToOneField 关联。定位的实现是前端页面通过浏览器 Geolocation 或者让用户手动输入城市/商圈拿到的经纬度 PUT 到 Profile 接口后端保存好后商品列表页会带着当前经纬度参数去查。要注意的是浏览器定位必须是在 HTTPS 环境下才能正常使用本地开发用 runserver 访问 127.0.0.1 是可以的但局域网 IP 访问会被浏览器拒绝踩过这个坑的人都懂。权限控制项目里分了“普通用户”和“商家”两种角色。商家发布商品必须登录且 is_staff 或分组为商家Django 的login_required装饰器用得很勤。这里有个改进空间真正的生产项目建议用更细粒度的权限比如门店店主只能管自己店里的商品不能动别人门店的货。这个项目里虽然做了基础区分但还没到 shop_id 混合过滤二次开发时需要补上。3.2 临期商品发布与管理商家端商品发布页面做成了表单形式选择门店、填标题、填商品原价和折扣价、设置到期时间、上传视频、设置库存。后端接收数据后将商品和关联的视频保存。过期商品的处理分成两层第一层是查询过滤。所有对外商品列表的 queryset 都加了expire_time__gttimezone.now()这样过期商品自动从用户端消失。第二层是状态更新。虽然不强制但源码里在商品详情页会检查当前时间超过到期时间就提示“已过期或已下架”。如果想做到“到点自动下架”可以接 Celery 定时任务来更新 status但作为学习项目请求时过滤更简单也够用。3.3 视频上传与播放模块视频上传是 Django 的FileField存储路径在MEDIA_ROOT/videos/。表单校验里做了简单扩展限制文件后缀为 mp4、mov、avi限制大小不超过 100MB。前端视频播放用的是原生 HTML5video controlsDjango 模板里直接指向/media/videos/xxx.mp4。这里有个开发者经常忽略的点视频编码格式不兼容。HTML5 播放器基本只保证 MP4H.264 AAC在所有浏览器下能播放而很多手机拍出来的 mov/avi 或 H.265 编码的 mp4Chrome 能放但 Safari 未必能放。最好的做法是在上传时用 FFmpeg 统一转码成 H.264 编码的 MP4并压缩分辨率。这个项目没有集成转码逻辑因此上线前一定要补上或者在上传前加格式提示。视频封面也很关键。列表页如果直接渲染 video 标签加载会很卡所以项目做了一个 cover 字段存视频封面图。封面图要么前端上传时截帧要么上传后由后端异步生成。源码里是放在商品表单里手动上传封面的虽然多了一步操作但在没有异步任务框架时反而是最稳的办法。3.4 商品列表、详情与订单流程商品列表页按“距离近优先”和“离到期近优先”两种排序切换。距离排序用经纬度计算后写入排序 key到期时间排序直接用order_by(expire_time)。详情页展示商品基本信息、视频、库存、门店位置可以下单。订单设计成了主从表结构下单时会重新读取商品当前价格、库存然后创建 Order 和 OrderItem 并扣减库存。因为这是个小型项目没有引入事务笔记但实际上写订单应该用transaction.atomic()包住整个库存检查和扣减不然高并发下会超卖。源码里也有一点简单的原子处理不过只能防程序错误不能防并发读者要清楚这个边界。订单状态比较简单待自提、已完成、已取消。没有支付流程毕竟临期商品通常线下扫码支付或者自提时付款。如果要做线上支付可以在 Order 上增加一个 pay_status 和支付回调接口。3.5 Admin后台配置Django Admin 是这个项目的一大亮点。源码里对 Product、Shop、Order 都做了自定义Product 列表展示标题、门店、折扣价、到期时间、状态搜索字段标题、门店名过滤器到期时间、状态。Order 列表支持按“门店”过滤按“下单时间”排序。Shop 后台能快速添加门店坐标地图展示需要额外插件但手动填经纬度已经整理清楚了。Admin 不只是给开发者用的项目上线后商家运营也可以开一个只读账号用 Admin 看销售记录。如果嫌 Admin 不好看可以换 grappelli 或改成简单的前端管理页面但业务逻辑不用动。4. 关键代码拆解与避坑指南4.1 settings.py 里的多媒体和数据库配置打开settings.py有几段配置是视频平台能跑起来的核心MEDIA_URL /media/ MEDIA_ROOT BASE_DIR / media STATIC_URL /static/ STATICFILES_DIRS [BASE_DIR / static]开发环境用 runserver 时一定要在主 urls.py 里加 static 的转发不然 /media/ 路径全部 404from django.conf import settings from django.conf.urls.static import static urlpatterns [ # ... ] static(settings.MEDIA_URL, document_rootsettings.MEDIA_ROOT)数据库配置学习阶段用 SQLite 完全没问题。要改成 MySQL 只需改 DATABASES 里的 ENGINE 为对应驱动再跑一次 migrate。注意中文字段排序和 emoji 用户名需要 utf8mb4如果用 MySQL 记得建库时指定。4.2 经纬度距离排序实现项目里算同城距离的代码虽然简短但是最实用的一段。Haversine 公式计算两点球面距离import math def distance(lat1, lng1, lat2, lng2): radius 6371.0 dlat math.radians(lat2 - lat1) dlng math.radians(lng2 - lng1) a math.sin(dlat / 2) ** 2 math.cos(math.radians(lat1)) * math.cos(math.radians(lat2)) * math.sin(dlng / 2) ** 2 c 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a)) return radius * c拿到用户坐标后对所有门店算一遍距离过滤掉超过 5000 米的再按距离排序。这种全量计算在数据量小的时候很舒服代码可读性也高。但商品超过上万条后性能会明显下降解决办法是先用“经纬度范围”粗过滤出一个矩形再对矩形内的数据精排。项目里已经通过latitude__range和longitude__range做了一次粗筛然后算精确距离思路很正确。需要注意的是纬度范围需要根据地图投影换算边界处会有误差但对于同城场景多留一点余量就行。4.3 视频文件校验与封面生成文件上传不能完全相信前端限制后端一定要再做一遍校验。源码中有个自定义的clean_video方法检查扩展名和大小并调用了 Pillow 来验证图片封面的真伪。def clean_video(self): video self.cleaned_data.get(video) if video: ext os.path.splitext(video.name)[-1].lower() if ext not in [.mp4, .mov, .avi]: raise ValidationError(仅支持 mp4/mov/avi 格式) if video.size 100 * 1024 * 1024: raise ValidationError(视频文件不能超过 100MB) return video如果要做视频封面自动截取可以用 FFmpeg 在 post_save 信号里执行命令ffmpeg -i input.mp4 -ss 00:00:02 -vframes 1 cover.jpg这在 Linux 服务器上很好用。Windows 开发环境下需要配置好 FFmpeg 环境变量不然命令执行会报找不到。4.4 权限、CSRF与XSS防护Django 默认开启了 CSRF 中间件只要模板里使用了{% csrf_token %}所有 POST 表单都能被保护。源码没有关闭这个中间件这是加分项。另外所有用户输入都经过模板自动转义XSS 风险很小。视频上传时要注意不要允许用户传 HTML 或 SVG 文件伪装成图片项目已在 PIlow 的验证中规避了这个问题。生产环境更要把DEBUGFalse、配好ALLOWED_HOSTS并给 media 目录设置独立的域名或Cookie隔离防止上传的恶意文件借助同一域名执行脚本。5. 常见问题与排查技巧实录我把这个项目跑通前后可能踩的坑整理成了速查表开发或者部署时可以直接对照症状可能原因解决方式视频、图片 404主 urls 没配 static(media) 或服务器没指到 MEDIA_ROOT本地在主 urls 加 static服务器配置 /media/ 路径指向存放目录上传视频按钮没反应文件大于服务器限制或后端校验失败检查前端 form 是否带 enctype后端限制 value 是否太小用手机访问定位失败浏览器 Geolocation 只在 HTTPS 生效本地用 127.0.0.1 测试局域网使用 HTTPS 证书距离排序结果不对经纬度填反前纬后经Profile 和 Shop 都要统一存“纬度 lat / 经度 lng”注意模型字段注释过期商品还在列表queryset 没有expire_time__gtnow给所有对外查询补上过期时间过滤mp4 在 Safari 打不开H.265 编码不被 HTML5 支持统一用 FFmpeg 转成 H.264 AAC下单库存变成负数订单接口没做事务用transaction.atomic()包住库存检查和扣减后台找不到商品商品归属于某门店Admin 默认不过滤给 ProductAdmin 加list_filter (shop,)其中“经纬度填反”是最容易出现的看着地图上的坐标直接复制到后台往往城市能对上但距离离谱原因就是经纬度顺序没统一。建议在所有门店表单里做范围校验纬度必须在 -90 到 90经度必须在 -180 到 180否则立刻报错。6. 从源码跑通到二次开发6.1 本地30分钟跑通拿到源码后按下面的顺序基本不会出问题解压源码包命令行进入根目录确认manage.py存在。创建虚拟环境并激活python -m venv venvWindows 执行venv\Scripts\activate。安装依赖pip install -r requirements.txt。数据库迁移python manage.py migrate。创建管理账号python manage.py createsuperuser。启动服务python manage.py runserver。浏览器打开http://127.0.0.1:8000/admin先建一个分类、一个门店、一个商品再到前台看列表。如果迁移时报错多半是 Python 或 Django 版本差异修改 requirements 里的版本号重新安装即可。6.2 二次开发可以往哪些方向扩这套代码的可扩展空间很大我列几个比较实际的方向接入真实支付和退款流程增加支付回调、退款申请、商家结算。把视频转码和封面截取做成异步任务上传后立刻返回后台处理。增加“超值抢购”活动表支持限量秒杀。注意要在事务中扣库存。做小区/办公楼自提点模式把“同城”细化为“同园区”。增加收藏、点赞、评论让视频内容更贴近短视频交互。前端换成手机App或小程序壳子后端直接用现有 API 适配。建议优先补“视频转码”和“订单事务”这两块因为它们是生产环境最容易出问题的地方。6.3 我的一些真实使用感受这个项目完整度在同类 Dajngo 开源 Demo 里算高的尤其数据模型和 Admin 后台设计得很规范适合拿来当毕业设计、个人作品集或者创业 MVP。但它也带着明显的“教学项目”痕迹视频存储本地、没有转码、订单没有支付、权限粒度粗。这些不一定是缺点反而给了后来者很大的发挥空间。如果是我拿到代码第一件事不会急着改功能而是先把 models 全部梳理一遍画清楚表关系再跑一遍迁移和测试。把基础数据准备好后再做一个小型压测看订单接口在高并发下的表现。最后再决定是上云存储还是加消息队列这样心里有底后续改起来也不慌。说实话做这种同城临期生意技术不是最大的门槛而是如何让用户信任“临期不等于差”。这个项目的代码已经把业务模型搭好了你真正要去运营时得在商品展示、信用评价和售后服务上多花心思。技术方案上Django 足够稳业务方案上视频内容才是真正拉开差距的地方。