Python+Django三端民宿预订系统：架构设计与实战解析-代码聚汇网

做民宿预订这个项目之前，我心里其实是有过犹豫的。市面上成熟的民宿预订方案一抓一大把，直接套个SaaS或者开源的民宿系统改改就行了，为什么还要拿Python + Django这套技术栈从头写一套“小程序端 + PC Web端 + 手机浏览器端”三端通用的民宿预订系统？后来真正动手之后我明白了：如果只是应付“能下单、能收款”，那确实没必要折腾。但民宿老板真正要的不只是一个订房页面，而是一套能把房态、订单、价格日历、客户管理全部串起来、并且随时能在手机和电脑上操作的管理工具。Django的ORM和Admin体系加上小程序端灵活的交互，恰好可以把这个“既要给客人用、又要给自己管”的需求做得比较舒服。

这篇博文主要针对有Python基础、想把Django和小程序串成一个完整闭环项目的开发者。我会从系统架构、数据模型设计、Django后端接口实现、小程序端对接、PC管理端要点，再到真正的部署上线和踩坑排查，把整个项目的关键设计决策和实操细节都摊开来讲。内容偏实战，项目里直接能落地的代码思路和配置都会给到，至于具体业务细节，可以根据你自己接手的民宿项目灵活调整。

1. 一套系统三端跑：民宿预订项目的整体架构与数据流设计

1.1 为什么这个小程序系统要同时做PC Web端

一开始的需求其实很单纯，民宿老板说：“我要一个小程序，客人能看房、订房、付钱。”听起来很简单，但等你把需求往细了挖，就会发现单做一个小程序根本不够用。

客人端确实是小程序最方便，微信里扫码就能进，不用下载App，也不用注册账号。但民宿老板自己呢？他每天要改房价、关房态、查订单、看哪个房间今天该打扫了。这些操作如果都挤在小程序里做，要么把管理功能堆在同一个前端项目里导致小程序包体积膨胀、审核也麻烦，要么老板只能天天抱着手机在小程序后台里戳来戳去，体验很差。

所以这套系统最终定了三端：

小程序端：给C端客人使用，负责房源展示、房态日历、下单支付、订单查询、退款申请；
PC Web管理端：给民宿老板和运营人员使用，负责房源管理、价格日历批量设置、订单处理、经营数据统计；
手机H5端：给客人和管理员在手机浏览器上应急用的轻量版本，复用同一套API。

三个端共用同一个Django后端，数据完全打通。这样一来，老板在PC上设置好某间房下周一到周三的价格，小程序端客人刷新立即生效；客人在小程序上提交了订单，PC后台马上能看到待确认订单，还能推送提醒。这套“一后端多前端”的结构，是这类业务系统的核心骨架。

1.2 三端共用的核心数据模型

民宿预订业务的本质，就是“房态、价格、订单”三张表之间的状态博弈。这里我把最核心的数据模型列出来，这几个模型是所有业务接口的基石：

code复制House（房源模型）
- 名称、封面图、轮播图、地址、描述
- 房型类型（整栋/单间）、面积、可住人数
- 基础设施：无线网、空调、厨房、停车位等
- 基础价格（平时价）、押金、清洁费
- 上架状态、审核状态
- owner（关联民宿主账号）

Room（房间/房源库存单元）
- 归属House
- 房号、房间描述、最大入住人数
- 默认价格（用于价格日历未设置时的兜底）

PriceCalendar（价格日历）
- 关联Room
- 日期、当日价格、当日房态（可订/已订/停售/打扫中）
- 是否被手动锁房
- unique约束：(room_id, date)

Order（订单模型）
- 订单号（业务编号，如BZ+日期+随机串）
- 关联Room、下单用户
- 入住日期、离店日期、入住人数
- 款项明细：房费总额、清洁费、押金、优惠金额、实付金额
- 订单状态：待支付 / 待确认 / 已确认 / 已入住 / 已离店 / 已取消 / 退款中 / 已退款
- 联系人姓名、手机号
- 支付信息：微信支付单号、支付时间
- created_at、updated_at

