简介这是一套基于Python Django框架开发的文档管理系统完整源码面向Web开发初学者与Django进阶学习者解决企业或团队中常见的文档上传、分类存储、权限管控与在线检索等核心管理需求。压缩包共64个文件包含15个Python后端逻辑文件含models、views、urls等核心模块、10个JavaScript交互脚本、12个CSS样式文件及配套HTML模板、静态资源与数据库迁移文件整体体积仅1.62MB结构清晰便于快速部署与二次开发。已有1888人下载学习项目以dinosaur-master为根目录内置用户认证、文件上传下载、搜索过滤、RESTful接口扩展等典型功能模块代码组织遵循Django标准应用划分附带requirements.txt依赖清单与完整settings配置可直接运行并作为教学案例深入理解MVC架构、QuerySet操作及中间件机制。 拿到这个项目第一反应就是亲切。Django框架写文档管理系统几乎是每个Python后端开发都会经历的一个练手项目但它又不像TodoList那样简单到没有营养文档管理涉及文件上传、权限控制、版本管理、全文检索这些真实业务里躲不掉的问题。如果你正在找工作准备项目经验或者公司内部确实缺一个轻量级的文件共享工具这套源码值得你花时间好好盘一遍。我花了一整天把整个项目完整走了一遍从解压到跑通再到把核心代码逐行读完。这篇博文会把整个系统的设计思路、核心实现、部署流程和常见坑一次性讲透你能直接照着操作也能从中提炼出自己的改造方案。1. 项目整体设计与需求拆解1.1 文档管理系统到底解决了什么问题在聊代码之前先想清楚一件事文档管理系统和普通网盘的区别在哪里网盘的核心是存储和同步而文档管理系统的核心是组织、检索、权限和协作。企业内部常见的场景是合同文件散落在各个员工电脑里方案文档通过微信传来传去最后分不清哪个是最终版新人入职找不到历史项目资料。这套系统要解决的就是这些问题把散落的文件收拢到一个统一的平台里通过分类、标签、权限和版本控制让文件变得可管理、可追溯。明白这个定位你就能理解源码里为什么会有那些看起来多余的设计。比如版本管理模块普通文件上传系统根本不需要但文档管理系统必须有因为合同和方案终稿经常要回滚。再比如操作日志这不是为了监控员工而是为了在文件误删或越权操作时能快速定位责任人。1.2 为什么选Django而不是Flask或FastAPI项目选择了Django这个选型很务实。我见过不少人用Flask搭类似系统做到用户认证和文件管理的时候需要自己拼第三方库经常出现兼容性问题。Django的优势在于全家桶式的一体化设计自带的Admin后台可以快速管理用户和文档自带ORM让数据库操作变得简单自带认证系统直接解决了登录权限问题自带模板引擎方便渲染管理页面。这套源码的目标不是炫技而是用最少的时间成本交付一个能用的系统Django正好是这个场景下的最优解。如果你后续要把它改造成API服务对接前端Django REST Framework也有成熟的生态扩展起来不费劲。Flask适合微服务和高度定制化的场景但系统性功能多的时候Django的开发效率优势非常明显。1.3 源码包目录结构说明解压zip文件后项目目录大概是这样的结构doc_management/ # 项目根目录 ├── manage.py # Django管理入口 ├── requirements.txt # 依赖包清单 ├── docs/ # 项目说明文档 ├── static/ # 静态资源目录 ├── media/ # 上传文件存放目录运行时生成 ├── apps/ │ ├── users/ # 用户模块 │ ├── documents/ # 文档核心模块 │ ├── categories/ # 分类模块 │ └── operations/ # 操作日志模块 └── config/ # 项目配置目录 ├── settings.py # 总配置 ├── urls.py # 总路由 └── wsgi.py # WSGI入口先用tree命令看一遍整体结构再开始跑代码。有的人拿到源码就急着python manage.py runserver结果报一堆错其实问题都出在依赖没装齐或者数据库没迁移。第一步永远是看requirements.txt和README这是快速理解项目的最短路径。2. 核心数据模型与数据库设计2.1 用户与权限模型设计Django自带的User模型提供了用户名、密码、邮箱等基础字段这套项目在它的基础上扩展了用户画像和权限维度。看apps/users/models.py时会发现它通过OneToOneField关联了一个Profile模型记录部门、职位、手机号等业务字段。权限这块用了Django的Group机制。技术含量在于权限粒度的设计思路系统把用户分为管理员、部门主管、普通员工三个层级。管理员拥有所有权限部门主管可以管理本部门文档能审批他人上传的文件普通员工只能上传和查看自己有权限的文档。这个模型看起来很基础但扩展性很好你可以在此基础上加入更细粒度的权限控制比如单人单文件授权、时效性授权等。2.2 文档模型设计细节文档表是系统的核心看完模型字段之后你会明白一个合格文档管理系统的设计思路。模型大概长这样class Document(models.Model): STATUS_CHOICES ( (pending, 待审核), (published, 已发布), (archived, 已归档), (rejected, 已拒绝), ) title models.CharField(max_length255, verbose_name文档标题) file models.FileField(upload_todocuments/%Y/%m/, verbose_name文件) summary models.TextField(blankTrue, verbose_name文档摘要) category models.ForeignKey(Category, on_deletemodels.PROTECT, verbose_name所属分类) tags models.ManyToManyField(Tag, blankTrue, verbose_name标签) uploader models.ForeignKey(User, on_deletemodels.SET_NULL, nullTrue, verbose_name上传者) status models.CharField(max_length20, choicesSTATUS_CHOICES, defaultpending, verbose_name状态) version models.IntegerField(default1, verbose_name版本号) download_count models.IntegerField(default0, verbose_name下载次数) created_at models.DateTimeField(auto_now_addTrue) updated_at models.DateTimeField(auto_nowTrue) class Meta: db_table document ordering [-created_at]每个字段都有讲究。upload_todocuments/%Y/%m/表示按年月份分目录存储一个月的文件放在一个文件夹里避免单个目录文件过多影响IO性能。on_deletemodels.PROTECT表示有文档关联的分类不允许删除这是一个很多新手容易忽略的细节直接CASCADE会导致分类删除后文档失去归属。status字段则把审核流程内嵌到了文档生命周期中。版本控制这里值得特别说一下。这个项目没有用单独的版本表而是在同一个文档模型里通过version字段和覆盖上传机制来管理。当用户上传一个新版本时系统将旧文件重命名后存到media/versions/目录然后再写入新文件。这个方案简单且足够应对绝大多数场景但如果你想做得更专业可以参考Git的思路每次修改存储一个快照对象记录diff信息这样就能支持任意历史版本的预览和回滚。2.3 分类与标签的设计差异分类和标签在概念上很容易混但在数据库设计里是完全不同的两种结构。分类是树形层级结构一个文档只能属于一个分类代码里用ForeignKey实现Category模型里有个parent自关联字段来支持二级甚至三级分类。标签是扁平的多对多关系一个文档可以打多个标签用ManyToManyField实现标签之间没有层级关系。为什么需要两种维度的组织方式我举个例子你就明白了一个销售合同文件在分类上属于销售部-合同这个目录在标签上可以同时打上2024年度、重要客户、待续签等多个标签。分类回答的是文件放在哪里的问题标签回答的是文件有哪些属性的问题。两者结合才能在文件数量上来之后还保持高检索效率。这个设计思路放到图书、商品、工单等任何内容管理系统里都通用。3. 关键功能模块的实现思路3.1 文件上传与存储方案文件上传是文档管理系统最核心的交互这套项目在原生Django文件上传基础上做了优化。Django原生request.FILES拿到的是内存或临时文件小文件没问题但大文件直接把内存吃满。源码里通过chunked_upload方式处理大文件前端把文件切成每块5MB逐块上传到服务端临时目录全部上传完成后由后端合并写入正式目录。对应的视图函数核心代码逻辑class FileChunkUploadView(LoginRequiredMixin, View): def post(self, request): chunk request.FILES.get(chunk) chunk_index request.POST.get(chunkIndex) upload_id request.POST.get(uploadId) # 临时目录按 upload_id 区分一次上传任务 temp_dir os.path.join(settings.MEDIA_ROOT, tmp, upload_id) os.makedirs(temp_dir, exist_okTrue) chunk_path os.path.join(temp_dir, f{chunk_index}.part) with open(chunk_path, wb) as destination: for chunk_data in chunk.chunks(): destination.write(chunk_data) return JsonResponse({status: ok}) class FileMergeView(LoginRequiredMixin, View): def post(self, request): upload_id request.POST.get(uploadId) file_name request.POST.get(fileName) temp_dir os.path.join(settings.MEDIA_ROOT, tmp, upload_id) chunk_files sorted(os.listdir(temp_dir), keylambda x: int(x.split(.)[0])) final_path os.path.join(settings.MEDIA_ROOT, documents, file_name) with open(final_path, wb) as final_file: for chunk_file in chunk_files: chunk_path os.path.join(temp_dir, chunk_file) with open(chunk_path, rb) as cf: final_file.write(cf.read()) shutil.rmtree(temp_dir) return JsonResponse({status: ok, url: /media/documents/ file_name})设计细节这里说一下。分块上传解决了大文件上传超时和服务端内存压力两个问题但对后端合并的服务器磁盘IO有一定要求。如果你的使用场景以10MB下的小文件为主直接一次上传就够了不必追求分块方案。如果你的文档经常超过500MB除了保留分块之外还建议考虑断点续传的支持。文件类型校验这道关卡一定要做。源码里通过文件扩展名白名单和后端MIME类型双重校验杜绝了只改扩展名就能伪装上传恶意文件的情况。判断文件真实类型有个很实用的技巧读取文件的头几个字节判断magic number比如PDF文件头永远是25 50 44 46JPEG是FF D8 FF这比后端收到的Content-Type靠谱得多。3.2 在线预览的实现方式文档管理系统跟网盘相比一个显著优势就是在线预览能力。这套源码的预览方案不复杂但很实用PDF文件直接通过浏览器的iframe预览图片文件用HTML的img标签展示Office文件则通过调用LibreOffice把文档转换成PDF后再显示。很多人不知道的是Debian/Ubuntu系统上LibreOffice是预装的但CentOS服务器上需要手动安装可以用yum install libreoffice-headless实现无界面转换。转换后的PDF文件缓存在media/preview/目录下第一次预览时转换以后直接读缓存。代码执行逻辑大概是调用subprocess拼接命令libreoffice --headless --convert-to pdf 源文件.docx --outdir 输出目录为了安全考虑转换后的PDF文件名用了md5(文件路径页码)作为随机名避免用户猜到存储路径。这个方案唯一的缺点是首次转换需要几秒钟用户体验上有点卡可以提前对上传的文件做异步转换用户打开预览时直接读转换好的文件。如果需要支持更精细的预览体验比如PDF按页懒加载、Office文档的在线编辑就需要引入更专业的技术方案了。PDF预览可以搭配PDF.js做前端渲染Office在线编辑则要部署Collabora Online或OnlyOffice服务这些都已经超出了这款轻量级项目的能力范围属于后续改造的方向。3.3 全文检索与文件筛选检索功能直接决定了文件多了之后系统好不好用。源码实现了两种检索方式数据库检索和文件内容检索。数据库检索很简单就是对标题、摘要、标签这几个字段做icontains模糊查询用Q对象把多个搜索条件组合起来def search_documents(request): keyword request.GET.get(q, ) category_id request.GET.get(category, ) documents Document.objects.filter( Q(title__icontainskeyword) | Q(summary__icontainskeyword) | Q(tags__name__icontainskeyword) ) if category_id: documents documents.filter(category_idcategory_id) return render(request, documents/search_result.html, {documents: documents})文件内容检索这块源码实现得比较基础基本思路是后端读取文本文件的纯文本内容然后存到一个DocumentContent表里搜索时在关联表内做模糊查询。PDF和Word这类二进制格式要先做文本抽取PDF用PyPDF2Word用python-docx。这个方案的问题在于文件量一旦超过1万份icontains的模糊查询会非常吃力。生产上建议引入Elasticsearch或Meilisearch做全文检索引擎用Django的信号机制在文档上传时自动同步索引。中等体量的项目用Meilisearch就够了安装简单中文分词效果也不错还不需要像Elasticsearch那样给JVM堆内存调优。筛选功能上源码支持按分类、标签、上传时间、文件类型进行组合筛选。这些筛选条件都是通过URL查询参数传递的比如/documents/?category3tag5doc_typepdf这种设计让筛选条件具备可分享性和可收藏性比前端全状态管理更优雅。4. 安全设计权限控制与文件防护4.1 登录认证与会话管理系统使用了Django内置的SessionMiddleware和AuthenticationMiddleware登录凭证通过Session ID存于Cookie中。默认情况下Django的Session是存在数据库里的项目则是把它转移到了Redis性能上提升明显而且可以方便地设置过期时间。有一点值得拎出来说源码里的装饰器使用非常规范。需要登录才能访问的视图统一加了login_required它会在用户未登录时自动重定向到登录页需要特定权限才能操作的地方用了permission_required。除了装饰器之外项目里还在模板层做了权限判断未授权用户不但无法访问操作接口连操作按钮都看不到。密码安全方面Django默认使用PBKDF2算法对密码进行哈希并且自动添加随机盐值。如果你的部署环境要求更高可以在settings.py里切换到Argon2PasswordHasher这是目前公认安全性最高的密码哈希算法。4.2 文件下载鉴权与防盗链这是文档管理系统最容易出问题的地方。很多人做了登录认证就以为文件安全了但实际上如果没有单独的下载接口用户可以直接把文件URL复制给别人不经登录就能下载。这套项目的做法是文件不在媒体服务器上直接暴露而是通过视图接口做权限判断后转发文件流。核心逻辑class DocumentDownloadView(LoginRequiredMixin, View): def get(self, request, doc_id): document get_object_or_404(Document, iddoc_id) # 检查用户是否有权下载此文档 if not request.user.has_perm(documents.download_document, document): raise PermissionDenied(您没有权限下载此文档) file_path document.file.path response FileResponse(open(file_path, rb)) response[Content-Disposition] fattachment; filename{document.title} # 更新下载计数 document.download_count 1 document.save(update_fields[download_count]) return response这里有一个容易被忽略的安全漏洞路径穿越。如果doc_id是伪造的或者文件名中包含../就可能让用户下载到服务器上的任意文件。源码在Document模型查询时通过get_object_or_404保证了对象必然存在并且用户权限校验发生在文件打开之前这就能挡住绝大多数非法访问。更进一步的做法是检查文件真实路径是否在MEDIA_ROOT内real_path os.path.realpath(file_path) media_root os.path.realpath(settings.MEDIA_ROOT) if not real_path.startswith(media_root): raise PermissionDenied(非法文件路径)4.3 常见安全坑点清单系统里已经处理了一些坑但实际部署后你还会遇到其他问题。我整理了一个安全清单都是文档系统上线后被攻击的高发点上传漏洞攻击者上传WebShell文件借IIS/Nginx的解析漏洞执行恶意代码。对策扩展名白名单文件头校验上传目录禁止执行脚本。XSS跨站脚本文档标题、摘要字段未做转义攻击者输入带script的内容其他用户访问时脚本被浏览器执行。Django模板默认自动转义能挡掉大部分但如果用了|safe过滤器就要格外小心。目录浏览Nginx/Apache默认开启目录浏览media目录下的文件被直接列出来。对策在Nginx配置中关闭autoindex。越权访问用户A通过修改URL中的文档ID访问用户B的文档。对策每个视图都做对象级别的权限校验而不是只做登录校验。文件大小限制没有限制上传文件大小攻击者上传超大文件把磁盘写满。对策前端限制 Nginxclient_max_body_size DjangoFILE_UPLOAD_MAX_MEMORY_SIZE三重限制。敏感信息泄露上传的文档包含身份证号、手机号等个人信息未做脱敏和加密存储。对策涉密文档单独加密存储上传前做敏感信息扫描。5. 本地运行到线上部署的完整实操5.1 环境准备与依赖安装拿到源码后第一步是创建Python虚拟环境把依赖装干净。我的环境是Python 3.10Django版本建议用3.2 LTS版本兼容性和稳定性都经过充分验证。# 创建虚拟环境 python3 -m venv venv source venv/bin/activate # 安装依赖 pip install -r requirements.txtrequirements.txt主要包含以下核心依赖Django3.2.18 django-crispy-forms2.0 Pillow10.0.0 PyPDF23.0.1 python-docx1.1.0 redis5.0.0 django-redis5.3.0在装PyPDF2和python-docx之前建议先安装系统的libmagic库否则这两个包在识别文件类型时可能出现奇怪的报错。Debian/Ubuntu用apt install libmagic-devmacOS用brew install libmagic。5.2 数据库配置与迁移默认配置用的是SQLite零配置直接跑。但如果要做正式项目建议换到MySQL或PostgreSQL。我的建议是直接用PostgreSQL对全文检索和并发写入的支持明显优于MySQL。修改config/settings.py里的数据库配置DATABASES { default: { ENGINE: django.db.backends.postgresql, NAME: doc_management, USER: doc_user, PASSWORD: 你的密码, HOST: 127.0.0.1, PORT: 5432, } }执行数据库迁移命令初始化所有数据表python manage.py makemigrations python manage.py migrate python manage.py createsuperuser首次迁移完成后确认表已经建好。5.3 关键环境变量配置settings.py里有几个必须修改的配置项。SECRET_KEY是Django用于密码加密和Session签名的密钥默认源码里带的那个只适合本地开发线上部署必须换成随机生成的字符串可以用下面命令生成python -c from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())DEBUG必须改成False否则生产环境一旦报错会把完整堆栈信息暴露给访问者包括绝对路径和源码片段这是高危信息泄露。ALLOWED_HOSTS必须明确配置服务器的域名或IP不然Django会拒绝所有请求。如果有多台服务器要负载均衡这就要配合Nginx的反向代理设置一起配置。5.4 使用Nginx Gunicorn部署本地运行确认没问题后部署到服务器上的方案我推荐Gunicorn Nginx。我用systemd管理Gunicorn进程写一个服务单元文件[Unit] DescriptionDoc Management System Afternetwork.target [Service] Userwww-data Groupwww-data WorkingDirectory/var/www/doc_management ExecStart/var/www/doc_management/venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8001 config.wsgi:application Restartalways [Install] WantedBymulti-user.targetGunicorn的workers数量按服务器CPU核心数的2倍加1来配置比如2核配置5个worker。不要在workers上贪多worker太多会导致上下文切换开销变大性能反而下降。Nginx配置要点server { listen 80; server_name your-domain.com; client_max_body_size 100M; location /static/ { alias /var/www/doc_management/static/; } location /media/ { alias /var/www/doc_management/media/; } location / { proxy_pass http://127.0.0.1:8001; 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_set_header X-Forwarded-Proto $scheme; } }client_max_body_size必须设置否则默认只允许1MB的请求体大文件上传会直接报413这个错我见过很多人踩。X-Forwarded-Proto这个头部很重要Django只有在收到这个头后才知道当前请求是通过HTTPS进来的否则生成的回跳URL都是http://开头导致回调地址错误。6. 常见问题与排查技巧实录6.1 数据库迁移失败现象执行python manage.py migrate时报django.db.migrations.exceptions.InconsistentMigrationHistory。原因最常见的是users应用里的迁移依赖了内置的auth迁移但执行顺序错乱或者之前已经手动创建过表导致迁移记录和实际数据库状态不一致。解决办法先备份数据然后重置指定应用的迁移记录python manage.py migrate users zero python manage.py migrate documents zero python manage.py migrate如果重置无效可以直接把数据库删了重建然后用python manage.py migrate --run-syncdb生成全新结构。开发环境怎么折腾都行生产环境只建议通过数据迁移和备份恢复的方式处理。6.2 上传大文件报内存溢出现象上传超过200MB的文件时进程内存飙高甚至直接OOM被系统杀掉。原因Django默认在上传文件时会把文件先读入内存只有超过FILE_UPLOAD_MAX_MEMORY_SIZE时才写入临时文件。如果这个值设置得过大大文件就会把内存撑爆。解决办法在settings.py里明确限制FILE_UPLOAD_MAX_MEMORY_SIZE 5242880 # 5MB超过则写入临时文件 FILE_UPLOAD_TEMP_DIR /tmp/django_upload_tmp/同时确保这个临时目录有足够的磁盘空间并在系统层面用cron定期清理遗留的临时文件因为用户上传到一半关闭页面临时文件往往不会被清理。6.3 文件预览显示乱码或无法打开现象PDF预览正常但Word文档转换成PDF后显示乱码。原因LibreOffice转换时找不到所需的中文字体特别是在服务器上只装了英文字体的情况下。解决办法安装中文字体包yum install -y fontconfig fc-list :langzh安装完成后刷新字体缓存fc-cache -fv如果还是一样检查系统里是否安装了wqy-zenhei、wqy-microhei或者Noto Sans CJK SC这类中文字体。转换后可以在测试环境手动执行一次LibreOffice命令看看是否有缺失字体的警告信息。6.4 下载文件名中文乱码现象下载的文件名是中文在浏览器里显示为乱码。原因Content-Disposition头部的filename参数只支持ASCII字符中文需要做RFC 5987编码from urllib.parse import quote filename quote(document.title) response[Content-Disposition] fattachment; filename*UTF-8{filename}这个坑在Django 2.x时代就有了至今很多人还在踩顺手记下来。6.5 静态文件404现象后台管理页面CSS样式丢失页面裸奔。原因DEBUGFalse后Django不再自动提供静态文件服务需要手动收集静态文件到指定目录。解决办法python manage.py collectstatic然后在Nginx里正确配置静态文件目录指向收集后的staticfiles目录。6.6 常见问题速查表整理一个排查速查表方便日常定位问题现象可能原因解决方式迁移报错迁移记录不一致重置迁移或重建数据库上传大文件内存溢出内存阈值设置不当调整FILE_UPLOAD_MAX_MEMORY_SIZE中文文件名乱码Content-Disposition编码问题使用filename*参数并URL编码验证码不显示Redis未启动或Pillow缺失检查Redis进程和Pillow依赖预览PDF空白LibreOffice未安装或字体缺失安装LibreOffice和中文语言包定时备份不生效crontab环境变量问题使用绝对路径并在crontab中设置PYTHONPATH下载PDF直接打开Content-Type配置不当显式设置application/octet-stream页面无权限提示装饰器未添加或权限码拼写错误检查视图和模板的权限判断逻辑7. 对后续扩展的一些实际建议这套系统跑通之后如果你想继续迭代我根据自己的经验给几个方向性的建议。第一是把本项目改造成前后端分离的API服务。保持现在的数据模型不动把视图层替换成Django REST Framework前端用Vue或React重新写。适合场景是系统需要同时服务Web端和移动端。第二是加入文档流程审批。现在只有简单的状态机实际业务中文件要经过发起-初审-复审-发布-归档等多级流程可以引入django-simple-workflow这类轻量级审批流框架。第三是强化敏感信息识别。对于包含身份证、银行卡、手机号的文档增加自动脱敏和加密存储能力。这个需求在许多行业都是刚需。如果你是为了面试准备项目经验建议在原项目基础上加一个你自己构思的差异化功能点比如基于jieba分词的中文搜索分词优化、基于协同过滤的相关文档推荐、基于Celery的异步文件转码队列。做项目最重要的不是功能多而是要有清晰的实现思路和对比优化过程面试官想听的是你的思考逻辑和踩坑经历。这套源码本质上是一个非常标准的中等复杂度Django项目读懂它对你理解Django MTV架构、ORM建模、文件处理、权限控制会有很大帮助。如果你在运行过程中遇到上面没提到的问题建议先去查一下Django的日志输出大多数问题都能看到具体报错堆栈定位和修复只是时间问题。本文还有配套的精品资源点击获取 Django文档管理系统源码解析：从权限控制到Nginx部署实战
简介这是一套基于Python Django框架开发的文档管理系统完整源码面向Web开发初学者与Django进阶学习者解决企业或团队中常见的文档上传、分类存储、权限管控与在线检索等核心管理需求。压缩包共64个文件包含15个Python后端逻辑文件含models、views、urls等核心模块、10个JavaScript交互脚本、12个CSS样式文件及配套HTML模板、静态资源与数据库迁移文件整体体积仅1.62MB结构清晰便于快速部署与二次开发。已有1888人下载学习项目以dinosaur-master为根目录内置用户认证、文件上传下载、搜索过滤、RESTful接口扩展等典型功能模块代码组织遵循Django标准应用划分附带requirements.txt依赖清单与完整settings配置可直接运行并作为教学案例深入理解MVC架构、QuerySet操作及中间件机制。 拿到这个项目第一反应就是亲切。Django框架写文档管理系统几乎是每个Python后端开发都会经历的一个练手项目但它又不像TodoList那样简单到没有营养文档管理涉及文件上传、权限控制、版本管理、全文检索这些真实业务里躲不掉的问题。如果你正在找工作准备项目经验或者公司内部确实缺一个轻量级的文件共享工具这套源码值得你花时间好好盘一遍。我花了一整天把整个项目完整走了一遍从解压到跑通再到把核心代码逐行读完。这篇博文会把整个系统的设计思路、核心实现、部署流程和常见坑一次性讲透你能直接照着操作也能从中提炼出自己的改造方案。1. 项目整体设计与需求拆解1.1 文档管理系统到底解决了什么问题在聊代码之前先想清楚一件事文档管理系统和普通网盘的区别在哪里网盘的核心是存储和同步而文档管理系统的核心是组织、检索、权限和协作。企业内部常见的场景是合同文件散落在各个员工电脑里方案文档通过微信传来传去最后分不清哪个是最终版新人入职找不到历史项目资料。这套系统要解决的就是这些问题把散落的文件收拢到一个统一的平台里通过分类、标签、权限和版本控制让文件变得可管理、可追溯。明白这个定位你就能理解源码里为什么会有那些看起来多余的设计。比如版本管理模块普通文件上传系统根本不需要但文档管理系统必须有因为合同和方案终稿经常要回滚。再比如操作日志这不是为了监控员工而是为了在文件误删或越权操作时能快速定位责任人。1.2 为什么选Django而不是Flask或FastAPI项目选择了Django这个选型很务实。我见过不少人用Flask搭类似系统做到用户认证和文件管理的时候需要自己拼第三方库经常出现兼容性问题。Django的优势在于全家桶式的一体化设计自带的Admin后台可以快速管理用户和文档自带ORM让数据库操作变得简单自带认证系统直接解决了登录权限问题自带模板引擎方便渲染管理页面。这套源码的目标不是炫技而是用最少的时间成本交付一个能用的系统Django正好是这个场景下的最优解。如果你后续要把它改造成API服务对接前端Django REST Framework也有成熟的生态扩展起来不费劲。Flask适合微服务和高度定制化的场景但系统性功能多的时候Django的开发效率优势非常明显。1.3 源码包目录结构说明解压zip文件后项目目录大概是这样的结构doc_management/ # 项目根目录 ├── manage.py # Django管理入口 ├── requirements.txt # 依赖包清单 ├── docs/ # 项目说明文档 ├── static/ # 静态资源目录 ├── media/ # 上传文件存放目录运行时生成 ├── apps/ │ ├── users/ # 用户模块 │ ├── documents/ # 文档核心模块 │ ├── categories/ # 分类模块 │ └── operations/ # 操作日志模块 └── config/ # 项目配置目录 ├── settings.py # 总配置 ├── urls.py # 总路由 └── wsgi.py # WSGI入口先用tree命令看一遍整体结构再开始跑代码。有的人拿到源码就急着python manage.py runserver结果报一堆错其实问题都出在依赖没装齐或者数据库没迁移。第一步永远是看requirements.txt和README这是快速理解项目的最短路径。2. 核心数据模型与数据库设计2.1 用户与权限模型设计Django自带的User模型提供了用户名、密码、邮箱等基础字段这套项目在它的基础上扩展了用户画像和权限维度。看apps/users/models.py时会发现它通过OneToOneField关联了一个Profile模型记录部门、职位、手机号等业务字段。权限这块用了Django的Group机制。技术含量在于权限粒度的设计思路系统把用户分为管理员、部门主管、普通员工三个层级。管理员拥有所有权限部门主管可以管理本部门文档能审批他人上传的文件普通员工只能上传和查看自己有权限的文档。这个模型看起来很基础但扩展性很好你可以在此基础上加入更细粒度的权限控制比如单人单文件授权、时效性授权等。2.2 文档模型设计细节文档表是系统的核心看完模型字段之后你会明白一个合格文档管理系统的设计思路。模型大概长这样class Document(models.Model): STATUS_CHOICES ( (pending, 待审核), (published, 已发布), (archived, 已归档), (rejected, 已拒绝), ) title models.CharField(max_length255, verbose_name文档标题) file models.FileField(upload_todocuments/%Y/%m/, verbose_name文件) summary models.TextField(blankTrue, verbose_name文档摘要) category models.ForeignKey(Category, on_deletemodels.PROTECT, verbose_name所属分类) tags models.ManyToManyField(Tag, blankTrue, verbose_name标签) uploader models.ForeignKey(User, on_deletemodels.SET_NULL, nullTrue, verbose_name上传者) status models.CharField(max_length20, choicesSTATUS_CHOICES, defaultpending, verbose_name状态) version models.IntegerField(default1, verbose_name版本号) download_count models.IntegerField(default0, verbose_name下载次数) created_at models.DateTimeField(auto_now_addTrue) updated_at models.DateTimeField(auto_nowTrue) class Meta: db_table document ordering [-created_at]每个字段都有讲究。upload_todocuments/%Y/%m/表示按年月份分目录存储一个月的文件放在一个文件夹里避免单个目录文件过多影响IO性能。on_deletemodels.PROTECT表示有文档关联的分类不允许删除这是一个很多新手容易忽略的细节直接CASCADE会导致分类删除后文档失去归属。status字段则把审核流程内嵌到了文档生命周期中。版本控制这里值得特别说一下。这个项目没有用单独的版本表而是在同一个文档模型里通过version字段和覆盖上传机制来管理。当用户上传一个新版本时系统将旧文件重命名后存到media/versions/目录然后再写入新文件。这个方案简单且足够应对绝大多数场景但如果你想做得更专业可以参考Git的思路每次修改存储一个快照对象记录diff信息这样就能支持任意历史版本的预览和回滚。2.3 分类与标签的设计差异分类和标签在概念上很容易混但在数据库设计里是完全不同的两种结构。分类是树形层级结构一个文档只能属于一个分类代码里用ForeignKey实现Category模型里有个parent自关联字段来支持二级甚至三级分类。标签是扁平的多对多关系一个文档可以打多个标签用ManyToManyField实现标签之间没有层级关系。为什么需要两种维度的组织方式我举个例子你就明白了一个销售合同文件在分类上属于销售部-合同这个目录在标签上可以同时打上2024年度、重要客户、待续签等多个标签。分类回答的是文件放在哪里的问题标签回答的是文件有哪些属性的问题。两者结合才能在文件数量上来之后还保持高检索效率。这个设计思路放到图书、商品、工单等任何内容管理系统里都通用。3. 关键功能模块的实现思路3.1 文件上传与存储方案文件上传是文档管理系统最核心的交互这套项目在原生Django文件上传基础上做了优化。Django原生request.FILES拿到的是内存或临时文件小文件没问题但大文件直接把内存吃满。源码里通过chunked_upload方式处理大文件前端把文件切成每块5MB逐块上传到服务端临时目录全部上传完成后由后端合并写入正式目录。对应的视图函数核心代码逻辑class FileChunkUploadView(LoginRequiredMixin, View): def post(self, request): chunk request.FILES.get(chunk) chunk_index request.POST.get(chunkIndex) upload_id request.POST.get(uploadId) # 临时目录按 upload_id 区分一次上传任务 temp_dir os.path.join(settings.MEDIA_ROOT, tmp, upload_id) os.makedirs(temp_dir, exist_okTrue) chunk_path os.path.join(temp_dir, f{chunk_index}.part) with open(chunk_path, wb) as destination: for chunk_data in chunk.chunks(): destination.write(chunk_data) return JsonResponse({status: ok}) class FileMergeView(LoginRequiredMixin, View): def post(self, request): upload_id request.POST.get(uploadId) file_name request.POST.get(fileName) temp_dir os.path.join(settings.MEDIA_ROOT, tmp, upload_id) chunk_files sorted(os.listdir(temp_dir), keylambda x: int(x.split(.)[0])) final_path os.path.join(settings.MEDIA_ROOT, documents, file_name) with open(final_path, wb) as final_file: for chunk_file in chunk_files: chunk_path os.path.join(temp_dir, chunk_file) with open(chunk_path, rb) as cf: final_file.write(cf.read()) shutil.rmtree(temp_dir) return JsonResponse({status: ok, url: /media/documents/ file_name})设计细节这里说一下。分块上传解决了大文件上传超时和服务端内存压力两个问题但对后端合并的服务器磁盘IO有一定要求。如果你的使用场景以10MB下的小文件为主直接一次上传就够了不必追求分块方案。如果你的文档经常超过500MB除了保留分块之外还建议考虑断点续传的支持。文件类型校验这道关卡一定要做。源码里通过文件扩展名白名单和后端MIME类型双重校验杜绝了只改扩展名就能伪装上传恶意文件的情况。判断文件真实类型有个很实用的技巧读取文件的头几个字节判断magic number比如PDF文件头永远是25 50 44 46JPEG是FF D8 FF这比后端收到的Content-Type靠谱得多。3.2 在线预览的实现方式文档管理系统跟网盘相比一个显著优势就是在线预览能力。这套源码的预览方案不复杂但很实用PDF文件直接通过浏览器的iframe预览图片文件用HTML的img标签展示Office文件则通过调用LibreOffice把文档转换成PDF后再显示。很多人不知道的是Debian/Ubuntu系统上LibreOffice是预装的但CentOS服务器上需要手动安装可以用yum install libreoffice-headless实现无界面转换。转换后的PDF文件缓存在media/preview/目录下第一次预览时转换以后直接读缓存。代码执行逻辑大概是调用subprocess拼接命令libreoffice --headless --convert-to pdf 源文件.docx --outdir 输出目录为了安全考虑转换后的PDF文件名用了md5(文件路径页码)作为随机名避免用户猜到存储路径。这个方案唯一的缺点是首次转换需要几秒钟用户体验上有点卡可以提前对上传的文件做异步转换用户打开预览时直接读转换好的文件。如果需要支持更精细的预览体验比如PDF按页懒加载、Office文档的在线编辑就需要引入更专业的技术方案了。PDF预览可以搭配PDF.js做前端渲染Office在线编辑则要部署Collabora Online或OnlyOffice服务这些都已经超出了这款轻量级项目的能力范围属于后续改造的方向。3.3 全文检索与文件筛选检索功能直接决定了文件多了之后系统好不好用。源码实现了两种检索方式数据库检索和文件内容检索。数据库检索很简单就是对标题、摘要、标签这几个字段做icontains模糊查询用Q对象把多个搜索条件组合起来def search_documents(request): keyword request.GET.get(q, ) category_id request.GET.get(category, ) documents Document.objects.filter( Q(title__icontainskeyword) | Q(summary__icontainskeyword) | Q(tags__name__icontainskeyword) ) if category_id: documents documents.filter(category_idcategory_id) return render(request, documents/search_result.html, {documents: documents})文件内容检索这块源码实现得比较基础基本思路是后端读取文本文件的纯文本内容然后存到一个DocumentContent表里搜索时在关联表内做模糊查询。PDF和Word这类二进制格式要先做文本抽取PDF用PyPDF2Word用python-docx。这个方案的问题在于文件量一旦超过1万份icontains的模糊查询会非常吃力。生产上建议引入Elasticsearch或Meilisearch做全文检索引擎用Django的信号机制在文档上传时自动同步索引。中等体量的项目用Meilisearch就够了安装简单中文分词效果也不错还不需要像Elasticsearch那样给JVM堆内存调优。筛选功能上源码支持按分类、标签、上传时间、文件类型进行组合筛选。这些筛选条件都是通过URL查询参数传递的比如/documents/?category3tag5doc_typepdf这种设计让筛选条件具备可分享性和可收藏性比前端全状态管理更优雅。4. 安全设计权限控制与文件防护4.1 登录认证与会话管理系统使用了Django内置的SessionMiddleware和AuthenticationMiddleware登录凭证通过Session ID存于Cookie中。默认情况下Django的Session是存在数据库里的项目则是把它转移到了Redis性能上提升明显而且可以方便地设置过期时间。有一点值得拎出来说源码里的装饰器使用非常规范。需要登录才能访问的视图统一加了login_required它会在用户未登录时自动重定向到登录页需要特定权限才能操作的地方用了permission_required。除了装饰器之外项目里还在模板层做了权限判断未授权用户不但无法访问操作接口连操作按钮都看不到。密码安全方面Django默认使用PBKDF2算法对密码进行哈希并且自动添加随机盐值。如果你的部署环境要求更高可以在settings.py里切换到Argon2PasswordHasher这是目前公认安全性最高的密码哈希算法。4.2 文件下载鉴权与防盗链这是文档管理系统最容易出问题的地方。很多人做了登录认证就以为文件安全了但实际上如果没有单独的下载接口用户可以直接把文件URL复制给别人不经登录就能下载。这套项目的做法是文件不在媒体服务器上直接暴露而是通过视图接口做权限判断后转发文件流。核心逻辑class DocumentDownloadView(LoginRequiredMixin, View): def get(self, request, doc_id): document get_object_or_404(Document, iddoc_id) # 检查用户是否有权下载此文档 if not request.user.has_perm(documents.download_document, document): raise PermissionDenied(您没有权限下载此文档) file_path document.file.path response FileResponse(open(file_path, rb)) response[Content-Disposition] fattachment; filename{document.title} # 更新下载计数 document.download_count 1 document.save(update_fields[download_count]) return response这里有一个容易被忽略的安全漏洞路径穿越。如果doc_id是伪造的或者文件名中包含../就可能让用户下载到服务器上的任意文件。源码在Document模型查询时通过get_object_or_404保证了对象必然存在并且用户权限校验发生在文件打开之前这就能挡住绝大多数非法访问。更进一步的做法是检查文件真实路径是否在MEDIA_ROOT内real_path os.path.realpath(file_path) media_root os.path.realpath(settings.MEDIA_ROOT) if not real_path.startswith(media_root): raise PermissionDenied(非法文件路径)4.3 常见安全坑点清单系统里已经处理了一些坑但实际部署后你还会遇到其他问题。我整理了一个安全清单都是文档系统上线后被攻击的高发点上传漏洞攻击者上传WebShell文件借IIS/Nginx的解析漏洞执行恶意代码。对策扩展名白名单文件头校验上传目录禁止执行脚本。XSS跨站脚本文档标题、摘要字段未做转义攻击者输入带script的内容其他用户访问时脚本被浏览器执行。Django模板默认自动转义能挡掉大部分但如果用了|safe过滤器就要格外小心。目录浏览Nginx/Apache默认开启目录浏览media目录下的文件被直接列出来。对策在Nginx配置中关闭autoindex。越权访问用户A通过修改URL中的文档ID访问用户B的文档。对策每个视图都做对象级别的权限校验而不是只做登录校验。文件大小限制没有限制上传文件大小攻击者上传超大文件把磁盘写满。对策前端限制 Nginxclient_max_body_size DjangoFILE_UPLOAD_MAX_MEMORY_SIZE三重限制。敏感信息泄露上传的文档包含身份证号、手机号等个人信息未做脱敏和加密存储。对策涉密文档单独加密存储上传前做敏感信息扫描。5. 本地运行到线上部署的完整实操5.1 环境准备与依赖安装拿到源码后第一步是创建Python虚拟环境把依赖装干净。我的环境是Python 3.10Django版本建议用3.2 LTS版本兼容性和稳定性都经过充分验证。# 创建虚拟环境 python3 -m venv venv source venv/bin/activate # 安装依赖 pip install -r requirements.txtrequirements.txt主要包含以下核心依赖Django3.2.18 django-crispy-forms2.0 Pillow10.0.0 PyPDF23.0.1 python-docx1.1.0 redis5.0.0 django-redis5.3.0在装PyPDF2和python-docx之前建议先安装系统的libmagic库否则这两个包在识别文件类型时可能出现奇怪的报错。Debian/Ubuntu用apt install libmagic-devmacOS用brew install libmagic。5.2 数据库配置与迁移默认配置用的是SQLite零配置直接跑。但如果要做正式项目建议换到MySQL或PostgreSQL。我的建议是直接用PostgreSQL对全文检索和并发写入的支持明显优于MySQL。修改config/settings.py里的数据库配置DATABASES { default: { ENGINE: django.db.backends.postgresql, NAME: doc_management, USER: doc_user, PASSWORD: 你的密码, HOST: 127.0.0.1, PORT: 5432, } }执行数据库迁移命令初始化所有数据表python manage.py makemigrations python manage.py migrate python manage.py createsuperuser首次迁移完成后确认表已经建好。5.3 关键环境变量配置settings.py里有几个必须修改的配置项。SECRET_KEY是Django用于密码加密和Session签名的密钥默认源码里带的那个只适合本地开发线上部署必须换成随机生成的字符串可以用下面命令生成python -c from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())DEBUG必须改成False否则生产环境一旦报错会把完整堆栈信息暴露给访问者包括绝对路径和源码片段这是高危信息泄露。ALLOWED_HOSTS必须明确配置服务器的域名或IP不然Django会拒绝所有请求。如果有多台服务器要负载均衡这就要配合Nginx的反向代理设置一起配置。5.4 使用Nginx Gunicorn部署本地运行确认没问题后部署到服务器上的方案我推荐Gunicorn Nginx。我用systemd管理Gunicorn进程写一个服务单元文件[Unit] DescriptionDoc Management System Afternetwork.target [Service] Userwww-data Groupwww-data WorkingDirectory/var/www/doc_management ExecStart/var/www/doc_management/venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8001 config.wsgi:application Restartalways [Install] WantedBymulti-user.targetGunicorn的workers数量按服务器CPU核心数的2倍加1来配置比如2核配置5个worker。不要在workers上贪多worker太多会导致上下文切换开销变大性能反而下降。Nginx配置要点server { listen 80; server_name your-domain.com; client_max_body_size 100M; location /static/ { alias /var/www/doc_management/static/; } location /media/ { alias /var/www/doc_management/media/; } location / { proxy_pass http://127.0.0.1:8001; 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_set_header X-Forwarded-Proto $scheme; } }client_max_body_size必须设置否则默认只允许1MB的请求体大文件上传会直接报413这个错我见过很多人踩。X-Forwarded-Proto这个头部很重要Django只有在收到这个头后才知道当前请求是通过HTTPS进来的否则生成的回跳URL都是http://开头导致回调地址错误。6. 常见问题与排查技巧实录6.1 数据库迁移失败现象执行python manage.py migrate时报django.db.migrations.exceptions.InconsistentMigrationHistory。原因最常见的是users应用里的迁移依赖了内置的auth迁移但执行顺序错乱或者之前已经手动创建过表导致迁移记录和实际数据库状态不一致。解决办法先备份数据然后重置指定应用的迁移记录python manage.py migrate users zero python manage.py migrate documents zero python manage.py migrate如果重置无效可以直接把数据库删了重建然后用python manage.py migrate --run-syncdb生成全新结构。开发环境怎么折腾都行生产环境只建议通过数据迁移和备份恢复的方式处理。6.2 上传大文件报内存溢出现象上传超过200MB的文件时进程内存飙高甚至直接OOM被系统杀掉。原因Django默认在上传文件时会把文件先读入内存只有超过FILE_UPLOAD_MAX_MEMORY_SIZE时才写入临时文件。如果这个值设置得过大大文件就会把内存撑爆。解决办法在settings.py里明确限制FILE_UPLOAD_MAX_MEMORY_SIZE 5242880 # 5MB超过则写入临时文件 FILE_UPLOAD_TEMP_DIR /tmp/django_upload_tmp/同时确保这个临时目录有足够的磁盘空间并在系统层面用cron定期清理遗留的临时文件因为用户上传到一半关闭页面临时文件往往不会被清理。6.3 文件预览显示乱码或无法打开现象PDF预览正常但Word文档转换成PDF后显示乱码。原因LibreOffice转换时找不到所需的中文字体特别是在服务器上只装了英文字体的情况下。解决办法安装中文字体包yum install -y fontconfig fc-list :langzh安装完成后刷新字体缓存fc-cache -fv如果还是一样检查系统里是否安装了wqy-zenhei、wqy-microhei或者Noto Sans CJK SC这类中文字体。转换后可以在测试环境手动执行一次LibreOffice命令看看是否有缺失字体的警告信息。6.4 下载文件名中文乱码现象下载的文件名是中文在浏览器里显示为乱码。原因Content-Disposition头部的filename参数只支持ASCII字符中文需要做RFC 5987编码from urllib.parse import quote filename quote(document.title) response[Content-Disposition] fattachment; filename*UTF-8{filename}这个坑在Django 2.x时代就有了至今很多人还在踩顺手记下来。6.5 静态文件404现象后台管理页面CSS样式丢失页面裸奔。原因DEBUGFalse后Django不再自动提供静态文件服务需要手动收集静态文件到指定目录。解决办法python manage.py collectstatic然后在Nginx里正确配置静态文件目录指向收集后的staticfiles目录。6.6 常见问题速查表整理一个排查速查表方便日常定位问题现象可能原因解决方式迁移报错迁移记录不一致重置迁移或重建数据库上传大文件内存溢出内存阈值设置不当调整FILE_UPLOAD_MAX_MEMORY_SIZE中文文件名乱码Content-Disposition编码问题使用filename*参数并URL编码验证码不显示Redis未启动或Pillow缺失检查Redis进程和Pillow依赖预览PDF空白LibreOffice未安装或字体缺失安装LibreOffice和中文语言包定时备份不生效crontab环境变量问题使用绝对路径并在crontab中设置PYTHONPATH下载PDF直接打开Content-Type配置不当显式设置application/octet-stream页面无权限提示装饰器未添加或权限码拼写错误检查视图和模板的权限判断逻辑7. 对后续扩展的一些实际建议这套系统跑通之后如果你想继续迭代我根据自己的经验给几个方向性的建议。第一是把本项目改造成前后端分离的API服务。保持现在的数据模型不动把视图层替换成Django REST Framework前端用Vue或React重新写。适合场景是系统需要同时服务Web端和移动端。第二是加入文档流程审批。现在只有简单的状态机实际业务中文件要经过发起-初审-复审-发布-归档等多级流程可以引入django-simple-workflow这类轻量级审批流框架。第三是强化敏感信息识别。对于包含身份证、银行卡、手机号的文档增加自动脱敏和加密存储能力。这个需求在许多行业都是刚需。如果你是为了面试准备项目经验建议在原项目基础上加一个你自己构思的差异化功能点比如基于jieba分词的中文搜索分词优化、基于协同过滤的相关文档推荐、基于Celery的异步文件转码队列。做项目最重要的不是功能多而是要有清晰的实现思路和对比优化过程面试官想听的是你的思考逻辑和踩坑经历。这套源码本质上是一个非常标准的中等复杂度Django项目读懂它对你理解Django MTV架构、ORM建模、文件处理、权限控制会有很大帮助。如果你在运行过程中遇到上面没提到的问题建议先去查一下Django的日志输出大多数问题都能看到具体报错堆栈定位和修复只是时间问题。本文还有配套的精品资源点击获取