diff --git a/apps/core/admin.py b/apps/core/admin.py index ed3803b..f8cf366 100644 --- a/apps/core/admin.py +++ b/apps/core/admin.py @@ -1,12 +1,17 @@ +from pathlib import Path from django.contrib import admin from django.db import models +from django.http import JsonResponse from django.shortcuts import redirect, render from django.urls import path, reverse from django.utils.html import format_html from django.contrib import messages +from django.views.decorators.http import require_POST +from django.core.exceptions import PermissionDenied from ckeditor_uploader.widgets import CKEditorUploadingWidget -from .models import SiteSettings, Banner, DeployLog +from .models import SiteSettings, Banner, DeployLog, MediaFile from .deploy import start_deploy +from . import file_manager as fm @admin.register(SiteSettings) @@ -145,3 +150,130 @@ class DeployLogAdmin(admin.ModelAdmin): extra_context['deploy_url'] = reverse('admin:core_deploy_trigger') extra_context['has_running'] = DeployLog.objects.filter(status='running').exists() return super().changelist_view(request, extra_context) + + +# --------------------------------------------------------------- +# 媒体文件管理:通过一个 managed=False 的虚拟模型挂到左侧侧栏 +# --------------------------------------------------------------- + +@admin.register(MediaFile) +class MediaFileAdmin(admin.ModelAdmin): + """代理 Admin:点击侧栏"媒体文件"时跳转到自定义文件管理器页面。 + + 该模型 managed=False,不访问数据库,默认权限被禁用。 + """ + + def has_module_permission(self, request): + # 只有超级管理员或明确有 core.manage_files 权限才可见 + return request.user.is_superuser or request.user.has_perm('core.manage_files') + + def has_view_permission(self, request, obj=None): + return self.has_module_permission(request) + + def has_add_permission(self, request): + return False + + def has_change_permission(self, request, obj=None): + return False + + def has_delete_permission(self, request, obj=None): + return False + + def changelist_view(self, request, extra_context=None): + # 访问 admin/core/mediafile/ 时跳转到自定义页面 + return redirect(reverse('admin:core_mediafile_changelist')) + + +# --------------------------------------------------------------- +# 媒体文件管理器(无模型,自定义 URL + 视图) +# --------------------------------------------------------------- + +class MediaFileManagerAdmin: + """伪 Admin 入口:只用来注入 URL 和渲染页面。 + + 我们直接通过 admin_site 注册 custom_urls,而不是注册一个 ModelAdmin, + 因为这个功能不需要数据库模型。 + """ + model_name = 'mediafile' + app_label = 'core' + + @classmethod + def get_custom_urls(cls, admin_site): + view = admin_site.admin_view(cls.changelist_view) + delete_view = admin_site.admin_view(require_POST(cls.delete_view)) + preview_view = admin_site.admin_view(cls.preview_view) + + return [ + path('mediafiles/', view, name='core_mediafile_changelist'), + path('mediafiles/delete/', delete_view, name='core_mediafile_delete'), + path('mediafiles/preview/', preview_view, name='core_mediafile_preview'), + ] + + @staticmethod + def changelist_view(request): + # 权限校验:只有超级管理员或有 manage_files 权限者可访问 + if not (request.user.is_superuser or request.user.has_perm('core.manage_files')): + raise PermissionDenied + sub_path = request.GET.get('path', '').strip() + data = fm.list_media_files(sub_path) + usage = fm.get_storage_usage() + context = { + **admin.site.each_context(request), + 'title': '媒体文件管理', + 'data': data, + 'usage': usage, + 'list_url': reverse('admin:core_mediafile_changelist'), + 'delete_url': reverse('admin:core_mediafile_delete'), + 'preview_url': reverse('admin:core_mediafile_preview'), + 'opts': type('FakeOpts', (), { + 'verbose_name_plural': '媒体文件', + 'app_label': 'core', + 'model_name': 'mediafile', + })(), + } + return render(request, 'admin/core/mediafile/change_list.html', context) + + @staticmethod + def delete_view(request): + if not (request.user.is_superuser or request.user.has_perm('core.manage_files')): + if request.headers.get('X-Requested-With') == 'XMLHttpRequest': + return JsonResponse({'ok': False, 'msg': '无权删除'}, status=403) + raise PermissionDenied + rel_path = request.POST.get('path', '').strip() + ok, msg = fm.delete_media_file(rel_path) + if request.headers.get('X-Requested-With') == 'XMLHttpRequest': + return JsonResponse({'ok': ok, 'msg': msg}) + if ok: + messages.success(request, msg) + else: + messages.error(request, msg) + # 回到原目录 + parent = str(Path(rel_path).parent) if rel_path else '' + if parent == '.': + parent = '' + return redirect(f"{reverse('admin:core_mediafile_changelist')}?path={parent}") + + @staticmethod + def preview_view(request): + rel_path = request.GET.get('path', '').strip() + # 返回 JSON:文件 URL、路径、大小 + data = fm.list_media_files(rel_path and str(Path(rel_path).parent) or '') + target = next((f for f in data['files'] if f['path'] == rel_path), None) + if not target: + return JsonResponse({'ok': False, 'msg': '文件不存在'}, status=404) + return JsonResponse({'ok': True, 'file': target}) + + +# 注入 MediaFile 的 URL 到 admin.site +# 做法:覆写 AdminSite 的 get_urls 时追加 +_original_admin_get_urls = admin.AdminSite.get_urls + + +def _patched_admin_get_urls(self): + urls = _original_admin_get_urls(self) + urls.extend(MediaFileManagerAdmin.get_custom_urls(self)) + return urls + + +admin.AdminSite.get_urls = _patched_admin_get_urls + diff --git a/apps/core/apps.py b/apps/core/apps.py index 78e84f0..f6cad18 100644 --- a/apps/core/apps.py +++ b/apps/core/apps.py @@ -5,3 +5,8 @@ class CoreConfig(AppConfig): default_auto_field = 'django.db.models.BigAutoField' name = 'apps.core' verbose_name = '内容管理' + + def ready(self): + # 注册所有 ImageField 文件的自动清理信号 + from .signals import _register_cleanup_signals # noqa: F401 + _register_cleanup_signals() diff --git a/apps/core/file_manager.py b/apps/core/file_manager.py new file mode 100644 index 0000000..d0b9595 --- /dev/null +++ b/apps/core/file_manager.py @@ -0,0 +1,159 @@ +"""媒体文件管理:浏览和删除上传到 MEDIA_ROOT 的文件。 + +包含: +- list_media_files():按目录结构列出所有文件/子目录 +- delete_media_file(rel_path):删除指定相对路径的文件 +- get_storage_usage():统计目录占用大小 +""" +import os +from pathlib import Path +from django.conf import settings + +MEDIA_ROOT = settings.MEDIA_ROOT + + +def _rel(path: Path) -> str: + """把绝对路径转换为相对于 MEDIA_ROOT 的 Unix 风格路径。""" + return path.relative_to(MEDIA_ROOT).as_posix() + + +def _human_size(num_bytes: int) -> str: + """把字节数格式化成人类可读字符串。""" + for unit in ('B', 'KB', 'MB', 'GB'): + if num_bytes < 1024: + return f'{num_bytes:.1f} {unit}' if unit != 'B' else f'{int(num_bytes)} {unit}' + num_bytes /= 1024 + return f'{num_bytes:.1f} TB' + + +def list_media_files(sub_path: str = ''): + """列出 MEDIA_ROOT/sub_path 下的文件和子目录。 + + 返回结构: + { + 'current_path': 'uploads/', + 'parent_path': None or 'uploads/', + 'subdirs': [{'name': '2026', 'path': 'uploads/2026', 'count': 12, 'size': '1.2 MB'}], + 'files': [{'name': 'a.jpg', 'path': 'uploads/a.jpg', 'size': '200 KB', + 'url': '/media/uploads/a.jpg', 'modified': datetime}] + } + """ + root = MEDIA_ROOT / Path(sub_path) if sub_path else MEDIA_ROOT + # 防止路径穿越 + try: + root.resolve().relative_to(MEDIA_ROOT.resolve()) + except ValueError: + root = MEDIA_ROOT + + if not root.exists(): + root.mkdir(parents=True, exist_ok=True) + + current_rel = _rel(root) if root != MEDIA_ROOT else '' + parent_rel = str(Path(current_rel).parent) if current_rel else None + if parent_rel == '.': + parent_rel = '' + + subdirs = [] + files = [] + try: + entries = sorted(root.iterdir(), key=lambda p: (p.is_file(), p.name.lower())) + except PermissionError: + entries = [] + + for entry in entries: + try: + if entry.is_dir(): + file_count = sum(1 for f in entry.rglob('*') if f.is_file()) + total_bytes = sum(f.stat().st_size for f in entry.rglob('*') if f.is_file()) + subdirs.append({ + 'name': entry.name, + 'path': _rel(entry), + 'file_count': file_count, + 'size': _human_size(total_bytes), + }) + elif entry.is_file(): + stat = entry.stat() + rel = _rel(entry) + files.append({ + 'name': entry.name, + 'path': rel, + 'size': _human_size(stat.st_size), + 'size_bytes': stat.st_size, + 'url': f'{settings.MEDIA_URL}{rel}', + 'modified': stat.st_mtime, + 'is_image': entry.suffix.lower() in {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp', '.svg'}, + }) + except (PermissionError, OSError): + continue + + # 构建面包屑:每一级的 name 和完整路径 + breadcrumb = [] + if current_rel: + parts = Path(current_rel).parts + built = [] + for p in parts: + built.append(p) + breadcrumb.append({'name': p, 'path': '/'.join(built)}) + + return { + 'current_path': current_rel, + 'parent_path': parent_rel, + 'breadcrumb': breadcrumb, + 'subdirs': subdirs, + 'files': files, + 'total_size': _human_size(sum(f['size_bytes'] for f in files)), + } + + +def delete_media_file(rel_path: str) -> tuple[bool, str]: + """删除指定相对路径的文件。仅允许删除 MEDIA_ROOT 内的文件。 + + 返回 (是否成功, 提示信息)。 + """ + if not rel_path: + return False, '路径不能为空' + + target = (MEDIA_ROOT / Path(rel_path)).resolve() + try: + target.relative_to(MEDIA_ROOT.resolve()) + except ValueError: + return False, '非法路径:只能删除 media 目录内的文件' + + if not target.exists(): + return False, '文件不存在' + if not target.is_file(): + return False, '目标不是文件' + + try: + target.unlink() + except PermissionError: + return False, '没有删除权限,请联系服务器管理员检查 www-data 对 media 目录的权限' + except OSError as e: + return False, f'删除失败:{e}' + + return True, f'已删除:{rel_path}' + + +def get_storage_usage() -> dict: + """返回 media 根目录各子目录的占用概览。""" + summary = [] + total_bytes = 0 + if not MEDIA_ROOT.exists(): + return {'top_dirs': [], 'total': '0 B'} + for entry in sorted(MEDIA_ROOT.iterdir(), key=lambda p: p.name.lower()): + if entry.is_dir(): + size = sum(f.stat().st_size for f in entry.rglob('*') if f.is_file()) + count = sum(1 for f in entry.rglob('*') if f.is_file()) + total_bytes += size + summary.append({ + 'name': entry.name + '/', + 'size': _human_size(size), + 'count': count, + }) + elif entry.is_file(): + size = entry.stat().st_size + total_bytes += size + return { + 'top_dirs': summary, + 'total': _human_size(total_bytes), + } diff --git a/apps/core/models.py b/apps/core/models.py index b6e69bb..800ff9a 100644 --- a/apps/core/models.py +++ b/apps/core/models.py @@ -1,5 +1,25 @@ import uuid from django.db import models +from django.utils.translation import gettext_lazy as _ + + +class MediaFile(models.Model): + """代理模型:仅用于在后台侧栏显示"媒体文件管理"入口。 + + 真实文件系统管理逻辑在 core/file_manager.py 中。 + 此模型不会迁移数据库(managed = False)。 + """ + class Meta: + managed = False + verbose_name = '媒体文件' + verbose_name_plural = '媒体文件管理' + default_permissions = [] # 禁用默认的 add/change/delete/view + permissions = [ + ('manage_files', '可管理媒体文件'), + ] + + # 任意加一个字段,因为 Meta.managed=False,不会真的建表 + id = models.BigAutoField(primary_key=True) class SiteSettings(models.Model): diff --git a/apps/core/signals.py b/apps/core/signals.py new file mode 100644 index 0000000..1ef4130 --- /dev/null +++ b/apps/core/signals.py @@ -0,0 +1,89 @@ +"""自动清理 Django 模型 ImageField/FileField 文件的信号。 + +当: +1. 模型实例被删除时(post_delete) +2. 字段值被更改、旧文件不再被引用时(post_save 对比 pre_save 缓存的旧值) + +尝试删除磁盘上的旧文件(忽略失败、忽略不存在)。 +""" +import os +from django.db import models +from django.db.models.signals import post_delete, pre_save, post_save +from django.dispatch import receiver + + +_MODEL_CACHE = {} # 防止多次注册同一模型 + + +def _get_all_file_fields(model_cls): + """返回模型中所有的 FileField/ImageField 字段名。""" + return [ + f.attname for f in model_cls._meta.get_fields() + if isinstance(f, models.FileField) and f.attname + ] + + +def _safe_delete_file(file_field_instance): + """安全地删除 FileField 引用的磁盘文件,忽略失败。""" + try: + if file_field_instance and file_field_instance.name: + path = file_field_instance.path + if path and os.path.isfile(path): + os.remove(path) + except (OSError, ValueError): + pass + + +def _register_cleanup_signals(): + """注册所有已注册的 Django 应用中带 FileField/ImageField 的模型的清理信号。 + + 幂等:同一模型多次调用只会注册一次。 + """ + from django.apps import apps as django_apps + + for model in django_apps.get_models(): + if model in _MODEL_CACHE: + continue + file_fields = _get_all_file_fields(model) + if not file_fields: + _MODEL_CACHE[model] = None + continue + _MODEL_CACHE[model] = file_fields + + # 1. post_delete: 实例删除后删除所有文件 + def make_post_delete_handler(ffields): + @receiver(post_delete, sender=model, weak=False, dispatch_uid=f'cleanup_postdel_{model._meta.label}') + def handler(sender, instance, **kwargs): + for field_name in ffields: + _safe_delete_file(getattr(instance, field_name, None)) + return handler + + make_post_delete_handler(file_fields)() + + # 2. pre_save: 缓存旧值 + @receiver(pre_save, sender=model, weak=False, dispatch_uid=f'cleanup_presave_{model._meta.label}') + def presave_cache(sender, instance, **kwargs): + # 不是新建的情况下,缓存数据库中该记录的旧 FileField 值 + if not instance.pk: + instance.__old_filefield_values = None + return + try: + old = sender.objects.get(pk=instance.pk) + instance.__old_filefield_values = { + fn: getattr(old, fn, None) for fn in file_fields + } + except sender.DoesNotExist: + instance.__old_filefield_values = None + + # 3. post_save: 对比新旧值并删除不再引用的旧文件 + @receiver(post_save, sender=model, weak=False, dispatch_uid=f'cleanup_postsave_{model._meta.label}') + def postsave_cleanup(sender, instance, **kwargs): + old_vals = getattr(instance, '__old_filefield_values', None) + if not old_vals: + return + for field_name in file_fields: + old_file = old_vals.get(field_name) + new_file = getattr(instance, field_name, None) + if old_file and old_file.name: + if not new_file or new_file.name != old_file.name: + _safe_delete_file(old_file) diff --git a/templates/admin/core/mediafile/change_list.html b/templates/admin/core/mediafile/change_list.html new file mode 100644 index 0000000..4cdfd1c --- /dev/null +++ b/templates/admin/core/mediafile/change_list.html @@ -0,0 +1,339 @@ +{% extends "admin/base_site.html" %} +{% load i18n static %} + +{% block extrastyle %} +{{ block.super }} + +{% endblock %} + +{% block content %} +