User（用户模型）
- 唯一标识（小程序openid绑定）
- 昵称、头像、手机号
- 用户角色（guest/owner/admin）

这几个模型看起来不复杂，但表关系和数据约束一旦设计错了，后面会非常痛苦。尤其是PriceCalendar这个表，它承担了“价格 + 房态”双重职责，是整个系统的状态源头。不要用“开始日期-结束日期”区间段来存价格，那样改中间某一天的价格时你会崩溃。按天存储一行，虽然数据量会大一些，但查询和修改都极其简单清晰，配合Django的unique_together约束，能从根本上避免重复数据。

1.3 三端接口调用的数据流逻辑

Django后端只提供RESTful API，三端前端都走HTTP请求。数据流大概是这样的：

客人打开小程序，先调用wx.login()拿到code，后端用code换openid，在User表里匹配或创建用户，签发自定义登录态；
客人浏览房源列表，小程序调用GET /api/houses/?check_in=2025-06-01&check_out=2025-06-03接口，后端根据入住日期和离店日期，在PriceCalendar表里过滤出期间内所有可订且价格符合条件的房间；
客人提交订单，后端执行“创建订单 + 锁定房态 + 预占库存”的一系列事务操作，返回订单号和支付参数；
客人调用微信支付，支付成功后微信服务器异步回调Django接口，后端验签、更新订单状态、确认房态锁定；
老板在PC管理端登录后，调用GET /api/admin/orders接口查询所有订单，并进行接单、改价、退款等操作。

这里最关键的思路是：前端只负责展示和收集操作意图，所有状态变更和业务校验都放在后端完成。比如小程序端看起来“有房”，但提交订单时房间可能已经被别人占了，所以后端必须在下单时重新校验房态，而不是相信前端传过来的数据。这也是为什么接口设计比页面设计更重要的原因。

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

2. Django后端：从项目骨架到民宿业务模块落地

2.1 项目初始化与App拆分的考量

Django项目创建本身没什么好讲的，django-admin startproject一把梭。但App的拆分方式，我建议按业务域拆，而不是按技术层拆。

我当时是这样拆的：

code复制houses_app：房源与房态管理
orders_app：订单与支付
users_app：用户与登录认证
payments_app：支付回调与退款
statistics_app：经营统计
common_app：公共工具、异常处理、分页封装

这样拆分的好处是，每个App的业务边界非常清晰，后面做权限控制、写单元测试、甚至将来把某个模块拆成微服务，都能平滑过渡。如果你图省事把所有东西都塞进一个App，项目一开始写起来确实快，但等业务复杂到一定程度，一个models.py文件几千行，你会连想改一个字段都要翻半天。

创建App时要顺手解决几个基础问题：

第一，自定义用户模型。官方默认的User模型没有openid字段，而且扩展起来麻烦。所以要在项目启动后第一时间在users_app里创建自定义用户模型：

python复制class User(AbstractUser):
    openid = models.CharField(max_length=128, unique=True, null=True, blank=True)
    phone = models.CharField(max_length=20, null=True, blank=True)
    avatar = models.URLField(null=True, blank=True)
    nickname = models.CharField(max_length=64, null=True, blank=True)
    role = models.CharField(max_length=20, choices=(
        ('guest', '客人'), ('owner', '民宿主'), ('admin', '管理员')
    ), default='guest')

并且记得在settings.py里写AUTH_USER_MODEL = 'users_app.User'，这个配置必须在第一次migrate之前设置好，不然后面换用户模型会非常痛苦。

第二，Django REST Framework + SimpleJWT。小程序端不用session，用JWT来处理接口鉴权，前后端完全分离比较舒服。登录成功后返回一个access_token，小程序请求时放在Authorization: Bearer <token>头里。

第三，django-cors-headers配置跨域。PC Web管理端如果是独立域名部署，前端请求后端会跨域，这个中间件必须装。

