排查故障与平滑升级

学习目标

建立从症状到证据的排查顺序，查找孤立媒体，按兼容范围、弃用警告和回归测试逐步升级。

为什么先记录现状再修改

同时改数据库、依赖、配置和模板，会让故障原因难以辨认。出现问题先记录时间、请求、状态码、运行提交和最近改动，然后缩小范围。不要为了暂时消除错误关闭 CSRF、开启公网 DEBUG 或授予数据库 root 权限。

具体怎么做

新增 audit_media 管理命令。它比对数据库引用和本地 covers 目录，只列出缺失与疑似孤立文件，不自动删除。检查时避免正在替换图片的并发写入，最终删除前保留备份并确认没有其他应用引用。

本章新增或替换的完整文件

以下路径均相对于练习项目根目录。替换同名文件的全部内容；未列出的文件保持上一章版本。

blog/management/commands/audit_media.py

from pathlib import Path
from django.conf import settings
from django.core.management.base import BaseCommand
from blog.models import Post

class Command(BaseCommand):
    help = "只读列出孤立图片和缺失图片；不会删除文件。适用于本地文件存储。"

    def handle(self, *args, **options):
        media = Path(settings.MEDIA_ROOT)
        used = set(Post.objects.exclude(cover="").values_list("cover", flat=True))
        disk = {str(path.relative_to(media)) for path in (media / "covers").glob("*") if path.is_file()}
        self.stdout.write(f"引用 {len(used)} 张，磁盘 {len(disk)} 张")
        for name in sorted(used - disk):
            self.stdout.write("缺失：" + name)
        for name in sorted(disk - used):
            self.stdout.write("待人工确认的孤立文件：" + name)

python manage.py audit_media
docker compose logs --since=15m --tail=200 web nginx db
docker compose exec -T web python manage.py showmigrations

不要在公开问题描述中粘贴完整 .env、数据库导出、会话 Cookie 或密码重置链接。可以提供脱敏后的时间、异常类型、文件位置和复现步骤。

升级的实际流程

1. 在官方支持表确认目标稳定版、Python 和数据库最低要求，并检查第三方包兼容性。不要只把 requirements 中的 Django 数字改成“最新”。
2. 从当前小版本的最新补丁开始，阅读跨越的每份发布说明，在隔离分支逐步升级。
3. 运行弃用警告检查与完整测试：

python -Wa manage.py check
python -Wa manage.py test --settings=config.test_settings
python manage.py makemigrations --check --dry-run

1. 使用 MySQL 测试配置验证查询、排序、约束和锁。针对新配置例如 MAILERS，检查第三方组件是否仍使用旧邮件入口。
2. 在预发布环境还原备份，验证迁移、登录、密码重置、Admin、上传和 API；记录差异。
3. 按上一章备份和发布方案上线，保留旧镜像以及与数据库相匹配的恢复路径。

如何确认成功

媒体审计结果没有缺失引用；孤立文件先记录再决定处理。升级分支测试通过，部署检查的每条警告都有明确处理记录，关键页面在桌面和手机正常。不能因为 test 绿了就跳过真实 SMTP、TLS 续期和备份恢复验收。

练习：为一次“发布后图片 404”写出排查路径，区分数据库路径、卷挂载、文件权限和 Nginx alias。再写一份升级变更记录，说明实际验证过什么、仍有什么限制。

常见问题

pip freeze 能直接作为长期升级策略吗？ 它记录当前环境，不解释直接依赖与兼容约束，仍需要维护依赖清单和验证流程。静态目录可以清理吗？ 要核对实际挂载与旧页面缓存，不能误删媒体。系统稳定是否就不必升级？ 安全补丁和支持周期仍需持续关注，选择合适的维护窗口逐步处理。

官方参考

• 升级 Django
• 发布说明索引