1. 项目概述与需求拆解
1.1 为什么需要"流浪动物救助网站"
十几张A4纸打印的领养信息、贴在小区门口的过期告示、微信公众号后台一条条人工记录的救助申请——这是我第一次去本地流浪动物救助站调研时看到的真实场景。志愿者很多，但信息散落，领养人找不到合适的渠道，救助站也缺乏一套能统计申请、管理动物的系统。所以当朋友找到我，想做一个流浪动物救助网站时，需求其实非常明确：把所有待领养动物的信息集中展示，让救助站能发布、编辑动物档案，让用户能搜索、提交领养申请，同时留一个后台给管理员审核和统计。
这个项目最终落地成了一套前后端分离的网站，技术栈是Python + Vue，后端以Django为主，Flask做辅助服务，开发工具用Pycharm。写这篇文章是希望把从环境搭建到部署上线的完整过程复盘一遍，特别是那些搜索引擎里不告诉你、只有自己踩过坑才能总结出来的细节，给正在做类似项目的人一个参考。
1.2 技术选型：为什么是Python + Vue + Django + Flask
选型的时候我对比过几个方案。为什么坚持Python？因为除了我这个开发熟悉之外，后续接爬虫同步外部宠物数据、跑一些简单的数据分析脚本都非常方便。Python生态里Vue并没有直接关系，前端选Vue是因为它对新手友好、中文文档齐全、生态成熟，配合Element UI这类组件库能很快把后台管理界面做出来。
后端为什么Django为主？核心原因是Django自带ORM、Admin后台、用户认证和迁移机制，对于这种“大量表格管理”的场景太合适了。特别是Admin后台，几乎是白送的管理界面，救助站工作人员只需要登录Django Admin就能录入动物信息、审核领养申请，省掉大量重复开发。
那Flask放哪里？我单独做了一个轻量服务跑图片压缩和外部数据采集。原因很简单：Django的ORM很重，处理高并发小请求不如Flask轻巧。救助站每天可能从不同平台同步几十条流浪猫狗信息，这些操作不涉及复杂业务逻辑，用Flask写一个小接口，独立部署，互不干扰。两个服务通过数据库和HTTP通信。听起来复杂，实际在项目结构上只是一体化下的分模块，后面我会详细说明。
2. 环境准备与项目骨架搭建
2.1 Pycharm配置Python开发环境
很多初学者第一个卡点不是代码，而是开发环境。我用的版本是Pycharm 2024专业版，社区版也没问题，只是专业版对Web项目支持更完整。Pycharm专业版需要激活的话，建议直接用JetBrains官方渠道，学生和教师可以免费申请教育授权，比自己找破解靠谱得多，也不会有安全风险。
创建项目时，Python解释器我选择Python 3.10，这个版本对Django、DRF、Channels的兼容性都比较稳定。用Pycharm的Virtualenv新建一个干净的虚拟环境，注意别把全局环境搞乱。具体步骤：打开Pycharm，New Project，选择Virtualenv作为环境类型，Location指向项目目录，Base interpreter选择一个已安装的Python 3.10，然后点击Create。项目创建完成后，在Terminal里输入pip install django djangorestframework channels pillow django-cors-headers，把这些基础依赖装好。千万不要图省事用conda的base环境，多个项目很容易版本冲突。
如果你从Git拉取的代码，直接在Pycharm的Settings-project-python interpreter里选择Venv，Pycharm会自动识别requirements.txt并提示安装依赖，这个功能很实用。
2.2 创建Django项目与基础APP
在Pycharm底部Terminal执行：
django-admin startproject paw_shelter cd paw_shelter python manage.py startapp animals python manage.py startapp users创建完以后，目录结构大概是：
- paw_shelter/（项目名）
- paw_shelter/（配置目录）
- animals/（动物模块）
- users/（用户模块）
记得把新APP和第三方库加入INSTALLED_APPS，位置在paw_shelter/settings.py里：
INSTALLED_APPS = [ 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', # 第三方 'rest_framework', 'corsheaders', 'channels', # 自建APP 'animals', 'users', ]同时加一个REST_FRAMEWORK配置，设置默认分页和认证方式：
REST_FRAMEWORK = { 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination', 'PAGE_SIZE': 10, 'DEFAULT_AUTHENTICATION_CLASSES': [ 'rest_framework.authentication.SessionAuthentication', 'rest_framework.authentication.TokenAuthentication', ] }这个配置决定了后面所有列表接口默认分页，避免一页返回几百条数据导致前端卡死。
2.3 Flask辅助服务的定位与项目结构
Django负责主业务，Flask服务单独放在flask_service/目录下，不参与Django的启动流程。我用的版本是Flask 2.3，创建一个main.py写一个简单的接口：
from flask import Flask, jsonify, request from flask_cors import CORS import os app = Flask(__name__) CORS(app) @app.route('/health', methods=['GET']) def health(): return jsonify(status="ok") @app.route('/compact', methods=['POST']) def compact_image(): # 接收前端上传的图片，使用Pillow压缩后返回 return jsonify(result="done") if __name__ == '__main__': app.run(host="0.0.0.0", port=5001)这个服务独立运行，只通过HTTP和Django通信，不共用数据库。你可能会问，为什么不用Django自带的功能？因为图片压缩和爬虫同步这类任务一旦写进Django主线程，业务高峰期会占用大量资源，甚至阻塞正常API请求。拆出去以后，Flask挂了不影响主业务，Django挂了也不影响图片处理。这个分层在项目维护期非常香，改爬虫代码再也不用重启主服务了。
3. 后端核心实现（Django为主）
3.1 数据模型设计要点
流浪动物救助网站最核心的模型是Animal（动物信息），它和救助站、领养申请、用户形成几个主链路。我设计的字段如下：
class Animal(models.Model): class Status(models.TextChoices): AVAILABLE = 'available', '待领养' PENDING = 'pending', '审核中' ADOPTED = 'adopted', '已领养' name = models.CharField(max_length=50, verbose_name="昵称") species = models.CharField(max_length=20, choices=[('dog', '狗'), ('cat', '猫')]) gender = models.CharField(max_length=10, blank=True) age = models.PositiveIntegerField(blank=True, null=True) image = models.ImageField(upload_to='animals/', blank=True) description = models.TextField(blank=True) status = models.CharField(max_length=20, choices=Status.choices, default=Status.AVAILABLE) created_at = models.DateTimeField(auto_now_add=True) updated_at = models.DateTimeField(auto_now=True)这里有几个关键点：Status用TextChoices而不是简单的字符常量，在Django Admin和前端序列化里都更容易维护；image字段依赖Pillow库，创建模型前记得pip install pillow；年龄用PositiveIntegerField，防止出现负数这种脏数据。
领养申请模型：
class AdoptionApplication(models.Model): animal = models.ForeignKey(Animal, on_delete=models.CASCADE, related_name='applications') applicant_name = models.CharField(max_length=50) phone = models.CharField(max_length=20) address = models.CharField(max_length=200) reason = models.TextField() status = models.CharField(max_length=20, choices=[ ('pending', '待审核'), ('approved', '已通过'), ('rejected', '已拒绝'), ], default='pending') created_at = models.DateTimeField(auto_now_add=True)on_delete=models.CASCADE的意思是动物被删除时，关联的领养申请也会被删除，符合业务逻辑：没有动物了，申请还存在就没有意义。related_name='applications'允许我们通过animal.applications.all()反向查询所有申请，这在写序列化时会很有用。
3.2 序列化与API视图
有模型之后，用DRF写接口效率非常高。以Animal为例：
from rest_framework import serializers from .models import Animal class AnimalSerializer(serializers.ModelSerializer): class Meta: model = Animal fields = ['id', 'name', 'species', 'status', 'image', 'description']视图我用viewsets.ModelViewSet，配合Django Rest Framework的DefaultRouter，一行路由就能搞定几乎所有CRUD接口：
from rest_framework import viewsets from .models import Animal from .serializers import AnimalSerializer class AnimalViewSet(viewsets.ModelViewSet): queryset = Animal.objects.all() serializer_class = AnimalSerializer def get_queryset(self): # 支持按品种和状态过滤 qs = super().get_queryset() species = self.request.query_params.get('species') status = self.request.query_params.get('status') if species: qs = qs.filter(species=species) if status: qs = qs.filter(status=status) return qs路由注册时，在paw_shelter/urls.py里：
from rest_framework.routers import DefaultRouter from animals.views import AnimalViewSet router = DefaultRouter() router.register(r'animals', AnimalViewSet, basename='animal') urlpatterns += router.urls默认情况下，/api/animals/支持GET列表、POST新增，/api/animals/{id}/支持GET、PUT、PATCH、DELETE。这种开发速度是SQL写死无法比的，非常适合救助站这种业务经常微调的场景。
3.3 Django执行查询与删除对象：实际写法与注意事项
这个项目里删除场景很多：管理员删除了错误发布的动物信息、用户撤销了领养申请。很多新手在Django里删除对象时容易忽视条件控制，直接Animal.objects.all().delete()，这是最危险的写法，能把整个表清空。正确的操作逻辑是：先获取对象，再删除单个对象。
# 删除单个对象 animal = Animal.objects.get(id=animal_id) animal.delete() # 批量删除符合条件的对象 Animal.objects.filter(created_at__lte=cutoff_date, status='pending').delete()删除前务必要确认两步：第一步，用filter条件把目标范围锁死；第二步，先查出一条打印确认，再执行删除。我建议在这里做一个软删除设计，给Animal模型加一个is_active字段，默认True，删除时改为False即可：
# 软删除 animal = Animal.objects.get(id=animal_id) animal.is_active = False animal.save()好处是数据可回退，一旦误删还能恢复。对于救助站这种长期运营项目，软删除比物理删除安全得多。如果非要物理删除，执行前一定要用transaction.atomic()包裹，避免删除过程中数据库崩溃导致数据不一致。
另外需要注意，删除关联对象时，Django默认级联删除（CASCADE），如果Animal被删除，它的AdoptionApplication也会被删。如果不想级联，可以把外键改为SET_NULL，同时允许字段为null=True, blank=True，这样删除动物后申请记录还在，只是animal字段变成空。
3.4 WebSocket推送：后台数据实时推给前端
这个项目里有个需求：救助站工作人员在后台审核一个领养申请，前端页面上志愿者的界面希望马上看到状态变化。传统做法是前端轮询接口，每10秒请求一次，浪费资源且不实时。我用Django Channels实现了WebSocket推送。
安装依赖：
pip install channels channels-redis在settings.py里配置：
ASGI_APPLICATION = 'paw_shelter.asgi.application' CHANNEL_LAYERS = { 'default': { 'BACKEND': 'channels_redis.core.RedisChannelLayer', 'CONFIG': { 'hosts': [('127.0.0.1', 6379)], }, }, }创建consumers.py：
from channels.generic.websocket import AsyncWebsocketConsumer import json class NoticeConsumer(AsyncWebsocketConsumer): async def connect(self): self.group_name = 'notice' await self.channel_layer.group_add(self.group_name, self.channel_name) await self.accept() async def disconnect(self, close_code): await self.channel_layer.group_discard(self.group_name, self.channel_name) async def send_notice(self, event): await self.send(text_data=json.dumps(event['message']))路由层面在asgi.py里：
from channels.auth import AuthMiddlewareStack from channels.routing import ProtocolTypeRouter, URLRouter from django.urls import path from animals.consumers import NoticeConsumer application = ProtocolTypeRouter({ 'http': django_asgi_app, 'websocket': ( URLRouter([ path('ws/notice/', NoticeConsumer.as_asgi()), ]) ), })后台审核完一个申请，只需要往channel layer发送一条消息，前端就会实时收到。我在Django Admin的model方法里加上async_to_sync(channel_layer.group_send)(...)调用，非常简单。生产环境用Redis做channel layer，本地可以先用内存版。这里有个坑：Django Channels对WSGI/ASGI部署有要求，用runserver可以跑，生产上必须换成daphne paw_shelter.asgi:application启动，不然WebSocket不生效。
4. 前端Vue实现
4.1 Vue项目初始化与路由配置
前端我用Vue 3 + Vite + Vue Router。用Pycharm的Terminal执行：
npm create vite@latest frontend -- --template vue cd frontend npm install npm install vue-router@4 axios element-plus路由配置是Vue单页应用的核心。我把页面分成公共页面和管理后台两块，采用动态路由匹配：
import { createRouter, createWebHistory } from 'vue-router' import Home from '@/views/Home.vue' const routes = [ { path: '/', name: 'home', component: Home }, { path: '/animals', name: 'animals', component: () => import('@/views/AnimalList.vue') }, { path: '/animals/:id', name: 'animal-detail', component: () => import('@/views/AnimalDetail.vue') }, { path: '/apply/:animalId', name: 'apply', component: () => import('@/views/ApplicationForm.vue'), meta: { requiresAuth: true } }, { path: '/login', name: 'login', component: () => import('@/views/Login.vue') }, { path: '/admin', name: 'admin', component: () => import('@/views/AdminDashboard.vue'), meta: { requiresAuth: true, role: 'admin' } }, ] const router = createRouter({ history: createWebHistory(), routes, }) export default router注意我使用了路由懒加载，只有访问到对应地址时才加载对应组件，首页首屏加载速度明显提升。另外在路由守卫里判断用户是否登录、是否有管理员权限：
router.beforeEach((to, from, next) => { const token = localStorage.getItem('token') if (to.meta.requiresAuth && !token) { next('/login') } else { next() } })这里不用做太复杂的权限系统，前后端配合，前端过滤只是改善用户体验，真正的权限校验永远要在后端API里完成。
4.2 页面组件与Axios交互
Vue组件开发的思路是“页面拆组件”。AnimalList.vue里我拆出了AnimalCard.vue、FilterBar.vue和Pagination.vue，这样每个组件职责单一，后期加新页面可以复用。
请求API我用Axios封装了一个实例，放在src/utils/request.js：
import axios from 'axios' const request = axios.create({ baseURL: '/api', timeout: 5000, withCredentials: true, }) request.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) { config.headers.Authorization = `Token ${token}` } return config }) export default request我特意加上了withCredentials: true，因为Django的Session认证需要携带Cookie。如果不带，跨域请求即使配好了CORS，也拿不到用户的登录状态。前端调用接口时，只需要：
const { data } = await request.get('/animals/', { params: { species: currentSpecies, status: 'available', page: currentPage } })交互上有个细节：列表页和详情页的图片加载，我用了Vue的v-if加上加载失败占位图，不然用户访问一个已删除的动物图片会看到裂图，观感很差。类目筛选我做成标签切换，比下拉框更直观。
4.3 扩展：m3u8播放与直播场景
虽然救助网站核心功能是领养信息管理，但运营方提了一个很有价值的场景：在救助站门口装几个摄像头，让网友能在线看猫咪狗狗们的生活状态，提高领养转化率。这类实况视频用HLS协议传输，播放地址就是一个.m3u8链接。
我在Vue里实现时用了hls.js，代码非常简单：
import Hls from 'hls.js' const video = document.getElementById('live-video') if (Hls.isSupported()) { const hls = new Hls() hls.loadSource('https://your-stream-server/live/cat_shelter.m3u8') hls.attachMedia(video) }但必须提醒：浏览器自动播放视频有严格限制，必须静音才能自动播放，而且m3u8流跨域时需要在流媒体服务器配置Access-Control-Allow-Origin。如果不配置，前端会一直卡在加载中。第一次部署时我就是没配，调试了很久才发现是Nginx少加了CORS响应头。
5. 联调、部署与常见问题
5.1 跨域与Cookie处理
前后端分离，最烦的就是跨域。开发时我用Django的corsheaders解决：
INSTALLED_APPS = ['corsheaders', ...] MIDDLEWARE = ['corsheaders.middleware.CorsMiddleware', ...] CORS_ALLOWED_ORIGINS = [ 'http://localhost:5173', ] CORS_ALLOW_CREDENTIALS = True如果前端请求地址是http://localhost:5173，后端是http://localhost:8000，不加CORS配置，浏览器会直接拦截响应。加了CORS_ALLOW_CREDENTIALS = True之后，Cookie才能被浏览器保存和携带。
还有一个Django特有的CSRF防护。我用SessionAuthentication，所以在POST、PUT、DELETE请求中需要携带CSRF Token。最省事的方式是在前端从Cookie里读取csrftoken，然后加到请求头X-CSRFToken。我在request.js的拦截器里统一处理：
function getCookie(name) { const value = `; ${document.cookie}` const parts = value.split(`; ${name}=`) if (parts.length === 2) return parts.pop().split(';').shift() } request.interceptors.request.use(config => { const csrfToken = getCookie('csrftoken') if (csrfToken) config.headers['X-CSRFToken'] = csrfToken return config })只要第一次访问Django任意页面时Set-Cookie了csrftoken，后面所有请求都会自动带上。注意如果前后端域名不同，csrfCookie的SameSite=None; Secure属性必须设置好，否则测试环境用HTTP会无法携带Cookie。
5.2 Flask部署注意事项及整个系统的部署
Flask辅助服务部署比Django简单得多，但有几个点容易踩。我用的方式是gunicorn+gevent：
先创建wsgi.py：
from main import app if __name__ == "__main__": app.run()然后：
pip install gunicorn gevent gunicorn -w 2 -k gevent -b 0.0.0.0:5001 wsgi:app-w 2是指两个worker进程，-k gevent是异步worker，适合处理图片压缩这类带有IO等待的任务。Flask本身没有严格的并发限制，但图片压缩如果同步阻塞，用户并发一大就会排队，用gevent能明显提升吞吐。
整个系统最后用Nginx统一入口：
server { listen 80; server_name your-domain.com; # 前端静态文件 root /var/www/frontend/dist; index index.html; location /api { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /ws/ { proxy_pass http://127.0.0.1:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } location /media/ { alias /var/www/paw_shelter/media/; } location /flask/ { proxy_pass http://127.0.0.1:5001; } location / { try_files $uri $uri/ /index.html; } }我在/配置了try_files $uri $uri/ /index.html，这行非常重要。Vue使用history路由，刷新一个子页面路径时，如果Nginx不认识这个路径，会返回404。加了这个配置，所有请求先在静态目录里找文件，找不到就返回Vue的index.html，再由前端路由接管。
5.3 实际调试中遇到的坑与解决技巧
整个项目开发中，我记了十几个坑，这里挑三四个最典型的。
第一个坑是Django的runserver和daphne切换问题。开发时用python manage.py runserver调试REST API，一切正常；一上WebSocket就发现连不上，控制台报WebSocket connection failed。后来发现runserver虽然能处理HTTP，但不是完整的ASGI服务器，必须用daphne paw_shelter.asgi:application启动才能跑WebSocket。用Pycharm配置启动参数时，我单独建了一个Daphne运行配置，命令行写daphne paw_shelter.asgi:application -b 0.0.0.0 -p 8000，记得选好Python解释器。
第二个坑是图片上传的大小限制。Django默认DATA_UPLOAD_MAX_MEMORY_SIZE是2.5MB，用户上传一张手机拍摄的猫照片，经常4MB以上，接口直接500。在settings.py里加上：
DATA_UPLOAD_MAX_MEMORY_SIZE = 1024 * 1024 * 10 FILE_UPLOAD_MAX_MEMORY_SIZE = 1024 * 1024 * 10顺便把前端也限制一下上传大小，用Element Plus的before-upload检查文件size，超过5MB直接提示，不让请求发出去。
第三个坑是数据库的时区问题。Django默认创建时间用的UTC，前端显示时差8小时，需要把：
TIME_ZONE = 'Asia/Shanghai' USE_TZ = True设置好后，所有auto_now_add的字段都会按上海时间存储。如果已经存了UTC时间，可以先写脚本批量转换，不然前端展示“两个小时后发布”会被用户投诉。
第四个坑是Vue打包后后端Admin的静态文件丢了。collectstatic把Django自带后台样式收集到/static/，但Nginx没加location /static/的alias，导致后台UI白板。在Nginx加一行配置即可：
location /static/ { alias /var/www/paw_shelter/static/; }这个错误非常隐蔽，日志里没有任何错误，浏览器控制台全是静态文件404。
6. 项目复盘与经验总结
6.1 数据安全与审核机制
做公益性质的平台，数据安全反而更要重视。我从一开始就给上传的动物信息加了人工审核流程：用户可以在前端提交“发现流浪动物”表单，但这条记录默认是pending状态，不会立即展示在首页，只有管理员登录后台审核通过后才会公开。这个机制能过滤大部分垃圾信息和恶意上传，降低后续救助站实际去现场核实的成本。
权限上，普通用户和管理员角色分开。普通用户只能浏览、提交领养申请、管理自己的资料；管理员拥有所有数据的增删改查权限。实现时我用了Django自带的Group权限，结合DRF的IsAuthenticatedOrReadOnly和DjangoObjectPermissions。代码层面，前端用路由守卫控制路由跳转，后端用权限类确保接口不会被绕过。这里特别提醒：永远不要相信前端的v-if和路由守卫，后端权限才是最后一道闸门。
另外，所有用户提交的内容，包括申请理由、动物描述，都要在模板里进行HTML转义。Vue默认是转义输出，所以直接用{{ content }}就不会有XSS风险，但要注意不要使用v-html渲染任何用户输入。我在做后台统计页面时不小心用v-html渲染了一段用户填写的救助地点，结果一个用户填入了一段带样式的脚本，虽然没什么危害，但也给我敲了警钟。v-html能不用就不用，实在要用一定要对内容做安全过滤。
6.2 我的几点实操体会
项目收尾阶段，我最大的体会是“先构建核心闭环，再谈锦上添花”。救助站最需要的是“录入动物—前端展示—用户申请—后台审核”这条主链路，其他比如在线直播、数据可视化、多语言支持，都是后面根据运营反馈一点点加的。第一版如果功能堆太多，开发周期拉长，光调试就可能拖垮热情。
关于Flask和Django共存，很多人质疑是不是多余。我的经验是，当一个服务里同时存在重业务API和轻量定时任务时，拆开部署之后的幸福感会非常强。Flask服务每次发布，只需要重新启动一个很小的进程，不影响主流程；而Django只要改模型，迁移数据库、重启主服务，也不用担心把爬虫或图片处理那部分搞挂。两个服务之间的唯一通信是图片存储路径和动物ID，耦合度很低。
最后也是最重要的一点：部署前把备份做好。我用Crontab每天凌晨对SQLite数据库（或生产上的MySQL）进行一次备份，保留最近七天的文件。有一次我发现某个清理脚本误删了几个月前的动物记录，就是因为有备份才能快速恢复，不然对救助站来说可能意味着几只动物信息永久丢失。做这个项目的过程中，我重新理解了“技术是为公益服务的”这句话，稳定、可靠、不添乱，比花哨的功能更让人放心。
Pycharm里最后留一个我经常用到的调试技巧：当Django接口莫名返回500时，把Pycharm的运行配置里加一个环境变量DJANGO_DEBUG=1，然后就能在浏览器看到完整的Django错误页，而不仅仅是“服务器错误”。这个技巧解决了我至少三分之一的问题。