2.2 民宿业务核心接口设计与权限控制

接口设计不是说“能返回JSON就算完”，要考虑三个层次：字段校验、业务校验、权限校验。

以“创建订单”为例，这个接口是整个系统的核心，也是并发压力最大的地方。接口路径是POST /api/orders/，请求体大致长这样：

json复制{
  "room_id": 12,
  "check_in": "2025-06-01",
  "check_out": "2025-06-03",
  "guest_name": "张三",
  "guest_phone": "13800138000",
  "guest_count": 2
}

后端要做的事情：

校验参数格式（日期合法性、入住人数不超过最大可住人数）；
从价格日历表查出入住期间每一天的价格，累加房费，再加上清洁费、押金，算出总金额；
校验房间在这期间是否全部可订（比如系统里有没有“该日期已被其他订单占用”的记录）；
用事务把订单创建和房态锁定绑在一起，同时把这几天的PriceCalendar设为“已订”；
如果锁房成功，就调微信支付统一下单接口，拿到支付参数返回前端。

关键代码里的锁房逻辑，我用的是select_for_update()加上对PriceCalendar的原子更新：

python复制from django.db import transaction
from django.db.models import F

with transaction.atomic():
    lock_dates = PriceCalendar.objects.select_for_update().filter(
        room_id=room_id,
        date__range=(check_in, check_out - timedelta(days=1)),
        status__in=['available', 'pending']
    )
    if len(lock_dates) != nights:
        raise BusinessError('所选日期中有房间已被预订')
    # 更新状态，利用查询条件做并发控制
    updated = PriceCalendar.objects.filter(
        pk__in=[d.pk for d in lock_dates],
        status__in=['available', 'pending']
    ).update(status='locked')
    if updated != nights:
        raise BusinessError('房源库存不足，请重新选择日期')
    order = Order.objects.create(...)

这个写法核心在于：先锁定行，再尝试更新，更新行数不满足条件就抛异常。这样两个用户同时下单同一间房时，数据库行锁会保证只有一个人能成功更新所有日期的房态，另一个人更新行数不足，订单创建失败。这里不建议只用exists()检查后直接创建订单，因为检查到创建之间有一段时间窗口，高并发下很容易超卖。

权限控制方面，我用了Django REST Framework的permission_classes做角色基础控制。比如：

客人角色：可以创建订单、查看自己的订单、申请退款，但绝对不能访问管理后台接口；
民宿主角色：可以管理自己名下的房源、处理属于自己的订单；
超级管理员：可以操作一切。

需要注意的是，光有IsAuthenticated不够，还得在视图里判断资源归属。比如民宿主A更新房源，要校验“这间房是不是属于当前登录用户”。用DRF的get_queryset()方法重写，也是一种常见做法：

python复制class HouseViewSet(viewsets.ModelViewSet):
    def get_queryset(self):
        user = self.request.user
        if user.role == 'admin':
            return House.objects.all()
        if user.role == 'owner':
            return House.objects.filter(owner=user)
        return House.objects.filter(status='published')

2.3 价格日历批量设置与房态管理

民宿老板最常用的功能，其实是价格和房态管理。客人端看房态只是日历上“可订/已订”的区别，但老板需要的是：旺季设高价、淡季搞促销、某间房今天要打扫不能卖、某间房下个月有人长租锁定。

所以我专门设计了“批量价格设置”功能。这个接口要支持三种操作：

按单个日期设置：选中某天，填个价格；
按日期区间设置：比如整个国庆假期，周一到周五一个价、周末一个价；
按星期规则设置：例如“每周五、周六价格上涨20%”，这个用来设置长期规则很实用。

后端的实现思路是把前端的操作参数标准化成一组[start_date, end_date, weekday_set, price, status]数组，然后在事务里先查已有的PriceCalendar记录，已存在的做更新，不存在的做插入，并且跳过已被订单锁定的日期。这里有个细节：如果日期对应已有“已入住/已确认”订单，管理人员会收到提示，不能直接把价格改了，但因为历史订单金额已定，改价只影响未来新单。

房态管理接口还需要一个“锁房”动作。有些民宿主和线下渠道合作，某几天的房间已经通过线下卖掉了，需要在小程序里也标记为不可订。这个就是PUT /api/houses/{id}/calendar/接口里传一个locked状态。锁房操作不受订单占用检查影响，可以直接覆盖。

3. 小程序端与PC Web端的差异化实现思路

3.1 小程序端：微信登录与授权信息的坑

小程序端我用的原生小程序框架，没有上uni-app（虽然uniapp可以跨端，但小程序的原生组件和微信支付体验还是原生最稳）。整个小程序端核心页面包括：首页房源列表、房源详情、房态日历、订单提交、订单列表、个人中心。

微信登录是第一个容易翻车的点。很多人第一次写小程序登录，会直接在前端页面里调wx.getUserProfile拿昵称头像，然后拿去后端当注册信息。但这里有个大坑：getUserProfile拿到的用户信息，并不能保证是真实的，而且微信后续对头像昵称的获取规则又调整过，现在基础库版本高的，甚至不再弹出授权框。

正确做登录的方式是：

在wx.login()成功回调后，用code去后端换openid和session_key；
后端生成自定义token返回；
前端用自定义token去请求业务接口；
如果业务需要手机号，在小程序端用button open-type="getPhoneNumber"让用户主动授权，把获取到的手机号code传给后端，后端拿着code向微信接口换取真实手机号。

我在项目里遇到过“小程序获取登录后的微信用户失败”这个问题，错误信息很长，带一长串参数，核心原因通常是：后端没有正确处理code换openid的时序，或者前端在code还没换成功时就提前去调了带登录态的业务接口。解决办法就是严格按上面的顺序来，并在小程序端封装一个request方法，在onLaunch里先完成登录并存储token，后续所有请求都等这个登录promise resolve后再发起。

另外，小程序的房态日历组件，不要自己从头写轮子。日历组件看着简单，但要处理“跨月选择、可选区间限制、不可订日期置灰”这些状态，自己调样式会调到怀疑人生。我当时用的是miniprogram-calendar这类现成插件改出来的，省了不少时间。房态数据从后端接口取回来后，需要映射成{ '2025-06-01': {status: 'available', price: 368}, '2025-06-02': {status: 'locked', price: 0} }这样的结构，日历组件直接读值渲染。

3.2 PC Web管理端：给民宿老板用的后台到底要做什么

PC管理端是给老板用的，所以核心不是做得花哨，而是高效。技术选型我用的Vue3 + Element Plus + ECharts，Django负责提供管理API。

PC管理端的功能模块可以理解为：仪表盘、房源管理、价格日历、订单管理、客户管理、评价管理、系统设置。

这里重点说几个容易被忽视的设计决策：

第一，价格日历在PC端不能做成一张静态表格，要做成真正的“日历+批量操作”视图。我用的方式是把一个月的日期按星期排列渲染成网格，每格显示当日价格和房态，格子右上角有个状态色块（绿色可订、红色已订、灰色锁房），鼠标悬停弹出快捷操作：改价格、设为不可订、标记打扫中。批量操作时，按住鼠标左键拖拽选中多个日期，松手后弹出统一设置窗口。这种交互方式老板用起来非常顺手，比一个一个改效率高一个量级。

第二，订单列表的筛选条件要足够强。老板每天会面对“待确认订单”“待入住订单”“退款申请”这些不同状态的订单，所以顶栏筛选必须有：日期范围、订单状态、房源名称、客人手机号。另外还要支持导出Excel，这个用Django的openpyxl库生成.xlsx文件就行，注意导出时数据量要是大了，记得放到Celery异步任务里去处理。

第三，经营统计的图表，至少要有：近30天订单量趋势、各房源收入排行、入住率统计、渠道来源占比。ECharts的数据格式后端直接返回聚合好的JSON，不要在前端做二次聚合。

3.3 手机H5端与移动端适配

手机H5端其实是个很实用的补充。客人可能从朋友圈点开一个链接，或者老板在微信聊天里临时发个房源链接给客户，这时候如果对方没装小程序，或者一时半会儿找不到小程序入口，H5页面就能顶上。

H5端我用的Vue3 + Vant组件库，页面结构和小程序基本一致，接口完全复用。因为Vant的组件风格和微信小程序很接近，所以两个端之间切换也没什么割裂感。

需要注意的点是：

H5端不能用wx.login，但可以通过公众号网页授权或手机号登录来识别用户；
微信内置浏览器的支付是wx.chooseWXPay，和后端对接的是公众号支付，不是小程序支付，两种支付的参数不一样；
H5端的页面要禁止被iframe嵌入，防止有人恶意嵌套你的页面做钓鱼，这个在Django的响应头里加X-Frame-Options: DENY就行。

H5端在PC浏览器上也能访问，不过页面会有最大宽度限制，我设了max-width: 480px并且居中，避免在PC上打开时布局拉垮。

4. 订单状态流转与并发防超卖：民宿预订最容易踩的坑

4.1 房间库存的并发控制与超卖问题

民宿预订和普通电商不一样的地方在于，它有严格的时间维度。一个房间6月1日被订了，不代表6月2日也不能卖，所以不能用“库存总数减一”这种简单模式。正确的设计是“按日期维度进行预占”。

前面第2节我提到用select_for_update()锁行，这里把并发控制的问题再展开讲一下。

假设现在两个客人同时看中了同一间房，都想订6月1日到6月3日。两个请求同时到达后端，正常情况下，系统应该只允许一个订单成功。在没有行锁的情况下，两个请求都可能查出“这几天都是available”，然后都创建了订单，这就超卖了。

用select_for_update()加事务之后，两个请求同时执行到filter(...).select_for_update()这一行时，第二个请求会被数据库阻塞，直到第一个请求的事务提交或回滚。第一个请求把房态更新成了locked并创建订单，提交事务后，第二个请求才拿到行数据，这时候它看到的已经是locked了，更新行数就是0，判断失败，订单创建被拒绝。

这是最稳妥的数据库层方案。当然也可以用Redis分布式锁来做，但考虑到这个项目的并发量级，数据库行锁完全够用，而且不用多维护一套Redis锁的过期时间问题。

还有几个细节值得注意：

事务要尽量短，锁行之后不要做耗时的外部调用（比如请求微信支付接口），不然一个事务锁着行等网络响应，其他请求全堵住；
正确顺序是：先锁行 → 更新房态 → 创建订单 → 提交事务 → 再请求微信支付。支付失败时订单状态标记为“待支付”，让用户在前端重新发起支付或者超时自动取消；
订单创建后，要在房态表里留一个“pending”而不是直接“locked”的状态。pending表示“这单已创建但没支付”，需要在15分钟内完成支付。这个状态用于过期订单自动释放，比直接用locked安全。

4.2 订单超时未支付的自动释放

客人在小程序上提交了订单，但是后来没有付款，这时候被锁定的房间不能一直被占着。所以需要一个定时任务，把超过15分钟未支付的订单自动取消，同时释放房态。

我用的是Celery + Redis做异步任务，然后在Django里配了一个Celery Beat的定时任务，每5分钟跑一次“取消超时订单”的任务。

任务逻辑：

python复制def cancel_expired_orders():
    now = timezone.now()
    expired_orders = Order.objects.filter(
        status='pending',
        created_at__lt=now - timedelta(minutes=15)
    ).select_for_update()
    for order in expired_orders:
        with transaction.atomic():
            order.status = 'cancelled'
            order.cancel_reason = '超时未支付自动取消'
            order.save()
            PriceCalendar.objects.filter(
                room_id=order.room_id,
                date__range=(order.check_in, order.check_out - timedelta(days=1)),
                status='pending'
            ).update(status='available')

这里要注意，更新房态时只更新status='pending'的记录，避免把后来其他订单已经锁定的日期误释放。用日期范围更新的时候，order.check_out - timedelta(days=1)这个边界条件非常关键，因为民宿订单离店当天是不占房的。

Celery Beat的定时配置：

python复制CELERY_BEAT_SCHEDULE = {
    'cancel-expired-orders-every-5-min': {
        'task': 'orders_app.tasks.cancel_expired_orders',
        'schedule': crontab(minute='*/5'),
    },
}

线上跑下来，这个任务非常稳定。要注意如果项目部署在宝塔面板，不要忘记给Celery Beat单独配置进程守护，不然重启服务器后定时任务不会自动起来。

4.3 支付回调的幂等处理与金额核对

微信支付成功之后，微信服务器会异步回调你配置的通知URL。这个回调有几个特性需要注意：一是可能会重复通知多次，二是通知顺序不保证，三是有可能延迟。所以回调处理函数必须是幂等的。

我的回调处理逻辑：

python复制@csrf_exempt
def wechat_pay_callback(request):
    # 1. 解析并验签
    data = parse_wechat_payment_callback(request.body)
    if not verify_wechat_signature(data):
        return JsonResponse({'code': 'FAIL', 'message': '签名错误'})
    
    # 2. 取出商户订单号（业务订单号）
    out_trade_no = data['out_trade_no']
    transaction_id = data['transaction_id']
    total_fee = data['total_fee']  # 单位：分
    
    # 3. 幂等处理
    with transaction.atomic():
        order = Order.objects.select_for_update().get(order_no=out_trade_no)
        if order.status in ('confirmed', 'paid'):
            # 已经处理过，直接返回成功，不再执行二次更新
            return JsonResponse({'code': 'SUCCESS', 'message': 'OK'})
        if order.status != 'pending':
            # 订单状态异常，记录日志，返回失败让微信重试
            logger.error(f'订单状态异常: {order.order_no} {order.status}')
            return JsonResponse({'code': 'FAIL', 'message': '订单状态异常'})
        # 4. 核对金额
        if order.actual_amount * 100 != total_fee:
            logger.error(f'订单金额不匹配: {order.order_no}')
            return JsonResponse({'code': 'FAIL', 'message': '金额不一致'})
        # 5. 更新订单状态和房态
        order.status = 'confirmed'
        order.paid_at = timezone.now()
        order.wechat_transaction_id = transaction_id
        order.save()
        PriceCalendar.objects.filter(
            room_id=order.room_id,
            date__range=(order.check_in, order.check_out - timedelta(days=1)),
            status='pending'
        ).update(status='locked')
    
    return JsonResponse({'code': 'SUCCESS', 'message': 'OK'})

这段代码里最关键的是第3步的幂等判断。因为微信回调可能不止一次，如果不做幂等，第二次回调时订单已经是confirmed了，再查一遍房态更新可能会误伤数据。特别是status从pending到locked的更新，如果重复执行且房态已经被其他操作改成available，那就麻烦了。

金额核对也很重要，回调里的金额一定要和数据库订单的实付金额比对，防止支付金额不符的情况。我甚至建议连下单时生成的prepay_id也存下来，回调时校验一下，增加一层安全性。

5. 部署上线：宝塔环境部署Django项目的完整记录

5.1 服务器环境准备与依赖部署

部署这块，我用的是宝塔面板 + Nginx + uWSGI + Python虚拟环境 + MySQL + Redis的组合。宝塔的最大优势是图形化管理MySQL、Redis和进程守护，对中小型项目来说效率非常高。

先说环境准备的流程：

在服务器上安装宝塔面板，然后在软件商店里安装Nginx、MySQL 5.7或8.0、Redis、Python项目管理器；
用Python项目管理器创建Python 3.10版本的虚拟环境，把项目代码拉进服务器；
在项目目录下安装依赖：pip install -r requirements.txt，这里有个小坑，uWSGI在Python 3.10版本编译时偶尔会报错，建议直接用pip install uwsgi之前先装好python3-dev和build-essential；
配置环境变量文件.env，里面放数据库连接信息、微信小程序appid和secret、Django的secret_key、Redis地址等，项目代码里用python-decouple读取，不要把密钥写死在settings.py。

settings.py里几个关键配置：

python复制DEBUG = False
ALLOWED_HOSTS = ['api.yourdomain.com']

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': config('DB_NAME'),
        'USER': config('DB_USER'),
        'PASSWORD': config('DB_PASSWORD'),
        'HOST': '127.0.0.1',
        'PORT': '3306',
        'OPTIONS': {
            'charset': 'utf8mb4',
        },
    }
}

CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': config('REDIS_URL'),
        'OPTIONS': {'CLIENT_CLASS': 'django_redis.client.DefaultClient'},
    }
}

STATIC_ROOT = '/www/wwwroot/your_project/static'
MEDIA_ROOT = '/www/wwwroot/your_project/media'

这里特别提醒：DEBUG=False之后，Django不会再帮你处理静态文件，所以collectstatic必须执行一遍，把admin后台等静态文件收集到STATIC_ROOT目录。

5.2 uWSGI与Nginx配置：让小程序接口稳定响应

uWSGI负责把Python代码跑起来，Nginx负责接收外部HTTP请求并把动态请求转发给uWSGI。我在项目根目录下建了一个uwsgi.ini配置：

ini复制[uwsgi]
chdir = /www/wwwroot/your_project
module = your_project.wsgi:application
master = true
processes = 4
threads = 2
socket = 127.0.0.1:8001
chmod-socket = 664
vacuum = true
max-requests = 5000
daemonize = /www/wwwroot/your_project/logs/uwsgi.log

然后Nginx配置：

nginx复制server {
    listen 80;
    server_name api.yourdomain.com;

    client_max_body_size 10m;

    location /static/ {
        alias /www/wwwroot/your_project/static/;
    }

    location /media/ {
        alias /www/wwwroot/your_project/media/;
    }

    location / {
        include uwsgi_params;
        uwsgi_pass 127.0.0.1:8001;
        uwsgi_read_timeout 60;
        uwsgi_send_timeout 60;
    }
}

配置完成后执行uwsgi --ini uwsgi.ini启动，再用宝塔的进程守护管理器把uwsgi加进去做开机自启。注意Nginx配置里的client_max_body_size要调大一些，否则上传房源图片时容易报413错误。

部署完成后，建议先用curl http://127.0.0.1:8001/api/health/测试uWSGI是否正常，再通过域名访问测试Nginx转发是否正常。这样可以快速定位问题是出在Nginx层还是uWSGI层。

5.3 部署后常见问题排查

部署环节我踩过几个坑，值得专门说：

第一个坑：小程序接口请求报“URL域名不合法”。微信小程序要求所有请求的域名必须是小程序后台里配置过的合法域名，且必须是HTTPS、不能带端口。所以部署时必须给API域名配置SSL证书，宝塔的SSL面板可以一键申请Let‘s Encrypt证书，然后把小程序后台的“request合法域名”填成https://api.yourdomain.com。开发阶段可以在小程序开发者工具里勾选“不校验合法域名”，但真机预览必须配好。

第二个坑：静态文件404。DEBUG=False时，如果你没有执行collectstatic，admin后台和DRF的可浏览API页面都是没有样式的。执行完collectstatic之后，还要确认Nginx的location /static/配置指向了正确的STATIC_ROOT目录，否则也会404。

第三个坑：跨域问题。小程序端请求后端不涉及浏览器跨域，但PC Web管理端在浏览器里请求API会遇到CORS。我在settings里用了django-cors-headers，配置成：

python复制CORS_ALLOWED_ORIGINS = [
    'https://admin.yourdomain.com',
]

只允许管理后台域名，不建议直接CORS_ALLOW_ALL_ORIGINS = True，那等于是对所有网站开放了跨域访问，安全隐患很大。

第四个坑：微信支付的回调URL必须是公网可访问的HTTPS地址，而且要在微信支付商户平台后台配置。

5.4 部署后接口性能优化与Redis缓存

项目跑起来之后，我做的第一件性能优化是给“首页房源列表”加Redis缓存。民宿的房源信息变动频率不高，完全没必要每次都查数据库。我用Django的cache_page装饰器做了全页面缓存，或者用cache.set/cache.get缓存接口返回的JSON。

缓存键的设计要注意：同一个接口带不同参数（日期、页码）要缓存成不同key，但又要避免缓存太碎片化导致内存暴涨。我用的策略是：把房态信息按“房源ID+日期”缓存，价格日历按“月维度”缓存，这样粒度比较合理。

实测下来，首页接口的响应时间从没加缓存前的150ms降到了30ms左右，效果还是很明显的。但要注意，民宿价格一旦修改，必须主动删除对应房源和日期的缓存。不然客人看到的还是旧价格。这里可以在价格日历的save()方法里重写缓存删除逻辑，或者用Django的signal post_save来清除缓存。

另外一个优化点是数据库索引。价格日历表在查询时最常用的条件是room_id + date，所以我给这两个字段建了联合索引：

python复制class Meta:
    unique_together = ('room', 'date')
    indexes = [
        models.Index(fields=['room', 'date']),
        models.Index(fields=['status']),
    ]

订单表上给order_no建了唯一索引，status字段也建了索引，这样订单查询和超时任务的性能都有保障。

6. 一套民宿预订系统的前后端联调经验总结

前后端联调是整个项目里最耗时间、也最容易出小问题的时候。我这里把几个重要的联调经验和大家分享一下。

第一，接口返回格式要统一。我在common_app里封装了一个统一的响应结构：

json复制{
  "code": 0,
  "message": "success",
  "data": {}
}

所有接口都按这个结构返回，错误码定义好：0成功，1001参数错误，1002未登录，2001房态冲突，2002订单状态不允许此操作，3001支付失败等等。前端只需要统一封装一个请求拦截器，判断code字段即可。不用在联调时每个接口单独写错误处理逻辑。

第二，时间格式要统一标准化。小程序端和后端之间传日期，全部用YYYY-MM-DD字符串；带时间的时间戳，统一用ISO格式字符串。不要一会儿传时间戳，一会儿传字符串，更不要让后端返回local time带时区歧义。我在Django的serializer里配置了：

python复制DATETIME_FORMAT = '%Y-%m-%d %H:%M:%S'
DATE_FORMAT = '%Y-%m-%d'

第三，联调时的日志要留足。Django这边我用logging记录每个接口的请求参数和响应状态，特别是下单和支付回调这类关键接口。联调时如果小程序那边说“下单失败”，去看后端日志能立刻定位是参数问题还是业务校验问题，不用来回猜。

第四，接口版本号。虽然这个项目不大，但一开始我就给所有接口加了/api/v1/前缀。后面如果因为业务调整导致接口不兼容，可以平滑地上/api/v2/，旧版小程序不受影响。这也是一个比较有前瞻性的设计。

最后说一个容易被新手忽略的点：小程序的代码包如果超过2MB，主包体积超限就发布不了。我的做法是把首页、房源详情、订单中心这些核心页面放主包，个人中心、退款申请、关于我们这些低频页面放分包。后端接口不变，前端分包只需要调整pages.json的配置即可。实际上做下来，主包体积从1.9MB降到了1.2MB左右，开发体验和审核体验都好很多。

整个项目做完，我的体会是：民宿预订系统真正难的地方不是写代码，而是把“房态状态机”设计清楚、把并发下的数据一致性守住。Django的ORM和事务机制在这类业务里其实非常顺手，配合小程序端灵活的交互，确实可以搭出一套完整可商用的三端预订系统。如果你正在规划类似项目，希望这份落地记录能让你少走一些弯路。

Python+Django三端民宿预订系统：架构设计与实战解析