mly:完成DjangoBlog代码注释

src/DjangoBlog/accounts/admin.py

@@ -1,52 +1,83 @@
+# 导入Django表单相关模块
 from django import forms
+# 导入Django管理员相关模块
 from django.contrib.auth.admin import UserAdmin
 from django.contrib.auth.forms import UserChangeForm
 from django.contrib.auth.forms import UsernameField
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
 
 # Register your models here.
+# 导入自定义的用户模型
 from .models import BlogUser
 
 
+# 自定义用户创建表单，用于管理员界面创建新用户
 class BlogUserCreationForm(forms.ModelForm):
+    # 密码字段1，使用密码输入控件
     password1 = forms.CharField(label=_('password'), widget=forms.PasswordInput)
+    # 密码字段2，用于确认密码，使用密码输入控件
     password2 = forms.CharField(label=_('Enter password again'), widget=forms.PasswordInput)
 
     class Meta:
+        # 指定关联的模型
         model = BlogUser
+        # 指定表单中包含的字段
         fields = ('email',)
 
+    # 密码确认验证方法
     def clean_password2(self):
         # Check that the two password entries match
+        # 获取两个密码字段的值
         password1 = self.cleaned_data.get("password1")
         password2 = self.cleaned_data.get("password2")
+        # 检查两个密码是否匹配
         if password1 and password2 and password1 != password2:
+            # 如果不匹配则抛出验证错误
             raise forms.ValidationError(_("passwords do not match"))
+        # 返回确认密码的值
         return password2
 
+    # 保存用户的方法
     def save(self, commit=True):
         # Save the provided password in hashed format
+        # 调用父类的save方法但不立即提交到数据库
         user = super().save(commit=False)
+        # 设置哈希后的密码
         user.set_password(self.cleaned_data["password1"])
+        # 如果设置为立即提交
         if commit:
+            # 设置用户来源为管理员站点
             user.source = 'adminsite'
+            # 保存用户到数据库
             user.save()
+        # 返回用户对象
         return user
 
 
+# 自定义用户修改表单，用于管理员界面修改用户信息
 class BlogUserChangeForm(UserChangeForm):
     class Meta:
+        # 指定关联的模型
         model = BlogUser
+        # 包含所有字段
         fields = '__all__'
+        # 指定字段类型映射
         field_classes = {'username': UsernameField}
 
+    # 初始化方法
     def __init__(self, *args, **kwargs):
+        # 调用父类的初始化方法
         super().__init__(*args, **kwargs)
 
 
+# 自定义用户管理类，用于配置Django管理员界面的用户管理
 class BlogUserAdmin(UserAdmin):
+    # 指定修改用户时使用的表单
     form = BlogUserChangeForm
+    # 指定创建用户时使用的表单
     add_form = BlogUserCreationForm
+    # 指定列表页面显示的字段
     list_display = (
         'id',
         'nickname',
@@ -55,6 +86,9 @@ class BlogUserAdmin(UserAdmin):
         'last_login',
         'date_joined',
         'source')
+    # 指定列表页面中哪些字段可以作为链接点击进入编辑页面
     list_display_links = ('id', 'username')
+    # 指定默认排序字段，按ID倒序排列
     ordering = ('-id',)
-    search_fields = ('username', 'nickname', 'email')
+    # 指定搜索字段，支持按用户名、昵称、邮箱搜索
+    search_fields = ('username', 'nickname', 'email')

src/DjangoBlog/accounts/apps.py

@@ -1,5 +1,8 @@
+# 导入Django应用配置基类
 from django.apps import AppConfig
 
 
+# 定义账户应用的配置类
 class AccountsConfig(AppConfig):
-    name = 'accounts'
+    # 指定应用的完整Python路径
+    name = 'accounts'

src/DjangoBlog/accounts/forms.py

@@ -1,26 +1,41 @@
+# 导入Django表单相关模块
 from django import forms
+# 导入Django认证系统相关模块
 from django.contrib.auth import get_user_model, password_validation
+# 导入Django内置的认证表单
 from django.contrib.auth.forms import AuthenticationForm, UserCreationForm
+# 导入验证错误异常
 from django.core.exceptions import ValidationError
+# 导入表单控件模块
 from django.forms import widgets
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
+# 导入自定义工具模块
 from . import utils
+# 导入自定义用户模型
 from .models import BlogUser
 
 
+# 登录表单类，继承自Django内置的AuthenticationForm
 class LoginForm(AuthenticationForm):
     def __init__(self, *args, **kwargs):
+        # 调用父类的初始化方法
         super(LoginForm, self).__init__(*args, **kwargs)
+        # 自定义用户名输入框的HTML属性
         self.fields['username'].widget = widgets.TextInput(
             attrs={'placeholder': "username", "class": "form-control"})
+        # 自定义密码输入框的HTML属性
         self.fields['password'].widget = widgets.PasswordInput(
             attrs={'placeholder': "password", "class": "form-control"})
 
 
+# 注册表单类，继承自Django内置的UserCreationForm
 class RegisterForm(UserCreationForm):
     def __init__(self, *args, **kwargs):
+        # 调用父类的初始化方法
         super(RegisterForm, self).__init__(*args, **kwargs)
 
+        # 自定义各个表单字段的HTML属性
         self.fields['username'].widget = widgets.TextInput(
             attrs={'placeholder': "username", "class": "form-control"})
         self.fields['email'].widget = widgets.EmailInput(
@@ -30,18 +45,27 @@ class RegisterForm(UserCreationForm):
         self.fields['password2'].widget = widgets.PasswordInput(
             attrs={'placeholder': "repeat password", "class": "form-control"})
 
+    # 邮箱字段验证方法
     def clean_email(self):
+        # 获取邮箱数据
         email = self.cleaned_data['email']
+        # 检查邮箱是否已存在
         if get_user_model().objects.filter(email=email).exists():
+            # 如果邮箱已存在则抛出验证错误
             raise ValidationError(_("email already exists"))
+        # 返回验证通过的邮箱
         return email
 
     class Meta:
+        # 指定关联的用户模型
         model = get_user_model()
+        # 指定表单中包含的字段
         fields = ("username", "email")
 
 
+# 忘记密码表单类，继承自forms.Form
 class ForgetPasswordForm(forms.Form):
+    # 新密码字段1
     new_password1 = forms.CharField(
         label=_("New password"),
         widget=forms.PasswordInput(
@@ -52,6 +76,7 @@ class ForgetPasswordForm(forms.Form):
         ),
     )
 
+    # 新密码字段2，用于确认密码
     new_password2 = forms.CharField(
         label="确认密码",
         widget=forms.PasswordInput(
@@ -62,6 +87,7 @@ class ForgetPasswordForm(forms.Form):
         ),
     )
 
+    # 邮箱字段
     email = forms.EmailField(
         label='邮箱',
         widget=forms.TextInput(
@@ -72,6 +98,7 @@ class ForgetPasswordForm(forms.Form):
         ),
     )
 
+    # 验证码字段
     code = forms.CharField(
         label=_('Code'),
         widget=forms.TextInput(
@@ -82,36 +109,55 @@ class ForgetPasswordForm(forms.Form):
         ),
     )
 
+    # 确认密码验证方法
     def clean_new_password2(self):
+        # 获取两个密码字段的值
         password1 = self.data.get("new_password1")
         password2 = self.data.get("new_password2")
+        # 检查两个密码是否匹配
         if password1 and password2 and password1 != password2:
+            # 如果不匹配则抛出验证错误
             raise ValidationError(_("passwords do not match"))
+        # 使用Django内置的密码验证器验证密码强度
         password_validation.validate_password(password2)
 
+        # 返回验证通过的密码
         return password2
 
+    # 邮箱验证方法
     def clean_email(self):
+        # 获取邮箱数据
         user_email = self.cleaned_data.get("email")
+        # 检查邮箱是否存在于用户表中
         if not BlogUser.objects.filter(
                 email=user_email
         ).exists():
             # todo 这里的报错提示可以判断一个邮箱是不是注册过，如果不想暴露可以修改
+            # 如果邮箱不存在则抛出验证错误
             raise ValidationError(_("email does not exist"))
+        # 返回验证通过的邮箱
         return user_email
 
+    # 验证码验证方法
     def clean_code(self):
+        # 获取验证码数据
         code = self.cleaned_data.get("code")
+        # 使用工具函数验证验证码的有效性
         error = utils.verify(
             email=self.cleaned_data.get("email"),
             code=code,
         )
+        # 如果验证返回错误信息
         if error:
+            # 抛出验证错误
             raise ValidationError(error)
+        # 返回验证通过的验证码
         return code
 
 
+# 忘记密码验证码表单类，用于请求发送验证码
 class ForgetPasswordCodeForm(forms.Form):
+    # 邮箱字段
     email = forms.EmailField(
         label=_('Email'),
-    )
+    )

src/DjangoBlog/accounts/migrations/0001_initial.py

@@ -1,5 +1,6 @@
 # Generated by Django 4.1.7 on 2023-03-02 07:14
 
+# 导入Django内置的认证系统相关模块
 import django.contrib.auth.models
 import django.contrib.auth.validators
 from django.db import migrations, models
@@ -7,43 +8,71 @@ import django.utils.timezone
 
 
 class Migration(migrations.Migration):
+    """
+    数据库迁移类，用于创建BlogUser模型
+    这是初始迁移文件(initial = True)
+    """
 
     initial = True
 
+    # 依赖的迁移文件，这里依赖Django auth应用的迁移
     dependencies = [
         ('auth', '0012_alter_user_first_name_max_length'),
     ]
 
     operations = [
+        # 创建BlogUser模型表的操作
         migrations.CreateModel(
             name='BlogUser',
             fields=[
+                # 主键ID，使用BigAutoField自增字段
                 ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                # 密码字段，使用Django认证系统的密码存储格式
                 ('password', models.CharField(max_length=128, verbose_name='password')),
+                # 最后登录时间，记录用户最后一次登录的时间
                 ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')),
+                # 超级用户标志，拥有所有权限
                 ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')),
+                # 用户名字段，具有唯一性验证和格式验证
                 ('username', models.CharField(error_messages={'unique': 'A user with that username already exists.'}, help_text='Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.', max_length=150, unique=True, validators=[django.contrib.auth.validators.UnicodeUsernameValidator()], verbose_name='username')),
+                # 名字字段，可为空
                 ('first_name', models.CharField(blank=True, max_length=150, verbose_name='first name')),
+                # 姓氏字段，可为空
                 ('last_name', models.CharField(blank=True, max_length=150, verbose_name='last name')),
+                # 邮箱字段，可为空
                 ('email', models.EmailField(blank=True, max_length=254, verbose_name='email address')),
+                # 员工状态标志，决定用户是否可以登录管理后台
                 ('is_staff', models.BooleanField(default=False, help_text='Designates whether the user can log into this admin site.', verbose_name='staff status')),
+                # 活跃状态标志，用于软删除而非真正删除账户
                 ('is_active', models.BooleanField(default=True, help_text='Designates whether this user should be treated as active. Unselect this instead of deleting accounts.', verbose_name='active')),
+                # 账户创建时间，默认使用当前时间
                 ('date_joined', models.DateTimeField(default=django.utils.timezone.now, verbose_name='date joined')),
+                # 自定义字段：昵称，可为空
                 ('nickname', models.CharField(blank=True, max_length=100, verbose_name='昵称')),
+                # 自定义字段：创建时间，默认使用当前时间
                 ('created_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='创建时间')),
+                # 自定义字段：最后修改时间，默认使用当前时间
                 ('last_mod_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='修改时间')),
+                # 自定义字段：创建来源，记录用户的注册来源
                 ('source', models.CharField(blank=True, max_length=100, verbose_name='创建来源')),
+                # 用户组多对多关系，关联到Django的Group模型
                 ('groups', models.ManyToManyField(blank=True, help_text='The groups this user belongs to. A user will get all permissions granted to each of their groups.', related_name='user_set', related_query_name='user', to='auth.group', verbose_name='groups')),
+                # 用户权限多对多关系，关联到Django的Permission模型
                 ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user.', related_name='user_set', related_query_name='user', to='auth.permission', verbose_name='user permissions')),
             ],
             options={
+                # 单数形式的显示名称
                 'verbose_name': '用户',
+                # 复数形式的显示名称
                 'verbose_name_plural': '用户',
+                # 默认排序方式，按ID倒序排列
                 'ordering': ['-id'],
+                # 指定获取最新记录的依据字段
                 'get_latest_by': 'id',
             },
+            # 指定模型的管理器，使用Django默认的UserManager
             managers=[
                 ('objects', django.contrib.auth.models.UserManager()),
             ],
         ),
-    ]
+    ]

src/DjangoBlog/accounts/migrations/0002_alter_bloguser_options_remove_bloguser_created_time_and_more.py

@@ -5,42 +5,54 @@ import django.utils.timezone
 
 
 class Migration(migrations.Migration):
+    """
+    数据库迁移类，用于修改BlogUser模型
+    这是对0001_initial迁移的后续修改
+    """
 
+    # 依赖之前的初始迁移文件
     dependencies = [
         ('accounts', '0001_initial'),
     ]
 
     operations = [
+        # 修改模型的元数据选项
         migrations.AlterModelOptions(
             name='bloguser',
             options={'get_latest_by': 'id', 'ordering': ['-id'], 'verbose_name': 'user', 'verbose_name_plural': 'user'},
         ),
+        # 删除created_time字段
         migrations.RemoveField(
             model_name='bloguser',
             name='created_time',
         ),
+        # 删除last_mod_time字段
         migrations.RemoveField(
             model_name='bloguser',
             name='last_mod_time',
         ),
+        # 新增creation_time字段，使用当前时间作为默认值
         migrations.AddField(
             model_name='bloguser',
             name='creation_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='creation time'),
         ),
+        # 新增last_modify_time字段，使用当前时间作为默认值
         migrations.AddField(
             model_name='bloguser',
             name='last_modify_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='last modify time'),
         ),
+        # 修改nickname字段的verbose_name
         migrations.AlterField(
             model_name='bloguser',
             name='nickname',
             field=models.CharField(blank=True, max_length=100, verbose_name='nick name'),
         ),
+        # 修改source字段的verbose_name
         migrations.AlterField(
             model_name='bloguser',
             name='source',
             field=models.CharField(blank=True, max_length=100, verbose_name='create source'),
         ),
-    ]
+    ]

src/DjangoBlog/accounts/models.py

@@ -1,35 +1,59 @@
+# 导入Django认证系统抽象用户基类
 from django.contrib.auth.models import AbstractUser
+# 导入Django数据库模型模块
 from django.db import models
+# 导入URL反向解析模块
 from django.urls import reverse
+# 导入时区相关模块
 from django.utils.timezone import now
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
+# 导入自定义工具函数
 from djangoblog.utils import get_current_site
 
 
 # Create your models here.
 
+# 自定义博客用户模型，继承自Django的AbstractUser基类
 class BlogUser(AbstractUser):
+    # 昵称字段，最大长度100字符，允许为空
     nickname = models.CharField(_('nick name'), max_length=100, blank=True)
+    # 创建时间字段，默认值为当前时间
     creation_time = models.DateTimeField(_('creation time'), default=now)
+    # 最后修改时间字段，默认值为当前时间
     last_modify_time = models.DateTimeField(_('last modify time'), default=now)
+    # 创建来源字段，最大长度100字符，允许为空
     source = models.CharField(_('create source'), max_length=100, blank=True)
 
+    # 获取用户绝对URL的方法
     def get_absolute_url(self):
+        # 使用反向解析生成作者详情页的URL
         return reverse(
             'blog:author_detail', kwargs={
                 'author_name': self.username})
 
+    # 对象的字符串表示方法
     def __str__(self):
+        # 使用邮箱作为对象的字符串表示
         return self.email
 
+    # 获取用户完整URL的方法（包含域名）
     def get_full_url(self):
+        # 获取当前站点的域名
         site = get_current_site().domain
+        # 构建完整的URL地址
         url = "https://{site}{path}".format(site=site,
                                             path=self.get_absolute_url())
+        # 返回完整的URL
         return url
 
+    # 模型的元数据配置
     class Meta:
+        # 默认按ID倒序排列
         ordering = ['-id']
+        # 单数形式的显示名称
         verbose_name = _('user')
+        # 复数形式的显示名称，与单数形式相同
         verbose_name_plural = verbose_name
-        get_latest_by = 'id'
+        # 指定获取最新记录的依据字段
+        get_latest_by = 'id'

src/DjangoBlog/accounts/tests.py

@@ -1,48 +1,72 @@
+# 导入Django测试相关模块
 from django.test import Client, RequestFactory, TestCase
+# 导入URL反向解析模块
 from django.urls import reverse
+# 导入时区相关模块
 from django.utils import timezone
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
 
+# 导入账户模型
 from accounts.models import BlogUser
+# 导入博客模型
 from blog.models import Article, Category
+# 导入工具函数
 from djangoblog.utils import *
+# 导入当前应用的工具模块
 from . import utils
 
 
 # Create your tests here.
 
+# 账户测试类，继承自Django的TestCase
 class AccountTest(TestCase):
+    # 测试前置设置方法
     def setUp(self):
+        # 创建测试客户端
         self.client = Client()
+        # 创建请求工厂
         self.factory = RequestFactory()
+        # 创建测试用户
         self.blog_user = BlogUser.objects.create_user(
             username="test",
             email="admin@admin.com",
             password="12345678"
         )
+        # 设置测试用的新密码
         self.new_test = "xxx123--="
 
+    # 测试账户验证功能
     def test_validate_account(self):
+        # 获取当前站点域名
         site = get_current_site().domain
+        # 创建超级用户
         user = BlogUser.objects.create_superuser(
             email="liangliangyy1@gmail.com",
             username="liangliangyy1",
             password="qwer!@#$ggg")
+        # 获取刚创建的用户
         testuser = BlogUser.objects.get(username='liangliangyy1')
 
+        # 测试登录功能
         loginresult = self.client.login(
             username='liangliangyy1',
             password='qwer!@#$ggg')
+        # 断言登录成功
         self.assertEqual(loginresult, True)
+        # 访问管理员页面
         response = self.client.get('/admin/')
+        # 断言访问成功
         self.assertEqual(response.status_code, 200)
 
+        # 创建测试分类
         category = Category()
         category.name = "categoryaaa"
         category.creation_time = timezone.now()
         category.last_modify_time = timezone.now()
         category.save()
 
+        # 创建测试文章
         article = Article()
         article.title = "nicetitleaaa"
         article.body = "nicecontentaaa"
@@ -52,44 +76,59 @@ class AccountTest(TestCase):
         article.status = 'p'
         article.save()
 
+        # 访问文章管理页面
         response = self.client.get(article.get_admin_url())
+        # 断言访问成功
         self.assertEqual(response.status_code, 200)
 
+    # 测试注册功能
     def test_validate_register(self):
+        # 断言注册前用户不存在
         self.assertEquals(
             0, len(
                 BlogUser.objects.filter(
                     email='user123@user.com')))
+        # 发送注册请求
         response = self.client.post(reverse('account:register'), {
             'username': 'user1233',
             'email': 'user123@user.com',
             'password1': 'password123!q@wE#R$T',
             'password2': 'password123!q@wE#R$T',
         })
+        # 断言注册后用户存在
         self.assertEquals(
             1, len(
                 BlogUser.objects.filter(
                     email='user123@user.com')))
+        # 获取刚注册的用户
         user = BlogUser.objects.filter(email='user123@user.com')[0]
+        # 生成验证签名
         sign = get_sha256(get_sha256(settings.SECRET_KEY + str(user.id)))
         path = reverse('accounts:result')
+        # 构建验证URL
         url = '{path}?type=validation&id={id}&sign={sign}'.format(
             path=path, id=user.id, sign=sign)
+        # 访问验证页面
         response = self.client.get(url)
         self.assertEqual(response.status_code, 200)
 
+        # 登录用户
         self.client.login(username='user1233', password='password123!q@wE#R$T')
         user = BlogUser.objects.filter(email='user123@user.com')[0]
+        # 设置为超级用户和管理员
         user.is_superuser = True
         user.is_staff = True
         user.save()
+        # 删除侧边栏缓存
         delete_sidebar_cache()
+        # 创建分类
         category = Category()
         category.name = "categoryaaa"
         category.creation_time = timezone.now()
         category.last_modify_time = timezone.now()
         category.save()
 
+        # 创建文章
         article = Article()
         article.category = category
         article.title = "nicetitle333"
@@ -100,36 +139,48 @@ class AccountTest(TestCase):
         article.status = 'p'
         article.save()
 
+        # 访问文章管理页面
         response = self.client.get(article.get_admin_url())
         self.assertEqual(response.status_code, 200)
 
+        # 测试退出登录
         response = self.client.get(reverse('account:logout'))
         self.assertIn(response.status_code, [301, 302, 200])
 
+        # 退出后访问文章管理页面应该重定向
         response = self.client.get(article.get_admin_url())
         self.assertIn(response.status_code, [301, 302, 200])
 
+        # 测试错误密码登录
         response = self.client.post(reverse('account:login'), {
             'username': 'user1233',
             'password': 'password123'
         })
         self.assertIn(response.status_code, [301, 302, 200])
 
+        # 错误密码登录后访问文章管理页面应该重定向
         response = self.client.get(article.get_admin_url())
         self.assertIn(response.status_code, [301, 302, 200])
 
+    # 测试邮箱验证码功能
     def test_verify_email_code(self):
         to_email = "admin@admin.com"
+        # 生成验证码
         code = generate_code()
+        # 设置验证码
         utils.set_code(to_email, code)
+        # 发送验证邮件
         utils.send_verify_email(to_email, code)
 
+        # 测试正确验证码验证
         err = utils.verify("admin@admin.com", code)
         self.assertEqual(err, None)
 
+        # 测试错误邮箱验证
         err = utils.verify("admin@123.com", code)
         self.assertEqual(type(err), str)
 
+    # 测试忘记密码邮箱验证码发送成功情况
     def test_forget_password_email_code_success(self):
         resp = self.client.post(
             path=reverse("account:forget_password_code"),
@@ -139,21 +190,26 @@ class AccountTest(TestCase):
         self.assertEqual(resp.status_code, 200)
         self.assertEqual(resp.content.decode("utf-8"), "ok")
 
+    # 测试忘记密码邮箱验证码发送失败情况
     def test_forget_password_email_code_fail(self):
+        # 测试空数据提交
         resp = self.client.post(
             path=reverse("account:forget_password_code"),
             data=dict()
         )
         self.assertEqual(resp.content.decode("utf-8"), "错误的邮箱")
 
+        # 测试错误邮箱格式提交
         resp = self.client.post(
             path=reverse("account:forget_password_code"),
             data=dict(email="admin@com")
         )
         self.assertEqual(resp.content.decode("utf-8"), "错误的邮箱")
 
+    # 测试忘记密码重置成功情况
     def test_forget_password_email_success(self):
         code = generate_code()
+        # 设置验证码
         utils.set_code(self.blog_user.email, code)
         data = dict(
             new_password1=self.new_test,
@@ -161,6 +217,7 @@ class AccountTest(TestCase):
             email=self.blog_user.email,
             code=code,
         )
+        # 提交重置密码请求
         resp = self.client.post(
             path=reverse("account:forget_password"),
             data=data
@@ -174,6 +231,7 @@ class AccountTest(TestCase):
         self.assertNotEqual(blog_user, None)
         self.assertEqual(blog_user.check_password(data["new_password1"]), True)
 
+    # 测试忘记密码时邮箱不存在的情况
     def test_forget_password_email_not_user(self):
         data = dict(
             new_password1=self.new_test,
@@ -188,7 +246,7 @@ class AccountTest(TestCase):
 
         self.assertEqual(resp.status_code, 200)
 
-
+    # 测试忘记密码时验证码错误的情况
     def test_forget_password_email_code_error(self):
         code = generate_code()
         utils.set_code(self.blog_user.email, code)
@@ -203,5 +261,4 @@ class AccountTest(TestCase):
             data=data
         )
 
-        self.assertEqual(resp.status_code, 200)
-
+        self.assertEqual(resp.status_code, 200)

src/DjangoBlog/accounts/urls.py

@@ -1,28 +1,58 @@
+# 导入Django URL路由相关模块
 from django.urls import path
 from django.urls import re_path
 
+# 导入当前应用的视图模块
 from . import views
+# 导入登录表单类
 from .forms import LoginForm
 
+# 定义应用的命名空间
 app_name = "accounts"
 
-urlpatterns = [re_path(r'^login/$',
-                       views.LoginView.as_view(success_url='/'),
-                       name='login',
-                       kwargs={'authentication_form': LoginForm}),
-               re_path(r'^register/$',
-                       views.RegisterView.as_view(success_url="/"),
-                       name='register'),
-               re_path(r'^logout/$',
-                       views.LogoutView.as_view(),
-                       name='logout'),
-               path(r'account/result.html',
-                    views.account_result,
-                    name='result'),
-               re_path(r'^forget_password/$',
-                       views.ForgetPasswordView.as_view(),
-                       name='forget_password'),
-               re_path(r'^forget_password_code/$',
-                       views.ForgetPasswordEmailCode.as_view(),
-                       name='forget_password_code'),
-               ]
+# 定义URL模式列表
+urlpatterns = [
+    # 登录URL，使用正则表达式匹配路径
+    re_path(r'^login/$',
+            # 使用类视图，设置登录成功后的重定向URL
+            views.LoginView.as_view(success_url='/'),
+            # URL名称
+            name='login',
+            # 传递额外参数，指定认证表单类
+            kwargs={'authentication_form': LoginForm}),
+
+    # 注册URL，使用正则表达式匹配路径
+    re_path(r'^register/$',
+            # 使用类视图，设置注册成功后的重定向URL
+            views.RegisterView.as_view(success_url="/"),
+            # URL名称
+            name='register'),
+
+    # 退出登录URL，使用正则表达式匹配路径
+    re_path(r'^logout/$',
+            # 使用类视图
+            views.LogoutView.as_view(),
+            # URL名称
+            name='logout'),
+
+    # 账户结果页面URL，使用path匹配精确路径
+    path(r'account/result.html',
+         # 使用函数视图
+         views.account_result,
+         # URL名称
+         name='result'),
+
+    # 忘记密码URL，使用正则表达式匹配路径
+    re_path(r'^forget_password/$',
+            # 使用类视图
+            views.ForgetPasswordView.as_view(),
+            # URL名称
+            name='forget_password'),
+
+    # 忘记密码验证码URL，使用正则表达式匹配路径
+    re_path(r'^forget_password_code/$',
+            # 使用类视图
+            views.ForgetPasswordEmailCode.as_view(),
+            # URL名称
+            name='forget_password_code'),
+]

src/DjangoBlog/accounts/user_login_backend.py

@@ -1,26 +1,41 @@
+# 导入Django认证系统相关模块
 from django.contrib.auth import get_user_model
 from django.contrib.auth.backends import ModelBackend
 
 
+# 自定义认证后端类，允许使用用户名或邮箱登录
 class EmailOrUsernameModelBackend(ModelBackend):
     """
     允许使用用户名或邮箱登录
     """
 
+    # 用户认证方法
     def authenticate(self, request, username=None, password=None, **kwargs):
+        # 判断输入的用户名是否包含@符号（即是否为邮箱格式）
         if '@' in username:
+            # 如果是邮箱格式，则使用email字段进行查询
             kwargs = {'email': username}
         else:
+            # 如果不是邮箱格式，则使用username字段进行查询
             kwargs = {'username': username}
         try:
+            # 根据用户名或邮箱获取用户对象
             user = get_user_model().objects.get(**kwargs)
+            # 验证密码是否正确
             if user.check_password(password):
+                # 密码正确则返回用户对象
                 return user
+        # 捕获用户不存在的异常
         except get_user_model().DoesNotExist:
+            # 用户不存在则返回None
             return None
 
+    # 根据用户ID获取用户对象的方法
     def get_user(self, username):
         try:
+            # 根据主键（用户ID）获取用户对象
             return get_user_model().objects.get(pk=username)
+        # 捕获用户不存在的异常
         except get_user_model().DoesNotExist:
-            return None
+            # 用户不存在则返回None
+            return None

src/DjangoBlog/accounts/utils.py

@@ -1,15 +1,22 @@
+# 导入类型提示模块
 import typing
+# 导入时间间隔模块
 from datetime import timedelta
 
+# 导入Django缓存模块
 from django.core.cache import cache
+# 导入国际化翻译函数
 from django.utils.translation import gettext
 from django.utils.translation import gettext_lazy as _
 
+# 导入自定义邮件发送工具函数
 from djangoblog.utils import send_email
 
+# 定义验证码的生存时间（Time To Live），设置为5分钟
 _code_ttl = timedelta(minutes=5)
 
 
+# 发送验证邮件的函数
 def send_verify_email(to_mail: str, code: str, subject: str = _("Verify Email")):
     """发送重设密码验证码
     Args:
@@ -17,12 +24,15 @@ def send_verify_email(to_mail: str, code: str, subject: str = _("Verify Email"))
         subject: 邮件主题
         code: 验证码
     """
+    # 构建邮件HTML内容，包含验证码信息
     html_content = _(
         "You are resetting the password, the verification code is：%(code)s, valid within 5 minutes, please keep it "
         "properly") % {'code': code}
+    # 调用邮件发送函数发送验证邮件
     send_email([to_mail], subject, html_content)
 
 
+# 验证验证码有效性的函数
 def verify(email: str, code: str) -> typing.Optional[str]:
     """验证code是否有效
     Args:
@@ -34,16 +44,23 @@ def verify(email: str, code: str) -> typing.Optional[str]:
         这里的错误处理不太合理，应该采用raise抛出
         否测调用方也需要对error进行处理
     """
+    # 从缓存中获取该邮箱对应的验证码
     cache_code = get_code(email)
+    # 比较输入的验证码和缓存中的验证码是否一致
     if cache_code != code:
+        # 如果不一致，返回错误信息
         return gettext("Verification code error")
 
 
+# 设置验证码到缓存的函数
 def set_code(email: str, code: str):
     """设置code"""
+    # 将邮箱和验证码存入缓存，设置过期时间为_code_ttl定义的秒数
     cache.set(email, code, _code_ttl.seconds)
 
 
+# 从缓存获取验证码的函数
 def get_code(email: str) -> typing.Optional[str]:
     """获取code"""
-    return cache.get(email)
+    # 根据邮箱从缓存中获取验证码，如果不存在则返回None
+    return cache.get(email)

src/DjangoBlog/accounts/views.py

@@ -1,59 +1,92 @@
+# 导入日志模块
 import logging
+# 导入Django国际化翻译模块
 from django.utils.translation import gettext_lazy as _
+# 导入Django配置模块
 from django.conf import settings
+# 导入Django认证相关模块
 from django.contrib import auth
 from django.contrib.auth import REDIRECT_FIELD_NAME
 from django.contrib.auth import get_user_model
 from django.contrib.auth import logout
 from django.contrib.auth.forms import AuthenticationForm
 from django.contrib.auth.hashers import make_password
+# 导入HTTP响应相关模块
 from django.http import HttpResponseRedirect, HttpResponseForbidden
 from django.http.request import HttpRequest
 from django.http.response import HttpResponse
+# 导入快捷函数模块
 from django.shortcuts import get_object_or_404
 from django.shortcuts import render
+# 导入URL反向解析模块
 from django.urls import reverse
+# 导入方法装饰器模块
 from django.utils.decorators import method_decorator
 from django.utils.http import url_has_allowed_host_and_scheme
+# 导入视图基类
 from django.views import View
+# 导入视图装饰器模块
 from django.views.decorators.cache import never_cache
 from django.views.decorators.csrf import csrf_protect
 from django.views.decorators.debug import sensitive_post_parameters
+# 导入通用类视图
 from django.views.generic import FormView, RedirectView
 
+# 导入自定义工具函数
 from djangoblog.utils import send_email, get_sha256, get_current_site, generate_code, delete_sidebar_cache
+# 导入当前应用的工具模块
 from . import utils
+# 导入自定义表单类
 from .forms import RegisterForm, LoginForm, ForgetPasswordForm, ForgetPasswordCodeForm
+# 导入用户模型
 from .models import BlogUser
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
 
 # Create your views here.
 
+# 注册视图类，继承自FormView
 class RegisterView(FormView):
+    # 指定使用的表单类
     form_class = RegisterForm
+    # 指定模板名称
     template_name = 'account/registration_form.html'
 
+    # 使用CSRF保护装饰器
     @method_decorator(csrf_protect)
     def dispatch(self, *args, **kwargs):
+        # 调用父类的dispatch方法
         return super(RegisterView, self).dispatch(*args, **kwargs)
 
+    # 表单验证通过后的处理
     def form_valid(self, form):
+        # 检查表单是否有效
         if form.is_valid():
+            # 保存用户但不提交到数据库
             user = form.save(False)
+            # 设置用户为非活跃状态
             user.is_active = False
+            # 设置用户来源为注册
             user.source = 'Register'
+            # 保存用户到数据库
             user.save(True)
+            # 获取当前站点域名
             site = get_current_site().domain
+            # 生成验证签名
             sign = get_sha256(get_sha256(settings.SECRET_KEY + str(user.id)))
 
+            # 如果是调试模式，使用本地地址
             if settings.DEBUG:
                 site = '127.0.0.1:8000'
+            # 获取结果页面的URL路径
             path = reverse('account:result')
+            # 构建完整的验证URL
             url = "http://{site}{path}?type=validation&id={id}&sign={sign}".format(
                 site=site, path=path, id=user.id, sign=sign)
 
+            # 构建邮件内容
             content = """
                             <p>请点击下面链接验证您的邮箱</p>
 
@@ -64,6 +97,7 @@ class RegisterView(FormView):
                             如果上面链接无法打开，请将此链接复制至浏览器。
                             {url}
                             """.format(url=url)
+            # 发送验证邮件
             send_email(
                 emailto=[
                     user.email,
@@ -71,134 +105,201 @@ class RegisterView(FormView):
                 title='验证您的电子邮箱',
                 content=content)
 
+            # 构建注册结果页面的URL
             url = reverse('accounts:result') + \
                   '?type=register&id=' + str(user.id)
+            # 重定向到结果页面
             return HttpResponseRedirect(url)
         else:
+            # 表单无效则重新渲染表单页面
             return self.render_to_response({
                 'form': form
             })
 
 
+# 退出登录视图类，继承自RedirectView
 class LogoutView(RedirectView):
+    # 指定退出后重定向的URL
     url = '/login/'
 
+    # 使用永不缓存装饰器
     @method_decorator(never_cache)
     def dispatch(self, request, *args, **kwargs):
+        # 调用父类的dispatch方法
         return super(LogoutView, self).dispatch(request, *args, **kwargs)
 
+    # GET请求处理
     def get(self, request, *args, **kwargs):
+        # 执行退出登录操作
         logout(request)
+        # 删除侧边栏缓存
         delete_sidebar_cache()
+        # 调用父类的GET方法进行重定向
         return super(LogoutView, self).get(request, *args, **kwargs)
 
 
+# 登录视图类，继承自FormView
 class LoginView(FormView):
+    # 指定使用的表单类
     form_class = LoginForm
+    # 指定模板名称
     template_name = 'account/login.html'
+    # 指定登录成功后的默认重定向URL
     success_url = '/'
+    # 指定重定向字段名
     redirect_field_name = REDIRECT_FIELD_NAME
+    # 设置登录会话的生存时间（一个月）
     login_ttl = 2626560  # 一个月的时间
 
+    # 使用多个装饰器保护视图
     @method_decorator(sensitive_post_parameters('password'))
     @method_decorator(csrf_protect)
     @method_decorator(never_cache)
     def dispatch(self, request, *args, **kwargs):
-
+        # 调用父类的dispatch方法
         return super(LoginView, self).dispatch(request, *args, **kwargs)
 
+    # 获取上下文数据
     def get_context_data(self, **kwargs):
+        # 获取重定向目标URL
         redirect_to = self.request.GET.get(self.redirect_field_name)
+        # 如果没有指定重定向目标，使用默认首页
         if redirect_to is None:
             redirect_to = '/'
+        # 将重定向目标添加到上下文
         kwargs['redirect_to'] = redirect_to
 
+        # 调用父类方法获取上下文数据
         return super(LoginView, self).get_context_data(**kwargs)
 
+    # 表单验证通过后的处理
     def form_valid(self, form):
+        # 创建认证表单实例
         form = AuthenticationForm(data=self.request.POST, request=self.request)
 
+        # 检查表单是否有效
         if form.is_valid():
+            # 删除侧边栏缓存
             delete_sidebar_cache()
+            # 记录日志
             logger.info(self.redirect_field_name)
 
+            # 执行登录操作
             auth.login(self.request, form.get_user())
+            # 如果用户选择了"记住我"，设置会话过期时间
             if self.request.POST.get("remember"):
                 self.request.session.set_expiry(self.login_ttl)
+            # 调用父类的form_valid方法进行重定向
             return super(LoginView, self).form_valid(form)
-            # return HttpResponseRedirect('/')
         else:
+            # 表单无效则重新渲染表单页面
             return self.render_to_response({
                 'form': form
             })
 
+    # 获取成功登录后的重定向URL
     def get_success_url(self):
-
+        # 从POST数据中获取重定向目标
         redirect_to = self.request.POST.get(self.redirect_field_name)
+        # 检查重定向URL是否安全
         if not url_has_allowed_host_and_scheme(
                 url=redirect_to, allowed_hosts=[
                     self.request.get_host()]):
+            # 如果不安全，使用默认的成功URL
             redirect_to = self.success_url
+        # 返回重定向URL
         return redirect_to
 
 
+# 账户结果页面视图函数
 def account_result(request):
+    # 获取请求参数
     type = request.GET.get('type')
     id = request.GET.get('id')
 
+    # 根据ID获取用户对象，如果不存在则返回404
     user = get_object_or_404(get_user_model(), id=id)
+    # 记录日志
     logger.info(type)
+    # 如果用户已经是活跃状态，重定向到首页
     if user.is_active:
         return HttpResponseRedirect('/')
+    # 检查类型参数是否有效
     if type and type in ['register', 'validation']:
+        # 根据不同类型显示不同内容
         if type == 'register':
             content = '''
     恭喜您注册成功，一封验证邮件已经发送到您的邮箱，请验证您的邮箱后登录本站。
     '''
             title = '注册成功'
         else:
+            # 验证类型需要验证签名
             c_sign = get_sha256(get_sha256(settings.SECRET_KEY + str(user.id)))
             sign = request.GET.get('sign')
+            # 如果签名不匹配，返回403禁止访问
             if sign != c_sign:
                 return HttpResponseForbidden()
+            # 激活用户账户
             user.is_active = True
             user.save()
             content = '''
             恭喜您已经成功的完成邮箱验证，您现在可以使用您的账号来登录本站。
             '''
             title = '验证成功'
+        # 渲染结果页面
         return render(request, 'account/result.html', {
             'title': title,
             'content': content
         })
     else:
+        # 参数无效则重定向到首页
         return HttpResponseRedirect('/')
 
 
+# 忘记密码视图类，继承自FormView
 class ForgetPasswordView(FormView):
+    # 指定使用的表单类
     form_class = ForgetPasswordForm
+    # 指定模板名称
     template_name = 'account/forget_password.html'
 
+    # 表单验证通过后的处理
     def form_valid(self, form):
+        # 检查表单是否有效
         if form.is_valid():
+            # 根据邮箱获取用户对象
             blog_user = BlogUser.objects.filter(email=form.cleaned_data.get("email")).get()
+            # 使用新密码的哈希值更新用户密码
             blog_user.password = make_password(form.cleaned_data["new_password2"])
+            # 保存用户信息
             blog_user.save()
+            # 重定向到登录页面
             return HttpResponseRedirect('/login/')
         else:
+            # 表单无效则重新渲染表单页面
             return self.render_to_response({'form': form})
 
 
+# 忘记密码邮箱验证码视图类，继承自View
 class ForgetPasswordEmailCode(View):
 
+    # POST请求处理
     def post(self, request: HttpRequest):
+        # 创建忘记密码验证码表单实例
         form = ForgetPasswordCodeForm(request.POST)
+        # 检查表单是否有效
         if not form.is_valid():
+            # 表单无效返回错误信息
             return HttpResponse("错误的邮箱")
+        # 获取邮箱地址
         to_email = form.cleaned_data["email"]
 
+        # 生成验证码
         code = generate_code()
+        # 发送验证邮件
         utils.send_verify_email(to_email, code)
+        # 将验证码存入缓存
         utils.set_code(to_email, code)
 
-        return HttpResponse("ok")
+        # 返回成功响应
+        return HttpResponse("ok")

src/DjangoBlog/blog/admin.py

@@ -1,48 +1,72 @@
+# 导入Django表单模块
 from django import forms
+# 导入Django管理员模块
 from django.contrib import admin
+# 导入用户模型获取函数
 from django.contrib.auth import get_user_model
+# 导入URL反向解析模块
 from django.urls import reverse
+# 导入HTML格式化工具
 from django.utils.html import format_html
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
 
 # Register your models here.
+# 导入博客模型
 from .models import Article, Category, Tag, Links, SideBar, BlogSettings
 
 
+# 文章表单类
 class ArticleForm(forms.ModelForm):
     # body = forms.CharField(widget=AdminPagedownWidget())
 
     class Meta:
+        # 指定关联的模型
         model = Article
+        # 包含所有字段
         fields = '__all__'
 
 
+# 发布文章的管理动作函数
 def makr_article_publish(modeladmin, request, queryset):
+    # 将选中的文章状态更新为发布
     queryset.update(status='p')
 
 
+# 将文章设为草稿的管理动作函数
 def draft_article(modeladmin, request, queryset):
+    # 将选中的文章状态更新为草稿
     queryset.update(status='d')
 
 
+# 关闭文章评论的管理动作函数
 def close_article_commentstatus(modeladmin, request, queryset):
+    # 将选中的文章评论状态更新为关闭
     queryset.update(comment_status='c')
 
 
+# 打开文章评论的管理动作函数
 def open_article_commentstatus(modeladmin, request, queryset):
+    # 将选中的文章评论状态更新为打开
     queryset.update(comment_status='o')
 
 
+# 设置管理动作的显示描述
 makr_article_publish.short_description = _('Publish selected articles')
 draft_article.short_description = _('Draft selected articles')
 close_article_commentstatus.short_description = _('Close article comments')
 open_article_commentstatus.short_description = _('Open article comments')
 
 
+# 文章管理类
 class ArticlelAdmin(admin.ModelAdmin):
+    # 每页显示的文章数量
     list_per_page = 20
+    # 搜索字段
     search_fields = ('body', 'title')
+    # 使用的表单类
     form = ArticleForm
+    # 列表页面显示的字段
     list_display = (
         'id',
         'title',
@@ -53,62 +77,97 @@ class ArticlelAdmin(admin.ModelAdmin):
         'status',
         'type',
         'article_order')
+    # 列表中可作为链接点击的字段
     list_display_links = ('id', 'title')
+    # 列表过滤器
     list_filter = ('status', 'type', 'category')
+    # 日期层次导航
     date_hierarchy = 'creation_time'
+    # 水平过滤器（用于多对多字段）
     filter_horizontal = ('tags',)
+    # 排除的字段（不在表单中显示）
     exclude = ('creation_time', 'last_modify_time')
+    # 是否显示"在站点查看"按钮
     view_on_site = True
+    # 可用的管理动作
     actions = [
         makr_article_publish,
         draft_article,
         close_article_commentstatus,
         open_article_commentstatus]
+    # 使用原始ID字段（显示ID而不是下拉选择）
     raw_id_fields = ('author', 'category',)
 
+    # 自定义方法：显示分类链接
     def link_to_category(self, obj):
+        # 获取分类模型的app_label和model_name
         info = (obj.category._meta.app_label, obj.category._meta.model_name)
+        # 生成分类编辑页面的URL
         link = reverse('admin:%s_%s_change' % info, args=(obj.category.id,))
+        # 返回格式化的HTML链接
         return format_html(u'<a href="%s">%s</a>' % (link, obj.category.name))
 
+    # 设置自定义方法的显示名称
     link_to_category.short_description = _('category')
 
+    # 获取表单的方法
     def get_form(self, request, obj=None, **kwargs):
+        # 调用父类的get_form方法
         form = super(ArticlelAdmin, self).get_form(request, obj, **kwargs)
+        # 限制作者字段只能选择超级用户
         form.base_fields['author'].queryset = get_user_model(
         ).objects.filter(is_superuser=True)
+        # 返回表单
         return form
 
+    # 保存模型的方法
     def save_model(self, request, obj, form, change):
+        # 调用父类的save_model方法
         super(ArticlelAdmin, self).save_model(request, obj, form, change)
 
+    # 获取"在站点查看"按钮URL的方法
     def get_view_on_site_url(self, obj=None):
+        # 如果提供了对象
         if obj:
+            # 获取文章的完整URL
             url = obj.get_full_url()
             return url
         else:
+            # 否则返回当前站点域名
             from djangoblog.utils import get_current_site
             site = get_current_site().domain
             return site
 
 
+# 标签管理类
 class TagAdmin(admin.ModelAdmin):
+    # 排除的字段
     exclude = ('slug', 'last_mod_time', 'creation_time')
 
 
+# 分类管理类
 class CategoryAdmin(admin.ModelAdmin):
+    # 列表页面显示的字段
     list_display = ('name', 'parent_category', 'index')
+    # 排除的字段
     exclude = ('slug', 'last_mod_time', 'creation_time')
 
 
+# 友情链接管理类
 class LinksAdmin(admin.ModelAdmin):
+    # 排除的字段
     exclude = ('last_mod_time', 'creation_time')
 
 
+# 侧边栏管理类
 class SideBarAdmin(admin.ModelAdmin):
+    # 列表页面显示的字段
     list_display = ('name', 'content', 'is_enable', 'sequence')
+    # 排除的字段
     exclude = ('last_mod_time', 'creation_time')
 
 
+# 博客设置管理类
 class BlogSettingsAdmin(admin.ModelAdmin):
-    pass
+    # 使用默认配置
+    pass

src/DjangoBlog/blog/apps.py

@@ -1,5 +1,8 @@
+# 导入Django应用配置基类
 from django.apps import AppConfig
 
 
+# 定义博客应用的配置类
 class BlogConfig(AppConfig):
-    name = 'blog'
+    # 指定应用的完整Python路径
+    name = 'blog'

src/DjangoBlog/blog/context_processors.py

@@ -1,43 +1,76 @@
+# 导入日志模块
 import logging
 
+# 导入Django时区工具
 from django.utils import timezone
 
+# 导入自定义工具函数
 from djangoblog.utils import cache, get_blog_setting
+# 导入博客模型
 from .models import Category, Article
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
 
+# SEO处理器函数，用于生成模板上下文变量
 def seo_processor(requests):
+    # 缓存键名
     key = 'seo_processor'
+    # 尝试从缓存获取数据
     value = cache.get(key)
+    # 如果缓存中存在数据，直接返回
     if value:
         return value
     else:
+        # 记录日志，表示正在设置处理器缓存
         logger.info('set processor cache.')
+        # 获取博客设置
         setting = get_blog_setting()
+        # 构建上下文数据字典
         value = {
+            # 网站名称
             'SITE_NAME': setting.site_name,
+            # 是否显示谷歌广告
             'SHOW_GOOGLE_ADSENSE': setting.show_google_adsense,
+            # 谷歌广告代码
             'GOOGLE_ADSENSE_CODES': setting.google_adsense_codes,
+            # 网站SEO描述
             'SITE_SEO_DESCRIPTION': setting.site_seo_description,
+            # 网站描述
             'SITE_DESCRIPTION': setting.site_description,
+            # 网站关键词
             'SITE_KEYWORDS': setting.site_keywords,
+            # 网站基础URL
             'SITE_BASE_URL': requests.scheme + '://' + requests.get_host() + '/',
+            # 文章摘要长度
             'ARTICLE_SUB_LENGTH': setting.article_sub_length,
+            # 导航分类列表（所有分类）
             'nav_category_list': Category.objects.all(),
+            # 导航页面（类型为页面且已发布的文章）
             'nav_pages': Article.objects.filter(
                 type='p',
                 status='p'),
+            # 是否开启网站评论功能
             'OPEN_SITE_COMMENT': setting.open_site_comment,
+            # 备案号
             'BEIAN_CODE': setting.beian_code,
+            # 网站统计代码
             'ANALYTICS_CODE': setting.analytics_code,
+            # 公安备案号
             "BEIAN_CODE_GONGAN": setting.gongan_beiancode,
+            # 是否显示公安备案号
             "SHOW_GONGAN_CODE": setting.show_gongan_code,
+            # 当前年份
             "CURRENT_YEAR": timezone.now().year,
+            # 公共头部内容
             "GLOBAL_HEADER": setting.global_header,
+            # 公共尾部内容
             "GLOBAL_FOOTER": setting.global_footer,
+            # 评论是否需要审核
             "COMMENT_NEED_REVIEW": setting.comment_need_review,
         }
+        # 将数据存入缓存，有效期10小时
         cache.set(key, value, 60 * 60 * 10)
-        return value
+        # 返回上下文数据
+        return value

src/DjangoBlog/blog/documents.py

@@ -1,26 +1,41 @@
+# 导入时间模块
 import time
 
+# 导入Elasticsearch客户端模块
 import elasticsearch.client
+# 导入Django配置模块
 from django.conf import settings
+# 导入Elasticsearch DSL相关类
 from elasticsearch_dsl import Document, InnerDoc, Date, Integer, Long, Text, Object, GeoPoint, Keyword, Boolean
+# 导入Elasticsearch连接模块
 from elasticsearch_dsl.connections import connections
 
+# 导入文章模型
 from blog.models import Article
 
+# 检查是否启用Elasticsearch
 ELASTICSEARCH_ENABLED = hasattr(settings, 'ELASTICSEARCH_DSL')
 
+# 如果启用Elasticsearch，创建连接并设置geoip管道
 if ELASTICSEARCH_ENABLED:
+    # 创建Elasticsearch连接
     connections.create_connection(
         hosts=[settings.ELASTICSEARCH_DSL['default']['hosts']])
+    # 导入Elasticsearch客户端
     from elasticsearch import Elasticsearch
 
+    # 创建Elasticsearch客户端实例
     es = Elasticsearch(settings.ELASTICSEARCH_DSL['default']['hosts'])
+    # 导入Ingest客户端
     from elasticsearch.client import IngestClient
 
+    # 创建Ingest客户端
     c = IngestClient(es)
     try:
+        # 尝试获取geoip管道
         c.get_pipeline('geoip')
     except elasticsearch.exceptions.NotFoundError:
+        # 如果geoip管道不存在，创建它
         c.put_pipeline('geoip', body='''{
               "description" : "Add geoip info",
               "processors" : [
@@ -33,90 +48,139 @@ if ELASTICSEARCH_ENABLED:
             }''')
 
 
+# 定义GeoIP内部文档类
 class GeoIp(InnerDoc):
+    # 大洲名称字段
     continent_name = Keyword()
+    # 国家ISO代码字段
     country_iso_code = Keyword()
+    # 国家名称字段
     country_name = Keyword()
+    # 地理位置字段（经纬度）
     location = GeoPoint()
 
 
+# 定义用户代理浏览器内部文档类
 class UserAgentBrowser(InnerDoc):
+    # 浏览器家族字段
     Family = Keyword()
+    # 浏览器版本字段
     Version = Keyword()
 
 
+# 定义用户代理操作系统内部文档类，继承自UserAgentBrowser
 class UserAgentOS(UserAgentBrowser):
     pass
 
 
+# 定义用户代理设备内部文档类
 class UserAgentDevice(InnerDoc):
+    # 设备家族字段
     Family = Keyword()
+    # 设备品牌字段
     Brand = Keyword()
+    # 设备型号字段
     Model = Keyword()
 
 
+# 定义用户代理内部文档类
 class UserAgent(InnerDoc):
+    # 浏览器信息对象
     browser = Object(UserAgentBrowser, required=False)
+    # 操作系统信息对象
     os = Object(UserAgentOS, required=False)
+    # 设备信息对象
     device = Object(UserAgentDevice, required=False)
+    # 原始用户代理字符串
     string = Text()
+    # 是否为机器人标识
     is_bot = Boolean()
 
 
+# 定义耗时文档类，继承自Document
 class ElapsedTimeDocument(Document):
+    # URL字段
     url = Keyword()
+    # 耗时字段（毫秒）
     time_taken = Long()
+    # 日志时间字段
     log_datetime = Date()
+    # IP地址字段
     ip = Keyword()
+    # GeoIP信息对象
     geoip = Object(GeoIp, required=False)
+    # 用户代理信息对象
     useragent = Object(UserAgent, required=False)
 
+    # 索引配置类
     class Index:
+        # 索引名称
         name = 'performance'
+        # 索引设置
         settings = {
-            "number_of_shards": 1,
-            "number_of_replicas": 0
+            "number_of_shards": 1,  # 分片数量
+            "number_of_replicas": 0  # 副本数量
         }
 
+    # 元数据类
     class Meta:
+        # 文档类型
         doc_type = 'ElapsedTime'
 
 
+# 耗时文档管理器类
 class ElaspedTimeDocumentManager:
+    # 构建索引的静态方法
     @staticmethod
     def build_index():
         from elasticsearch import Elasticsearch
+        # 创建Elasticsearch客户端
         client = Elasticsearch(settings.ELASTICSEARCH_DSL['default']['hosts'])
+        # 检查索引是否存在
         res = client.indices.exists(index="performance")
+        # 如果索引不存在，初始化索引
         if not res:
             ElapsedTimeDocument.init()
 
+    # 删除索引的静态方法
     @staticmethod
     def delete_index():
         from elasticsearch import Elasticsearch
+        # 创建Elasticsearch客户端
         es = Elasticsearch(settings.ELASTICSEARCH_DSL['default']['hosts'])
+        # 删除索引，忽略400和404错误
         es.indices.delete(index='performance', ignore=[400, 404])
 
+    # 创建耗时文档的静态方法
     @staticmethod
     def create(url, time_taken, log_datetime, useragent, ip):
+        # 构建索引（如果不存在）
         ElaspedTimeDocumentManager.build_index()
+        # 创建用户代理对象
         ua = UserAgent()
+        # 设置浏览器信息
         ua.browser = UserAgentBrowser()
         ua.browser.Family = useragent.browser.family
         ua.browser.Version = useragent.browser.version_string
 
+        # 设置操作系统信息
         ua.os = UserAgentOS()
         ua.os.Family = useragent.os.family
         ua.os.Version = useragent.os.version_string
 
+        # 设置设备信息
         ua.device = UserAgentDevice()
         ua.device.Family = useragent.device.family
         ua.device.Brand = useragent.device.brand
         ua.device.Model = useragent.device.model
+        # 设置原始用户代理字符串
         ua.string = useragent.ua_string
+        # 设置是否为机器人标识
         ua.is_bot = useragent.is_bot
 
+        # 创建耗时文档对象
         doc = ElapsedTimeDocument(
+            # 使用当前时间戳作为文档ID
             meta={
                 'id': int(
                     round(
@@ -127,69 +191,99 @@ class ElaspedTimeDocumentManager:
             time_taken=time_taken,
             log_datetime=log_datetime,
             useragent=ua, ip=ip)
+        # 保存文档，使用geoip管道处理IP地址
         doc.save(pipeline="geoip")
 
 
+# 定义文章文档类，继承自Document
 class ArticleDocument(Document):
+    # 正文字段，使用ik分词器
     body = Text(analyzer='ik_max_word', search_analyzer='ik_smart')
+    # 标题字段，使用ik分词器
     title = Text(analyzer='ik_max_word', search_analyzer='ik_smart')
+    # 作者对象字段
     author = Object(properties={
         'nickname': Text(analyzer='ik_max_word', search_analyzer='ik_smart'),
         'id': Integer()
     })
+    # 分类对象字段
     category = Object(properties={
         'name': Text(analyzer='ik_max_word', search_analyzer='ik_smart'),
         'id': Integer()
     })
+    # 标签对象字段
     tags = Object(properties={
         'name': Text(analyzer='ik_max_word', search_analyzer='ik_smart'),
         'id': Integer()
     })
 
+    # 发布时间字段
     pub_time = Date()
+    # 状态字段
     status = Text()
+    # 评论状态字段
     comment_status = Text()
+    # 类型字段
     type = Text()
+    # 浏览量字段
     views = Integer()
+    # 文章排序字段
     article_order = Integer()
 
+    # 索引配置类
     class Index:
+        # 索引名称
         name = 'blog'
+        # 索引设置
         settings = {
-            "number_of_shards": 1,
-            "number_of_replicas": 0
+            "number_of_shards": 1,  # 分片数量
+            "number_of_replicas": 0  # 副本数量
         }
 
+    # 元数据类
     class Meta:
+        # 文档类型
         doc_type = 'Article'
 
 
+# 文章文档管理器类
 class ArticleDocumentManager():
 
+    # 初始化方法
     def __init__(self):
+        # 创建索引
         self.create_index()
 
+    # 创建索引方法
     def create_index(self):
         ArticleDocument.init()
 
+    # 删除索引方法
     def delete_index(self):
         from elasticsearch import Elasticsearch
+        # 创建Elasticsearch客户端
         es = Elasticsearch(settings.ELASTICSEARCH_DSL['default']['hosts'])
+        # 删除索引，忽略400和404错误
         es.indices.delete(index='blog', ignore=[400, 404])
 
+    # 将文章对象转换为文档对象的方法
     def convert_to_doc(self, articles):
         return [
             ArticleDocument(
+                # 使用文章ID作为文档ID
                 meta={
                     'id': article.id},
                 body=article.body,
                 title=article.title,
+                # 作者信息
                 author={
                     'nickname': article.author.username,
                     'id': article.author.id},
+                # 分类信息
                 category={
                     'name': article.category.name,
                     'id': article.category.id},
+                # 标签信息列表
                 tags=[
                     {
                         'name': t.name,
@@ -201,13 +295,20 @@ class ArticleDocumentManager():
                 views=article.views,
                 article_order=article.article_order) for article in articles]
 
+    # 重建索引方法
     def rebuild(self, articles=None):
+        # 初始化索引
         ArticleDocument.init()
+        # 获取所有文章或指定文章
         articles = articles if articles else Article.objects.all()
+        # 转换为文档对象
         docs = self.convert_to_doc(articles)
+        # 保存所有文档
         for doc in docs:
             doc.save()
 
+    # 更新文档方法
     def update_docs(self, docs):
+        # 保存更新的文档
         for doc in docs:
-            doc.save()
+            doc.save()

src/DjangoBlog/blog/forms.py

@@ -1,19 +1,32 @@
+# 导入日志模块
 import logging
 
+# 导入Django表单模块
 from django import forms
+# 导入Haystack搜索表单基类
 from haystack.forms import SearchForm
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
 
+# 博客搜索表单类，继承自Haystack的SearchForm
 class BlogSearchForm(SearchForm):
+    # 定义查询数据字段，设置为必填字段
     querydata = forms.CharField(required=True)
 
+    # 重写搜索方法
     def search(self):
+        # 调用父类的search方法获取基础搜索结果
         datas = super(BlogSearchForm, self).search()
+        # 检查表单数据是否有效
         if not self.is_valid():
+            # 如果表单无效，返回无查询结果
             return self.no_query_found()
 
+        # 如果查询数据存在且有效
         if self.cleaned_data['querydata']:
+            # 记录查询数据的日志
             logger.info(self.cleaned_data['querydata'])
-        return datas
+        # 返回搜索结果
+        return datas

src/DjangoBlog/blog/management/commands/build_index.py

@@ -1,18 +1,29 @@
+# 导入Django管理命令基类
 from django.core.management.base import BaseCommand
 
+# 导入Elasticsearch相关文档和管理器类
 from blog.documents import ElapsedTimeDocument, ArticleDocumentManager, ElaspedTimeDocumentManager, \
     ELASTICSEARCH_ENABLED
 
 
 # TODO 参数化
+# 自定义管理命令类，用于构建搜索索引
 class Command(BaseCommand):
+    # 命令的帮助信息
     help = 'build search index'
 
+    # 命令的主要处理逻辑
     def handle(self, *args, **options):
+        # 检查Elasticsearch是否启用
         if ELASTICSEARCH_ENABLED:
+            # 构建耗时文档的索引
             ElaspedTimeDocumentManager.build_index()
+            # 创建耗时文档管理器实例并初始化
             manager = ElapsedTimeDocument()
             manager.init()
+            # 创建文章文档管理器实例
             manager = ArticleDocumentManager()
+            # 删除现有索引
             manager.delete_index()
-            manager.rebuild()
+            # 重新构建索引
+            manager.rebuild()

src/DjangoBlog/blog/management/commands/build_search_words.py

@@ -1,13 +1,20 @@
+# 导入Django管理命令基类
 from django.core.management.base import BaseCommand
 
+# 导入博客模型
 from blog.models import Tag, Category
 
 
 # TODO 参数化
+# 自定义管理命令类，用于构建搜索词
 class Command(BaseCommand):
+    # 命令的帮助信息
     help = 'build search words'
 
+    # 命令的主要处理逻辑
     def handle(self, *args, **options):
+        # 构建搜索词数据集：获取所有标签名称和分类名称，使用集合去重
         datas = set([t.name for t in Tag.objects.all()] +
                     [t.name for t in Category.objects.all()])
-        print('\n'.join(datas))
+        # 将数据集中的每个搜索词按行打印输出
+        print('\n'.join(datas))

src/DjangoBlog/blog/management/commands/clear_cache.py

@@ -1,11 +1,18 @@
+# 导入Django管理命令基类
 from django.core.management.base import BaseCommand
 
+# 导入缓存工具
 from djangoblog.utils import cache
 
 
+# 自定义管理命令类，用于清除整个缓存
 class Command(BaseCommand):
+    # 命令的帮助信息
     help = 'clear the whole cache'
 
+    # 命令的主要处理逻辑
     def handle(self, *args, **options):
+        # 清除所有缓存
         cache.clear()
-        self.stdout.write(self.style.SUCCESS('Cleared cache\n'))
+        # 输出成功信息到标准输出
+        self.stdout.write(self.style.SUCCESS('Cleared cache\n'))

src/DjangoBlog/blog/management/commands/create_testdata.py

@@ -1,40 +1,58 @@
+# 导入Django认证系统相关模块
 from django.contrib.auth import get_user_model
 from django.contrib.auth.hashers import make_password
 from django.core.management.base import BaseCommand
 
+# 导入博客模型
 from blog.models import Article, Tag, Category
 
 
+# 自定义管理命令类，用于创建测试数据
 class Command(BaseCommand):
+    # 命令的帮助信息
     help = 'create test datas'
 
+    # 命令的主要处理逻辑
     def handle(self, *args, **options):
+        # 获取或创建测试用户
         user = get_user_model().objects.get_or_create(
             email='test@test.com', username='测试用户', password=make_password('test!q@w#eTYU'))[0]
 
+        # 获取或创建父类目
         pcategory = Category.objects.get_or_create(
             name='我是父类目', parent_category=None)[0]
 
+        # 获取或创建子类目
         category = Category.objects.get_or_create(
             name='子类目', parent_category=pcategory)[0]
 
+        # 保存子类目
         category.save()
+        # 创建基础标签
         basetag = Tag()
         basetag.name = "标签"
         basetag.save()
+        # 循环创建20篇测试文章
         for i in range(1, 20):
+            # 获取或创建文章
             article = Article.objects.get_or_create(
                 category=category,
                 title='nice title ' + str(i),
                 body='nice content ' + str(i),
                 author=user)[0]
+            # 创建新标签
             tag = Tag()
             tag.name = "标签" + str(i)
             tag.save()
+            # 为文章添加标签
             article.tags.add(tag)
             article.tags.add(basetag)
+            # 保存文章
             article.save()
 
+        # 导入缓存工具
         from djangoblog.utils import cache
+        # 清除所有缓存
         cache.clear()
-        self.stdout.write(self.style.SUCCESS('created test datas \n'))
+        # 输出成功信息到标准输出
+        self.stdout.write(self.style.SUCCESS('created test datas \n'))

src/DjangoBlog/blog/management/commands/ping_baidu.py

@@ -1,15 +1,22 @@
+# 导入Django管理命令基类
 from django.core.management.base import BaseCommand
 
+# 导入蜘蛛通知工具和站点工具
 from djangoblog.spider_notify import SpiderNotify
 from djangoblog.utils import get_current_site
+# 导入博客模型
 from blog.models import Article, Tag, Category
 
+# 获取当前站点域名
 site = get_current_site().domain
 
 
+# 自定义管理命令类，用于通知百度搜索引擎URL更新
 class Command(BaseCommand):
+    # 命令的帮助信息
     help = 'notify baidu url'
 
+    # 添加命令行参数
     def add_arguments(self, parser):
         parser.add_argument(
             'data_type',
@@ -21,30 +28,42 @@ class Command(BaseCommand):
                 'category'],
             help='article : all article,tag : all tag,category: all category,all: All of these')
 
+    # 获取完整URL的方法
     def get_full_url(self, path):
+        # 构建包含域名的完整URL
         url = "https://{site}{path}".format(site=site, path=path)
         return url
 
+    # 命令的主要处理逻辑
     def handle(self, *args, **options):
+        # 获取命令行参数中的数据类型
         type = options['data_type']
+        # 输出开始处理的信息
         self.stdout.write('start get %s' % type)
 
+        # 初始化URL列表
         urls = []
+        # 如果类型是文章或全部，获取所有已发布文章的URL
         if type == 'article' or type == 'all':
             for article in Article.objects.filter(status='p'):
                 urls.append(article.get_full_url())
+        # 如果类型是标签或全部，获取所有标签的URL
         if type == 'tag' or type == 'all':
             for tag in Tag.objects.all():
                 url = tag.get_absolute_url()
                 urls.append(self.get_full_url(url))
+        # 如果类型是分类或全部，获取所有分类的URL
         if type == 'category' or type == 'all':
             for category in Category.objects.all():
                 url = category.get_absolute_url()
                 urls.append(self.get_full_url(url))
 
+        # 输出开始通知的信息，显示URL数量
         self.stdout.write(
             self.style.SUCCESS(
                 'start notify %d urls' %
                 len(urls)))
+        # 调用百度蜘蛛通知工具，通知所有URL
         SpiderNotify.baidu_notify(urls)
-        self.stdout.write(self.style.SUCCESS('finish notify'))
+        # 输出完成通知的信息
+        self.stdout.write(self.style.SUCCESS('finish notify'))

src/DjangoBlog/blog/management/commands/sync_user_avatar.py

@@ -1,47 +1,82 @@
+# 导入请求库
 import requests
+# 导入Django管理命令基类
 from django.core.management.base import BaseCommand
+# 导入静态文件处理模块
 from django.templatetags.static import static
 
+# 导入自定义工具函数
 from djangoblog.utils import save_user_avatar
+# 导入OAuth用户模型
 from oauth.models import OAuthUser
+# 导入OAuth管理器获取函数
 from oauth.oauthmanager import get_manager_by_type
 
 
+# 自定义管理命令类，用于同步用户头像
 class Command(BaseCommand):
+    # 命令的帮助信息
     help = 'sync user avatar'
 
+    # 测试图片URL是否可访问的方法
     def test_picture(self, url):
         try:
+            # 发送GET请求测试图片URL，设置2秒超时
             if requests.get(url, timeout=2).status_code == 200:
+                # 如果返回状态码为200，说明图片可访问
                 return True
         except:
+            # 如果发生任何异常，说明图片不可访问
             pass
 
+    # 命令的主要处理逻辑
     def handle(self, *args, **options):
+        # 获取静态文件基础URL
         static_url = static("../")
+        # 获取所有OAuth用户
         users = OAuthUser.objects.all()
+        # 输出开始同步的信息，显示用户数量
         self.stdout.write(f'开始同步{len(users)}个用户头像')
+        # 遍历每个用户
         for u in users:
+            # 输出开始同步当前用户的信息
             self.stdout.write(f'开始同步:{u.nickname}')
+            # 获取用户的头像URL
             url = u.picture
+            # 如果存在头像URL
             if url:
+                # 检查URL是否以静态文件路径开头
                 if url.startswith(static_url):
+                    # 测试静态图片是否可访问
                     if self.test_picture(url):
+                        # 如果可访问，跳过当前用户
                         continue
                     else:
+                        # 如果不可访问，检查用户是否有元数据
                         if u.metadata:
+                            # 根据用户类型获取对应的OAuth管理器
                             manage = get_manager_by_type(u.type)
+                            # 从元数据中获取头像URL
                             url = manage.get_picture(u.metadata)
+                            # 保存用户头像并返回新的URL
                             url = save_user_avatar(url)
                         else:
+                            # 如果没有元数据，使用默认头像
                             url = static('blog/img/avatar.png')
                 else:
+                    # 如果不是静态文件路径，直接保存用户头像
                     url = save_user_avatar(url)
             else:
+                # 如果没有头像URL，使用默认头像
                 url = static('blog/img/avatar.png')
+            # 如果成功获取到头像URL
             if url:
+                # 输出结束同步当前用户的信息
                 self.stdout.write(
                     f'结束同步:{u.nickname}.url:{url}')
+                # 更新用户的头像URL
                 u.picture = url
+                # 保存用户信息
                 u.save()
-        self.stdout.write('结束同步')
+        # 输出结束同步的信息
+        self.stdout.write('结束同步')

src/DjangoBlog/blog/middleware.py

@@ -1,42 +1,68 @@
+# 导入日志模块
 import logging
+# 导入时间模块
 import time
 
+# 导入IP获取工具
 from ipware import get_client_ip
+# 导入用户代理解析工具
 from user_agents import parse
 
+# 导入Elasticsearch相关配置和管理器
 from blog.documents import ELASTICSEARCH_ENABLED, ElaspedTimeDocumentManager
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
 
+# 在线中间件类，用于记录页面渲染时间和用户访问信息
 class OnlineMiddleware(object):
+    # 初始化方法
     def __init__(self, get_response=None):
+        # 保存get_response函数引用
         self.get_response = get_response
+        # 调用父类的初始化方法
         super().__init__()
 
+    # 调用方法，处理请求和响应
     def __call__(self, request):
         ''' page render time '''
+        # 记录请求开始时间
         start_time = time.time()
+        # 调用后续中间件和视图，获取响应
         response = self.get_response(request)
+        # 获取用户代理字符串
         http_user_agent = request.META.get('HTTP_USER_AGENT', '')
+        # 获取客户端IP地址
         ip, _ = get_client_ip(request)
+        # 解析用户代理信息
         user_agent = parse(http_user_agent)
+        # 检查响应是否为流式响应
         if not response.streaming:
             try:
+                # 计算页面渲染耗时
                 cast_time = time.time() - start_time
+                # 如果启用了Elasticsearch
                 if ELASTICSEARCH_ENABLED:
+                    # 将耗时转换为毫秒并保留两位小数
                     time_taken = round((cast_time) * 1000, 2)
+                    # 获取请求的URL路径
                     url = request.path
+                    # 导入Django时区工具
                     from django.utils import timezone
+                    # 创建耗时文档记录
                     ElaspedTimeDocumentManager.create(
                         url=url,
                         time_taken=time_taken,
                         log_datetime=timezone.now(),
                         useragent=user_agent,
                         ip=ip)
+                # 在响应内容中替换加载时间占位符
                 response.content = response.content.replace(
                     b'<!!LOAD_TIMES!!>', str.encode(str(cast_time)[:5]))
             except Exception as e:
+                # 记录中间件执行过程中的错误
                 logger.error("Error OnlineMiddleware: %s" % e)
 
-        return response
+        # 返回响应对象
+        return response

src/DjangoBlog/blog/migrations/0001_initial.py

@@ -1,137 +1,228 @@
 # Generated by Django 4.1.7 on 2023-03-02 07:14
 
+# 导入Django设置模块
 from django.conf import settings
+# 导入数据库迁移和模型模块
 from django.db import migrations, models
+# 导入数据库删除操作模块
 import django.db.models.deletion
+# 导入时区工具
 import django.utils.timezone
+# 导入Markdown编辑器字段
 import mdeditor.fields
 
 
+# 数据库迁移类
 class Migration(migrations.Migration):
 
+    # 标记为初始迁移
     initial = True
 
+    # 依赖关系，依赖于用户模型的迁移
     dependencies = [
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
 
+    # 迁移操作列表
     operations = [
+        # 创建博客设置表
         migrations.CreateModel(
             name='BlogSettings',
             fields=[
+                # 主键ID，使用BigAutoField自增字段
                 ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                # 网站名称字段，默认值为空字符串
                 ('sitename', models.CharField(default='', max_length=200, verbose_name='网站名称')),
+                # 网站描述字段，文本类型
                 ('site_description', models.TextField(default='', max_length=1000, verbose_name='网站描述')),
+                # 网站SEO描述字段
                 ('site_seo_description', models.TextField(default='', max_length=1000, verbose_name='网站SEO描述')),
+                # 网站关键字字段
                 ('site_keywords', models.TextField(default='', max_length=1000, verbose_name='网站关键字')),
+                # 文章摘要长度字段，整数类型，默认300
                 ('article_sub_length', models.IntegerField(default=300, verbose_name='文章摘要长度')),
+                # 侧边栏文章数目字段，默认10
                 ('sidebar_article_count', models.IntegerField(default=10, verbose_name='侧边栏文章数目')),
+                # 侧边栏评论数目字段，默认5
                 ('sidebar_comment_count', models.IntegerField(default=5, verbose_name='侧边栏评论数目')),
+                # 文章页面默认显示评论数目字段，默认5
                 ('article_comment_count', models.IntegerField(default=5, verbose_name='文章页面默认显示评论数目')),
+                # 是否显示谷歌广告字段，布尔类型，默认False
                 ('show_google_adsense', models.BooleanField(default=False, verbose_name='是否显示谷歌广告')),
+                # 谷歌广告代码字段，可为空
                 ('google_adsense_codes', models.TextField(blank=True, default='', max_length=2000, null=True, verbose_name='广告内容')),
+                # 是否打开网站评论功能字段，布尔类型，默认True
                 ('open_site_comment', models.BooleanField(default=True, verbose_name='是否打开网站评论功能')),
+                # 备案号字段，可为空
                 ('beiancode', models.CharField(blank=True, default='', max_length=2000, null=True, verbose_name='备案号')),
+                # 网站统计代码字段
                 ('analyticscode', models.TextField(default='', max_length=1000, verbose_name='网站统计代码')),
+                # 是否显示公安备案号字段，布尔类型，默认False
                 ('show_gongan_code', models.BooleanField(default=False, verbose_name='是否显示公安备案号')),
+                # 公安备案号字段，可为空
                 ('gongan_beiancode', models.TextField(blank=True, default='', max_length=2000, null=True, verbose_name='公安备案号')),
             ],
             options={
+                # 单数形式的显示名称
                 'verbose_name': '网站配置',
+                # 复数形式的显示名称
                 'verbose_name_plural': '网站配置',
             },
         ),
+        # 创建友情链接表
         migrations.CreateModel(
             name='Links',
             fields=[
+                # 主键ID
                 ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                # 链接名称字段，具有唯一性约束
                 ('name', models.CharField(max_length=30, unique=True, verbose_name='链接名称')),
+                # 链接地址字段，URL格式
                 ('link', models.URLField(verbose_name='链接地址')),
+                # 排序字段，整数类型，具有唯一性约束
                 ('sequence', models.IntegerField(unique=True, verbose_name='排序')),
+                # 是否显示字段，布尔类型，默认True
                 ('is_enable', models.BooleanField(default=True, verbose_name='是否显示')),
+                # 显示类型字段，选择类型，有多个选项
                 ('show_type', models.CharField(choices=[('i', '首页'), ('l', '列表页'), ('p', '文章页面'), ('a', '全站'), ('s', '友情链接页面')], default='i', max_length=1, verbose_name='显示类型')),
+                # 创建时间字段，默认当前时间
                 ('created_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='创建时间')),
+                # 最后修改时间字段，默认当前时间
                 ('last_mod_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='修改时间')),
             ],
             options={
+                # 单数形式的显示名称
                 'verbose_name': '友情链接',
+                # 复数形式的显示名称
                 'verbose_name_plural': '友情链接',
+                # 默认按排序字段升序排列
                 'ordering': ['sequence'],
             },
         ),
+        # 创建侧边栏表
         migrations.CreateModel(
             name='SideBar',
             fields=[
+                # 主键ID
                 ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                # 标题字段
                 ('name', models.CharField(max_length=100, verbose_name='标题')),
+                # 内容字段，文本类型
                 ('content', models.TextField(verbose_name='内容')),
+                # 排序字段，整数类型，具有唯一性约束
                 ('sequence', models.IntegerField(unique=True, verbose_name='排序')),
+                # 是否启用字段，布尔类型，默认True
                 ('is_enable', models.BooleanField(default=True, verbose_name='是否启用')),
+                # 创建时间字段，默认当前时间
                 ('created_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='创建时间')),
+                # 最后修改时间字段，默认当前时间
                 ('last_mod_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='修改时间')),
             ],
             options={
+                # 单数形式的显示名称
                 'verbose_name': '侧边栏',
+                # 复数形式的显示名称
                 'verbose_name_plural': '侧边栏',
+                # 默认按排序字段升序排列
                 'ordering': ['sequence'],
             },
         ),
+        # 创建标签表
         migrations.CreateModel(
             name='Tag',
             fields=[
+                # 主键ID，使用AutoField自增字段
                 ('id', models.AutoField(primary_key=True, serialize=False)),
+                # 创建时间字段，默认当前时间
                 ('created_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='创建时间')),
+                # 最后修改时间字段，默认当前时间
                 ('last_mod_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='修改时间')),
+                # 标签名字段，具有唯一性约束
                 ('name', models.CharField(max_length=30, unique=True, verbose_name='标签名')),
+                # 标签slug字段，用于URL，可为空，默认值'no-slug'
                 ('slug', models.SlugField(blank=True, default='no-slug', max_length=60)),
             ],
             options={
+                # 单数形式的显示名称
                 'verbose_name': '标签',
+                # 复数形式的显示名称
                 'verbose_name_plural': '标签',
+                # 默认按标签名升序排列
                 'ordering': ['name'],
             },
         ),
+        # 创建分类表
         migrations.CreateModel(
             name='Category',
             fields=[
+                # 主键ID，使用AutoField自增字段
                 ('id', models.AutoField(primary_key=True, serialize=False)),
+                # 创建时间字段，默认当前时间
                 ('created_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='创建时间')),
+                # 最后修改时间字段，默认当前时间
                 ('last_mod_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='修改时间')),
+                # 分类名字段，具有唯一性约束
                 ('name', models.CharField(max_length=30, unique=True, verbose_name='分类名')),
+                # 分类slug字段，用于URL，可为空，默认值'no-slug'
                 ('slug', models.SlugField(blank=True, default='no-slug', max_length=60)),
+                # 权重排序字段，整数类型，默认0，越大越靠前
                 ('index', models.IntegerField(default=0, verbose_name='权重排序-越大越靠前')),
+                # 父级分类字段，外键关联到自身，可为空
                 ('parent_category', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, to='blog.category', verbose_name='父级分类')),
             ],
             options={
+                # 单数形式的显示名称
                 'verbose_name': '分类',
+                # 复数形式的显示名称
                 'verbose_name_plural': '分类',
+                # 默认按权重倒序排列
                 'ordering': ['-index'],
             },
         ),
+        # 创建文章表
         migrations.CreateModel(
             name='Article',
             fields=[
+                # 主键ID，使用AutoField自增字段
                 ('id', models.AutoField(primary_key=True, serialize=False)),
+                # 创建时间字段，默认当前时间
                 ('created_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='创建时间')),
+                # 最后修改时间字段，默认当前时间
                 ('last_mod_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='修改时间')),
+                # 标题字段，具有唯一性约束
                 ('title', models.CharField(max_length=200, unique=True, verbose_name='标题')),
+                # 正文字段，使用Markdown编辑器
                 ('body', mdeditor.fields.MDTextField(verbose_name='正文')),
+                # 发布时间字段，默认当前时间
                 ('pub_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='发布时间')),
+                # 文章状态字段，选择类型，草稿或发表
                 ('status', models.CharField(choices=[('d', '草稿'), ('p', '发表')], default='p', max_length=1, verbose_name='文章状态')),
+                # 评论状态字段，选择类型，打开或关闭
                 ('comment_status', models.CharField(choices=[('o', '打开'), ('c', '关闭')], default='o', max_length=1, verbose_name='评论状态')),
+                # 类型字段，选择类型，文章或页面
                 ('type', models.CharField(choices=[('a', '文章'), ('p', '页面')], default='a', max_length=1, verbose_name='类型')),
+                # 浏览量字段，正整数类型，默认0
                 ('views', models.PositiveIntegerField(default=0, verbose_name='浏览量')),
+                # 文章排序字段，整数类型，默认0，数字越大越靠前
                 ('article_order', models.IntegerField(default=0, verbose_name='排序,数字越大越靠前')),
+                # 是否显示toc目录字段，布尔类型，默认False
                 ('show_toc', models.BooleanField(default=False, verbose_name='是否显示toc目录')),
+                # 作者字段，外键关联到用户模型
                 ('author', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL, verbose_name='作者')),
+                # 分类字段，外键关联到分类模型
                 ('category', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='blog.category', verbose_name='分类')),
+                # 标签集合字段，多对多关联到标签模型，可为空
                 ('tags', models.ManyToManyField(blank=True, to='blog.tag', verbose_name='标签集合')),
             ],
             options={
+                # 单数形式的显示名称
                 'verbose_name': '文章',
+                # 复数形式的显示名称
                 'verbose_name_plural': '文章',
+                # 默认按文章排序倒序、发布时间倒序排列
                 'ordering': ['-article_order', '-pub_time'],
+                # 指定获取最新记录的依据字段
                 'get_latest_by': 'id',
             },
         ),
-    ]
+    ]

src/DjangoBlog/blog/migrations/0002_blogsettings_global_footer_and_more.py

@@ -1,23 +1,31 @@
 # Generated by Django 4.1.7 on 2023-03-29 06:08
 
+# 导入数据库迁移和模型模块
 from django.db import migrations, models
 
 
+# 数据库迁移类
 class Migration(migrations.Migration):
 
+    # 依赖关系，依赖于blog应用的0001_initial迁移
     dependencies = [
         ('blog', '0001_initial'),
     ]
 
+    # 迁移操作列表
     operations = [
+        # 向BlogSettings模型添加global_footer字段
         migrations.AddField(
             model_name='blogsettings',
             name='global_footer',
+            # 文本类型字段，用于存储公共尾部内容
             field=models.TextField(blank=True, default='', null=True, verbose_name='公共尾部'),
         ),
+        # 向BlogSettings模型添加global_header字段
         migrations.AddField(
             model_name='blogsettings',
             name='global_header',
+            # 文本类型字段，用于存储公共头部内容
             field=models.TextField(blank=True, default='', null=True, verbose_name='公共头部'),
         ),
-    ]
+    ]

src/DjangoBlog/blog/migrations/0003_blogsettings_comment_need_review.py

@@ -1,17 +1,23 @@
 # Generated by Django 4.2.1 on 2023-05-09 07:45
 
+# 导入数据库迁移和模型模块
 from django.db import migrations, models
 
 
+# 数据库迁移类
 class Migration(migrations.Migration):
+    # 依赖关系，依赖于blog应用的0002_blogsettings_global_footer_and_more迁移
     dependencies = [
         ('blog', '0002_blogsettings_global_footer_and_more'),
     ]
 
+    # 迁移操作列表
     operations = [
+        # 向BlogSettings模型添加comment_need_review字段
         migrations.AddField(
             model_name='blogsettings',
             name='comment_need_review',
+            # 布尔类型字段，用于控制评论是否需要审核，默认值为False
             field=models.BooleanField(default=False, verbose_name='评论是否需要审核'),
         ),
-    ]
+    ]

src/DjangoBlog/blog/migrations/0004_rename_analyticscode_blogsettings_analytics_code_and_more.py

@@ -1,27 +1,40 @@
 # Generated by Django 4.2.1 on 2023-05-09 07:51
 
+# 导入数据库迁移模块
 from django.db import migrations
 
 
+# 数据库迁移类
 class Migration(migrations.Migration):
+    # 依赖关系，依赖于blog应用的0003_blogsettings_comment_need_review迁移
     dependencies = [
         ('blog', '0003_blogsettings_comment_need_review'),
     ]
 
+    # 迁移操作列表
     operations = [
+        # 重命名字段操作：将analyticscode重命名为analytics_code
         migrations.RenameField(
             model_name='blogsettings',
+            # 原字段名
             old_name='analyticscode',
+            # 新字段名
             new_name='analytics_code',
         ),
+        # 重命名字段操作：将beiancode重命名为beian_code
         migrations.RenameField(
             model_name='blogsettings',
+            # 原字段名
             old_name='beiancode',
+            # 新字段名
             new_name='beian_code',
         ),
+        # 重命名字段操作：将sitename重命名为site_name
         migrations.RenameField(
             model_name='blogsettings',
+            # 原字段名
             old_name='sitename',
+            # 新字段名
             new_name='site_name',
         ),
-    ]
+    ]

src/DjangoBlog/blog/migrations/0005_alter_article_options_alter_category_options_and_more.py

@@ -1,300 +1,367 @@
 # Generated by Django 4.2.5 on 2023-09-06 13:13
 
+# 导入Django设置模块
 from django.conf import settings
+# 导入数据库迁移和模型模块
 from django.db import migrations, models
+# 导入数据库删除操作模块
 import django.db.models.deletion
+# 导入时区工具
 import django.utils.timezone
+# 导入Markdown编辑器字段
 import mdeditor.fields
 
 
+# 数据库迁移类
 class Migration(migrations.Migration):
 
+    # 依赖关系，依赖于blog应用的0004重命名字段迁移和用户模型
     dependencies = [
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
         ('blog', '0004_rename_analyticscode_blogsettings_analytics_code_and_more'),
     ]
 
+    # 迁移操作列表
     operations = [
+        # 修改Article模型的元数据选项，更新显示名称和排序
         migrations.AlterModelOptions(
             name='article',
             options={'get_latest_by': 'id', 'ordering': ['-article_order', '-pub_time'], 'verbose_name': 'article', 'verbose_name_plural': 'article'},
         ),
+        # 修改Category模型的元数据选项，更新显示名称
         migrations.AlterModelOptions(
             name='category',
             options={'ordering': ['-index'], 'verbose_name': 'category', 'verbose_name_plural': 'category'},
         ),
+        # 修改Links模型的元数据选项，更新显示名称
         migrations.AlterModelOptions(
             name='links',
             options={'ordering': ['sequence'], 'verbose_name': 'link', 'verbose_name_plural': 'link'},
         ),
+        # 修改Sidebar模型的元数据选项，更新显示名称
         migrations.AlterModelOptions(
             name='sidebar',
             options={'ordering': ['sequence'], 'verbose_name': 'sidebar', 'verbose_name_plural': 'sidebar'},
         ),
+        # 修改Tag模型的元数据选项，更新显示名称
         migrations.AlterModelOptions(
             name='tag',
             options={'ordering': ['name'], 'verbose_name': 'tag', 'verbose_name_plural': 'tag'},
         ),
+        # 删除Article模型的created_time字段
         migrations.RemoveField(
             model_name='article',
             name='created_time',
         ),
+        # 删除Article模型的last_mod_time字段
         migrations.RemoveField(
             model_name='article',
             name='last_mod_time',
         ),
+        # 删除Category模型的created_time字段
         migrations.RemoveField(
             model_name='category',
             name='created_time',
         ),
+        # 删除Category模型的last_mod_time字段
         migrations.RemoveField(
             model_name='category',
             name='last_mod_time',
         ),
+        # 删除Links模型的created_time字段
         migrations.RemoveField(
             model_name='links',
             name='created_time',
         ),
+        # 删除Sidebar模型的created_time字段
         migrations.RemoveField(
             model_name='sidebar',
             name='created_time',
         ),
+        # 删除Tag模型的created_time字段
         migrations.RemoveField(
             model_name='tag',
             name='created_time',
         ),
+        # 删除Tag模型的last_mod_time字段
         migrations.RemoveField(
             model_name='tag',
             name='last_mod_time',
         ),
+        # 向Article模型添加creation_time字段
         migrations.AddField(
             model_name='article',
             name='creation_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='creation time'),
         ),
+        # 向Article模型添加last_modify_time字段
         migrations.AddField(
             model_name='article',
             name='last_modify_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='modify time'),
         ),
+        # 向Category模型添加creation_time字段
         migrations.AddField(
             model_name='category',
             name='creation_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='creation time'),
         ),
+        # 向Category模型添加last_modify_time字段
         migrations.AddField(
             model_name='category',
             name='last_modify_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='modify time'),
         ),
+        # 向Links模型添加creation_time字段
         migrations.AddField(
             model_name='links',
             name='creation_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='creation time'),
         ),
+        # 向Sidebar模型添加creation_time字段
         migrations.AddField(
             model_name='sidebar',
             name='creation_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='creation time'),
         ),
+        # 向Tag模型添加creation_time字段
         migrations.AddField(
             model_name='tag',
             name='creation_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='creation time'),
         ),
+        # 向Tag模型添加last_modify_time字段
         migrations.AddField(
             model_name='tag',
             name='last_modify_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='modify time'),
         ),
+        # 修改Article模型的article_order字段的verbose_name
         migrations.AlterField(
             model_name='article',
             name='article_order',
             field=models.IntegerField(default=0, verbose_name='order'),
         ),
+        # 修改Article模型的author字段的verbose_name
         migrations.AlterField(
             model_name='article',
             name='author',
             field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL, verbose_name='author'),
         ),
+        # 修改Article模型的body字段的verbose_name
         migrations.AlterField(
             model_name='article',
             name='body',
             field=mdeditor.fields.MDTextField(verbose_name='body'),
         ),
+        # 修改Article模型的category字段的verbose_name
         migrations.AlterField(
             model_name='article',
             name='category',
             field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='blog.category', verbose_name='category'),
         ),
+        # 修改Article模型的comment_status字段的verbose_name和选项值
         migrations.AlterField(
             model_name='article',
             name='comment_status',
             field=models.CharField(choices=[('o', 'Open'), ('c', 'Close')], default='o', max_length=1, verbose_name='comment status'),
         ),
+        # 修改Article模型的pub_time字段的verbose_name
         migrations.AlterField(
             model_name='article',
             name='pub_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='publish time'),
         ),
+        # 修改Article模型的show_toc字段的verbose_name
         migrations.AlterField(
             model_name='article',
             name='show_toc',
             field=models.BooleanField(default=False, verbose_name='show toc'),
         ),
+        # 修改Article模型的status字段的verbose_name和选项值
         migrations.AlterField(
             model_name='article',
             name='status',
             field=models.CharField(choices=[('d', 'Draft'), ('p', 'Published')], default='p', max_length=1, verbose_name='status'),
         ),
+        # 修改Article模型的tags字段的verbose_name
         migrations.AlterField(
             model_name='article',
             name='tags',
             field=models.ManyToManyField(blank=True, to='blog.tag', verbose_name='tag'),
         ),
+        # 修改Article模型的title字段的verbose_name
         migrations.AlterField(
             model_name='article',
             name='title',
             field=models.CharField(max_length=200, unique=True, verbose_name='title'),
         ),
+        # 修改Article模型的type字段的verbose_name和选项值
         migrations.AlterField(
             model_name='article',
             name='type',
             field=models.CharField(choices=[('a', 'Article'), ('p', 'Page')], default='a', max_length=1, verbose_name='type'),
         ),
+        # 修改Article模型的views字段的verbose_name
         migrations.AlterField(
             model_name='article',
             name='views',
             field=models.PositiveIntegerField(default=0, verbose_name='views'),
         ),
+        # 修改BlogSettings模型的article_comment_count字段的verbose_name
         migrations.AlterField(
             model_name='blogsettings',
             name='article_comment_count',
             field=models.IntegerField(default=5, verbose_name='article comment count'),
         ),
+        # 修改BlogSettings模型的article_sub_length字段的verbose_name
         migrations.AlterField(
             model_name='blogsettings',
             name='article_sub_length',
             field=models.IntegerField(default=300, verbose_name='article sub length'),
         ),
+        # 修改BlogSettings模型的google_adsense_codes字段的verbose_name
         migrations.AlterField(
             model_name='blogsettings',
             name='google_adsense_codes',
             field=models.TextField(blank=True, default='', max_length=2000, null=True, verbose_name='adsense code'),
         ),
+        # 修改BlogSettings模型的open_site_comment字段的verbose_name
         migrations.AlterField(
             model_name='blogsettings',
             name='open_site_comment',
             field=models.BooleanField(default=True, verbose_name='open site comment'),
         ),
+        # 修改BlogSettings模型的show_google_adsense字段的verbose_name
         migrations.AlterField(
             model_name='blogsettings',
             name='show_google_adsense',
             field=models.BooleanField(default=False, verbose_name='show adsense'),
         ),
+        # 修改BlogSettings模型的sidebar_article_count字段的verbose_name
         migrations.AlterField(
             model_name='blogsettings',
             name='sidebar_article_count',
             field=models.IntegerField(default=10, verbose_name='sidebar article count'),
         ),
+        # 修改BlogSettings模型的sidebar_comment_count字段的verbose_name
         migrations.AlterField(
             model_name='blogsettings',
             name='sidebar_comment_count',
             field=models.IntegerField(default=5, verbose_name='sidebar comment count'),
         ),
+        # 修改BlogSettings模型的site_description字段的verbose_name
         migrations.AlterField(
             model_name='blogsettings',
             name='site_description',
             field=models.TextField(default='', max_length=1000, verbose_name='site description'),
         ),
+        # 修改BlogSettings模型的site_keywords字段的verbose_name
         migrations.AlterField(
             model_name='blogsettings',
             name='site_keywords',
             field=models.TextField(default='', max_length=1000, verbose_name='site keywords'),
         ),
+        # 修改BlogSettings模型的site_name字段的verbose_name
         migrations.AlterField(
             model_name='blogsettings',
             name='site_name',
             field=models.CharField(default='', max_length=200, verbose_name='site name'),
         ),
+        # 修改BlogSettings模型的site_seo_description字段的verbose_name
         migrations.AlterField(
             model_name='blogsettings',
             name='site_seo_description',
             field=models.TextField(default='', max_length=1000, verbose_name='site seo description'),
         ),
+        # 修改Category模型的index字段的verbose_name
         migrations.AlterField(
             model_name='category',
             name='index',
             field=models.IntegerField(default=0, verbose_name='index'),
         ),
+        # 修改Category模型的name字段的verbose_name
         migrations.AlterField(
             model_name='category',
             name='name',
             field=models.CharField(max_length=30, unique=True, verbose_name='category name'),
         ),
+        # 修改Category模型的parent_category字段的verbose_name
         migrations.AlterField(
             model_name='category',
             name='parent_category',
             field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, to='blog.category', verbose_name='parent category'),
         ),
+        # 修改Links模型的is_enable字段的verbose_name
         migrations.AlterField(
             model_name='links',
             name='is_enable',
             field=models.BooleanField(default=True, verbose_name='is show'),
         ),
+        # 修改Links模型的last_mod_time字段的verbose_name
         migrations.AlterField(
             model_name='links',
             name='last_mod_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='modify time'),
         ),
+        # 修改Links模型的link字段的verbose_name
         migrations.AlterField(
             model_name='links',
             name='link',
             field=models.URLField(verbose_name='link'),
         ),
+        # 修改Links模型的name字段的verbose_name
         migrations.AlterField(
             model_name='links',
             name='name',
             field=models.CharField(max_length=30, unique=True, verbose_name='link name'),
         ),
+        # 修改Links模型的sequence字段的verbose_name
         migrations.AlterField(
             model_name='links',
             name='sequence',
             field=models.IntegerField(unique=True, verbose_name='order'),
         ),
+        # 修改Links模型的show_type字段的verbose_name和选项值
         migrations.AlterField(
             model_name='links',
             name='show_type',
             field=models.CharField(choices=[('i', 'index'), ('l', 'list'), ('p', 'post'), ('a', 'all'), ('s', 'slide')], default='i', max_length=1, verbose_name='show type'),
         ),
+        # 修改Sidebar模型的content字段的verbose_name
         migrations.AlterField(
             model_name='sidebar',
             name='content',
             field=models.TextField(verbose_name='content'),
         ),
+        # 修改Sidebar模型的is_enable字段的verbose_name
         migrations.AlterField(
             model_name='sidebar',
             name='is_enable',
             field=models.BooleanField(default=True, verbose_name='is enable'),
         ),
+        # 修改Sidebar模型的last_mod_time字段的verbose_name
         migrations.AlterField(
             model_name='sidebar',
             name='last_mod_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='modify time'),
         ),
+        # 修改Sidebar模型的name字段的verbose_name
         migrations.AlterField(
             model_name='sidebar',
             name='name',
             field=models.CharField(max_length=100, verbose_name='title'),
         ),
+        # 修改Sidebar模型的sequence字段的verbose_name
         migrations.AlterField(
             model_name='sidebar',
             name='sequence',
             field=models.IntegerField(unique=True, verbose_name='order'),
         ),
+        # 修改Tag模型的name字段的verbose_name
         migrations.AlterField(
             model_name='tag',
             name='name',
             field=models.CharField(max_length=30, unique=True, verbose_name='tag name'),
         ),
-    ]
+    ]

src/DjangoBlog/blog/migrations/0006_alter_blogsettings_options.py

@@ -1,17 +1,23 @@
 # Generated by Django 4.2.7 on 2024-01-26 02:41
 
+# 导入数据库迁移模块
 from django.db import migrations
 
 
+# 数据库迁移类
 class Migration(migrations.Migration):
 
+    # 依赖关系，依赖于blog应用的0005迁移文件
     dependencies = [
         ('blog', '0005_alter_article_options_alter_category_options_and_more'),
     ]
 
+    # 迁移操作列表
     operations = [
+        # 修改BlogSettings模型的元数据选项
         migrations.AlterModelOptions(
             name='blogsettings',
+            # 更新显示名称配置，将中文改为英文
             options={'verbose_name': 'Website configuration', 'verbose_name_plural': 'Website configuration'},
         ),
-    ]
+    ]

src/DjangoBlog/blog/models.py

@@ -1,122 +1,176 @@
+# 导入日志模块
 import logging
+# 导入正则表达式模块
 import re
+# 导入抽象基类模块
 from abc import abstractmethod
 
+# 导入Django配置模块
 from django.conf import settings
+# 导入验证错误异常
 from django.core.exceptions import ValidationError
+# 导入数据库模型模块
 from django.db import models
+# 导入URL反向解析模块
 from django.urls import reverse
+# 导入时区工具
 from django.utils.timezone import now
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
+# 导入Markdown编辑器字段
 from mdeditor.fields import MDTextField
+# 导入slug生成工具
 from uuslug import slugify
 
+# 导入自定义缓存工具
 from djangoblog.utils import cache_decorator, cache
+# 导入获取当前站点工具
 from djangoblog.utils import get_current_site
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
 
+# 链接显示类型选择类
 class LinkShowType(models.TextChoices):
-    I = ('i', _('index'))
-    L = ('l', _('list'))
-    P = ('p', _('post'))
-    A = ('a', _('all'))
-    S = ('s', _('slide'))
+    I = ('i', _('index'))      # 首页显示
+    L = ('l', _('list'))       # 列表页显示
+    P = ('p', _('post'))       # 文章页面显示
+    A = ('a', _('all'))        # 全站显示
+    S = ('s', _('slide'))      # 友情链接页面显示
 
 
+# 基础模型抽象类
 class BaseModel(models.Model):
+    # 主键ID字段
     id = models.AutoField(primary_key=True)
+    # 创建时间字段
     creation_time = models.DateTimeField(_('creation time'), default=now)
+    # 最后修改时间字段
     last_modify_time = models.DateTimeField(_('modify time'), default=now)
 
+    # 保存方法
     def save(self, *args, **kwargs):
+        # 检查是否为更新文章浏览量的操作
         is_update_views = isinstance(
             self,
             Article) and 'update_fields' in kwargs and kwargs['update_fields'] == ['views']
         if is_update_views:
+            # 如果是更新浏览量，直接更新数据库
             Article.objects.filter(pk=self.pk).update(views=self.views)
         else:
+            # 如果模型有slug字段，自动生成slug
             if 'slug' in self.__dict__:
                 slug = getattr(
                     self, 'title') if 'title' in self.__dict__ else getattr(
                     self, 'name')
                 setattr(self, 'slug', slugify(slug))
+            # 调用父类的保存方法
             super().save(*args, **kwargs)
 
+    # 获取完整URL的方法
     def get_full_url(self):
+        # 获取当前站点域名
         site = get_current_site().domain
+        # 构建完整URL
         url = "https://{site}{path}".format(site=site,
                                             path=self.get_absolute_url())
         return url
 
+    # 元数据配置
     class Meta:
+        # 标记为抽象类，不会创建数据库表
         abstract = True
 
+    # 抽象方法，子类必须实现
     @abstractmethod
     def get_absolute_url(self):
         pass
 
 
+# 文章模型类，继承自BaseModel
 class Article(BaseModel):
     """文章"""
+    # 状态选择项
     STATUS_CHOICES = (
-        ('d', _('Draft')),
-        ('p', _('Published')),
+        ('d', _('Draft')),      # 草稿
+        ('p', _('Published')),  # 已发布
     )
+    # 评论状态选择项
     COMMENT_STATUS = (
-        ('o', _('Open')),
-        ('c', _('Close')),
+        ('o', _('Open')),       # 打开评论
+        ('c', _('Close')),      # 关闭评论
     )
+    # 类型选择项
     TYPE = (
-        ('a', _('Article')),
-        ('p', _('Page')),
+        ('a', _('Article')),    # 文章
+        ('p', _('Page')),       # 页面
     )
+    # 标题字段，具有唯一性约束
     title = models.CharField(_('title'), max_length=200, unique=True)
+    # 正文字段，使用Markdown编辑器
     body = MDTextField(_('body'))
+    # 发布时间字段
     pub_time = models.DateTimeField(
         _('publish time'), blank=False, null=False, default=now)
+    # 状态字段
     status = models.CharField(
         _('status'),
         max_length=1,
         choices=STATUS_CHOICES,
         default='p')
+    # 评论状态字段
     comment_status = models.CharField(
         _('comment status'),
         max_length=1,
         choices=COMMENT_STATUS,
         default='o')
+    # 类型字段
     type = models.CharField(_('type'), max_length=1, choices=TYPE, default='a')
+    # 浏览量字段，正整数
     views = models.PositiveIntegerField(_('views'), default=0)
+    # 作者字段，外键关联到用户模型
     author = models.ForeignKey(
         settings.AUTH_USER_MODEL,
         verbose_name=_('author'),
         blank=False,
         null=False,
         on_delete=models.CASCADE)
+    # 文章排序字段
     article_order = models.IntegerField(
         _('order'), blank=False, null=False, default=0)
+    # 是否显示目录字段
     show_toc = models.BooleanField(_('show toc'), blank=False, null=False, default=False)
+    # 分类字段，外键关联到分类模型
     category = models.ForeignKey(
         'Category',
         verbose_name=_('category'),
         on_delete=models.CASCADE,
         blank=False,
         null=False)
+    # 标签字段，多对多关联到标签模型
     tags = models.ManyToManyField('Tag', verbose_name=_('tag'), blank=True)
 
+    # 将正文转换为字符串的方法
     def body_to_string(self):
         return self.body
 
+    # 对象的字符串表示
     def __str__(self):
         return self.title
 
+    # 元数据配置
     class Meta:
+        # 默认排序：按文章排序倒序，发布时间倒序
         ordering = ['-article_order', '-pub_time']
+        # 单数形式的显示名称
         verbose_name = _('article')
+        # 复数形式的显示名称
         verbose_name_plural = verbose_name
+        # 指定获取最新记录的依据字段
         get_latest_by = 'id'
 
+    # 获取绝对URL的方法
     def get_absolute_url(self):
         return reverse('blog:detailbyid', kwargs={
             'article_id': self.id,
@@ -125,83 +179,112 @@ class Article(BaseModel):
             'day': self.creation_time.day
         })
 
+    # 获取分类树的方法，使用缓存装饰器
     @cache_decorator(60 * 60 * 10)
     def get_category_tree(self):
+        # 获取分类树
         tree = self.category.get_category_tree()
+        # 提取分类名称和URL
         names = list(map(lambda c: (c.name, c.get_absolute_url()), tree))
 
         return names
 
+    # 保存方法
     def save(self, *args, **kwargs):
         super().save(*args, **kwargs)
 
+    # 增加浏览量的方法
     def viewed(self):
         self.views += 1
         self.save(update_fields=['views'])
 
+    # 获取评论列表的方法
     def comment_list(self):
+        # 构建缓存键
         cache_key = 'article_comments_{id}'.format(id=self.id)
+        # 尝试从缓存获取评论列表
         value = cache.get(cache_key)
         if value:
+            # 如果缓存存在，记录日志并返回
             logger.info('get article comments:{id}'.format(id=self.id))
             return value
         else:
+            # 如果缓存不存在，从数据库查询并设置缓存
             comments = self.comment_set.filter(is_enable=True).order_by('-id')
             cache.set(cache_key, comments, 60 * 100)
             logger.info('set article comments:{id}'.format(id=self.id))
             return comments
 
+    # 获取管理员URL的方法
     def get_admin_url(self):
         info = (self._meta.app_label, self._meta.model_name)
         return reverse('admin:%s_%s_change' % info, args=(self.pk,))
 
+    # 获取下一篇文章的方法，使用缓存
     @cache_decorator(expiration=60 * 100)
     def next_article(self):
         # 下一篇
         return Article.objects.filter(
             id__gt=self.id, status='p').order_by('id').first()
 
+    # 获取上一篇文章的方法，使用缓存
     @cache_decorator(expiration=60 * 100)
     def prev_article(self):
         # 前一篇
         return Article.objects.filter(id__lt=self.id, status='p').first()
 
+    # 获取文章第一张图片URL的方法
     def get_first_image_url(self):
         """
         Get the first image url from article.body.
         :return:
         """
+        # 使用正则表达式匹配Markdown图片语法
         match = re.search(r'!\[.*?\]\((.+?)\)', self.body)
         if match:
+            # 如果匹配到图片，返回图片URL
             return match.group(1)
+        # 如果没有图片，返回空字符串
         return ""
 
 
+# 分类模型类，继承自BaseModel
 class Category(BaseModel):
     """文章分类"""
+    # 分类名称字段，具有唯一性约束
     name = models.CharField(_('category name'), max_length=30, unique=True)
+    # 父级分类字段，自关联外键
     parent_category = models.ForeignKey(
         'self',
         verbose_name=_('parent category'),
         blank=True,
         null=True,
         on_delete=models.CASCADE)
+    # slug字段，用于URL
     slug = models.SlugField(default='no-slug', max_length=60, blank=True)
+    # 排序索引字段
     index = models.IntegerField(default=0, verbose_name=_('index'))
 
+    # 元数据配置
     class Meta:
+        # 默认按索引倒序排列
         ordering = ['-index']
+        # 单数形式的显示名称
         verbose_name = _('category')
+        # 复数形式的显示名称
         verbose_name_plural = verbose_name
 
+    # 获取绝对URL的方法
     def get_absolute_url(self):
         return reverse(
             'blog:category_detail', kwargs={
                 'category_name': self.slug})
 
+    # 对象的字符串表示
     def __str__(self):
         return self.name
 
+    # 获取分类树的方法，使用缓存
     @cache_decorator(60 * 60 * 10)
     def get_category_tree(self):
         """
@@ -210,6 +293,7 @@ class Category(BaseModel):
         """
         categorys = []
 
+        # 递归解析分类的父级
         def parse(category):
             categorys.append(category)
             if category.parent_category:
@@ -218,6 +302,7 @@ class Category(BaseModel):
         parse(self)
         return categorys
 
+    # 获取子分类的方法，使用缓存
     @cache_decorator(60 * 60 * 10)
     def get_sub_categorys(self):
         """
@@ -227,6 +312,7 @@ class Category(BaseModel):
         categorys = []
         all_categorys = Category.objects.all()
 
+        # 递归解析分类的子级
         def parse(category):
             if category not in categorys:
                 categorys.append(category)
@@ -240,137 +326,200 @@ class Category(BaseModel):
         return categorys
 
 
+# 标签模型类，继承自BaseModel
 class Tag(BaseModel):
     """文章标签"""
+    # 标签名称字段，具有唯一性约束
     name = models.CharField(_('tag name'), max_length=30, unique=True)
+    # slug字段，用于URL
     slug = models.SlugField(default='no-slug', max_length=60, blank=True)
 
+    # 对象的字符串表示
     def __str__(self):
         return self.name
 
+    # 获取绝对URL的方法
     def get_absolute_url(self):
         return reverse('blog:tag_detail', kwargs={'tag_name': self.slug})
 
+    # 获取标签下文章数量的方法，使用缓存
     @cache_decorator(60 * 60 * 10)
     def get_article_count(self):
         return Article.objects.filter(tags__name=self.name).distinct().count()
 
+    # 元数据配置
     class Meta:
+        # 默认按名称升序排列
         ordering = ['name']
+        # 单数形式的显示名称
         verbose_name = _('tag')
+        # 复数形式的显示名称
         verbose_name_plural = verbose_name
 
 
+# 友情链接模型类
 class Links(models.Model):
     """友情链接"""
 
+    # 链接名称字段，具有唯一性约束
     name = models.CharField(_('link name'), max_length=30, unique=True)
+    # 链接地址字段
     link = models.URLField(_('link'))
+    # 排序字段，具有唯一性约束
     sequence = models.IntegerField(_('order'), unique=True)
+    # 是否启用字段
     is_enable = models.BooleanField(
         _('is show'), default=True, blank=False, null=False)
+    # 显示类型字段
     show_type = models.CharField(
         _('show type'),
         max_length=1,
         choices=LinkShowType.choices,
         default=LinkShowType.I)
+    # 创建时间字段
     creation_time = models.DateTimeField(_('creation time'), default=now)
+    # 最后修改时间字段
     last_mod_time = models.DateTimeField(_('modify time'), default=now)
 
+    # 元数据配置
     class Meta:
+        # 默认按排序字段升序排列
         ordering = ['sequence']
+        # 单数形式的显示名称
         verbose_name = _('link')
+        # 复数形式的显示名称
         verbose_name_plural = verbose_name
 
+    # 对象的字符串表示
     def __str__(self):
         return self.name
 
 
+# 侧边栏模型类
 class SideBar(models.Model):
     """侧边栏,可以展示一些html内容"""
+    # 标题字段
     name = models.CharField(_('title'), max_length=100)
+    # 内容字段
     content = models.TextField(_('content'))
+    # 排序字段，具有唯一性约束
     sequence = models.IntegerField(_('order'), unique=True)
+    # 是否启用字段
     is_enable = models.BooleanField(_('is enable'), default=True)
+    # 创建时间字段
     creation_time = models.DateTimeField(_('creation time'), default=now)
+    # 最后修改时间字段
     last_mod_time = models.DateTimeField(_('modify time'), default=now)
 
+    # 元数据配置
     class Meta:
+        # 默认按排序字段升序排列
         ordering = ['sequence']
+        # 单数形式的显示名称
         verbose_name = _('sidebar')
+        # 复数形式的显示名称
         verbose_name_plural = verbose_name
 
+    # 对象的字符串表示
     def __str__(self):
         return self.name
 
 
+# 博客设置模型类
 class BlogSettings(models.Model):
     """blog的配置"""
+    # 网站名称字段
     site_name = models.CharField(
         _('site name'),
         max_length=200,
         null=False,
         blank=False,
         default='')
+    # 网站描述字段
     site_description = models.TextField(
         _('site description'),
         max_length=1000,
         null=False,
         blank=False,
         default='')
+    # 网站SEO描述字段
     site_seo_description = models.TextField(
         _('site seo description'), max_length=1000, null=False, blank=False, default='')
+    # 网站关键词字段
     site_keywords = models.TextField(
         _('site keywords'),
         max_length=1000,
         null=False,
         blank=False,
         default='')
+    # 文章摘要长度字段
     article_sub_length = models.IntegerField(_('article sub length'), default=300)
+    # 侧边栏文章数量字段
     sidebar_article_count = models.IntegerField(_('sidebar article count'), default=10)
+    # 侧边栏评论数量字段
     sidebar_comment_count = models.IntegerField(_('sidebar comment count'), default=5)
+    # 文章页面评论数量字段
     article_comment_count = models.IntegerField(_('article comment count'), default=5)
+    # 是否显示谷歌广告字段
     show_google_adsense = models.BooleanField(_('show adsense'), default=False)
+    # 谷歌广告代码字段
     google_adsense_codes = models.TextField(
         _('adsense code'), max_length=2000, null=True, blank=True, default='')
+    # 是否开启网站评论字段
     open_site_comment = models.BooleanField(_('open site comment'), default=True)
+    # 公共头部内容字段
     global_header = models.TextField("公共头部", null=True, blank=True, default='')
+    # 公共尾部内容字段
     global_footer = models.TextField("公共尾部", null=True, blank=True, default='')
+    # 备案号字段
     beian_code = models.CharField(
         '备案号',
         max_length=2000,
         null=True,
         blank=True,
         default='')
+    # 网站统计代码字段
     analytics_code = models.TextField(
         "网站统计代码",
         max_length=1000,
         null=False,
         blank=False,
         default='')
+    # 是否显示公安备案号字段
     show_gongan_code = models.BooleanField(
         '是否显示公安备案号', default=False, null=False)
+    # 公安备案号字段
     gongan_beiancode = models.TextField(
         '公安备案号',
         max_length=2000,
         null=True,
         blank=True,
         default='')
+    # 评论是否需要审核字段
     comment_need_review = models.BooleanField(
         '评论是否需要审核', default=False, null=False)
 
+    # 元数据配置
     class Meta:
+        # 单数形式的显示名称
         verbose_name = _('Website configuration')
+        # 复数形式的显示名称
         verbose_name_plural = verbose_name
 
+    # 对象的字符串表示
     def __str__(self):
         return self.site_name
 
+    # 数据验证方法
     def clean(self):
+        # 确保只能有一个配置实例
         if BlogSettings.objects.exclude(id=self.id).count():
             raise ValidationError(_('There can only be one configuration'))
 
+    # 保存方法
     def save(self, *args, **kwargs):
         super().save(*args, **kwargs)
+        # 导入缓存工具
         from djangoblog.utils import cache
-        cache.clear()
+        # 保存配置后清除所有缓存
+        cache.clear()

src/DjangoBlog/blog/search_indexes.py

@@ -1,13 +1,20 @@
+# 导入Haystack搜索索引模块
 from haystack import indexes
 
+# 导入文章模型
 from blog.models import Article
 
 
+# 文章搜索索引类，用于配置Haystack搜索引擎
 class ArticleIndex(indexes.SearchIndex, indexes.Indexable):
+    # 定义主搜索字段，document=True表示这是主要的搜索字段
+    # use_template=True表示使用模板文件来定义搜索内容
     text = indexes.CharField(document=True, use_template=True)
 
+    # 指定该索引关联的模型
     def get_model(self):
         return Article
 
+    # 定义索引查询集，只索引已发布的文章
     def index_queryset(self, using=None):
-        return self.get_model().objects.filter(status='p')
+        return self.get_model().objects.filter(status='p')

src/DjangoBlog/blog/tests.py

@@ -1,42 +1,73 @@
+# 导入操作系统模块
 import os
 
+# 导入Django配置模块
 from django.conf import settings
+# 导入文件上传处理模块
 from django.core.files.uploadedfile import SimpleUploadedFile
+# 导入管理命令调用模块
 from django.core.management import call_command
+# 导入分页器模块
 from django.core.paginator import Paginator
+# 导入静态文件处理模块
 from django.templatetags.static import static
+# 导入测试相关模块
 from django.test import Client, RequestFactory, TestCase
+# 导入URL反向解析模块
 from django.urls import reverse
+# 导入时区相关模块
 from django.utils import timezone
 
+# 导入账户模型
 from accounts.models import BlogUser
+# 导入博客搜索表单
 from blog.forms import BlogSearchForm
+# 导入博客模型
 from blog.models import Article, Category, Tag, SideBar, Links
+# 导入博客模板标签
 from blog.templatetags.blog_tags import load_pagination_info, load_articletags
+# 导入自定义工具函数
 from djangoblog.utils import get_current_site, get_sha256
+# 导入OAuth相关模型
 from oauth.models import OAuthUser, OAuthConfig
 
 
 # Create your tests here.
 
+# 文章测试类
 class ArticleTest(TestCase):
+    # 测试前置设置方法
     def setUp(self):
+        # 创建测试客户端
         self.client = Client()
+        # 创建请求工厂
         self.factory = RequestFactory()
 
+    # 测试文章验证功能
     def test_validate_article(self):
+        # 获取当前站点域名
         site = get_current_site().domain
+        # 获取或创建测试用户
         user = BlogUser.objects.get_or_create(
             email="liangliangyy@gmail.com",
             username="liangliangyy")[0]
+        # 设置用户密码
         user.set_password("liangliangyy")
+        # 设置为员工用户
         user.is_staff = True
+        # 设置为超级用户
         user.is_superuser = True
+        # 保存用户
         user.save()
+        # 访问用户详情页面
         response = self.client.get(user.get_absolute_url())
+        # 断言访问成功
         self.assertEqual(response.status_code, 200)
+        # 访问邮件发送日志管理页面
         response = self.client.get('/admin/servermanager/emailsendlog/')
+        # 访问日志条目管理页面
         response = self.client.get('admin/admin/logentry/')
+        # 创建侧边栏实例
         s = SideBar()
         s.sequence = 1
         s.name = 'test'
@@ -44,16 +75,19 @@ class ArticleTest(TestCase):
         s.is_enable = True
         s.save()
 
+        # 创建分类实例
         category = Category()
         category.name = "category"
         category.creation_time = timezone.now()
         category.last_mod_time = timezone.now()
         category.save()
 
+        # 创建标签实例
         tag = Tag()
         tag.name = "nicetag"
         tag.save()
 
+        # 创建文章实例
         article = Article()
         article.title = "nicetitle"
         article.body = "nicecontent"
@@ -63,11 +97,15 @@ class ArticleTest(TestCase):
         article.status = 'p'
 
         article.save()
+        # 断言初始标签数量为0
         self.assertEqual(0, article.tags.count())
+        # 为文章添加标签
         article.tags.add(tag)
         article.save()
+        # 断言标签数量为1
         self.assertEqual(1, article.tags.count())
 
+        # 循环创建20篇测试文章
         for i in range(20):
             article = Article()
             article.title = "nicetitle" + str(i)
@@ -79,96 +117,129 @@ class ArticleTest(TestCase):
             article.save()
             article.tags.add(tag)
             article.save()
+        # 检查是否启用Elasticsearch
         from blog.documents import ELASTICSEARCH_ENABLED
         if ELASTICSEARCH_ENABLED:
+            # 构建搜索索引
             call_command("build_index")
+            # 搜索测试文章
             response = self.client.get('/search', {'q': 'nicetitle'})
             self.assertEqual(response.status_code, 200)
 
+        # 访问文章详情页面
         response = self.client.get(article.get_absolute_url())
         self.assertEqual(response.status_code, 200)
+        # 通知蜘蛛文章URL
         from djangoblog.spider_notify import SpiderNotify
         SpiderNotify.notify(article.get_absolute_url())
+        # 访问标签详情页面
         response = self.client.get(tag.get_absolute_url())
         self.assertEqual(response.status_code, 200)
 
+        # 访问分类详情页面
         response = self.client.get(category.get_absolute_url())
         self.assertEqual(response.status_code, 200)
 
+        # 搜索测试
         response = self.client.get('/search', {'q': 'django'})
         self.assertEqual(response.status_code, 200)
+        # 测试文章标签模板标签
         s = load_articletags(article)
         self.assertIsNotNone(s)
 
+        # 用户登录
         self.client.login(username='liangliangyy', password='liangliangyy')
 
+        # 访问文章归档页面
         response = self.client.get(reverse('blog:archives'))
         self.assertEqual(response.status_code, 200)
 
+        # 测试分页功能 - 所有文章
         p = Paginator(Article.objects.all(), settings.PAGINATE_BY)
         self.check_pagination(p, '', '')
 
+        # 测试分页功能 - 标签归档
         p = Paginator(Article.objects.filter(tags=tag), settings.PAGINATE_BY)
         self.check_pagination(p, '分类标签归档', tag.slug)
 
+        # 测试分页功能 - 作者文章归档
         p = Paginator(
             Article.objects.filter(
                 author__username='liangliangyy'), settings.PAGINATE_BY)
         self.check_pagination(p, '作者文章归档', 'liangliangyy')
 
+        # 测试分页功能 - 分类目录归档
         p = Paginator(Article.objects.filter(category=category), settings.PAGINATE_BY)
         self.check_pagination(p, '分类目录归档', category.slug)
 
+        # 测试搜索表单
         f = BlogSearchForm()
         f.search()
-        # self.client.login(username='liangliangyy', password='liangliangyy')
+        # 通知百度蜘蛛文章URL
         from djangoblog.spider_notify import SpiderNotify
         SpiderNotify.baidu_notify([article.get_full_url()])
 
+        # 测试Gravatar相关模板标签
         from blog.templatetags.blog_tags import gravatar_url, gravatar
         u = gravatar_url('liangliangyy@gmail.com')
         u = gravatar('liangliangyy@gmail.com')
 
+        # 创建友情链接
         link = Links(
             sequence=1,
             name="lylinux",
             link='https://wwww.lylinux.net')
         link.save()
+        # 访问友情链接页面
         response = self.client.get('/links.html')
         self.assertEqual(response.status_code, 200)
 
+        # 访问RSS订阅
         response = self.client.get('/feed/')
         self.assertEqual(response.status_code, 200)
 
+        # 访问网站地图
         response = self.client.get('/sitemap.xml')
         self.assertEqual(response.status_code, 200)
 
+        # 访问管理页面相关URL
         self.client.get("/admin/blog/article/1/delete/")
         self.client.get('/admin/servermanager/emailsendlog/')
         self.client.get('/admin/admin/logentry/')
         self.client.get('/admin/admin/logentry/1/change/')
 
+    # 检查分页功能的方法
     def check_pagination(self, p, type, value):
+        # 遍历所有分页
         for page in range(1, p.num_pages + 1):
+            # 加载分页信息
             s = load_pagination_info(p.page(page), type, value)
             self.assertIsNotNone(s)
+            # 检查上一页链接
             if s['previous_url']:
                 response = self.client.get(s['previous_url'])
                 self.assertEqual(response.status_code, 200)
+            # 检查下一页链接
             if s['next_url']:
                 response = self.client.get(s['next_url'])
                 self.assertEqual(response.status_code, 200)
 
+    # 测试图片相关功能
     def test_image(self):
         import requests
+        # 下载测试图片
         rsp = requests.get(
             'https://www.python.org/static/img/python-logo.png')
         imagepath = os.path.join(settings.BASE_DIR, 'python.png')
+        # 保存图片到本地
         with open(imagepath, 'wb') as file:
             file.write(rsp.content)
+        # 测试未授权上传
         rsp = self.client.post('/upload')
         self.assertEqual(rsp.status_code, 403)
+        # 生成上传签名
         sign = get_sha256(get_sha256(settings.SECRET_KEY))
+        # 测试授权上传
         with open(imagepath, 'rb') as file:
             imgfile = SimpleUploadedFile(
                 'python.png', file.read(), content_type='image/jpg')
@@ -176,17 +247,23 @@ class ArticleTest(TestCase):
             rsp = self.client.post(
                 '/upload?sign=' + sign, form_data, follow=True)
             self.assertEqual(rsp.status_code, 200)
+        # 删除测试图片
         os.remove(imagepath)
+        # 测试头像保存和邮件发送功能
         from djangoblog.utils import save_user_avatar, send_email
         send_email(['qq@qq.com'], 'testTitle', 'testContent')
         save_user_avatar(
             'https://www.python.org/static/img/python-logo.png')
 
+    # 测试错误页面
     def test_errorpage(self):
+        # 访问不存在的页面
         rsp = self.client.get('/eee')
         self.assertEqual(rsp.status_code, 404)
 
+    # 测试管理命令
     def test_commands(self):
+        # 创建测试用户
         user = BlogUser.objects.get_or_create(
             email="liangliangyy@gmail.com",
             username="liangliangyy")[0]
@@ -195,12 +272,14 @@ class ArticleTest(TestCase):
         user.is_superuser = True
         user.save()
 
+        # 创建OAuth配置
         c = OAuthConfig()
         c.type = 'qq'
         c.appkey = 'appkey'
         c.appsecret = 'appsecret'
         c.save()
 
+        # 创建OAuth用户
         u = OAuthUser()
         u.type = 'qq'
         u.openid = 'openid'
@@ -212,6 +291,7 @@ class ArticleTest(TestCase):
 }'''
         u.save()
 
+        # 创建另一个OAuth用户
         u = OAuthUser()
         u.type = 'qq'
         u.openid = 'openid1'
@@ -222,6 +302,7 @@ class ArticleTest(TestCase):
         }'''
         u.save()
 
+        # 执行各种管理命令
         from blog.documents import ELASTICSEARCH_ENABLED
         if ELASTICSEARCH_ENABLED:
             call_command("build_index")
@@ -229,4 +310,4 @@ class ArticleTest(TestCase):
         call_command("create_testdata")
         call_command("clear_cache")
         call_command("sync_user_avatar")
-        call_command("build_search_words")
+        call_command("build_search_words")

src/DjangoBlog/blog/urls.py

@@ -1,62 +1,93 @@
+# 导入Django URL路由相关模块
 from django.urls import path
+# 导入缓存页面装饰器
 from django.views.decorators.cache import cache_page
 
+# 导入当前应用的视图模块
 from . import views
 
+# 定义应用的命名空间
 app_name = "blog"
+
+# 定义URL模式列表
 urlpatterns = [
+    # 首页URL，使用类视图
     path(
         r'',
         views.IndexView.as_view(),
         name='index'),
+
+    # 首页分页URL，支持页码参数
     path(
         r'page/<int:page>/',
         views.IndexView.as_view(),
         name='index_page'),
+
+    # 文章详情页URL，包含年月日和文章ID参数
     path(
         r'article/<int:year>/<int:month>/<int:day>/<int:article_id>.html',
         views.ArticleDetailView.as_view(),
         name='detailbyid'),
+
+    # 分类详情页URL，使用分类名称slug参数
     path(
         r'category/<slug:category_name>.html',
         views.CategoryDetailView.as_view(),
         name='category_detail'),
+
+    # 分类详情分页URL，包含分类名称和页码参数
     path(
         r'category/<slug:category_name>/<int:page>.html',
         views.CategoryDetailView.as_view(),
         name='category_detail_page'),
+
+    # 作者详情页URL，使用作者名称参数
     path(
         r'author/<author_name>.html',
         views.AuthorDetailView.as_view(),
         name='author_detail'),
+
+    # 作者详情分页URL，包含作者名称和页码参数
     path(
         r'author/<author_name>/<int:page>.html',
         views.AuthorDetailView.as_view(),
         name='author_detail_page'),
+
+    # 标签详情页URL，使用标签名称slug参数
     path(
         r'tag/<slug:tag_name>.html',
         views.TagDetailView.as_view(),
         name='tag_detail'),
+
+    # 标签详情分页URL，包含标签名称和页码参数
     path(
         r'tag/<slug:tag_name>/<int:page>.html',
         views.TagDetailView.as_view(),
         name='tag_detail_page'),
+
+    # 文章归档页URL，使用缓存装饰器缓存1小时
     path(
         'archives.html',
         cache_page(
             60 * 60)(
             views.ArchivesView.as_view()),
         name='archives'),
+
+    # 友情链接页URL
     path(
         'links.html',
         views.LinkListView.as_view(),
         name='links'),
+
+    # 文件上传URL，使用函数视图
     path(
         r'upload',
         views.fileupload,
         name='upload'),
+
+    # 清理缓存URL
     path(
         r'clean',
         views.clean_cache_view,
         name='clean'),
-]
+]

src/DjangoBlog/blog/views.py

@@ -1,127 +1,182 @@
+# 导入日志模块
 import logging
+# 导入操作系统模块
 import os
+# 导入UUID生成模块
 import uuid
 
+# 导入Django配置模块
 from django.conf import settings
+# 导入分页器模块
 from django.core.paginator import Paginator
+# 导入HTTP响应模块
 from django.http import HttpResponse, HttpResponseForbidden
+# 导入快捷函数模块
 from django.shortcuts import get_object_or_404
 from django.shortcuts import render
+# 导入静态文件处理模块
 from django.templatetags.static import static
+# 导入时区相关模块
 from django.utils import timezone
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
+# 导入CSRF豁免装饰器
 from django.views.decorators.csrf import csrf_exempt
+# 导入通用视图类
 from django.views.generic.detail import DetailView
 from django.views.generic.list import ListView
+# 导入Haystack搜索视图
 from haystack.views import SearchView
 
+# 导入博客模型
 from blog.models import Article, Category, LinkShowType, Links, Tag
+# 导入评论表单
 from comments.forms import CommentForm
+# 导入插件管理模块
 from djangoblog.plugin_manage import hooks
 from djangoblog.plugin_manage.hook_constants import ARTICLE_CONTENT_HOOK_NAME
+# 导入自定义工具函数
 from djangoblog.utils import cache, get_blog_setting, get_sha256
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
 
+# 文章列表视图基类，继承自ListView
 class ArticleListView(ListView):
-    # template_name属性用于指定使用哪个模板进行渲染
+    # 指定使用的模板名称
     template_name = 'blog/article_index.html'
 
-    # context_object_name属性用于给上下文变量取名（在模板中使用该名字）
+    # 指定上下文对象名称（在模板中使用的变量名）
     context_object_name = 'article_list'
 
-    # 页面类型，分类目录或标签列表等
+    # 页面类型，用于标识是分类目录、标签列表等
     page_type = ''
+    # 每页显示的文章数量，从设置中获取
     paginate_by = settings.PAGINATE_BY
+    # 页码参数名
     page_kwarg = 'page'
+    # 链接显示类型，默认为列表页显示
     link_type = LinkShowType.L
 
+    # 获取视图缓存键的方法
     def get_view_cache_key(self):
         return self.request.get['pages']
 
+    # 页码属性，使用property装饰器
     @property
     def page_number(self):
+        # 从URL参数或GET参数获取页码，默认为1
         page_kwarg = self.page_kwarg
         page = self.kwargs.get(
             page_kwarg) or self.request.GET.get(page_kwarg) or 1
         return page
 
+    # 获取查询集缓存键的方法，子类必须重写
     def get_queryset_cache_key(self):
         """
         子类重写.获得queryset的缓存key
         """
         raise NotImplementedError()
 
+    # 获取查询集数据的方法，子类必须重写
     def get_queryset_data(self):
         """
         子类重写.获取queryset的数据
         """
         raise NotImplementedError()
 
+    # 从缓存获取查询集数据的方法
     def get_queryset_from_cache(self, cache_key):
         '''
         缓存页面数据
         :param cache_key: 缓存key
         :return:
         '''
+        # 尝试从缓存获取数据
         value = cache.get(cache_key)
         if value:
+            # 如果缓存存在，记录日志并返回数据
             logger.info('get view cache.key:{key}'.format(key=cache_key))
             return value
         else:
+            # 如果缓存不存在，从数据库获取数据并设置缓存
             article_list = self.get_queryset_data()
             cache.set(cache_key, article_list)
             logger.info('set view cache.key:{key}'.format(key=cache_key))
             return article_list
 
+    # 重写获取查询集的方法，使用缓存
     def get_queryset(self):
         '''
         重写默认，从缓存获取数据
         :return:
         '''
+        # 获取缓存键
         key = self.get_queryset_cache_key()
+        # 从缓存获取数据
         value = self.get_queryset_from_cache(key)
         return value
 
+    # 获取上下文数据的方法
     def get_context_data(self, **kwargs):
+        # 添加链接类型到上下文
         kwargs['linktype'] = self.link_type
+        # 调用父类的方法
         return super(ArticleListView, self).get_context_data(**kwargs)
 
 
+# 首页视图，继承自ArticleListView
 class IndexView(ArticleListView):
     '''
     首页
     '''
-    # 友情链接类型
+    # 设置链接显示类型为首页显示
     link_type = LinkShowType.I
 
+    # 获取查询集数据的方法
     def get_queryset_data(self):
+        # 获取所有类型为文章且状态为已发布的文章
         article_list = Article.objects.filter(type='a', status='p')
         return article_list
 
+    # 获取查询集缓存键的方法
     def get_queryset_cache_key(self):
+        # 构建缓存键，包含页码
         cache_key = 'index_{page}'.format(page=self.page_number)
         return cache_key
 
 
+# 文章详情视图，继承自DetailView
 class ArticleDetailView(DetailView):
     '''
     文章详情页面
     '''
+    # 指定使用的模板名称
     template_name = 'blog/article_detail.html'
+    # 指定模型
     model = Article
+    # 指定URL中的主键参数名
     pk_url_kwarg = 'article_id'
+    # 指定上下文对象名称
     context_object_name = "article"
 
+    # 获取上下文数据的方法
     def get_context_data(self, **kwargs):
+        # 创建评论表单实例
         comment_form = CommentForm()
 
+        # 获取文章评论列表
         article_comments = self.object.comment_list()
+        # 获取父级评论（没有父评论的评论）
         parent_comments = article_comments.filter(parent_comment=None)
+        # 获取博客设置
         blog_setting = get_blog_setting()
+        # 对父级评论进行分页
         paginator = Paginator(parent_comments, blog_setting.article_comment_count)
+        # 获取评论页码参数
         page = self.request.GET.get('comment_page', '1')
+        # 验证页码参数
         if not page.isnumeric():
             page = 1
         else:
@@ -131,25 +186,31 @@ class ArticleDetailView(DetailView):
             if page > paginator.num_pages:
                 page = paginator.num_pages
 
+        # 获取当前页的评论
         p_comments = paginator.page(page)
+        # 计算下一页和上一页的页码
         next_page = p_comments.next_page_number() if p_comments.has_next() else None
         prev_page = p_comments.previous_page_number() if p_comments.has_previous() else None
 
+        # 构建评论分页URL
         if next_page:
             kwargs[
                 'comment_next_page_url'] = self.object.get_absolute_url() + f'?comment_page={next_page}#commentlist-container'
         if prev_page:
             kwargs[
                 'comment_prev_page_url'] = self.object.get_absolute_url() + f'?comment_page={prev_page}#commentlist-container'
+        # 添加各种数据到上下文
         kwargs['form'] = comment_form
         kwargs['article_comments'] = article_comments
         kwargs['p_comments'] = p_comments
         kwargs['comment_count'] = len(
             article_comments) if article_comments else 0
 
+        # 添加上一篇和下一篇文章
         kwargs['next_article'] = self.object.next_article
         kwargs['prev_article'] = self.object.prev_article
 
+        # 调用父类方法获取上下文
         context = super(ArticleDetailView, self).get_context_data(**kwargs)
         article = self.object
         # Action Hook, 通知插件"文章详情已获取"
@@ -157,131 +218,189 @@ class ArticleDetailView(DetailView):
         return context
 
 
+# 分类详情视图，继承自ArticleListView
 class CategoryDetailView(ArticleListView):
     '''
     分类目录列表
     '''
+    # 设置页面类型
     page_type = "分类目录归档"
 
+    # 获取查询集数据的方法
     def get_queryset_data(self):
+        # 从URL参数获取分类slug
         slug = self.kwargs['category_name']
+        # 获取分类对象，如果不存在返回404
         category = get_object_or_404(Category, slug=slug)
 
+        # 获取分类名称
         categoryname = category.name
         self.categoryname = categoryname
+        # 获取所有子分类的名称列表
         categorynames = list(
             map(lambda c: c.name, category.get_sub_categorys()))
+        # 获取该分类及其子分类下的所有已发布文章
         article_list = Article.objects.filter(
             category__name__in=categorynames, status='p')
         return article_list
 
+    # 获取查询集缓存键的方法
     def get_queryset_cache_key(self):
+        # 从URL参数获取分类slug
         slug = self.kwargs['category_name']
+        # 获取分类对象
         category = get_object_or_404(Category, slug=slug)
+        # 获取分类名称
         categoryname = category.name
         self.categoryname = categoryname
+        # 构建缓存键，包含分类名称和页码
         cache_key = 'category_list_{categoryname}_{page}'.format(
             categoryname=categoryname, page=self.page_number)
         return cache_key
 
+    # 获取上下文数据的方法
     def get_context_data(self, **kwargs):
-
+        # 处理分类名称，只取最后一部分
         categoryname = self.categoryname
         try:
             categoryname = categoryname.split('/')[-1]
         except BaseException:
             pass
+        # 添加上下文数据
         kwargs['page_type'] = CategoryDetailView.page_type
         kwargs['tag_name'] = categoryname
         return super(CategoryDetailView, self).get_context_data(**kwargs)
 
 
+# 作者详情视图，继承自ArticleListView
 class AuthorDetailView(ArticleListView):
     '''
     作者详情页
     '''
+    # 设置页面类型
     page_type = '作者文章归档'
 
+    # 获取查询集缓存键的方法
     def get_queryset_cache_key(self):
+        # 导入slug生成工具
         from uuslug import slugify
+        # 对作者名称进行slug处理
         author_name = slugify(self.kwargs['author_name'])
+        # 构建缓存键，包含作者名称和页码
         cache_key = 'author_{author_name}_{page}'.format(
             author_name=author_name, page=self.page_number)
         return cache_key
 
+    # 获取查询集数据的方法
     def get_queryset_data(self):
+        # 从URL参数获取作者名称
         author_name = self.kwargs['author_name']
+        # 获取该作者的所有已发布文章
         article_list = Article.objects.filter(
             author__username=author_name, type='a', status='p')
         return article_list
 
+    # 获取上下文数据的方法
     def get_context_data(self, **kwargs):
+        # 从URL参数获取作者名称
         author_name = self.kwargs['author_name']
+        # 添加上下文数据
         kwargs['page_type'] = AuthorDetailView.page_type
         kwargs['tag_name'] = author_name
         return super(AuthorDetailView, self).get_context_data(**kwargs)
 
 
+# 标签详情视图，继承自ArticleListView
 class TagDetailView(ArticleListView):
     '''
     标签列表页面
     '''
+    # 设置页面类型
     page_type = '分类标签归档'
 
+    # 获取查询集数据的方法
     def get_queryset_data(self):
+        # 从URL参数获取标签slug
         slug = self.kwargs['tag_name']
+        # 获取标签对象，如果不存在返回404
         tag = get_object_or_404(Tag, slug=slug)
+        # 获取标签名称
         tag_name = tag.name
         self.name = tag_name
+        # 获取该标签下的所有已发布文章
         article_list = Article.objects.filter(
             tags__name=tag_name, type='a', status='p')
         return article_list
 
+    # 获取查询集缓存键的方法
     def get_queryset_cache_key(self):
+        # 从URL参数获取标签slug
         slug = self.kwargs['tag_name']
+        # 获取标签对象
         tag = get_object_or_404(Tag, slug=slug)
+        # 获取标签名称
         tag_name = tag.name
         self.name = tag_name
+        # 构建缓存键，包含标签名称和页码
         cache_key = 'tag_{tag_name}_{page}'.format(
             tag_name=tag_name, page=self.page_number)
         return cache_key
 
+    # 获取上下文数据的方法
     def get_context_data(self, **kwargs):
-        # tag_name = self.kwargs['tag_name']
+        # 获取标签名称
         tag_name = self.name
+        # 添加上下文数据
         kwargs['page_type'] = TagDetailView.page_type
         kwargs['tag_name'] = tag_name
         return super(TagDetailView, self).get_context_data(**kwargs)
 
 
+# 文章归档视图，继承自ArticleListView
 class ArchivesView(ArticleListView):
     '''
     文章归档页面
     '''
+    # 设置页面类型
     page_type = '文章归档'
+    # 不分页
     paginate_by = None
     page_kwarg = None
+    # 指定使用的模板名称
     template_name = 'blog/article_archives.html'
 
+    # 获取查询集数据的方法
     def get_queryset_data(self):
+        # 获取所有已发布的文章
         return Article.objects.filter(status='p').all()
 
+    # 获取查询集缓存键的方法
     def get_queryset_cache_key(self):
+        # 使用固定的缓存键
         cache_key = 'archives'
         return cache_key
 
 
+# 友情链接列表视图，继承自ListView
 class LinkListView(ListView):
+    # 指定模型
     model = Links
+    # 指定使用的模板名称
     template_name = 'blog/links_list.html'
 
+    # 获取查询集的方法
     def get_queryset(self):
+        # 只获取已启用的友情链接
         return Links.objects.filter(is_enable=True)
 
 
+# Elasticsearch搜索视图，继承自Haystack的SearchView
 class EsSearchView(SearchView):
+    # 获取上下文数据的方法
     def get_context(self):
+        # 构建分页
         paginator, page = self.build_page()
+        # 构建上下文数据
         context = {
             "query": self.query,
             "form": self.form,
@@ -289,13 +408,16 @@ class EsSearchView(SearchView):
             "paginator": paginator,
             "suggestion": None,
         }
+        # 如果有拼写建议，添加到上下文
         if hasattr(self.results, "query") and self.results.query.backend.include_spelling:
             context["suggestion"] = self.results.query.get_spelling_suggestion()
+        # 更新额外上下文
         context.update(self.extra_context())
 
         return context
 
 
+# 文件上传视图，使用CSRF豁免装饰器
 @csrf_exempt
 def fileupload(request):
     """
@@ -303,31 +425,45 @@ def fileupload(request):
     :param request:
     :return:
     """
+    # 只处理POST请求
     if request.method == 'POST':
+        # 获取签名参数
         sign = request.GET.get('sign', None)
         if not sign:
             return HttpResponseForbidden()
+        # 验证签名
         if not sign == get_sha256(get_sha256(settings.SECRET_KEY)):
             return HttpResponseForbidden()
         response = []
+        # 遍历所有上传的文件
         for filename in request.FILES:
+            # 生成时间路径
             timestr = timezone.now().strftime('%Y/%m/%d')
+            # 图片扩展名列表
             imgextensions = ['jpg', 'png', 'jpeg', 'bmp']
             fname = u''.join(str(filename))
+            # 判断是否为图片文件
             isimage = len([i for i in imgextensions if fname.find(i) >= 0]) > 0
+            # 构建保存路径
             base_dir = os.path.join(settings.STATICFILES, "files" if not isimage else "image", timestr)
+            # 创建目录（如果不存在）
             if not os.path.exists(base_dir):
                 os.makedirs(base_dir)
+            # 生成保存路径，使用UUID作为文件名
             savepath = os.path.normpath(os.path.join(base_dir, f"{uuid.uuid4().hex}{os.path.splitext(filename)[-1]}"))
+            # 安全检查：确保保存路径在基础目录内
             if not savepath.startswith(base_dir):
                 return HttpResponse("only for post")
+            # 保存文件
             with open(savepath, 'wb+') as wfile:
                 for chunk in request.FILES[filename].chunks():
                     wfile.write(chunk)
+            # 如果是图片，进行压缩优化
             if isimage:
                 from PIL import Image
                 image = Image.open(savepath)
                 image.save(savepath, quality=20, optimize=True)
+            # 生成静态文件URL
             url = static(savepath)
             response.append(url)
         return HttpResponse(response)
@@ -336,13 +472,16 @@ def fileupload(request):
         return HttpResponse("only for post")
 
 
+# 404错误页面视图
 def page_not_found_view(
         request,
         exception,
         template_name='blog/error_page.html'):
+    # 记录错误日志
     if exception:
         logger.error(exception)
     url = request.get_full_path()
+    # 渲染错误页面
     return render(request,
                   template_name,
                   {'message': _('Sorry, the page you requested is not found, please click the home page to see other?'),
@@ -350,6 +489,7 @@ def page_not_found_view(
                   status=404)
 
 
+# 500服务器错误页面视图
 def server_error_view(request, template_name='blog/error_page.html'):
     return render(request,
                   template_name,
@@ -358,10 +498,12 @@ def server_error_view(request, template_name='blog/error_page.html'):
                   status=500)
 
 
+# 403权限拒绝页面视图
 def permission_denied_view(
         request,
         exception,
         template_name='blog/error_page.html'):
+    # 记录错误日志
     if exception:
         logger.error(exception)
     return render(
@@ -370,6 +512,8 @@ def permission_denied_view(
             'statuscode': '403'}, status=403)
 
 
+# 清理缓存视图
 def clean_cache_view(request):
+    # 清除所有缓存
     cache.clear()
-    return HttpResponse('ok')
+    return HttpResponse('ok')

src/DjangoBlog/comments/admin.py

@@ -1,49 +1,76 @@
+# 导入Django管理员模块
 from django.contrib import admin
+# 导入URL反向解析模块
 from django.urls import reverse
+# 导入HTML格式化工具
 from django.utils.html import format_html
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
 
 
+# 禁用评论状态的管理动作函数
 def disable_commentstatus(modeladmin, request, queryset):
+    # 将选中的评论的启用状态设置为False
     queryset.update(is_enable=False)
 
 
+# 启用评论状态的管理动作函数
 def enable_commentstatus(modeladmin, request, queryset):
+    # 将选中的评论的启用状态设置为True
     queryset.update(is_enable=True)
 
 
+# 设置管理动作的显示描述
 disable_commentstatus.short_description = _('Disable comments')
 enable_commentstatus.short_description = _('Enable comments')
 
 
+# 评论管理类
 class CommentAdmin(admin.ModelAdmin):
+    # 每页显示的评论数量
     list_per_page = 20
+    # 列表页面显示的字段
     list_display = (
         'id',
         'body',
-        'link_to_userinfo',
-        'link_to_article',
+        'link_to_userinfo',  # 自定义方法：用户信息链接
+        'link_to_article',   # 自定义方法：文章链接
         'is_enable',
         'creation_time')
+    # 列表中可作为链接点击的字段
     list_display_links = ('id', 'body', 'is_enable')
+    # 列表过滤器
     list_filter = ('is_enable',)
+    # 排除的字段（不在表单中显示）
     exclude = ('creation_time', 'last_modify_time')
+    # 可用的管理动作
     actions = [disable_commentstatus, enable_commentstatus]
+    # 使用原始ID字段（显示ID而不是下拉选择）
     raw_id_fields = ('author', 'article')
+    # 搜索字段
     search_fields = ('body',)
 
+    # 自定义方法：显示用户信息链接
     def link_to_userinfo(self, obj):
+        # 获取用户模型的app_label和model_name
         info = (obj.author._meta.app_label, obj.author._meta.model_name)
+        # 生成用户编辑页面的URL
         link = reverse('admin:%s_%s_change' % info, args=(obj.author.id,))
+        # 返回格式化的HTML链接，显示用户昵称或邮箱
         return format_html(
             u'<a href="%s">%s</a>' %
             (link, obj.author.nickname if obj.author.nickname else obj.author.email))
 
+    # 自定义方法：显示文章链接
     def link_to_article(self, obj):
+        # 获取文章模型的app_label和model_name
         info = (obj.article._meta.app_label, obj.article._meta.model_name)
+        # 生成文章编辑页面的URL
         link = reverse('admin:%s_%s_change' % info, args=(obj.article.id,))
+        # 返回格式化的HTML链接，显示文章标题
         return format_html(
             u'<a href="%s">%s</a>' % (link, obj.article.title))
 
+    # 设置自定义方法的显示名称
     link_to_userinfo.short_description = _('User')
-    link_to_article.short_description = _('Article')
+    link_to_article.short_description = _('Article')

src/DjangoBlog/comments/apps.py

@@ -1,5 +1,8 @@
+# 导入Django应用配置基类
 from django.apps import AppConfig
 
 
+# 定义评论应用的配置类
 class CommentsConfig(AppConfig):
-    name = 'comments'
+    # 指定应用的完整Python路径
+    name = 'comments'

src/DjangoBlog/comments/forms.py

@@ -1,13 +1,20 @@
+# 导入Django表单模块
 from django import forms
+# 导入模型表单基类
 from django.forms import ModelForm
 
+# 导入评论模型
 from .models import Comment
 
 
+# 评论表单类，继承自ModelForm
 class CommentForm(ModelForm):
+    # 父级评论ID字段，使用隐藏输入控件，非必填
     parent_comment_id = forms.IntegerField(
         widget=forms.HiddenInput, required=False)
 
     class Meta:
+        # 指定关联的模型
         model = Comment
-        fields = ['body']
+        # 指定表单中包含的字段，只包含评论正文字段
+        fields = ['body']

src/DjangoBlog/comments/migrations/0001_initial.py

@@ -1,38 +1,59 @@
 # Generated by Django 4.1.7 on 2023-03-02 07:14
 
+# 导入Django设置模块
 from django.conf import settings
+# 导入数据库迁移和模型模块
 from django.db import migrations, models
+# 导入数据库删除操作模块
 import django.db.models.deletion
+# 导入时区工具
 import django.utils.timezone
 
 
+# 数据库迁移类
 class Migration(migrations.Migration):
 
+    # 标记为初始迁移
     initial = True
 
+    # 依赖关系，依赖于博客应用的初始迁移和用户模型
     dependencies = [
         ('blog', '0001_initial'),
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
 
+    # 迁移操作列表
     operations = [
+        # 创建评论表
         migrations.CreateModel(
             name='Comment',
             fields=[
+                # 主键ID，使用BigAutoField自增字段
                 ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                # 评论正文字段，最大长度300字符
                 ('body', models.TextField(max_length=300, verbose_name='正文')),
+                # 创建时间字段，默认值为当前时间
                 ('created_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='创建时间')),
+                # 最后修改时间字段，默认值为当前时间
                 ('last_mod_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='修改时间')),
+                # 是否启用字段，布尔类型，默认True
                 ('is_enable', models.BooleanField(default=True, verbose_name='是否显示')),
+                # 文章字段，外键关联到文章模型，级联删除
                 ('article', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='blog.article', verbose_name='文章')),
+                # 作者字段，外键关联到用户模型，级联删除
                 ('author', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL, verbose_name='作者')),
+                # 父级评论字段，外键自关联，允许为空，级联删除
                 ('parent_comment', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, to='comments.comment', verbose_name='上级评论')),
             ],
             options={
+                # 单数形式的显示名称
                 'verbose_name': '评论',
+                # 复数形式的显示名称
                 'verbose_name_plural': '评论',
+                # 默认按ID倒序排列
                 'ordering': ['-id'],
+                # 指定获取最新记录的依据字段
                 'get_latest_by': 'id',
             },
         ),
-    ]
+    ]

src/DjangoBlog/comments/migrations/0002_alter_comment_is_enable.py

@@ -1,18 +1,24 @@
 # Generated by Django 4.1.7 on 2023-04-24 13:48
 
+# 导入数据库迁移和模型模块
 from django.db import migrations, models
 
 
+# 数据库迁移类
 class Migration(migrations.Migration):
 
+    # 依赖关系，依赖于comments应用的0001_initial迁移
     dependencies = [
         ('comments', '0001_initial'),
     ]
 
+    # 迁移操作列表
     operations = [
+        # 修改Comment模型的is_enable字段
         migrations.AlterField(
             model_name='comment',
             name='is_enable',
+            # 将默认值从True改为False，表示评论默认不显示（需要审核）
             field=models.BooleanField(default=False, verbose_name='是否显示'),
         ),
-    ]
+    ]

src/DjangoBlog/comments/migrations/0003_alter_comment_options_remove_comment_created_time_and_more.py

@@ -1,60 +1,76 @@
 # Generated by Django 4.2.5 on 2023-09-06 13:13
 
+# 导入Django设置模块
 from django.conf import settings
+# 导入数据库迁移和模型模块
 from django.db import migrations, models
+# 导入数据库删除操作模块
 import django.db.models.deletion
+# 导入时区工具
 import django.utils.timezone
 
 
+# 数据库迁移类
 class Migration(migrations.Migration):
 
+    # 依赖关系，依赖于用户模型、博客应用的0005迁移和评论应用的0002迁移
     dependencies = [
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
         ('blog', '0005_alter_article_options_alter_category_options_and_more'),
         ('comments', '0002_alter_comment_is_enable'),
     ]
 
+    # 迁移操作列表
     operations = [
+        # 修改Comment模型的元数据选项，更新显示名称
         migrations.AlterModelOptions(
             name='comment',
             options={'get_latest_by': 'id', 'ordering': ['-id'], 'verbose_name': 'comment', 'verbose_name_plural': 'comment'},
         ),
+        # 删除created_time字段
         migrations.RemoveField(
             model_name='comment',
             name='created_time',
         ),
+        # 删除last_mod_time字段
         migrations.RemoveField(
             model_name='comment',
             name='last_mod_time',
         ),
+        # 新增creation_time字段，使用当前时间作为默认值
         migrations.AddField(
             model_name='comment',
             name='creation_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='creation time'),
         ),
+        # 新增last_modify_time字段，使用当前时间作为默认值
         migrations.AddField(
             model_name='comment',
             name='last_modify_time',
             field=models.DateTimeField(default=django.utils.timezone.now, verbose_name='last modify time'),
         ),
+        # 修改article字段的verbose_name
         migrations.AlterField(
             model_name='comment',
             name='article',
             field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='blog.article', verbose_name='article'),
         ),
+        # 修改author字段的verbose_name
         migrations.AlterField(
             model_name='comment',
             name='author',
             field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL, verbose_name='author'),
         ),
+        # 修改is_enable字段的verbose_name
         migrations.AlterField(
             model_name='comment',
             name='is_enable',
             field=models.BooleanField(default=False, verbose_name='enable'),
         ),
+        # 修改parent_comment字段的verbose_name
         migrations.AlterField(
             model_name='comment',
             name='parent_comment',
             field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, to='comments.comment', verbose_name='parent comment'),
         ),
-    ]
+    ]

src/DjangoBlog/comments/models.py

@@ -1,39 +1,59 @@
+# 导入Django配置模块
 from django.conf import settings
+# 导入数据库模型模块
 from django.db import models
+# 导入时区工具
 from django.utils.timezone import now
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
 
+# 导入文章模型
 from blog.models import Article
 
 
 # Create your models here.
 
+# 评论模型类
 class Comment(models.Model):
+    # 评论正文字段，文本类型，最大长度300字符
     body = models.TextField('正文', max_length=300)
+    # 创建时间字段，默认值为当前时间
     creation_time = models.DateTimeField(_('creation time'), default=now)
+    # 最后修改时间字段，默认值为当前时间
     last_modify_time = models.DateTimeField(_('last modify time'), default=now)
+    # 作者字段，外键关联到用户模型，级联删除
     author = models.ForeignKey(
         settings.AUTH_USER_MODEL,
         verbose_name=_('author'),
         on_delete=models.CASCADE)
+    # 文章字段，外键关联到文章模型，级联删除
     article = models.ForeignKey(
         Article,
         verbose_name=_('article'),
         on_delete=models.CASCADE)
+    # 父级评论字段，外键自关联，允许为空，级联删除
     parent_comment = models.ForeignKey(
         'self',
         verbose_name=_('parent comment'),
         blank=True,
         null=True,
         on_delete=models.CASCADE)
+    # 是否启用字段，布尔类型，默认False（表示评论需要审核）
     is_enable = models.BooleanField(_('enable'),
                                     default=False, blank=False, null=False)
 
+    # 模型的元数据配置
     class Meta:
+        # 默认按ID倒序排列
         ordering = ['-id']
+        # 单数形式的显示名称
         verbose_name = _('comment')
+        # 复数形式的显示名称
         verbose_name_plural = verbose_name
+        # 指定获取最新记录的依据字段
         get_latest_by = 'id'
 
+    # 对象的字符串表示方法
     def __str__(self):
-        return self.body
+        # 使用评论正文作为对象的字符串表示
+        return self.body

src/DjangoBlog/comments/templatetags/comments_tags.py

@@ -1,30 +1,45 @@
+# 导入Django模板模块
 from django import template
 
+# 创建模板库注册实例
 register = template.Library()
 
 
+# 注册简单模板标签，用于解析评论树结构
 @register.simple_tag
 def parse_commenttree(commentlist, comment):
     """获得当前评论子评论的列表
         用法: {% parse_commenttree article_comments comment as childcomments %}
     """
+    # 初始化数据列表，用于存储子评论
     datas = []
 
+    # 定义递归函数，用于解析评论树
     def parse(c):
+        # 获取当前评论的所有直接子评论（已启用状态）
         childs = commentlist.filter(parent_comment=c, is_enable=True)
+        # 遍历每个子评论
         for child in childs:
+            # 将子评论添加到数据列表
             datas.append(child)
+            # 递归解析子评论的子评论
             parse(child)
 
+    # 从传入的评论开始解析
     parse(comment)
+    # 返回所有子评论的列表
     return datas
 
 
+# 注册包含标签，用于显示评论项
 @register.inclusion_tag('comments/tags/comment_item.html')
 def show_comment_item(comment, ischild):
     """评论"""
+    # 根据是否为子评论设置不同的深度值
+    # 子评论深度为1，父评论深度为2
     depth = 1 if ischild else 2
+    # 返回模板上下文数据
     return {
-        'comment_item': comment,
-        'depth': depth
-    }
+        'comment_item': comment,  # 评论对象
+        'depth': depth  # 评论深度，用于控制显示样式
+    }

src/DjangoBlog/comments/tests.py

@@ -1,42 +1,64 @@
+# 导入Django测试相关模块
 from django.test import Client, RequestFactory, TransactionTestCase
+# 导入URL反向解析模块
 from django.urls import reverse
 
+# 导入账户模型
 from accounts.models import BlogUser
+# 导入博客模型
 from blog.models import Category, Article
+# 导入评论模型
 from comments.models import Comment
+# 导入评论模板标签
 from comments.templatetags.comments_tags import *
+# 导入自定义工具函数
 from djangoblog.utils import get_max_articleid_commentid
 
 
 # Create your tests here.
 
+# 评论测试类，继承自TransactionTestCase
 class CommentsTest(TransactionTestCase):
+    # 测试前置设置方法
     def setUp(self):
+        # 创建测试客户端
         self.client = Client()
+        # 创建请求工厂
         self.factory = RequestFactory()
+        # 导入博客设置模型
         from blog.models import BlogSettings
+        # 创建博客设置实例
         value = BlogSettings()
+        # 设置评论需要审核
         value.comment_need_review = True
         value.save()
 
+        # 创建超级用户
         self.user = BlogUser.objects.create_superuser(
             email="liangliangyy1@gmail.com",
             username="liangliangyy1",
             password="liangliangyy1")
 
+    # 更新文章评论状态的方法
     def update_article_comment_status(self, article):
+        # 获取文章的所有评论
         comments = article.comment_set.all()
+        # 遍历评论并设置为启用状态
         for comment in comments:
             comment.is_enable = True
             comment.save()
 
+    # 测试评论验证功能
     def test_validate_comment(self):
+        # 用户登录
         self.client.login(username='liangliangyy1', password='liangliangyy1')
 
+        # 创建分类
         category = Category()
         category.name = "categoryccc"
         category.save()
 
+        # 创建文章
         article = Article()
         article.title = "nicetitleccc"
         article.body = "nicecontentccc"
@@ -46,35 +68,49 @@ class CommentsTest(TransactionTestCase):
         article.status = 'p'
         article.save()
 
+        # 获取评论提交URL
         comment_url = reverse(
             'comments:postcomment', kwargs={
                 'article_id': article.id})
 
+        # 提交第一条评论
         response = self.client.post(comment_url,
                                     {
                                         'body': '123ffffffffff'
                                     })
 
+        # 断言重定向响应
         self.assertEqual(response.status_code, 302)
 
+        # 重新获取文章对象
         article = Article.objects.get(pk=article.pk)
+        # 断言评论列表为空（因为评论需要审核）
         self.assertEqual(len(article.comment_list()), 0)
+        # 更新评论状态为启用
         self.update_article_comment_status(article)
 
+        # 断言评论列表有一条评论
         self.assertEqual(len(article.comment_list()), 1)
 
+        # 提交第二条评论
         response = self.client.post(comment_url,
                                     {
                                         'body': '123ffffffffff',
                                     })
 
+        # 断言重定向响应
         self.assertEqual(response.status_code, 302)
 
+        # 重新获取文章对象
         article = Article.objects.get(pk=article.pk)
+        # 更新评论状态为启用
         self.update_article_comment_status(article)
+        # 断言评论列表有两条评论
         self.assertEqual(len(article.comment_list()), 2)
+        # 获取第一条评论的ID作为父评论ID
         parent_comment_id = article.comment_list()[0].id
 
+        # 提交第三条评论（回复评论），包含Markdown格式内容
         response = self.client.post(comment_url,
                                     {
                                         'body': '''
@@ -93,17 +129,27 @@ class CommentsTest(TransactionTestCase):
                                         'parent_comment_id': parent_comment_id
                                     })
 
+        # 断言重定向响应
         self.assertEqual(response.status_code, 302)
+        # 更新评论状态为启用
         self.update_article_comment_status(article)
+        # 重新获取文章对象
         article = Article.objects.get(pk=article.pk)
+        # 断言评论列表有三条评论
         self.assertEqual(len(article.comment_list()), 3)
+        # 获取父评论对象
         comment = Comment.objects.get(id=parent_comment_id)
+        # 解析评论树结构
         tree = parse_commenttree(article.comment_list(), comment)
+        # 断言评论树有一条子评论
         self.assertEqual(len(tree), 1)
+        # 测试评论项显示模板标签
         data = show_comment_item(comment, True)
         self.assertIsNotNone(data)
+        # 测试获取最大文章ID和评论ID的函数
         s = get_max_articleid_commentid()
         self.assertIsNotNone(s)
 
+        # 测试发送评论邮件功能
         from comments.utils import send_comment_email
-        send_comment_email(comment)
+        send_comment_email(comment)

src/DjangoBlog/comments/urls.py

@@ -1,11 +1,17 @@
+# 导入Django URL路由相关模块
 from django.urls import path
 
+# 导入当前应用的视图模块
 from . import views
 
+# 定义应用的命名空间
 app_name = "comments"
+
+# 定义URL模式列表
 urlpatterns = [
+    # 评论提交URL，包含文章ID参数
     path(
         'article/<int:article_id>/postcomment',
         views.CommentPostView.as_view(),
         name='postcomment'),
-]
+]

src/DjangoBlog/comments/utils.py

@@ -1,17 +1,26 @@
+# 导入日志模块
 import logging
 
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
 
+# 导入自定义工具函数
 from djangoblog.utils import get_current_site
 from djangoblog.utils import send_email
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
 
+# 发送评论邮件的函数
 def send_comment_email(comment):
+    # 获取当前站点域名
     site = get_current_site().domain
+    # 邮件主题
     subject = _('Thanks for your comment')
+    # 构建文章完整URL
     article_url = f"https://{site}{comment.article.get_absolute_url()}"
+    # 构建给评论作者的邮件内容
     html_content = _("""<p>Thank you very much for your comments on this site</p>
                     You can visit <a href="%(article_url)s" rel="bookmark">%(article_title)s</a>
                     to review your comments,
@@ -19,10 +28,16 @@ def send_comment_email(comment):
                     <br />
                     If the link above cannot be opened, please copy this link to your browser.
                     %(article_url)s""") % {'article_url': article_url, 'article_title': comment.article.title}
+    # 获取评论作者的邮箱
     tomail = comment.author.email
+    # 发送邮件给评论作者
     send_email([tomail], subject, html_content)
+
+    # 尝试发送回复通知邮件给父评论作者
     try:
+        # 检查是否存在父评论（即当前评论是回复评论）
         if comment.parent_comment:
+            # 构建给父评论作者的邮件内容
             html_content = _("""Your comment on <a href="%(article_url)s" rel="bookmark">%(article_title)s</a><br/> has 
                    received a reply. <br/> %(comment_body)s
                     <br/>   
@@ -32,7 +47,10 @@ def send_comment_email(comment):
                      %(article_url)s
                     """) % {'article_url': article_url, 'article_title': comment.article.title,
                             'comment_body': comment.parent_comment.body}
+            # 获取父评论作者的邮箱
             tomail = comment.parent_comment.author.email
+            # 发送邮件给父评论作者
             send_email([tomail], subject, html_content)
     except Exception as e:
-        logger.error(e)
+        # 记录发送回复通知邮件时的错误
+        logger.error(e)

src/DjangoBlog/comments/views.py

@@ -1,63 +1,108 @@
 # Create your views here.
+# 导入Django核心异常模块
 from django.core.exceptions import ValidationError
+# 导入HTTP重定向响应模块
 from django.http import HttpResponseRedirect
+# 导入快捷函数模块
 from django.shortcuts import get_object_or_404
+# 导入方法装饰器模块
 from django.utils.decorators import method_decorator
+# 导入CSRF保护装饰器
 from django.views.decorators.csrf import csrf_protect
+# 导入通用表单视图类
 from django.views.generic.edit import FormView
 
+# 导入账户模型
 from accounts.models import BlogUser
+# 导入博客模型
 from blog.models import Article
+# 导入评论表单
 from .forms import CommentForm
+# 导入评论模型
 from .models import Comment
 
 
+# 评论提交视图类，继承自FormView
 class CommentPostView(FormView):
+    # 指定使用的表单类
     form_class = CommentForm
+    # 指定使用的模板名称
     template_name = 'blog/article_detail.html'
 
+    # 使用CSRF保护装饰器
     @method_decorator(csrf_protect)
     def dispatch(self, *args, **kwargs):
+        # 调用父类的dispatch方法
         return super(CommentPostView, self).dispatch(*args, **kwargs)
 
+    # GET请求处理方法
     def get(self, request, *args, **kwargs):
+        # 从URL参数获取文章ID
         article_id = self.kwargs['article_id']
+        # 获取文章对象，如果不存在返回404
         article = get_object_or_404(Article, pk=article_id)
+        # 获取文章详情页URL
         url = article.get_absolute_url()
+        # 重定向到文章详情页的评论区域
         return HttpResponseRedirect(url + "#comments")
 
+    # 表单验证失败的处理方法
     def form_invalid(self, form):
+        # 从URL参数获取文章ID
         article_id = self.kwargs['article_id']
+        # 获取文章对象
         article = get_object_or_404(Article, pk=article_id)
 
+        # 重新渲染模板，包含表单和文章信息
         return self.render_to_response({
             'form': form,
             'article': article
         })
 
+    # 表单验证成功的处理方法
     def form_valid(self, form):
         """提交的数据验证合法后的逻辑"""
+        # 获取当前用户
         user = self.request.user
+        # 获取用户对象
         author = BlogUser.objects.get(pk=user.pk)
+        # 从URL参数获取文章ID
         article_id = self.kwargs['article_id']
+        # 获取文章对象
         article = get_object_or_404(Article, pk=article_id)
 
+        # 检查文章评论状态和文章状态
         if article.comment_status == 'c' or article.status == 'c':
+            # 如果评论已关闭，抛出验证错误
             raise ValidationError("该文章评论已关闭.")
+
+        # 从表单获取评论数据但不保存到数据库
         comment = form.save(False)
+        # 设置评论关联的文章
         comment.article = article
+
+        # 获取博客设置
         from djangoblog.utils import get_blog_setting
         settings = get_blog_setting()
+        # 根据设置决定是否自动启用评论
         if not settings.comment_need_review:
             comment.is_enable = True
+
+        # 设置评论作者
         comment.author = author
 
+        # 检查是否存在父评论ID
         if form.cleaned_data['parent_comment_id']:
+            # 获取父评论对象
             parent_comment = Comment.objects.get(
                 pk=form.cleaned_data['parent_comment_id'])
+            # 设置父评论
             comment.parent_comment = parent_comment
 
+        # 保存评论到数据库
         comment.save(True)
+
+        # 重定向到文章详情页的特定评论位置
         return HttpResponseRedirect(
             "%s#div-comment-%d" %
-            (article.get_absolute_url(), comment.pk))
+            (article.get_absolute_url(), comment.pk))

src/DjangoBlog/djangoblog/admin_site.py

@@ -1,32 +1,56 @@
+# 导入Django管理员站点相关模块
 from django.contrib.admin import AdminSite
+# 导入日志条目模型
 from django.contrib.admin.models import LogEntry
+# 导入站点管理员类
 from django.contrib.sites.admin import SiteAdmin
+# 导入站点模型
 from django.contrib.sites.models import Site
 
+# 导入账户应用的管理类
 from accounts.admin import *
+# 导入博客应用的管理类
 from blog.admin import *
+# 导入博客模型
 from blog.models import *
+# 导入评论应用的管理类
 from comments.admin import *
+# 导入评论模型
 from comments.models import *
+# 导入自定义日志条目管理类
 from djangoblog.logentryadmin import LogEntryAdmin
+# 导入OAuth应用的管理类
 from oauth.admin import *
+# 导入OAuth模型
 from oauth.models import *
+# 导入OwnTracks应用的管理类
 from owntracks.admin import *
+# 导入OwnTracks模型
 from owntracks.models import *
+# 导入服务器管理应用的管理类
 from servermanager.admin import *
+# 导入服务器管理模型
 from servermanager.models import *
 
 
+# 自定义DjangoBlog管理员站点类，继承自AdminSite
 class DjangoBlogAdminSite(AdminSite):
+    # 站点头部标题
     site_header = 'djangoblog administration'
+    # 站点标题
     site_title = 'djangoblog site admin'
 
+    # 初始化方法
     def __init__(self, name='admin'):
+        # 调用父类的初始化方法
         super().__init__(name)
 
+    # 权限检查方法
     def has_permission(self, request):
+        # 只允许超级用户访问管理员站点
         return request.user.is_superuser
 
+    # 注释掉的URL配置方法（备用功能）
     # def get_urls(self):
     #     urls = super().get_urls()
     #     from django.urls import path
@@ -38,27 +62,36 @@ class DjangoBlogAdminSite(AdminSite):
     #     return urls + my_urls
 
 
+# 创建DjangoBlog管理员站点实例
 admin_site = DjangoBlogAdminSite(name='admin')
 
-admin_site.register(Article, ArticlelAdmin)
-admin_site.register(Category, CategoryAdmin)
-admin_site.register(Tag, TagAdmin)
-admin_site.register(Links, LinksAdmin)
-admin_site.register(SideBar, SideBarAdmin)
-admin_site.register(BlogSettings, BlogSettingsAdmin)
+# 注册博客相关模型和管理类
+admin_site.register(Article, ArticlelAdmin)          # 文章模型
+admin_site.register(Category, CategoryAdmin)         # 分类模型
+admin_site.register(Tag, TagAdmin)                   # 标签模型
+admin_site.register(Links, LinksAdmin)               # 友情链接模型
+admin_site.register(SideBar, SideBarAdmin)           # 侧边栏模型
+admin_site.register(BlogSettings, BlogSettingsAdmin) # 博客设置模型
 
-admin_site.register(commands, CommandsAdmin)
-admin_site.register(EmailSendLog, EmailSendLogAdmin)
+# 注册服务器管理相关模型和管理类
+admin_site.register(commands, CommandsAdmin)         # 命令模型
+admin_site.register(EmailSendLog, EmailSendLogAdmin) # 邮件发送日志模型
 
-admin_site.register(BlogUser, BlogUserAdmin)
+# 注册用户模型和管理类
+admin_site.register(BlogUser, BlogUserAdmin)         # 博客用户模型
 
-admin_site.register(Comment, CommentAdmin)
+# 注册评论模型和管理类
+admin_site.register(Comment, CommentAdmin)           # 评论模型
 
-admin_site.register(OAuthUser, OAuthUserAdmin)
-admin_site.register(OAuthConfig, OAuthConfigAdmin)
+# 注册OAuth相关模型和管理类
+admin_site.register(OAuthUser, OAuthUserAdmin)       # OAuth用户模型
+admin_site.register(OAuthConfig, OAuthConfigAdmin)   # OAuth配置模型
 
-admin_site.register(OwnTrackLog, OwnTrackLogsAdmin)
+# 注册OwnTracks相关模型和管理类
+admin_site.register(OwnTrackLog, OwnTrackLogsAdmin)  # OwnTracks日志模型
 
-admin_site.register(Site, SiteAdmin)
+# 注册Django内置站点模型和管理类
+admin_site.register(Site, SiteAdmin)                 # 站点模型
 
-admin_site.register(LogEntry, LogEntryAdmin)
+# 注册Django内置日志条目模型和管理类
+admin_site.register(LogEntry, LogEntryAdmin)         # 日志条目模型

src/DjangoBlog/djangoblog/apps.py

@@ -1,11 +1,19 @@
+# 导入Django应用配置基类
 from django.apps import AppConfig
 
+# 定义DjangoBlog应用配置类
 class DjangoblogAppConfig(AppConfig):
+    # 指定默认的自增字段类型为BigAutoField
     default_auto_field = 'django.db.models.BigAutoField'
+    # 指定应用的完整Python路径
     name = 'djangoblog'
 
+    # 应用准备就绪时调用的方法
     def ready(self):
+        # 调用父类的ready方法
         super().ready()
         # Import and load plugins here
+        # 导入并加载插件
         from .plugin_manage.loader import load_plugins
-        load_plugins() 
+        # 调用插件加载函数
+        load_plugins()

src/DjangoBlog/djangoblog/blog_signals.py

@@ -1,69 +1,106 @@
+# 导入线程模块
 import _thread
+# 导入日志模块
 import logging
 
+# 导入Django信号相关模块
 import django.dispatch
+# 导入Django配置模块
 from django.conf import settings
+# 导入管理员日志模型
 from django.contrib.admin.models import LogEntry
+# 导入用户登录/登出信号
 from django.contrib.auth.signals import user_logged_in, user_logged_out
+# 导入邮件发送模块
 from django.core.mail import EmailMultiAlternatives
+# 导入数据库保存后信号
 from django.db.models.signals import post_save
+# 导入信号接收器装饰器
 from django.dispatch import receiver
 
+# 导入评论模型
 from comments.models import Comment
+# 导入评论邮件工具函数
 from comments.utils import send_comment_email
+# 导入蜘蛛通知工具
 from djangoblog.spider_notify import SpiderNotify
+# 导入自定义缓存工具函数
 from djangoblog.utils import cache, expire_view_cache, delete_sidebar_cache, delete_view_cache
+# 导入获取当前站点工具
 from djangoblog.utils import get_current_site
+# 导入OAuth用户模型
 from oauth.models import OAuthUser
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
+# 定义OAuth用户登录信号
 oauth_user_login_signal = django.dispatch.Signal(['id'])
+# 定义发送邮件信号
 send_email_signal = django.dispatch.Signal(
     ['emailto', 'title', 'content'])
 
 
+# 注册发送邮件信号处理器
 @receiver(send_email_signal)
 def send_email_signal_handler(sender, **kwargs):
+    # 获取邮件接收者、标题和内容
     emailto = kwargs['emailto']
     title = kwargs['title']
     content = kwargs['content']
 
+    # 创建邮件对象
     msg = EmailMultiAlternatives(
         title,
         content,
         from_email=settings.DEFAULT_FROM_EMAIL,
         to=emailto)
+    # 设置邮件内容类型为HTML
     msg.content_subtype = "html"
 
+    # 导入邮件发送日志模型
     from servermanager.models import EmailSendLog
+    # 创建邮件发送日志记录
     log = EmailSendLog()
     log.title = title
     log.content = content
     log.emailto = ','.join(emailto)
 
+    # 尝试发送邮件
     try:
         result = msg.send()
+        # 记录发送结果（成功发送数量大于0）
         log.send_result = result > 0
     except Exception as e:
+        # 记录发送失败的错误信息
         logger.error(f"失败邮箱号: {emailto}, {e}")
         log.send_result = False
+    # 保存邮件发送日志
     log.save()
 
 
+# 注册OAuth用户登录信号处理器
 @receiver(oauth_user_login_signal)
 def oauth_user_login_signal_handler(sender, **kwargs):
+    # 获取OAuth用户ID
     id = kwargs['id']
+    # 获取OAuth用户对象
     oauthuser = OAuthUser.objects.get(id=id)
+    # 获取当前站点域名
     site = get_current_site().domain
+    # 检查用户头像是否需要更新
     if oauthuser.picture and not oauthuser.picture.find(site) >= 0:
+        # 导入保存用户头像工具函数
         from djangoblog.utils import save_user_avatar
+        # 保存用户头像并更新URL
         oauthuser.picture = save_user_avatar(oauthuser.picture)
         oauthuser.save()
 
+    # 删除侧边栏缓存
     delete_sidebar_cache()
 
 
+# 注册模型保存后信号处理器
 @receiver(post_save)
 def model_post_save_callback(
         sender,
@@ -73,50 +110,76 @@ def model_post_save_callback(
         using,
         update_fields,
         **kwargs):
+    # 初始化清除缓存标志
     clearcache = False
+    # 如果是管理员日志条目，直接返回
     if isinstance(instance, LogEntry):
         return
+    # 检查实例是否有get_full_url方法
     if 'get_full_url' in dir(instance):
+        # 判断是否为更新浏览量的操作
         is_update_views = update_fields == {'views'}
+        # 如果不是测试环境且不是更新浏览量的操作
         if not settings.TESTING and not is_update_views:
             try:
+                # 获取实例的完整URL并通知蜘蛛
                 notify_url = instance.get_full_url()
                 SpiderNotify.baidu_notify([notify_url])
             except Exception as ex:
+                # 记录通知蜘蛛时的错误
                 logger.error("notify sipder", ex)
+        # 如果不是更新浏览量的操作，设置清除缓存标志
         if not is_update_views:
             clearcache = True
 
+    # 如果是评论实例
     if isinstance(instance, Comment):
+        # 如果评论已启用
         if instance.is_enable:
+            # 获取文章路径
             path = instance.article.get_absolute_url()
+            # 获取当前站点域名
             site = get_current_site().domain
+            # 处理端口号
             if site.find(':') > 0:
                 site = site[0:site.find(':')]
 
+            # 使文章详情页缓存过期
             expire_view_cache(
                 path,
                 servername=site,
                 serverport=80,
                 key_prefix='blogdetail')
+            # 删除SEO处理器缓存
             if cache.get('seo_processor'):
                 cache.delete('seo_processor')
+            # 删除文章评论缓存
             comment_cache_key = 'article_comments_{id}'.format(
                 id=instance.article.id)
             cache.delete(comment_cache_key)
+            # 删除侧边栏缓存
             delete_sidebar_cache()
+            # 删除文章评论视图缓存
             delete_view_cache('article_comments', [str(instance.article.pk)])
 
+            # 在新线程中发送评论邮件
             _thread.start_new_thread(send_comment_email, (instance,))
 
+    # 如果需要清除缓存
     if clearcache:
+        # 清除所有缓存
         cache.clear()
 
 
+# 注册用户登录和登出信号处理器
 @receiver(user_logged_in)
 @receiver(user_logged_out)
 def user_auth_callback(sender, request, user, **kwargs):
+    # 如果用户存在且有用户名
     if user and user.username:
+        # 记录用户信息
         logger.info(user)
+        # 删除侧边栏缓存
         delete_sidebar_cache()
-        # cache.clear()
+        # 注释掉的清除所有缓存操作
+        # cache.clear()

src/DjangoBlog/djangoblog/elasticsearch_backend.py

@@ -180,4 +180,4 @@ class ElasticSearchModelSearchForm(ModelSearchForm):
 
 class ElasticSearchEngine(BaseEngine):
     backend = ElasticSearchBackend
-    query = ElasticSearchQuery
+    query = ElasticSearchQuery

src/DjangoBlog/djangoblog/feeds.py

@@ -1,40 +1,66 @@
+# 导入用户模型获取函数
 from django.contrib.auth import get_user_model
+# 导入RSS订阅视图基类
 from django.contrib.syndication.views import Feed
+# 导入时区相关模块
 from django.utils import timezone
+# 导入RSS 2.0 feed生成器
 from django.utils.feedgenerator import Rss201rev2Feed
 
+# 导入博客模型
 from blog.models import Article
+# 导入自定义Markdown工具
 from djangoblog.utils import CommonMarkdown
 
 
+# Django博客RSS订阅类，继承自Feed
 class DjangoBlogFeed(Feed):
+    # 指定feed类型为RSS 2.0
     feed_type = Rss201rev2Feed
 
+    # feed描述
     description = '大巧无工,重剑无锋.'
+    # feed标题
     title = "且听风吟 大巧无工,重剑无锋. "
+    # feed链接
     link = "/feed/"
 
+    # 获取作者名称的方法
     def author_name(self):
+        # 返回第一个用户的昵称
         return get_user_model().objects.first().nickname
 
+    # 获取作者链接的方法
     def author_link(self):
+        # 返回第一个用户的绝对URL
         return get_user_model().objects.first().get_absolute_url()
 
+    # 获取feed项的方法
     def items(self):
+        # 返回最近发布的5篇文章，按发布时间倒序排列
         return Article.objects.filter(type='a', status='p').order_by('-pub_time')[:5]
 
+    # 获取单个feed项标题的方法
     def item_title(self, item):
         return item.title
 
+    # 获取单个feed项描述的方法
     def item_description(self, item):
+        # 将Markdown内容转换为HTML
         return CommonMarkdown.get_markdown(item.body)
 
+    # 获取feed版权信息的方法
     def feed_copyright(self):
+        # 获取当前年份
         now = timezone.now()
         return "Copyright© {year} 且听风吟".format(year=now.year)
 
+    # 获取单个feed项链接的方法
     def item_link(self, item):
         return item.get_absolute_url()
 
+    # 获取单个feed项唯一标识的方法
     def item_guid(self, item):
-        return
+        # 这里缺少返回值，应该返回一个唯一标识符
+        # 通常可以使用文章的绝对URL或ID作为guid
+        return

src/DjangoBlog/djangoblog/logentryadmin.py

@@ -1,91 +1,135 @@
+# 导入Django管理员模块
 from django.contrib import admin
+# 导入删除操作常量
 from django.contrib.admin.models import DELETION
+# 导入内容类型模型
 from django.contrib.contenttypes.models import ContentType
+# 导入URL反向解析相关模块
 from django.urls import reverse, NoReverseMatch
+# 导入字符串强制转换工具
 from django.utils.encoding import force_str
+# 导入HTML转义工具
 from django.utils.html import escape
+# 导入安全字符串标记工具
 from django.utils.safestring import mark_safe
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
 
 
+# 日志条目管理类，继承自admin.ModelAdmin
 class LogEntryAdmin(admin.ModelAdmin):
+    # 列表页面过滤器
     list_filter = [
-        'content_type'
+        'content_type'  # 按内容类型过滤
     ]
 
+    # 搜索字段
     search_fields = [
-        'object_repr',
-        'change_message'
+        'object_repr',  # 对象表示
+        'change_message'  # 变更消息
     ]
 
+    # 列表中可作为链接点击的字段
     list_display_links = [
-        'action_time',
-        'get_change_message',
+        'action_time',  # 操作时间
+        'get_change_message',  # 变更消息
     ]
+
+    # 列表页面显示的字段
     list_display = [
-        'action_time',
-        'user_link',
-        'content_type',
-        'object_link',
-        'get_change_message',
+        'action_time',  # 操作时间
+        'user_link',  # 用户链接（自定义方法）
+        'content_type',  # 内容类型
+        'object_link',  # 对象链接（自定义方法）
+        'get_change_message',  # 变更消息
     ]
 
+    # 是否允许添加权限
     def has_add_permission(self, request):
+        # 禁止添加日志条目
         return False
 
+    # 是否允许修改权限
     def has_change_permission(self, request, obj=None):
+        # 只有超级用户或有修改日志权限的用户可以查看，但不能通过POST修改
         return (
                 request.user.is_superuser or
                 request.user.has_perm('admin.change_logentry')
         ) and request.method != 'POST'
 
+    # 是否允许删除权限
     def has_delete_permission(self, request, obj=None):
+        # 禁止删除日志条目
         return False
 
+    # 自定义方法：显示对象链接
     def object_link(self, obj):
+        # 转义对象表示字符串
         object_link = escape(obj.object_repr)
         content_type = obj.content_type
 
+        # 如果不是删除操作且内容类型存在
         if obj.action_flag != DELETION and content_type is not None:
-            # try returning an actual link instead of object repr string
+            # 尝试返回实际链接而不是对象表示字符串
             try:
+                # 构建对象编辑页面的URL
                 url = reverse(
                     'admin:{}_{}_change'.format(content_type.app_label,
                                                 content_type.model),
                     args=[obj.object_id]
                 )
+                # 创建HTML链接
                 object_link = '<a href="{}">{}</a>'.format(url, object_link)
             except NoReverseMatch:
+                # 如果无法构建URL，保持原样
                 pass
+        # 返回标记为安全的HTML
         return mark_safe(object_link)
 
+    # 设置自定义方法的排序字段
     object_link.admin_order_field = 'object_repr'
+    # 设置自定义方法的显示名称
     object_link.short_description = _('object')
 
+    # 自定义方法：显示用户链接
     def user_link(self, obj):
+        # 获取用户模型的内容类型
         content_type = ContentType.objects.get_for_model(type(obj.user))
+        # 转义用户字符串表示
         user_link = escape(force_str(obj.user))
         try:
-            # try returning an actual link instead of object repr string
+            # 尝试返回实际链接而不是用户表示字符串
+            # 构建用户编辑页面的URL
             url = reverse(
                 'admin:{}_{}_change'.format(content_type.app_label,
                                             content_type.model),
                 args=[obj.user.pk]
             )
+            # 创建HTML链接
             user_link = '<a href="{}">{}</a>'.format(url, user_link)
         except NoReverseMatch:
+            # 如果无法构建URL，保持原样
             pass
+        # 返回标记为安全的HTML
         return mark_safe(user_link)
 
+    # 设置自定义方法的排序字段
     user_link.admin_order_field = 'user'
+    # 设置自定义方法的显示名称
     user_link.short_description = _('user')
 
+    # 获取查询集的方法
     def get_queryset(self, request):
+        # 调用父类的get_queryset方法
         queryset = super(LogEntryAdmin, self).get_queryset(request)
+        # 预取关联的内容类型数据
         return queryset.prefetch_related('content_type')
 
+    # 获取管理动作的方法
     def get_actions(self, request):
+        # 调用父类的get_actions方法
         actions = super(LogEntryAdmin, self).get_actions(request)
+        # 删除"删除选中"动作
         if 'delete_selected' in actions:
             del actions['delete_selected']
-        return actions
+        return actions

src/DjangoBlog/djangoblog/settings.py

@@ -9,228 +9,252 @@ https://docs.djangoproject.com/en/1.10/topics/settings/
 For the full list of settings and their values, see
 https://docs.djangoproject.com/en/1.10/ref/settings/
 """
+# 导入操作系统模块
 import os
+# 导入系统模块
 import sys
+# 导入路径处理模块
 from pathlib import Path
 
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
 
 
+# 环境变量转换为布尔值的辅助函数
 def env_to_bool(env, default):
+    # 获取环境变量值
     str_val = os.environ.get(env)
+    # 如果环境变量不存在则返回默认值，否则进行布尔转换
     return default if str_val is None else str_val == 'True'
 
 
-# Build paths inside the project like this: BASE_DIR / 'subdir'.
+# 构建项目内部路径，如: BASE_DIR / 'subdir'
 BASE_DIR = Path(__file__).resolve().parent.parent
 
 # Quick-start development settings - unsuitable for production
 # See https://docs.djangoproject.com/en/1.10/howto/deployment/checklist/
 
 # SECURITY WARNING: keep the secret key used in production secret!
+# 从环境变量获取密钥，如果不存在则使用默认值（仅用于开发）
 SECRET_KEY = os.environ.get(
     'DJANGO_SECRET_KEY') or 'n9ceqv38)#&mwuat@(mjb_p%em$e8$qyr#fw9ot!=ba6lijx-6'
 # SECURITY WARNING: don't run with debug turned on in production!
+# 调试模式设置，从环境变量获取或默认为True
 DEBUG = env_to_bool('DJANGO_DEBUG', True)
 # DEBUG = False
+# 测试模式判断
 TESTING = len(sys.argv) > 1 and sys.argv[1] == 'test'
 
+# 允许的主机列表
 # ALLOWED_HOSTS = []
 ALLOWED_HOSTS = ['*', '127.0.0.1', 'example.com']
-# django 4.0新增配置
+# django 4.0新增配置，信任的CSRF来源
 CSRF_TRUSTED_ORIGINS = ['http://example.com']
-# Application definition
-
 
+# 应用定义
 INSTALLED_APPS = [
     # 'django.contrib.admin',
+    # 使用简化的管理员配置
     'django.contrib.admin.apps.SimpleAdminConfig',
-    'django.contrib.auth',
-    'django.contrib.contenttypes',
-    'django.contrib.sessions',
-    'django.contrib.messages',
-    'django.contrib.staticfiles',
-    'django.contrib.sites',
-    'django.contrib.sitemaps',
-    'mdeditor',
-    'haystack',
-    'blog',
-    'accounts',
-    'comments',
-    'oauth',
-    'servermanager',
-    'owntracks',
-    'compressor',
-    'djangoblog'
+    'django.contrib.auth',           # 认证系统
+    'django.contrib.contenttypes',   # 内容类型框架
+    'django.contrib.sessions',       # 会话框架
+    'django.contrib.messages',       # 消息框架
+    'django.contrib.staticfiles',    # 静态文件管理
+    'django.contrib.sites',          # 站点框架
+    'django.contrib.sitemaps',       # 站点地图
+    'mdeditor',                      # Markdown编辑器
+    'haystack',                      # 搜索框架
+    'blog',                          # 博客应用
+    'accounts',                      # 账户应用
+    'comments',                      # 评论应用
+    'oauth',                         # OAuth认证
+    'servermanager',                 # 服务器管理
+    'owntracks',                     # OwnTracks位置追踪
+    'compressor',                    # 静态文件压缩
+    'djangoblog'                     # 主应用
 ]
 
+# 中间件配置
 MIDDLEWARE = [
-
-    'django.middleware.security.SecurityMiddleware',
-    'django.contrib.sessions.middleware.SessionMiddleware',
-    'django.middleware.locale.LocaleMiddleware',
-    'django.middleware.gzip.GZipMiddleware',
-    # 'django.middleware.cache.UpdateCacheMiddleware',
-    'django.middleware.common.CommonMiddleware',
-    # 'django.middleware.cache.FetchFromCacheMiddleware',
-    'django.middleware.csrf.CsrfViewMiddleware',
-    'django.contrib.auth.middleware.AuthenticationMiddleware',
-    'django.contrib.messages.middleware.MessageMiddleware',
-    'django.middleware.clickjacking.XFrameOptionsMiddleware',
-    'django.middleware.http.ConditionalGetMiddleware',
-    'blog.middleware.OnlineMiddleware'
+    'django.middleware.security.SecurityMiddleware',          # 安全中间件
+    'django.contrib.sessions.middleware.SessionMiddleware',   # 会话中间件
+    'django.middleware.locale.LocaleMiddleware',              # 本地化中间件
+    'django.middleware.gzip.GZipMiddleware',                  # GZip压缩中间件
+    # 'django.middleware.cache.UpdateCacheMiddleware',        # 缓存更新中间件（注释）
+    'django.middleware.common.CommonMiddleware',              # 通用中间件
+    # 'django.middleware.cache.FetchFromCacheMiddleware',     # 缓存获取中间件（注释）
+    'django.middleware.csrf.CsrfViewMiddleware',              # CSRF保护中间件
+    'django.contrib.auth.middleware.AuthenticationMiddleware', # 认证中间件
+    'django.contrib.messages.middleware.MessageMiddleware',   # 消息中间件
+    'django.middleware.clickjacking.XFrameOptionsMiddleware', # 点击劫持保护
+    'django.middleware.http.ConditionalGetMiddleware',        # 条件GET中间件
+    'blog.middleware.OnlineMiddleware'                        # 自定义在线中间件
 ]
 
+# 根URL配置
 ROOT_URLCONF = 'djangoblog.urls'
 
+# 模板配置
 TEMPLATES = [
     {
-        'BACKEND': 'django.template.backends.django.DjangoTemplates',
-        'DIRS': [os.path.join(BASE_DIR, 'templates')],
-        'APP_DIRS': True,
+        'BACKEND': 'django.template.backends.django.DjangoTemplates',  # Django模板引擎
+        'DIRS': [os.path.join(BASE_DIR, 'templates')],                 # 模板目录
+        'APP_DIRS': True,                                              # 启用应用模板目录
         'OPTIONS': {
-            'context_processors': [
-                'django.template.context_processors.debug',
-                'django.template.context_processors.request',
-                'django.contrib.auth.context_processors.auth',
-                'django.contrib.messages.context_processors.messages',
-                'blog.context_processors.seo_processor'
+            'context_processors': [                                    # 上下文处理器
+                'django.template.context_processors.debug',           # 调试信息
+                'django.template.context_processors.request',         # 请求对象
+                'django.contrib.auth.context_processors.auth',        # 认证信息
+                'django.contrib.messages.context_processors.messages', # 消息框架
+                'blog.context_processors.seo_processor'               # 自定义SEO处理器
             ],
         },
     },
 ]
 
+# WSGI应用配置
 WSGI_APPLICATION = 'djangoblog.wsgi.application'
 
-# Database
+# 数据库配置
 # https://docs.djangoproject.com/en/1.10/ref/settings/#databases
-
-
 DATABASES = {
     'default': {
-        'ENGINE': 'django.db.backends.mysql',
-        'NAME': 'djangoblog',
-        'USER': 'root',
-        'PASSWORD': '123456',
-        'HOST': '127.0.0.1',
-        'PORT': 3306,
+        'ENGINE': 'django.db.backends.mysql',  # MySQL数据库引擎
+        'NAME': 'djangoblog',                  # 数据库名称
+        'USER': 'root',                        # 数据库用户
+        'PASSWORD': '123456',                  # 数据库密码
+        'HOST': '127.0.0.1',                  # 数据库主机
+        'PORT': 3306,                         # 数据库端口
     }
 }
 
-# Password validation
+# 密码验证配置
 # https://docs.djangoproject.com/en/1.10/ref/settings/#auth-password-validators
-
 AUTH_PASSWORD_VALIDATORS = [
     {
-        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
+        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',  # 用户属性相似性验证
     },
     {
-        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
+        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',           # 最小长度验证
     },
     {
-        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
+        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',          # 常见密码验证
     },
     {
-        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
+        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',         # 数字密码验证
     },
 ]
 
+# 多语言配置
 LANGUAGES = (
-    ('en', _('English')),
-    ('zh-hans', _('Simplified Chinese')),
-    ('zh-hant', _('Traditional Chinese')),
+    ('en', _('English')),                # 英语
+    ('zh-hans', _('Simplified Chinese')), # 简体中文
+    ('zh-hant', _('Traditional Chinese')), # 繁体中文
 )
+# 本地化文件路径
 LOCALE_PATHS = (
     os.path.join(BASE_DIR, 'locale'),
 )
 
+# 默认语言代码
 LANGUAGE_CODE = 'zh-hans'
-
+# 时区设置
 TIME_ZONE = 'Asia/Shanghai'
-
+# 启用国际化
 USE_I18N = True
-
+# 启用本地化
 USE_L10N = True
-
+# 使用时区
 USE_TZ = False
 
-# Static files (CSS, JavaScript, Images)
+# 静态文件配置 (CSS, JavaScript, Images)
 # https://docs.djangoproject.com/en/1.10/howto/static-files/
 
-
+# Haystack搜索配置
 HAYSTACK_CONNECTIONS = {
     'default': {
-        'ENGINE': 'djangoblog.whoosh_cn_backend.WhooshEngine',
-        'PATH': os.path.join(os.path.dirname(__file__), 'whoosh_index'),
+        'ENGINE': 'djangoblog.whoosh_cn_backend.WhooshEngine',  # Whoosh搜索引擎
+        'PATH': os.path.join(os.path.dirname(__file__), 'whoosh_index'),  # 索引路径
     },
 }
-# Automatically update searching index
+# 自动更新搜索索引
 HAYSTACK_SIGNAL_PROCESSOR = 'haystack.signals.RealtimeSignalProcessor'
-# Allow user login with username and password
+# 允许用户使用用户名和密码登录的认证后端
 AUTHENTICATION_BACKENDS = [
     'accounts.user_login_backend.EmailOrUsernameModelBackend']
 
+# 静态文件根目录
 STATIC_ROOT = os.path.join(BASE_DIR, 'collectedstatic')
-
+# 静态文件URL
 STATIC_URL = '/static/'
+# 静态文件目录
 STATICFILES = os.path.join(BASE_DIR, 'static')
 
+# 自定义用户模型
 AUTH_USER_MODEL = 'accounts.BlogUser'
+# 登录URL
 LOGIN_URL = '/login/'
 
+# 时间格式
 TIME_FORMAT = '%Y-%m-%d %H:%M:%S'
+# 日期时间格式
 DATE_TIME_FORMAT = '%Y-%m-%d'
 
-# bootstrap color styles
+# bootstrap颜色样式
 BOOTSTRAP_COLOR_TYPES = [
     'default', 'primary', 'success', 'info', 'warning', 'danger'
 ]
 
-# paginate
+# 分页设置
 PAGINATE_BY = 10
-# http cache timeout
+# HTTP缓存超时时间（秒）
 CACHE_CONTROL_MAX_AGE = 2592000
-# cache setting
+# 缓存配置
 CACHES = {
     'default': {
-        'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
-        'TIMEOUT': 10800,
-        'LOCATION': 'unique-snowflake',
+        'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',  # 本地内存缓存
+        'TIMEOUT': 10800,                                            # 缓存超时3小时
+        'LOCATION': 'unique-snowflake',                              # 缓存位置标识
     }
 }
-# 使用redis作为缓存
+# 如果设置了Redis环境变量，使用Redis作为缓存
 if os.environ.get("DJANGO_REDIS_URL"):
     CACHES = {
         'default': {
-            'BACKEND': 'django.core.cache.backends.redis.RedisCache',
-            'LOCATION': f'redis://{os.environ.get("DJANGO_REDIS_URL")}',
+            'BACKEND': 'django.core.cache.backends.redis.RedisCache',  # Redis缓存后端
+            'LOCATION': f'redis://{os.environ.get("DJANGO_REDIS_URL")}',  # Redis连接地址
         }
     }
 
+# 站点ID
 SITE_ID = 1
+# 百度站长平台通知URL
 BAIDU_NOTIFY_URL = os.environ.get('DJANGO_BAIDU_NOTIFY_URL') \
                    or 'http://data.zz.baidu.com/urls?site=https://www.lylinux.net&token=1uAOGrMsUm5syDGn'
 
-# Email:
-EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
-EMAIL_USE_TLS = env_to_bool('DJANGO_EMAIL_TLS', False)
-EMAIL_USE_SSL = env_to_bool('DJANGO_EMAIL_SSL', True)
-EMAIL_HOST = os.environ.get('DJANGO_EMAIL_HOST') or 'smtp.mxhichina.com'
-EMAIL_PORT = int(os.environ.get('DJANGO_EMAIL_PORT') or 465)
-EMAIL_HOST_USER = os.environ.get('DJANGO_EMAIL_USER')
-EMAIL_HOST_PASSWORD = os.environ.get('DJANGO_EMAIL_PASSWORD')
-DEFAULT_FROM_EMAIL = EMAIL_HOST_USER
-SERVER_EMAIL = EMAIL_HOST_USER
-# Setting debug=false did NOT handle except email notifications
-ADMINS = [('admin', os.environ.get('DJANGO_ADMIN_EMAIL') or 'admin@admin.com')]
-# WX ADMIN password(Two times md5)
+# 邮件配置:
+EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'  # SMTP邮件后端
+EMAIL_USE_TLS = env_to_bool('DJANGO_EMAIL_TLS', False)         # 是否使用TLS
+EMAIL_USE_SSL = env_to_bool('DJANGO_EMAIL_SSL', True)          # 是否使用SSL
+EMAIL_HOST = os.environ.get('DJANGO_EMAIL_HOST') or 'smtp.mxhichina.com'  # 邮件主机
+EMAIL_PORT = int(os.environ.get('DJANGO_EMAIL_PORT') or 465)              # 邮件端口
+EMAIL_HOST_USER = os.environ.get('DJANGO_EMAIL_USER')                     # 邮件用户
+EMAIL_HOST_PASSWORD = os.environ.get('DJANGO_EMAIL_PASSWORD')             # 邮件密码
+DEFAULT_FROM_EMAIL = EMAIL_HOST_USER                                      # 默认发件人
+SERVER_EMAIL = EMAIL_HOST_USER                                            # 服务器邮件
+# 设置debug=false时处理异常邮件通知
+ADMINS = [('admin', os.environ.get('DJANGO_ADMIN_EMAIL') or 'admin@admin.com')]  # 管理员邮箱
+# 微信管理员密码(两次md5加密)
 WXADMIN = os.environ.get(
     'DJANGO_WXADMIN_PASSWORD') or '995F03AC401D6CABABAEF756FC4D43C7'
 
+# 日志路径配置
 LOG_PATH = os.path.join(BASE_DIR, 'logs')
 if not os.path.exists(LOG_PATH):
     os.makedirs(LOG_PATH, exist_ok=True)
 
+# 日志配置
 LOGGING = {
     'version': 1,
     'disable_existing_loggers': False,
@@ -240,42 +264,42 @@ LOGGING = {
     },
     'formatters': {
         'verbose': {
-            'format': '[%(asctime)s] %(levelname)s [%(name)s.%(funcName)s:%(lineno)d %(module)s] %(message)s',
+            'format': '[%(asctime)s] %(levelname)s [%(name)s.%(funcName)s:%(lineno)d %(module)s] %(message)s',  # 详细格式
         }
     },
     'filters': {
         'require_debug_false': {
-            '()': 'django.utils.log.RequireDebugFalse',
+            '()': 'django.utils.log.RequireDebugFalse',  # 要求调试关闭的过滤器
         },
         'require_debug_true': {
-            '()': 'django.utils.log.RequireDebugTrue',
+            '()': 'django.utils.log.RequireDebugTrue',   # 要求调试开启的过滤器
         },
     },
     'handlers': {
         'log_file': {
             'level': 'INFO',
-            'class': 'logging.handlers.TimedRotatingFileHandler',
-            'filename': os.path.join(LOG_PATH, 'djangoblog.log'),
-            'when': 'D',
+            'class': 'logging.handlers.TimedRotatingFileHandler',  # 时间轮转文件处理器
+            'filename': os.path.join(LOG_PATH, 'djangoblog.log'),  # 日志文件路径
+            'when': 'D',                                           # 按天轮转
             'formatter': 'verbose',
             'interval': 1,
             'delay': True,
-            'backupCount': 5,
+            'backupCount': 5,                                      # 保留5个备份文件
             'encoding': 'utf-8'
         },
         'console': {
             'level': 'DEBUG',
-            'filters': ['require_debug_true'],
+            'filters': ['require_debug_true'],                     # 仅在调试模式下输出到控制台
             'class': 'logging.StreamHandler',
             'formatter': 'verbose'
         },
         'null': {
-            'class': 'logging.NullHandler',
+            'class': 'logging.NullHandler',                        # 空处理器
         },
         'mail_admins': {
             'level': 'ERROR',
-            'filters': ['require_debug_false'],
-            'class': 'django.utils.log.AdminEmailHandler'
+            'filters': ['require_debug_false'],                    # 仅在非调试模式下发送邮件
+            'class': 'django.utils.log.AdminEmailHandler'          # 管理员邮件处理器
         }
     },
     'loggers': {
@@ -292,67 +316,72 @@ LOGGING = {
     }
 }
 
+# 静态文件查找器
 STATICFILES_FINDERS = (
-    'django.contrib.staticfiles.finders.FileSystemFinder',
-    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
+    'django.contrib.staticfiles.finders.FileSystemFinder',    # 文件系统查找器
+    'django.contrib.staticfiles.finders.AppDirectoriesFinder', # 应用目录查找器
     # other
-    'compressor.finders.CompressorFinder',
+    'compressor.finders.CompressorFinder',                    # 压缩器查找器
 )
+# 启用压缩
 COMPRESS_ENABLED = True
 # COMPRESS_OFFLINE = True
 
-
+# CSS压缩过滤器
 COMPRESS_CSS_FILTERS = [
     # creates absolute urls from relative ones
-    'compressor.filters.css_default.CssAbsoluteFilter',
+    'compressor.filters.css_default.CssAbsoluteFilter',  # 将相对URL转换为绝对URL
     # css minimizer
-    'compressor.filters.cssmin.CSSMinFilter'
+    'compressor.filters.cssmin.CSSMinFilter'             # CSS压缩过滤器
 ]
+# JavaScript压缩过滤器
 COMPRESS_JS_FILTERS = [
-    'compressor.filters.jsmin.JSMinFilter'
+    'compressor.filters.jsmin.JSMinFilter'               # JS压缩过滤器
 ]
 
-MEDIA_ROOT = os.path.join(BASE_DIR, 'uploads')
-MEDIA_URL = '/media/'
-X_FRAME_OPTIONS = 'SAMEORIGIN'
+# 媒体文件配置
+MEDIA_ROOT = os.path.join(BASE_DIR, 'uploads')  # 媒体文件根目录
+MEDIA_URL = '/media/'                           # 媒体文件URL
+X_FRAME_OPTIONS = 'SAMEORIGIN'                 # 框架选项
 
 # 安全头部配置 - 防XSS和其他攻击
-SECURE_BROWSER_XSS_FILTER = True
-SECURE_CONTENT_TYPE_NOSNIFF = True
-SECURE_REFERRER_POLICY = 'strict-origin-when-cross-origin'
+SECURE_BROWSER_XSS_FILTER = True               # 启用浏览器XSS过滤器
+SECURE_CONTENT_TYPE_NOSNIFF = True             # 防止MIME类型嗅探
+SECURE_REFERRER_POLICY = 'strict-origin-when-cross-origin'  # 引用策略
 
 # 内容安全策略 (CSP) - 防XSS攻击
-CSP_DEFAULT_SRC = ["'self'"]
-CSP_SCRIPT_SRC = ["'self'", "'unsafe-inline'", "cdn.mathjax.org", "*.googleapis.com"]
-CSP_STYLE_SRC = ["'self'", "'unsafe-inline'", "*.googleapis.com", "*.gstatic.com"]
-CSP_IMG_SRC = ["'self'", "data:", "*.lylinux.net", "*.gravatar.com", "*.githubusercontent.com"]
-CSP_FONT_SRC = ["'self'", "*.googleapis.com", "*.gstatic.com"]
-CSP_CONNECT_SRC = ["'self'"]
-CSP_FRAME_SRC = ["'none'"]
-CSP_OBJECT_SRC = ["'none'"]
-
+CSP_DEFAULT_SRC = ["'self'"]                                                   # 默认源
+CSP_SCRIPT_SRC = ["'self'", "'unsafe-inline'", "cdn.mathjax.org", "*.googleapis.com"]  # 脚本源
+CSP_STYLE_SRC = ["'self'", "'unsafe-inline'", "*.googleapis.com", "*.gstatic.com"]     # 样式源
+CSP_IMG_SRC = ["'self'", "data:", "*.lylinux.net", "*.gravatar.com", "*.githubusercontent.com"]  # 图片源
+CSP_FONT_SRC = ["'self'", "*.googleapis.com", "*.gstatic.com"]                 # 字体源
+CSP_CONNECT_SRC = ["'self'"]                                                   # 连接源
+CSP_FRAME_SRC = ["'none'"]                                                     # 框架源
+CSP_OBJECT_SRC = ["'none'"]                                                    # 对象源
+
+# 默认自增字段类型
 DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'
 
+# 如果设置了Elasticsearch环境变量，配置Elasticsearch
 if os.environ.get('DJANGO_ELASTICSEARCH_HOST'):
     ELASTICSEARCH_DSL = {
         'default': {
-            'hosts': os.environ.get('DJANGO_ELASTICSEARCH_HOST')
+            'hosts': os.environ.get('DJANGO_ELASTICSEARCH_HOST')  # Elasticsearch主机
         },
     }
     HAYSTACK_CONNECTIONS = {
         'default': {
-            'ENGINE': 'djangoblog.elasticsearch_backend.ElasticSearchEngine',
+            'ENGINE': 'djangoblog.elasticsearch_backend.ElasticSearchEngine',  # Elasticsearch引擎
         },
     }
 
-# Plugin System
-PLUGINS_DIR = BASE_DIR / 'plugins'
-ACTIVE_PLUGINS = [
-    'article_copyright',
-    'reading_time',
-    'external_links',
-    'view_count',
-    'seo_optimizer',
-    'image_lazy_loading',
-]
-
+# 插件系统配置
+PLUGINS_DIR = BASE_DIR / 'plugins'  # 插件目录
+ACTIVE_PLUGINS = [                  # 激活的插件列表
+    'article_copyright',             # 文章版权插件
+    'reading_time',                  # 阅读时间插件
+    'external_links',                # 外部链接插件
+    'view_count',                    # 浏览计数插件
+    'seo_optimizer',                 # SEO优化插件
+    'image_lazy_loading',            # 图片懒加载插件
+]

src/DjangoBlog/djangoblog/sitemap.py

@@ -1,59 +1,90 @@
+# 导入Django站点地图相关模块
 from django.contrib.sitemaps import Sitemap
+# 导入URL反向解析模块
 from django.urls import reverse
 
+# 导入博客模型
 from blog.models import Article, Category, Tag
 
 
+# 静态视图站点地图类
 class StaticViewSitemap(Sitemap):
+    # 优先级（0.0-1.0）
     priority = 0.5
+    # 更新频率
     changefreq = 'daily'
 
+    # 返回站点地图中包含的项
     def items(self):
+        # 只包含首页
         return ['blog:index', ]
 
+    # 获取每个项的URL
     def location(self, item):
+        # 使用反向解析生成URL
         return reverse(item)
 
 
+# 文章站点地图类
 class ArticleSiteMap(Sitemap):
+    # 更新频率为每月
     changefreq = "monthly"
+    # 优先级为0.6
     priority = "0.6"
 
+    # 返回所有已发布的文章
     def items(self):
         return Article.objects.filter(status='p')
 
+    # 获取文章的最后修改时间
     def lastmod(self, obj):
         return obj.last_modify_time
 
 
+# 分类站点地图类
 class CategorySiteMap(Sitemap):
+    # 更新频率为每周
     changefreq = "Weekly"
+    # 优先级为0.6
     priority = "0.6"
 
+    # 返回所有分类
     def items(self):
         return Category.objects.all()
 
+    # 获取分类的最后修改时间
     def lastmod(self, obj):
         return obj.last_modify_time
 
 
+# 标签站点地图类
 class TagSiteMap(Sitemap):
+    # 更新频率为每周
     changefreq = "Weekly"
+    # 优先级为0.3
     priority = "0.3"
 
+    # 返回所有标签
     def items(self):
         return Tag.objects.all()
 
+    # 获取标签的最后修改时间
     def lastmod(self, obj):
         return obj.last_modify_time
 
 
+# 用户站点地图类
 class UserSiteMap(Sitemap):
+    # 更新频率为每周
     changefreq = "Weekly"
+    # 优先级为0.3
     priority = "0.3"
 
+    # 返回所有有文章的作者（去重）
     def items(self):
+        # 使用set去重，获取所有不重复的作者
         return list(set(map(lambda x: x.author, Article.objects.all())))
 
+    # 获取用户的注册时间
     def lastmod(self, obj):
-        return obj.date_joined
+        return obj.date_joined

src/DjangoBlog/djangoblog/spider_notify.py

@@ -1,21 +1,33 @@
+# 导入日志模块
 import logging
 
+# 导入请求库
 import requests
+# 导入Django配置模块
 from django.conf import settings
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
 
+# 蜘蛛通知类（用于通知搜索引擎网站内容更新）
 class SpiderNotify():
+    # 百度通知的静态方法
     @staticmethod
     def baidu_notify(urls):
         try:
+            # 将URL列表用换行符连接成字符串
             data = '\n'.join(urls)
+            # 向百度站长平台提交URL更新通知
             result = requests.post(settings.BAIDU_NOTIFY_URL, data=data)
+            # 记录百度返回的结果
             logger.info(result.text)
         except Exception as e:
+            # 记录通知过程中的错误
             logger.error(e)
 
+    # 通用通知方法（目前仅支持百度）
     @staticmethod
     def notify(url):
-        SpiderNotify.baidu_notify(url)
+        # 调用百度通知方法，支持单个URL或URL列表
+        SpiderNotify.baidu_notify(url)

src/DjangoBlog/djangoblog/tests.py

@@ -1,15 +1,25 @@
+# 导入Django测试基类
 from django.test import TestCase
 
+# 导入自定义工具函数（使用通配符导入）
 from djangoblog.utils import *
 
 
+# Django博客测试类，继承自TestCase
 class DjangoBlogTest(TestCase):
+    # 测试前置设置方法
     def setUp(self):
+        # 此处为空，没有特殊的测试前置设置
         pass
 
+    # 测试工具函数的测试方法
     def test_utils(self):
+        # 测试get_sha256函数
         md5 = get_sha256('test')
+        # 断言返回值不为None
         self.assertIsNotNone(md5)
+
+        # 测试CommonMarkdown.get_markdown函数
         c = CommonMarkdown.get_markdown('''
         # Title1
 
@@ -23,10 +33,14 @@ class DjangoBlogTest(TestCase):
 
 
         ''')
+        # 断言返回值不为None
         self.assertIsNotNone(c)
+
+        # 测试parse_dict_to_url函数
         d = {
             'd': 'key1',
             'd2': 'key2'
         }
         data = parse_dict_to_url(d)
-        self.assertIsNotNone(data)
+        # 断言返回值不为None
+        self.assertIsNotNone(data)

src/DjangoBlog/djangoblog/urls.py

@@ -13,66 +13,86 @@ Including another URLconf
     1. Import the include() function: from django.conf.urls import url, include
     2. Add a URL to urlpatterns:  url(r'^blog/', include('blog.urls'))
 """
+# 导入Django配置模块
 from django.conf import settings
+# 导入国际化URL模式
 from django.conf.urls.i18n import i18n_patterns
+# 导入静态文件服务
 from django.conf.urls.static import static
+# 导入站点地图视图
 from django.contrib.sitemaps.views import sitemap
+# 导入URL路径相关模块
 from django.urls import path, include
 from django.urls import re_path
+# 导入Haystack搜索视图工厂
 from haystack.views import search_view_factory
+# 导入JSON响应
 from django.http import JsonResponse
+# 导入时间模块
 import time
 
+# 导入自定义视图和组件
 from blog.views import EsSearchView
 from djangoblog.admin_site import admin_site
 from djangoblog.elasticsearch_backend import ElasticSearchModelSearchForm
 from djangoblog.feeds import DjangoBlogFeed
 from djangoblog.sitemap import ArticleSiteMap, CategorySiteMap, StaticViewSitemap, TagSiteMap, UserSiteMap
 
+# 站点地图配置字典
 sitemaps = {
-
-    'blog': ArticleSiteMap,
-    'Category': CategorySiteMap,
-    'Tag': TagSiteMap,
-    'User': UserSiteMap,
-    'static': StaticViewSitemap
+    'blog': ArticleSiteMap,        # 文章站点地图
+    'Category': CategorySiteMap,   # 分类站点地图
+    'Tag': TagSiteMap,             # 标签站点地图
+    'User': UserSiteMap,           # 用户站点地图
+    'static': StaticViewSitemap    # 静态页面站点地图
 }
 
-handler404 = 'blog.views.page_not_found_view'
-handler500 = 'blog.views.server_error_view'
-handle403 = 'blog.views.permission_denied_view'
+# 自定义错误处理视图
+handler404 = 'blog.views.page_not_found_view'      # 404错误处理
+handler500 = 'blog.views.server_error_view'        # 500错误处理
+handle403 = 'blog.views.permission_denied_view'    # 403错误处理
 
 
+# 健康检查接口函数
 def health_check(request):
     """
     健康检查接口
     简单返回服务健康状态
     """
     return JsonResponse({
-        'status': 'healthy',
-        'timestamp': time.time()
+        'status': 'healthy',       # 服务状态
+        'timestamp': time.time()   # 当前时间戳
     })
 
+
+# 基础URL模式（不包含国际化）
 urlpatterns = [
-    path('i18n/', include('django.conf.urls.i18n')),
-    path('health/', health_check, name='health_check'),
+    path('i18n/', include('django.conf.urls.i18n')),  # 国际化URL
+    path('health/', health_check, name='health_check'),  # 健康检查接口
 ]
+
+# 添加国际化URL模式
 urlpatterns += i18n_patterns(
-    re_path(r'^admin/', admin_site.urls),
-    re_path(r'', include('blog.urls', namespace='blog')),
-    re_path(r'mdeditor/', include('mdeditor.urls')),
-    re_path(r'', include('comments.urls', namespace='comment')),
-    re_path(r'', include('accounts.urls', namespace='account')),
-    re_path(r'', include('oauth.urls', namespace='oauth')),
+    re_path(r'^admin/', admin_site.urls),  # 管理员站点URL
+    re_path(r'', include('blog.urls', namespace='blog')),  # 博客应用URL
+    re_path(r'mdeditor/', include('mdeditor.urls')),  # Markdown编辑器URL
+    re_path(r'', include('comments.urls', namespace='comment')),  # 评论应用URL
+    re_path(r'', include('accounts.urls', namespace='account')),  # 账户应用URL
+    re_path(r'', include('oauth.urls', namespace='oauth')),  # OAuth认证URL
+    # 站点地图XML文件
     re_path(r'^sitemap\.xml$', sitemap, {'sitemaps': sitemaps},
             name='django.contrib.sitemaps.views.sitemap'),
-    re_path(r'^feed/$', DjangoBlogFeed()),
-    re_path(r'^rss/$', DjangoBlogFeed()),
+    re_path(r'^feed/$', DjangoBlogFeed()),  # RSS订阅feed
+    re_path(r'^rss/$', DjangoBlogFeed()),   # RSS订阅rss（别名）
+    # 搜索功能，使用ElasticSearch后端
     re_path('^search', search_view_factory(view_class=EsSearchView, form_class=ElasticSearchModelSearchForm),
             name='search'),
-    re_path(r'', include('servermanager.urls', namespace='servermanager')),
-    re_path(r'', include('owntracks.urls', namespace='owntracks'))
-    , prefix_default_language=False) + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
+    re_path(r'', include('servermanager.urls', namespace='servermanager')),  # 服务器管理URL
+    re_path(r'', include('owntracks.urls', namespace='owntracks')),  # OwnTracks位置追踪URL
+    prefix_default_language=False  # 不为默认语言添加语言前缀
+) + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)  # 静态文件服务
+
+# 在调试模式下添加媒体文件服务
 if settings.DEBUG:
     urlpatterns += static(settings.MEDIA_URL,
-                          document_root=settings.MEDIA_ROOT)
+                          document_root=settings.MEDIA_ROOT)

src/DjangoBlog/djangoblog/utils.py

@@ -1,64 +1,92 @@
 #!/usr/bin/env python
 # encoding: utf-8
 
-
+# 导入日志模块
 import logging
+# 导入操作系统模块
 import os
+# 导入随机数模块
 import random
+# 导入字符串处理模块
 import string
+# 导入UUID生成模块
 import uuid
+# 导入哈希算法模块
 from hashlib import sha256
 
+# 导入HTML清理库
 import bleach
+# 导入Markdown处理库
 import markdown
+# 导入HTTP请求库
 import requests
+# 导入Django配置模块
 from django.conf import settings
+# 导入站点模型
 from django.contrib.sites.models import Site
+# 导入Django缓存模块
 from django.core.cache import cache
+# 导入静态文件处理模块
 from django.templatetags.static import static
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
 
+# 获取最大文章ID和评论ID的函数
 def get_max_articleid_commentid():
+    # 延迟导入，避免循环导入
     from blog.models import Article
     from comments.models import Comment
+    # 返回最新文章和评论的ID
     return (Article.objects.latest().pk, Comment.objects.latest().pk)
 
 
+# SHA256哈希函数
 def get_sha256(str):
+    # 创建SHA256哈希对象
     m = sha256(str.encode('utf-8'))
+    # 返回十六进制哈希值
     return m.hexdigest()
 
 
+# 缓存装饰器
 def cache_decorator(expiration=3 * 60):
     def wrapper(func):
         def news(*args, **kwargs):
             try:
+                # 尝试从视图获取缓存键
                 view = args[0]
                 key = view.get_cache_key()
             except:
                 key = None
             if not key:
+                # 如果没有缓存键，根据函数参数生成唯一键
                 unique_str = repr((func, args, kwargs))
 
                 m = sha256(unique_str.encode('utf-8'))
                 key = m.hexdigest()
+            # 尝试从缓存获取值
             value = cache.get(key)
             if value is not None:
                 # logger.info('cache_decorator get cache:%s key:%s' % (func.__name__, key))
                 if str(value) == '__default_cache_value__':
+                    # 如果是默认缓存值，返回None
                     return None
                 else:
+                    # 返回缓存值
                     return value
             else:
+                # 如果缓存不存在，执行函数并设置缓存
                 logger.debug(
                     'cache_decorator set cache:%s key:%s' %
                     (func.__name__, key))
                 value = func(*args, **kwargs)
                 if value is None:
+                    # 如果函数返回None，设置默认缓存值
                     cache.set(key, '__default_cache_value__', expiration)
                 else:
+                    # 设置实际缓存值
                     cache.set(key, value, expiration)
                 return value
 
@@ -67,6 +95,7 @@ def cache_decorator(expiration=3 * 60):
     return wrapper
 
 
+# 使视图缓存过期的函数
 def expire_view_cache(path, servername, serverport, key_prefix=None):
     '''
     刷新视图缓存
@@ -79,53 +108,66 @@ def expire_view_cache(path, servername, serverport, key_prefix=None):
     from django.http import HttpRequest
     from django.utils.cache import get_cache_key
 
+    # 创建模拟请求
     request = HttpRequest()
     request.META = {'SERVER_NAME': servername, 'SERVER_PORT': serverport}
     request.path = path
 
+    # 获取缓存键
     key = get_cache_key(request, key_prefix=key_prefix, cache=cache)
     if key:
         logger.info('expire_view_cache:get key:{path}'.format(path=path))
         if cache.get(key):
+            # 删除缓存
             cache.delete(key)
         return True
     return False
 
 
+# 获取当前站点的缓存函数
 @cache_decorator()
 def get_current_site():
     site = Site.objects.get_current()
     return site
 
 
+# Markdown处理类
 class CommonMarkdown:
+    # 转换Markdown的静态方法
     @staticmethod
     def _convert_markdown(value):
+        # 创建Markdown处理器，启用扩展
         md = markdown.Markdown(
             extensions=[
-                'extra',
-                'codehilite',
-                'toc',
-                'tables',
+                'extra',      # 额外功能
+                'codehilite', # 代码高亮
+                'toc',        # 目录生成
+                'tables',     # 表格支持
             ]
         )
+        # 转换Markdown为HTML
         body = md.convert(value)
+        # 获取目录
         toc = md.toc
         return body, toc
 
+    # 获取带目录的Markdown
     @staticmethod
     def get_markdown_with_toc(value):
         body, toc = CommonMarkdown._convert_markdown(value)
         return body, toc
 
+    # 获取不带目录的Markdown
     @staticmethod
     def get_markdown(value):
         body, toc = CommonMarkdown._convert_markdown(value)
         return body
 
 
+# 发送邮件函数
 def send_email(emailto, title, content):
     from djangoblog.blog_signals import send_email_signal
+    # 发送邮件信号
     send_email_signal.send(
         send_email.__class__,
         emailto=emailto,
@@ -133,24 +175,31 @@ def send_email(emailto, title, content):
         content=content)
 
 
+# 生成随机验证码函数
 def generate_code() -> str:
     """生成随机数验证码"""
+    # 从数字中随机选择6个字符
     return ''.join(random.sample(string.digits, 6))
 
 
+# 将字典解析为URL参数字符串
 def parse_dict_to_url(dict):
     from urllib.parse import quote
+    # 将字典键值对转换为URL编码的参数字符串
     url = '&'.join(['{}={}'.format(quote(k, safe='/'), quote(v, safe='/'))
                     for k, v in dict.items()])
     return url
 
 
+# 获取博客设置的函数
 def get_blog_setting():
+    # 尝试从缓存获取博客设置
     value = cache.get('get_blog_setting')
     if value:
         return value
     else:
         from blog.models import BlogSettings
+        # 如果没有博客设置，创建默认设置
         if not BlogSettings.objects.count():
             setting = BlogSettings()
             setting.site_name = 'djangoblog'
@@ -167,12 +216,15 @@ def get_blog_setting():
             setting.show_gongan_code = False
             setting.comment_need_review = False
             setting.save()
+        # 获取第一个博客设置
         value = BlogSettings.objects.first()
         logger.info('set cache get_blog_setting')
+        # 设置缓存
         cache.set('get_blog_setting', value)
         return value
 
 
+# 保存用户头像函数
 def save_user_avatar(url):
     '''
     保存用户头像
@@ -182,47 +234,67 @@ def save_user_avatar(url):
     logger.info(url)
 
     try:
+        # 头像保存基础目录
         basedir = os.path.join(settings.STATICFILES, 'avatar')
+        # 下载头像
         rsp = requests.get(url, timeout=2)
         if rsp.status_code == 200:
+            # 如果目录不存在则创建
             if not os.path.exists(basedir):
                 os.makedirs(basedir)
 
+            # 图片扩展名列表
             image_extensions = ['.jpg', '.png', 'jpeg', '.gif']
+            # 判断是否为图片
             isimage = len([i for i in image_extensions if url.endswith(i)]) > 0
+            # 获取文件扩展名
             ext = os.path.splitext(url)[1] if isimage else '.jpg'
+            # 生成唯一文件名
             save_filename = str(uuid.uuid4().hex) + ext
             logger.info('保存用户头像:' + basedir + save_filename)
+            # 保存文件
             with open(os.path.join(basedir, save_filename), 'wb+') as file:
                 file.write(rsp.content)
+            # 返回静态文件URL
             return static('avatar/' + save_filename)
     except Exception as e:
+        # 记录错误并返回默认头像
         logger.error(e)
         return static('blog/img/avatar.png')
 
 
+# 删除侧边栏缓存函数
 def delete_sidebar_cache():
     from blog.models import LinkShowType
+    # 生成所有侧边栏缓存键
     keys = ["sidebar" + x for x in LinkShowType.values]
     for k in keys:
         logger.info('delete sidebar key:' + k)
+        # 删除缓存
         cache.delete(k)
 
 
+# 删除视图缓存函数
 def delete_view_cache(prefix, keys):
     from django.core.cache.utils import make_template_fragment_key
+    # 生成模板片段缓存键
     key = make_template_fragment_key(prefix, keys)
+    # 删除缓存
     cache.delete(key)
 
 
+# 获取资源URL函数
 def get_resource_url():
     if settings.STATIC_URL:
+        # 如果设置了静态URL，直接返回
         return settings.STATIC_URL
     else:
+        # 否则构建完整URL
         site = get_current_site()
         return 'http://' + site.domain + '/static/'
 
 
+# 允许的HTML标签白名单
 ALLOWED_TAGS = ['a', 'abbr', 'acronym', 'b', 'blockquote', 'code', 'em', 'i', 'li', 'ol', 'pre', 'strong', 'ul', 'h1',
                 'h2', 'p', 'span', 'div']
 
@@ -235,6 +307,7 @@ ALLOWED_CLASSES = [
     's1', 'ss', 'bp', 'vc', 'vg', 'vi', 'il'
 ]
 
+# 自定义class属性过滤器
 def class_filter(tag, name, value):
     """自定义class属性过滤器"""
     if name == 'class':
@@ -245,28 +318,29 @@ def class_filter(tag, name, value):
 
 # 安全的属性白名单
 ALLOWED_ATTRIBUTES = {
-    'a': ['href', 'title'], 
-    'abbr': ['title'], 
-    'acronym': ['title'],
-    'span': class_filter,
-    'div': class_filter,
-    'pre': class_filter,
-    'code': class_filter
+    'a': ['href', 'title'],        # 链接允许href和title属性
+    'abbr': ['title'],             # 缩写允许title属性
+    'acronym': ['title'],          # 首字母缩写允许title属性
+    'span': class_filter,          # span使用自定义class过滤器
+    'div': class_filter,           # div使用自定义class过滤器
+    'pre': class_filter,           # pre使用自定义class过滤器
+    'code': class_filter           # code使用自定义class过滤器
 }
 
 # 安全的协议白名单 - 防止javascript:等危险协议
 ALLOWED_PROTOCOLS = ['http', 'https', 'mailto']
 
+# HTML清理函数
 def sanitize_html(html):
     """
     安全的HTML清理函数
     使用bleach库进行白名单过滤，防止XSS攻击
     """
     return bleach.clean(
-        html, 
-        tags=ALLOWED_TAGS, 
-        attributes=ALLOWED_ATTRIBUTES,
-        protocols=ALLOWED_PROTOCOLS,  # 限制允许的协议
-        strip=True,  # 移除不允许的标签而不是转义
-        strip_comments=True  # 移除HTML注释
-    )
+        html,
+        tags=ALLOWED_TAGS,                    # 允许的标签
+        attributes=ALLOWED_ATTRIBUTES,        # 允许的属性
+        protocols=ALLOWED_PROTOCOLS,          # 限制允许的协议
+        strip=True,                           # 移除不允许的标签而不是转义
+        strip_comments=True                   # 移除HTML注释
+    )

src/DjangoBlog/djangoblog/whoosh_cn_backend.py

@@ -1,7 +1,9 @@
 # encoding: utf-8
 
+# 导入Python 2/3兼容性支持
 from __future__ import absolute_import, division, print_function, unicode_literals
 
+# 导入标准库模块
 import json
 import os
 import re
@@ -9,20 +11,35 @@ import shutil
 import threading
 import warnings
 
+# 导入Python 2/3兼容性库
 import six
+# 导入Django配置模块
 from django.conf import settings
+# 导入Django配置异常
 from django.core.exceptions import ImproperlyConfigured
+# 导入日期时间模块
 from datetime import datetime
+# 导入字符串强制转换工具
 from django.utils.encoding import force_str
+# 导入Haystack搜索引擎基类
 from haystack.backends import BaseEngine, BaseSearchBackend, BaseSearchQuery, EmptyResults, log_query
+# 导入Haystack常量
 from haystack.constants import DJANGO_CT, DJANGO_ID, ID
+# 导入Haystack异常
 from haystack.exceptions import MissingDependency, SearchBackendError, SkipDocument
+# 导入Haystack输入类型
 from haystack.inputs import Clean, Exact, PythonData, Raw
+# 导入Haystack搜索结果模型
 from haystack.models import SearchResult
+# 导入Haystack工具函数
 from haystack.utils import get_identifier, get_model_ct
+# 导入Haystack日志工具
 from haystack.utils import log as logging
+# 导入Haystack模型加载工具
 from haystack.utils.app_loading import haystack_get_model
+# 导入结巴中文分词器
 from jieba.analyse import ChineseAnalyzer
+# 导入Whoosh搜索库相关模块
 from whoosh import index
 from whoosh.analysis import StemmingAnalyzer
 from whoosh.fields import BOOLEAN, DATETIME, IDLIST, KEYWORD, NGRAM, NGRAMWORDS, NUMERIC, Schema, TEXT
@@ -34,36 +51,40 @@ from whoosh.qparser import QueryParser
 from whoosh.searching import ResultsPage
 from whoosh.writing import AsyncWriter
 
+# 尝试导入Whoosh库，如果失败则抛出缺失依赖异常
 try:
     import whoosh
 except ImportError:
     raise MissingDependency(
         "The 'whoosh' backend requires the installation of 'Whoosh'. Please refer to the documentation.")
 
-# Handle minimum requirement.
+# 处理最低版本要求
 if not hasattr(whoosh, '__version__') or whoosh.__version__ < (2, 5, 0):
     raise MissingDependency(
         "The 'whoosh' backend requires version 2.5.0 or greater.")
 
-# Bubble up the correct error.
-
+# 日期时间正则表达式，用于匹配和解析日期时间字符串
 DATETIME_REGEX = re.compile(
     '^(?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})T(?P<hour>\d{2}):(?P<minute>\d{2}):(?P<second>\d{2})(\.\d{3,6}Z?)?$')
+# 线程本地存储，用于RAM存储
 LOCALS = threading.local()
 LOCALS.RAM_STORE = None
 
 
+# 自定义Whoosh HTML格式化器类
 class WhooshHtmlFormatter(HtmlFormatter):
     """
     This is a HtmlFormatter simpler than the whoosh.HtmlFormatter.
     We use it to have consistent results across backends. Specifically,
     Solr, Xapian and Elasticsearch are using this formatting.
     """
+    # 简化的HTML模板
     template = '<%(tag)s>%(t)s</%(tag)s>'
 
 
+# Whoosh搜索后端类，继承自BaseSearchBackend
 class WhooshSearchBackend(BaseSearchBackend):
-    # Word reserved by Whoosh for special use.
+    # Whoosh保留的关键字
     RESERVED_WORDS = (
         'AND',
         'NOT',
@@ -71,38 +92,47 @@ class WhooshSearchBackend(BaseSearchBackend):
         'TO',
     )
 
-    # Characters reserved by Whoosh for special use.
-    # The '\\' must come first, so as not to overwrite the other slash
-    # replacements.
+    # Whoosh保留的特殊字符
+    # '\\' 必须放在第一位，以免覆盖其他斜杠替换
     RESERVED_CHARACTERS = (
         '\\', '+', '-', '&&', '||', '!', '(', ')', '{', '}',
         '[', ']', '^', '"', '~', '*', '?', ':', '.',
     )
 
+    # 初始化方法
     def __init__(self, connection_alias, **connection_options):
+        # 调用父类初始化方法
         super(
             WhooshSearchBackend,
             self).__init__(
             connection_alias,
             **connection_options)
+        # 设置完成标志
         self.setup_complete = False
+        # 是否使用文件存储
         self.use_file_storage = True
+        # 发布限制大小
         self.post_limit = getattr(
             connection_options,
             'POST_LIMIT',
             128 * 1024 * 1024)
+        # 索引路径
         self.path = connection_options.get('PATH')
 
+        # 检查存储类型
         if connection_options.get('STORAGE', 'file') != 'file':
             self.use_file_storage = False
 
+        # 如果使用文件存储但没有指定路径，抛出配置错误
         if self.use_file_storage and not self.path:
             raise ImproperlyConfigured(
                 "You must specify a 'PATH' in your settings for connection '%s'." %
                 connection_alias)
 
+        # 设置日志器
         self.log = logging.getLogger('haystack')
 
+    # 设置方法，延迟加载直到需要时
     def setup(self):
         """
         Defers loading until needed.
@@ -110,16 +140,18 @@ class WhooshSearchBackend(BaseSearchBackend):
         from haystack import connections
         new_index = False
 
-        # Make sure the index is there.
+        # 确保索引目录存在
         if self.use_file_storage and not os.path.exists(self.path):
             os.makedirs(self.path)
             new_index = True
 
+        # 检查索引目录是否可写
         if self.use_file_storage and not os.access(self.path, os.W_OK):
             raise IOError(
                 "The path to your Whoosh index '%s' is not writable for the current user/group." %
                 self.path)
 
+        # 根据存储类型选择存储方式
         if self.use_file_storage:
             self.storage = FileStorage(self.path)
         else:
@@ -130,10 +162,13 @@ class WhooshSearchBackend(BaseSearchBackend):
 
             self.storage = LOCALS.RAM_STORE
 
+        # 构建schema和内容字段名
         self.content_field_name, self.schema = self.build_schema(
             connections[self.connection_alias].get_unified_index().all_searchfields())
+        # 创建查询解析器
         self.parser = QueryParser(self.content_field_name, schema=self.schema)
 
+        # 创建或打开索引
         if new_index is True:
             self.index = self.storage.create_index(self.schema)
         else:
@@ -142,19 +177,22 @@ class WhooshSearchBackend(BaseSearchBackend):
             except index.EmptyIndexError:
                 self.index = self.storage.create_index(self.schema)
 
+        # 标记设置完成
         self.setup_complete = True
 
+    # 构建schema的方法
     def build_schema(self, fields):
+        # 基础schema字段
         schema_fields = {
             ID: WHOOSH_ID(stored=True, unique=True),
             DJANGO_CT: WHOOSH_ID(stored=True),
             DJANGO_ID: WHOOSH_ID(stored=True),
         }
-        # Grab the number of keys that are hard-coded into Haystack.
-        # We'll use this to (possibly) fail slightly more gracefully later.
+        # 获取硬编码到Haystack中的键数量
         initial_key_count = len(schema_fields)
         content_field_name = ''
 
+        # 遍历所有字段，构建schema
         for field_name, field_class in fields.items():
             if field_class.is_multivalued:
                 if field_class.indexed is False:
@@ -173,7 +211,7 @@ class WhooshSearchBackend(BaseSearchBackend):
                 schema_fields[field_class.index_fieldname] = NUMERIC(
                     stored=field_class.stored, numtype=float, field_boost=field_class.boost)
             elif field_class.field_type == 'boolean':
-                # Field boost isn't supported on BOOLEAN as of 1.8.2.
+                # 在Whoosh 1.8.2中，BOOLEAN字段不支持字段提升
                 schema_fields[field_class.index_fieldname] = BOOLEAN(
                     stored=field_class.stored)
             elif field_class.field_type == 'ngram':
@@ -184,40 +222,43 @@ class WhooshSearchBackend(BaseSearchBackend):
                                                                         stored=field_class.stored,
                                                                         field_boost=field_class.boost)
             else:
+                # 使用中文分词器处理文本字段
                 # schema_fields[field_class.index_fieldname] = TEXT(stored=True, analyzer=StemmingAnalyzer(), field_boost=field_class.boost, sortable=True)
                 schema_fields[field_class.index_fieldname] = TEXT(
                     stored=True, analyzer=ChineseAnalyzer(), field_boost=field_class.boost, sortable=True)
+            # 标记内容字段
             if field_class.document is True:
                 content_field_name = field_class.index_fieldname
                 schema_fields[field_class.index_fieldname].spelling = True
 
-        # Fail more gracefully than relying on the backend to die if no fields
-        # are found.
+        # 如果没有找到字段，优雅地失败
         if len(schema_fields) <= initial_key_count:
             raise SearchBackendError(
                 "No fields were found in any search_indexes. Please correct this before attempting to search.")
 
         return (content_field_name, Schema(**schema_fields))
 
+    # 更新索引的方法
     def update(self, index, iterable, commit=True):
         if not self.setup_complete:
             self.setup()
 
         self.index = self.index.refresh()
+        # 使用异步写入器
         writer = AsyncWriter(self.index)
 
+        # 遍历所有对象，准备并更新文档
         for obj in iterable:
             try:
                 doc = index.full_prepare(obj)
             except SkipDocument:
                 self.log.debug(u"Indexing for object `%s` skipped", obj)
             else:
-                # Really make sure it's unicode, because Whoosh won't have it any
-                # other way.
+                # 确保所有值都是Unicode，因为Whoosh只接受Unicode
                 for key in doc:
                     doc[key] = self._from_python(doc[key])
 
-                # Document boosts aren't supported in Whoosh 2.5.0+.
+                # Whoosh 2.5.0+不支持文档提升
                 if 'boost' in doc:
                     del doc['boost']
 
@@ -227,9 +268,7 @@ class WhooshSearchBackend(BaseSearchBackend):
                     if not self.silently_fail:
                         raise
 
-                    # We'll log the object identifier but won't include the actual object
-                    # to avoid the possibility of that generating encoding errors while
-                    # processing the log message:
+                    # 记录对象标识符但不包含实际对象，以避免生成编码错误
                     self.log.error(
                         u"%s while preparing object for update" %
                         e.__class__.__name__,
@@ -239,11 +278,12 @@ class WhooshSearchBackend(BaseSearchBackend):
                                 "index": index,
                                 "object": get_identifier(obj)}})
 
+        # 如果有对象需要处理，提交写入
         if len(iterable) > 0:
-            # For now, commit no matter what, as we run into locking issues
-            # otherwise.
+            # 暂时无论如何都提交，否则会遇到锁定问题
             writer.commit()
 
+    # 移除文档的方法
     def remove(self, obj_or_string, commit=True):
         if not self.setup_complete:
             self.setup()
@@ -252,6 +292,7 @@ class WhooshSearchBackend(BaseSearchBackend):
         whoosh_id = get_identifier(obj_or_string)
 
         try:
+            # 通过查询删除文档
             self.index.delete_by_query(
                 q=self.parser.parse(
                     u'%s:"%s"' %
@@ -266,6 +307,7 @@ class WhooshSearchBackend(BaseSearchBackend):
                 e,
                 exc_info=True)
 
+    # 清空索引的方法
     def clear(self, models=None, commit=True):
         if not self.setup_complete:
             self.setup()
@@ -277,6 +319,7 @@ class WhooshSearchBackend(BaseSearchBackend):
 
         try:
             if models is None:
+                # 如果未指定模型，删除整个索引
                 self.delete_index()
             else:
                 models_to_delete = []
@@ -286,6 +329,7 @@ class WhooshSearchBackend(BaseSearchBackend):
                         u"%s:%s" %
                         (DJANGO_CT, get_model_ct(model)))
 
+                # 通过查询删除指定模型的文档
                 self.index.delete_by_query(
                     q=self.parser.parse(
                         u" OR ".join(models_to_delete)))
@@ -303,17 +347,18 @@ class WhooshSearchBackend(BaseSearchBackend):
                 self.log.error(
                     "Failed to clear Whoosh index: %s", e, exc_info=True)
 
+    # 删除索引的方法
     def delete_index(self):
-        # Per the Whoosh mailing list, if wiping out everything from the index,
-        # it's much more efficient to simply delete the index files.
+        # 根据Whoosh邮件列表，如果要清除索引中的所有内容，直接删除索引文件更高效
         if self.use_file_storage and os.path.exists(self.path):
             shutil.rmtree(self.path)
         elif not self.use_file_storage:
             self.storage.clean()
 
-        # Recreate everything.
+        # 重新创建所有内容
         self.setup()
 
+    # 优化索引的方法
     def optimize(self):
         if not self.setup_complete:
             self.setup()
@@ -321,13 +366,13 @@ class WhooshSearchBackend(BaseSearchBackend):
         self.index = self.index.refresh()
         self.index.optimize()
 
+    # 计算分页的方法
     def calculate_page(self, start_offset=0, end_offset=None):
-        # Prevent against Whoosh throwing an error. Requires an end_offset
-        # greater than 0.
+        # 防止Whoosh抛出错误。需要end_offset大于0
         if end_offset is not None and end_offset <= 0:
             end_offset = 1
 
-        # Determine the page.
+        # 确定页码
         page_num = 0
 
         if end_offset is None:
@@ -341,10 +386,11 @@ class WhooshSearchBackend(BaseSearchBackend):
         if page_length and page_length > 0:
             page_num = int(start_offset / page_length)
 
-        # Increment because Whoosh uses 1-based page numbers.
+        # 递增，因为Whoosh使用基于1的页码
         page_num += 1
         return page_num, page_length
 
+    # 搜索方法，使用日志查询装饰器
     @log_query
     def search(
             self,
@@ -369,7 +415,7 @@ class WhooshSearchBackend(BaseSearchBackend):
         if not self.setup_complete:
             self.setup()
 
-        # A zero length query should return no results.
+        # 零长度查询应该返回无结果
         if len(query_string) == 0:
             return {
                 'results': [],
@@ -378,8 +424,7 @@ class WhooshSearchBackend(BaseSearchBackend):
 
         query_string = force_str(query_string)
 
-        # A one-character query (non-wildcard) gets nabbed by a stopwords
-        # filter and should yield zero results.
+        # 单字符查询（非通配符）被停用词过滤器捕获，应该返回零结果
         if len(query_string) <= 1 and query_string != u'*':
             return {
                 'results': [],
@@ -389,9 +434,7 @@ class WhooshSearchBackend(BaseSearchBackend):
         reverse = False
 
         if sort_by is not None:
-            # Determine if we need to reverse the results and if Whoosh can
-            # handle what it's being asked to sort by. Reversing is an
-            # all-or-nothing action, unfortunately.
+            # 确定是否需要反转结果以及Whoosh是否可以处理被要求排序的内容
             sort_by_list = []
             reverse_counter = 0
 
@@ -417,6 +460,7 @@ class WhooshSearchBackend(BaseSearchBackend):
 
             sort_by = sort_by_list[0]
 
+        # 处理不支持的功能警告
         if facets is not None:
             warnings.warn(
                 "Whoosh does not handle faceting.",
@@ -438,19 +482,21 @@ class WhooshSearchBackend(BaseSearchBackend):
         narrowed_results = None
         self.index = self.index.refresh()
 
+        # 限制到注册模型的设置
         if limit_to_registered_models is None:
             limit_to_registered_models = getattr(
                 settings, 'HAYSTACK_LIMIT_TO_REGISTERED_MODELS', True)
 
+        # 处理模型选择
         if models and len(models):
             model_choices = sorted(get_model_ct(model) for model in models)
         elif limit_to_registered_models:
-            # Using narrow queries, limit the results to only models handled
-            # with the current routers.
+            # 使用窄查询，将结果限制为当前路由器处理的模型
             model_choices = self.build_models_list()
         else:
             model_choices = []
 
+        # 构建窄查询
         if len(model_choices) > 0:
             if narrow_queries is None:
                 narrow_queries = set()
@@ -460,9 +506,9 @@ class WhooshSearchBackend(BaseSearchBackend):
 
         narrow_searcher = None
 
+        # 处理窄查询
         if narrow_queries is not None:
-            # Potentially expensive? I don't see another way to do it in
-            # Whoosh...
+            # 可能很昂贵？在Whoosh中我没有看到其他方法...
             narrow_searcher = self.index.searcher()
 
             for nq in narrow_queries:
@@ -482,11 +528,12 @@ class WhooshSearchBackend(BaseSearchBackend):
 
         self.index = self.index.refresh()
 
+        # 执行搜索
         if self.index.doc_count():
             searcher = self.index.searcher()
             parsed_query = self.parser.parse(query_string)
 
-            # In the event of an invalid/stopworded query, recover gracefully.
+            # 如果查询无效/包含停用词，优雅地恢复
             if parsed_query is None:
                 return {
                     'results': [],
@@ -502,11 +549,12 @@ class WhooshSearchBackend(BaseSearchBackend):
                 'reverse': reverse,
             }
 
-            # Handle the case where the results have been narrowed.
+            # 处理结果被缩小的情况
             if narrowed_results is not None:
                 search_kwargs['filter'] = narrowed_results
 
             try:
+                # 执行分页搜索
                 raw_page = searcher.search_page(
                     parsed_query,
                     page_num,
@@ -522,8 +570,7 @@ class WhooshSearchBackend(BaseSearchBackend):
                     'spelling_suggestion': None,
                 }
 
-            # Because as of Whoosh 2.5.1, it will return the wrong page of
-            # results if you request something too high. :(
+            # 因为Whoosh 2.5.1中，如果请求的页码太高，它会返回错误的页面
             if raw_page.pagenum < page_num:
                 return {
                     'results': [],
@@ -531,6 +578,7 @@ class WhooshSearchBackend(BaseSearchBackend):
                     'spelling_suggestion': None,
                 }
 
+            # 处理搜索结果
             results = self._process_results(
                 raw_page,
                 highlight=highlight,
@@ -544,6 +592,7 @@ class WhooshSearchBackend(BaseSearchBackend):
 
             return results
         else:
+            # 处理空索引的情况
             if self.include_spelling:
                 if spelling_query:
                     spelling_suggestion = self.create_spelling_suggestion(
@@ -560,6 +609,7 @@ class WhooshSearchBackend(BaseSearchBackend):
                 'spelling_suggestion': spelling_suggestion,
             }
 
+    # 更多类似此内容的方法（推荐相关）
     def more_like_this(
             self,
             model_instance,
@@ -573,8 +623,7 @@ class WhooshSearchBackend(BaseSearchBackend):
         if not self.setup_complete:
             self.setup()
 
-        # Deferred models will have a different class ("RealClass_Deferred_fieldname")
-        # which won't be in our registry:
+        # 延迟模型会有不同的类，不在我们的注册表中
         model_klass = model_instance._meta.concrete_model
 
         field_name = self.content_field_name
@@ -582,19 +631,21 @@ class WhooshSearchBackend(BaseSearchBackend):
         narrowed_results = None
         self.index = self.index.refresh()
 
+        # 限制到注册模型的设置
         if limit_to_registered_models is None:
             limit_to_registered_models = getattr(
                 settings, 'HAYSTACK_LIMIT_TO_REGISTERED_MODELS', True)
 
+        # 处理模型选择
         if models and len(models):
             model_choices = sorted(get_model_ct(model) for model in models)
         elif limit_to_registered_models:
-            # Using narrow queries, limit the results to only models handled
-            # with the current routers.
+            # 使用窄查询，将结果限制为当前路由器处理的模型
             model_choices = self.build_models_list()
         else:
             model_choices = []
 
+        # 构建窄查询
         if len(model_choices) > 0:
             if narrow_queries is None:
                 narrow_queries = set()
@@ -607,9 +658,8 @@ class WhooshSearchBackend(BaseSearchBackend):
 
         narrow_searcher = None
 
+        # 处理窄查询
         if narrow_queries is not None:
-            # Potentially expensive? I don't see another way to do it in
-            # Whoosh...
             narrow_searcher = self.index.searcher()
 
             for nq in narrow_queries:
@@ -632,6 +682,7 @@ class WhooshSearchBackend(BaseSearchBackend):
         self.index = self.index.refresh()
         raw_results = EmptyResults()
 
+        # 执行更多类似此内容的搜索
         if self.index.doc_count():
             query = "%s:%s" % (ID, get_identifier(model_instance))
             searcher = self.index.searcher()
@@ -642,7 +693,7 @@ class WhooshSearchBackend(BaseSearchBackend):
                 raw_results = results[0].more_like_this(
                     field_name, top=end_offset)
 
-            # Handle the case where the results have been narrowed.
+            # 处理结果被缩小的情况
             if narrowed_results is not None and hasattr(raw_results, 'filter'):
                 raw_results.filter(narrowed_results)
 
@@ -658,8 +709,7 @@ class WhooshSearchBackend(BaseSearchBackend):
                 'spelling_suggestion': None,
             }
 
-        # Because as of Whoosh 2.5.1, it will return the wrong page of
-        # results if you request something too high. :(
+        # 因为Whoosh 2.5.1中，如果请求的页码太高，它会返回错误的页面
         if raw_page.pagenum < page_num:
             return {
                 'results': [],
@@ -667,6 +717,7 @@ class WhooshSearchBackend(BaseSearchBackend):
                 'spelling_suggestion': None,
             }
 
+        # 处理结果
         results = self._process_results(raw_page, result_class=result_class)
         searcher.close()
 
@@ -675,6 +726,7 @@ class WhooshSearchBackend(BaseSearchBackend):
 
         return results
 
+    # 处理搜索结果的方法
     def _process_results(
             self,
             raw_page,
@@ -685,8 +737,7 @@ class WhooshSearchBackend(BaseSearchBackend):
         from haystack import connections
         results = []
 
-        # It's important to grab the hits first before slicing. Otherwise, this
-        # can cause pagination failures.
+        # 在切片之前先获取命中数很重要
         hits = len(raw_page)
 
         if result_class is None:
@@ -697,6 +748,7 @@ class WhooshSearchBackend(BaseSearchBackend):
         unified_index = connections[self.connection_alias].get_unified_index()
         indexed_models = unified_index.get_indexed_models()
 
+        # 处理每个搜索结果
         for doc_offset, raw_result in enumerate(raw_page):
             score = raw_page.score(doc_offset) or 0
             app_label, model_name = raw_result[DJANGO_CT].split('.')
@@ -710,7 +762,7 @@ class WhooshSearchBackend(BaseSearchBackend):
 
                     if string_key in index.fields and hasattr(
                             index.fields[string_key], 'convert'):
-                        # Special-cased due to the nature of KEYWORD fields.
+                        # 由于KEYWORD字段的性质，需要特殊处理
                         if index.fields[string_key].is_multivalued:
                             if value is None or len(value) == 0:
                                 additional_fields[string_key] = []
@@ -723,9 +775,11 @@ class WhooshSearchBackend(BaseSearchBackend):
                     else:
                         additional_fields[string_key] = self._to_python(value)
 
+                # 删除系统字段
                 del (additional_fields[DJANGO_CT])
                 del (additional_fields[DJANGO_ID])
 
+                # 处理高亮显示
                 if highlight:
                     sa = StemmingAnalyzer()
                     formatter = WhooshHtmlFormatter('em')
@@ -742,6 +796,7 @@ class WhooshSearchBackend(BaseSearchBackend):
                         self.content_field_name: [whoosh_result],
                     }
 
+                # 创建搜索结果对象
                 result = result_class(
                     app_label,
                     model_name,
@@ -752,6 +807,7 @@ class WhooshSearchBackend(BaseSearchBackend):
             else:
                 hits -= 1
 
+        # 处理拼写建议
         if self.include_spelling:
             if spelling_query:
                 spelling_suggestion = self.create_spelling_suggestion(
@@ -767,6 +823,7 @@ class WhooshSearchBackend(BaseSearchBackend):
             'spelling_suggestion': spelling_suggestion,
         }
 
+    # 创建拼写建议的方法
     def create_spelling_suggestion(self, query_string):
         spelling_suggestion = None
         reader = self.index.reader()
@@ -776,17 +833,19 @@ class WhooshSearchBackend(BaseSearchBackend):
         if not query_string:
             return spelling_suggestion
 
-        # Clean the string.
+        # 清理字符串，移除保留字
         for rev_word in self.RESERVED_WORDS:
             cleaned_query = cleaned_query.replace(rev_word, '')
 
+        # 清理字符串，移除保留字符
         for rev_char in self.RESERVED_CHARACTERS:
             cleaned_query = cleaned_query.replace(rev_char, '')
 
-        # Break it down.
+        # 分解查询词
         query_words = cleaned_query.split()
         suggested_words = []
 
+        # 为每个查询词获取建议
         for word in query_words:
             suggestions = corrector.suggest(word, limit=1)
 
@@ -796,6 +855,7 @@ class WhooshSearchBackend(BaseSearchBackend):
         spelling_suggestion = ' '.join(suggested_words)
         return spelling_suggestion
 
+    # Python值转换为Whoosh字符串的方法
     def _from_python(self, value):
         """
         Converts Python values to a string for Whoosh.
@@ -813,12 +873,13 @@ class WhooshSearchBackend(BaseSearchBackend):
         elif isinstance(value, (list, tuple)):
             value = u','.join([force_str(v) for v in value])
         elif isinstance(value, (six.integer_types, float)):
-            # Leave it alone.
+            # 保持原样
             pass
         else:
             value = force_str(value)
         return value
 
+    # Whoosh值转换为Python值的方法
     def _to_python(self, value):
         """
         Converts values from Whoosh to native Python values.
@@ -848,10 +909,10 @@ class WhooshSearchBackend(BaseSearchBackend):
                     date_values['second'])
 
         try:
-            # Attempt to use json to load the values.
+            # 尝试使用json加载值
             converted_value = json.loads(value)
 
-            # Try to handle most built-in types.
+            # 尝试处理大多数内置类型
             if isinstance(
                     converted_value,
                     (list,
@@ -863,20 +924,22 @@ class WhooshSearchBackend(BaseSearchBackend):
                      complex)):
                 return converted_value
         except BaseException:
-            # If it fails (SyntaxError or its ilk) or we don't trust it,
-            # continue on.
+            # 如果失败（SyntaxError或其同类）或者我们不信任它，继续
             pass
 
         return value
 
 
+# Whoosh搜索查询类，继承自BaseSearchQuery
 class WhooshSearchQuery(BaseSearchQuery):
+    # 日期时间转换方法
     def _convert_datetime(self, date):
         if hasattr(date, 'hour'):
             return force_str(date.strftime('%Y%m%d%H%M%S'))
         else:
             return force_str(date.strftime('%Y%m%d000000'))
 
+    # 清理查询片段的方法
     def clean(self, query_fragment):
         """
         Provides a mechanism for sanitizing user input before presenting the
@@ -902,13 +965,14 @@ class WhooshSearchQuery(BaseSearchQuery):
 
         return ' '.join(cleaned_words)
 
+    # 构建查询片段的方法
     def build_query_fragment(self, field, filter_type, value):
         from haystack import connections
         query_frag = ''
         is_datetime = False
 
         if not hasattr(value, 'input_type_name'):
-            # Handle when we've got a ``ValuesListQuerySet``...
+            # 处理当我们有``ValuesListQuerySet``时...
             if hasattr(value, 'values_list'):
                 value = list(value)
 
@@ -916,26 +980,26 @@ class WhooshSearchQuery(BaseSearchQuery):
                 is_datetime = True
 
             if isinstance(value, six.string_types) and value != ' ':
-                # It's not an ``InputType``. Assume ``Clean``.
+                # 不是``InputType``。假设是``Clean``。
                 value = Clean(value)
             else:
                 value = PythonData(value)
 
-        # Prepare the query using the InputType.
+        # 使用InputType准备查询
         prepared_value = value.prepare(self)
 
         if not isinstance(prepared_value, (set, list, tuple)):
-            # Then convert whatever we get back to what pysolr wants if needed.
+            # 然后将我们得到的任何内容转换为pysolr需要的格式
             prepared_value = self.backend._from_python(prepared_value)
 
-        # 'content' is a special reserved word, much like 'pk' in
-        # Django's ORM layer. It indicates 'no special field'.
+        # 'content'是一个特殊的保留字，就像Django ORM层中的'pk'一样
         if field == 'content':
             index_fieldname = ''
         else:
             index_fieldname = u'%s:' % connections[self._using].get_unified_index(
             ).get_index_fieldname(field)
 
+        # 过滤器类型映射
         filter_types = {
             'content': '%s',
             'contains': '*%s*',
@@ -949,6 +1013,7 @@ class WhooshSearchQuery(BaseSearchQuery):
             'fuzzy': u'%s~',
         }
 
+        # 构建查询片段
         if value.post_process is False:
             query_frag = prepared_value
         else:
@@ -961,8 +1026,7 @@ class WhooshSearchQuery(BaseSearchQuery):
                 if value.input_type_name == 'exact':
                     query_frag = prepared_value
                 else:
-                    # Iterate over terms & incorportate the converted form of
-                    # each into the query.
+                    # 遍历术语并将每个的转换形式纳入查询
                     terms = []
 
                     if isinstance(prepared_value, six.string_types):
@@ -1026,19 +1090,17 @@ class WhooshSearchQuery(BaseSearchQuery):
 
                 query_frag = filter_types[filter_type] % prepared_value
 
+        # 添加括号
         if len(query_frag) and not isinstance(value, Raw):
             if not query_frag.startswith('(') and not query_frag.endswith(')'):
                 query_frag = "(%s)" % query_frag
 
         return u"%s%s" % (index_fieldname, query_frag)
 
-        # if not filter_type in ('in', 'range'):
-        #     # 'in' is a bit of a special case, as we don't want to
-        #     # convert a valid list/tuple to string. Defer handling it
-        #     # until later...
-        #     value = self.backend._from_python(value)
-
 
+# Whoosh搜索引擎类，继承自BaseEngine
 class WhooshEngine(BaseEngine):
+    # 指定后端类
     backend = WhooshSearchBackend
-    query = WhooshSearchQuery
+    # 指定查询类
+    query = WhooshSearchQuery

src/DjangoBlog/djangoblog/wsgi.py

@@ -7,10 +7,14 @@ For more information on this file, see
 https://docs.djangoproject.com/en/1.10/howto/deployment/wsgi/
 """
 
+# 导入操作系统模块
 import os
 
+# 导入Django WSGI应用获取函数
 from django.core.wsgi import get_wsgi_application
 
+# 设置默认的Django设置模块环境变量
 os.environ.setdefault("DJANGO_SETTINGS_MODULE", "djangoblog.settings")
 
-application = get_wsgi_application()
+# 获取WSGI应用实例
+application = get_wsgi_application()

src/DjangoBlog/fix_pet_blog.py

@@ -1,96 +1,106 @@
-# fix_pet_blog.py
+# 宠物博客数据修复脚本
 import os
 import django
+# 设置Django环境变量
 os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'djangoblog.settings')
+# 初始化Django配置
 django.setup()
 
+# 导入博客模型和用户模型
 from blog.models import Article, Category, Tag
 from accounts.models import BlogUser
 
 print("=== 修复宠物博客数据 ===")
 
-# 获取用户
+# 获取第一个用户作为文章作者
 user = BlogUser.objects.first()
 if not user:
     print("错误：没有找到用户")
     exit()
 
-# 为每个分类创建至少一篇文章
+# 为每个分类创建至少一篇文章的数据定义
 articles_data = [
-    # 狗狗日常
+    # 狗狗日常分类的文章
     {
         'title': '我家狗狗的表演',
         'body': '欲擒故纵，你们见过吗。就是要出去的时候，故意离你远远的，让人你没法给它套上项圈，其实它很想出去。',
         'category': '狗狗日常',
-        'tags': ['图文', '狗狗社交', '遛狗']
+        'tags': ['图文', '狗狗社交', '遛狗']  # 文章标签
     },
-    # 猫咪生活
+    # 猫咪生活分类的文章
     {
         'title': '猫咪的日常护理',
         'body': '定期为猫咪梳理毛发，保持清洁，注意观察猫咪的健康状况。',
         'category': '猫咪生活',
-        'tags': ['宠物美容', '宠物健康']
+        'tags': ['宠物美容', '宠物健康']  # 文章标签
     },
-    # 宠物健康
+    # 宠物健康分类的文章
     {
         'title': '宠物健康检查指南',
         'body': '定期带宠物进行健康检查，注意疫苗接种和驱虫的重要性。',
         'category': '宠物健康',
-        'tags': ['宠物医疗', '宠物健康']
+        'tags': ['宠物医疗', '宠物健康']  # 文章标签
     },
-    # 训练技巧
+    # 训练技巧分类的文章
     {
         'title': '如何训练狗狗坐下',
         'body': '使用零食诱导，当狗狗完成动作时及时奖励，重复训练。',
         'category': '训练技巧',
-        'tags': ['训练方法', '图文']
+        'tags': ['训练方法', '图文']  # 文章标签
     },
-    # 宠物用品
+    # 宠物用品分类的文章
     {
         'title': '推荐几款好用的宠物玩具',
         'body': '这些玩具既安全又有趣，能让宠物保持活跃和快乐。',
         'category': '宠物用品',
-        'tags': ['宠物玩具', '宠物用品']
+        'tags': ['宠物玩具', '宠物用品']  # 文章标签
     },
-    # 额外文章确保内容丰富
+    # 额外文章确保内容丰富 - 狗狗日常的补充文章
     {
         'title': '带狗狗散步的注意事项',
         'body': '选择合适的牵引绳，注意天气和路况，确保狗狗的安全。',
         'category': '狗狗日常',
-        'tags': ['遛狗', '狗狗社交']
+        'tags': ['遛狗', '狗狗社交']  # 文章标签
     },
+    # 额外文章确保内容丰富 - 宠物健康的补充文章
     {
         'title': '猫咪饮食健康指南',
         'body': '了解猫咪的营养需求，选择合适的猫粮和零食。',
         'category': '宠物健康',
-        'tags': ['宠物食品', '宠物健康']
+        'tags': ['宠物食品', '宠物健康']  # 文章标签
     }
 ]
 
-# 删除现有文章，重新创建
+# 删除现有文章，重新创建（清理旧数据）
 Article.objects.all().delete()
 print("已清理现有文章")
 
-# 创建新文章
+# 遍历文章数据，创建新文章
 for data in articles_data:
     try:
+        # 根据分类名称获取分类对象
         category = Category.objects.get(name=data['category'])
+        # 创建文章对象
         article = Article.objects.create(
-            title=data['title'],
-            body=data['body'],
-            author=user,
-            category=category,
-            status='p'
+            title=data['title'],  # 文章标题
+            body=data['body'],  # 文章内容
+            author=user,  # 文章作者
+            category=category,  # 文章分类
+            status='p'  # 发布状态（p表示已发布）
         )
+        # 为文章添加标签
         for tag_name in data['tags']:
-            tag, _ = Tag.objects.get_or_create(name=tag_name)
-            article.tags.add(tag)
+            tag, _ = Tag.objects.get_or_create(name=tag_name)  # 获取或创建标签
+            article.tags.add(tag)  # 将标签关联到文章
         print(f'创建文章: {data["title"]} (分类: {data["category"]})')
     except Exception as e:
+        # 处理创建文章过程中的异常
         print(f'创建文章失败 {data["title"]}: {e}')
 
 print("=== 修复完成 ===")
+# 输出统计信息
 print(f"总文章数: {Article.objects.count()}")
+# 遍历所有分类，输出每个分类的文章数量
 for category in Category.objects.all():
     count = Article.objects.filter(category=category).count()
     print(f"分类 '{category.name}': {count} 篇文章")

src/DjangoBlog/manage.py

@@ -1,22 +1,27 @@
 #!/usr/bin/env python
+# Django 管理脚本入口文件
 import os
 import sys
 
+# 主程序入口
 if __name__ == "__main__":
+    # 设置默认的Django设置模块
     os.environ.setdefault("DJANGO_SETTINGS_MODULE", "djangoblog.settings")
     try:
+        # 尝试导入Django命令行执行器
         from django.core.management import execute_from_command_line
     except ImportError:
-        # The above import may fail for some other reason. Ensure that the
-        # issue is really that Django is missing to avoid masking other
-        # exceptions on Python 2.
+        # 如果导入失败，检查是否是Django未安装导致的
+        # 上面的导入可能由于其他原因失败。确保问题确实是缺少Django，以避免掩盖Python 2上的其他异常。
         try:
-            import django
+            import django  # 尝试导入Django
         except ImportError:
+            # 如果Django导入失败，抛出明确的错误信息
             raise ImportError(
                 "Couldn't import Django. Are you sure it's installed and "
                 "available on your PYTHONPATH environment variable? Did you "
                 "forget to activate a virtual environment?"
             )
-        raise
-    execute_from_command_line(sys.argv)
+        raise  # 重新抛出原始异常
+    # 执行Django命令行命令
+    execute_from_command_line(sys.argv)

src/DjangoBlog/oauth/admin.py

@@ -1,54 +1,82 @@
+# 导入日志模块
 import logging
 
+# 导入Django管理员模块
 from django.contrib import admin
 # Register your models here.
+# 导入URL反向解析模块
 from django.urls import reverse
+# 导入HTML格式化工具
 from django.utils.html import format_html
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
 
+# OAuth用户管理类，继承自admin.ModelAdmin
 class OAuthUserAdmin(admin.ModelAdmin):
+    # 搜索字段
     search_fields = ('nickname', 'email')
+    # 每页显示的用户数量
     list_per_page = 20
+    # 列表页面显示的字段
     list_display = (
         'id',
         'nickname',
-        'link_to_usermodel',
-        'show_user_image',
+        'link_to_usermodel',  # 自定义方法：用户模型链接
+        'show_user_image',    # 自定义方法：显示用户头像
         'type',
         'email',
     )
+    # 列表中可作为链接点击的字段
     list_display_links = ('id', 'nickname')
+    # 列表过滤器
     list_filter = ('author', 'type',)
+    # 只读字段列表
     readonly_fields = []
 
+    # 获取只读字段的方法
     def get_readonly_fields(self, request, obj=None):
+        # 将所有字段设置为只读，包括普通字段和多对多字段
         return list(self.readonly_fields) + \
                [field.name for field in obj._meta.fields] + \
                [field.name for field in obj._meta.many_to_many]
 
+    # 是否允许添加权限
     def has_add_permission(self, request):
+        # 禁止添加OAuth用户
         return False
 
+    # 自定义方法：显示用户模型链接
     def link_to_usermodel(self, obj):
+        # 如果有关联的作者用户
         if obj.author:
+            # 获取用户模型的app_label和model_name
             info = (obj.author._meta.app_label, obj.author._meta.model_name)
+            # 生成用户编辑页面的URL
             link = reverse('admin:%s_%s_change' % info, args=(obj.author.id,))
+            # 返回格式化的HTML链接，显示用户昵称或邮箱
             return format_html(
                 u'<a href="%s">%s</a>' %
                 (link, obj.author.nickname if obj.author.nickname else obj.author.email))
 
+    # 自定义方法：显示用户头像
     def show_user_image(self, obj):
+        # 获取用户头像URL
         img = obj.picture
+        # 返回格式化的HTML图片标签，设置固定尺寸
         return format_html(
             u'<img src="%s" style="width:50px;height:50px"></img>' %
             (img))
 
+    # 设置自定义方法的显示名称
     link_to_usermodel.short_description = '用户'
     show_user_image.short_description = '用户头像'
 
 
+# OAuth配置管理类，继承自admin.ModelAdmin
 class OAuthConfigAdmin(admin.ModelAdmin):
+    # 列表页面显示的字段
     list_display = ('type', 'appkey', 'appsecret', 'is_enable')
-    list_filter = ('type',)
+    # 列表过滤器
+    list_filter = ('type',)

src/DjangoBlog/oauth/apps.py

@@ -1,5 +1,8 @@
+# 导入Django应用配置基类
 from django.apps import AppConfig
 
 
+# 定义OAuth应用的配置类
 class OauthConfig(AppConfig):
-    name = 'oauth'
+    # 指定应用的完整Python路径
+    name = 'oauth'

src/DjangoBlog/oauth/forms.py

@@ -1,12 +1,19 @@
+# 导入Django表单相关模块
 from django.contrib.auth.forms import forms
 from django.forms import widgets
 
 
+# 需要邮箱的表单类，继承自forms.Form
 class RequireEmailForm(forms.Form):
+    # 邮箱字段，必填
     email = forms.EmailField(label='电子邮箱', required=True)
+    # OAuth ID字段，使用隐藏输入控件，非必填
     oauthid = forms.IntegerField(widget=forms.HiddenInput, required=False)
 
+    # 初始化方法
     def __init__(self, *args, **kwargs):
+        # 调用父类的初始化方法
         super(RequireEmailForm, self).__init__(*args, **kwargs)
+        # 自定义邮箱字段的HTML属性
         self.fields['email'].widget = widgets.EmailInput(
-            attrs={'placeholder': "email", "class": "form-control"})
+            attrs={'placeholder': "email", "class": "form-control"})

src/DjangoBlog/oauth/models.py

@@ -1,67 +1,105 @@
 # Create your models here.
+# 导入Django配置模块
 from django.conf import settings
+# 导入验证错误异常
 from django.core.exceptions import ValidationError
+# 导入数据库模型模块
 from django.db import models
+# 导入时区工具
 from django.utils.timezone import now
+# 导入国际化翻译模块
 from django.utils.translation import gettext_lazy as _
 
 
+# OAuth用户模型类
 class OAuthUser(models.Model):
+    # 作者字段，外键关联到用户模型，允许为空
     author = models.ForeignKey(
         settings.AUTH_USER_MODEL,
         verbose_name=_('author'),
         blank=True,
         null=True,
         on_delete=models.CASCADE)
+    # 开放ID字段，最大长度50字符
     openid = models.CharField(max_length=50)
+    # 昵称字段，最大长度50字符
     nickname = models.CharField(max_length=50, verbose_name=_('nick name'))
+    # 令牌字段，最大长度150字符，允许为空
     token = models.CharField(max_length=150, null=True, blank=True)
+    # 头像字段，最大长度350字符，允许为空
     picture = models.CharField(max_length=350, blank=True, null=True)
+    # 类型字段，必填，最大长度50字符
     type = models.CharField(blank=False, null=False, max_length=50)
+    # 邮箱字段，最大长度50字符，允许为空
     email = models.CharField(max_length=50, null=True, blank=True)
+    # 元数据字段，文本类型，允许为空
     metadata = models.TextField(null=True, blank=True)
+    # 创建时间字段，默认值为当前时间
     creation_time = models.DateTimeField(_('creation time'), default=now)
+    # 最后修改时间字段，默认值为当前时间
     last_modify_time = models.DateTimeField(_('last modify time'), default=now)
 
+    # 对象的字符串表示方法
     def __str__(self):
         return self.nickname
 
+    # 模型的元数据配置
     class Meta:
+        # 单数形式的显示名称
         verbose_name = _('oauth user')
+        # 复数形式的显示名称
         verbose_name_plural = verbose_name
+        # 默认按创建时间倒序排列
         ordering = ['-creation_time']
 
 
+# OAuth配置模型类
 class OAuthConfig(models.Model):
+    # 类型选择项
     TYPE = (
-        ('weibo', _('weibo')),
-        ('google', _('google')),
-        ('github', 'GitHub'),
-        ('facebook', 'FaceBook'),
-        ('qq', 'QQ'),
+        ('weibo', _('weibo')),      # 微博
+        ('google', _('google')),    # 谷歌
+        ('github', 'GitHub'),       # GitHub
+        ('facebook', 'FaceBook'),   # Facebook
+        ('qq', 'QQ'),               # QQ
     )
+    # 类型字段，选择类型，默认值为'a'
     type = models.CharField(_('type'), max_length=10, choices=TYPE, default='a')
+    # 应用密钥字段，最大长度200字符
     appkey = models.CharField(max_length=200, verbose_name='AppKey')
+    # 应用密钥字段，最大长度200字符
     appsecret = models.CharField(max_length=200, verbose_name='AppSecret')
+    # 回调URL字段，最大长度200字符，必填，默认值为空字符串
     callback_url = models.CharField(
         max_length=200,
         verbose_name=_('callback url'),
         blank=False,
         default='')
+    # 是否启用字段，布尔类型，默认True
     is_enable = models.BooleanField(
         _('is enable'), default=True, blank=False, null=False)
+    # 创建时间字段，默认值为当前时间
     creation_time = models.DateTimeField(_('creation time'), default=now)
+    # 最后修改时间字段，默认值为当前时间
     last_modify_time = models.DateTimeField(_('last modify time'), default=now)
 
+    # 数据验证方法
     def clean(self):
+        # 检查同类型的配置是否已存在（排除当前记录）
         if OAuthConfig.objects.filter(
                 type=self.type).exclude(id=self.id).count():
+            # 如果已存在，抛出验证错误
             raise ValidationError(_(self.type + _('already exists')))
 
+    # 对象的字符串表示方法
     def __str__(self):
         return self.type
 
+    # 模型的元数据配置
     class Meta:
+        # 单数形式的显示名称
         verbose_name = 'oauth配置'
+        # 复数形式的显示名称
         verbose_name_plural = verbose_name
-        ordering = ['-creation_time']
+        # 默认按创建时间倒序排列
+        ordering = ['-creation_time']

src/DjangoBlog/oauth/oauthmanager.py

@@ -1,23 +1,31 @@
+# 导入标准库模块
 import json
 import logging
 import os
 import urllib.parse
+# 导入抽象基类模块
 from abc import ABCMeta, abstractmethod
 
+# 导入HTTP请求库
 import requests
 
+# 导入自定义工具函数
 from djangoblog.utils import cache_decorator
+# 导入OAuth模型
 from oauth.models import OAuthUser, OAuthConfig
 
+# 获取当前模块的日志器
 logger = logging.getLogger(__name__)
 
 
+# OAuth授权令牌异常类
 class OAuthAccessTokenException(Exception):
     '''
     oauth授权失败异常
     '''
 
 
+# 基础OAuth管理器抽象基类
 class BaseOauthManager(metaclass=ABCMeta):
     """获取用户授权"""
     AUTH_URL = None
@@ -28,55 +36,67 @@ class BaseOauthManager(metaclass=ABCMeta):
     '''icon图标名'''
     ICON_NAME = None
 
+    # 初始化方法
     def __init__(self, access_token=None, openid=None):
         self.access_token = access_token
         self.openid = openid
 
+    # 访问令牌是否设置的属性
     @property
     def is_access_token_set(self):
         return self.access_token is not None
 
+    # 是否已授权的属性
     @property
     def is_authorized(self):
         return self.is_access_token_set and self.access_token is not None and self.openid is not None
 
+    # 抽象方法：获取授权URL
     @abstractmethod
     def get_authorization_url(self, nexturl='/'):
         pass
 
+    # 抽象方法：通过授权码获取访问令牌
     @abstractmethod
     def get_access_token_by_code(self, code):
         pass
 
+    # 抽象方法：获取OAuth用户信息
     @abstractmethod
     def get_oauth_userinfo(self):
         pass
 
+    # 抽象方法：获取用户头像
     @abstractmethod
     def get_picture(self, metadata):
         pass
 
+    # GET请求方法
     def do_get(self, url, params, headers=None):
         rsp = requests.get(url=url, params=params, headers=headers)
         logger.info(rsp.text)
         return rsp.text
 
+    # POST请求方法
     def do_post(self, url, params, headers=None):
         rsp = requests.post(url, params, headers=headers)
         logger.info(rsp.text)
         return rsp.text
 
+    # 获取配置的方法
     def get_config(self):
         value = OAuthConfig.objects.filter(type=self.ICON_NAME)
         return value[0] if value else None
 
 
+# 微博OAuth管理器类
 class WBOauthManager(BaseOauthManager):
     AUTH_URL = 'https://api.weibo.com/oauth2/authorize'
     TOKEN_URL = 'https://api.weibo.com/oauth2/access_token'
     API_URL = 'https://api.weibo.com/2/users/show.json'
     ICON_NAME = 'weibo'
 
+    # 初始化方法
     def __init__(self, access_token=None, openid=None):
         config = self.get_config()
         self.client_id = config.appkey if config else ''
@@ -88,6 +108,7 @@ class WBOauthManager(BaseOauthManager):
             access_token=access_token,
             openid=openid)
 
+    # 获取授权URL的方法
     def get_authorization_url(self, nexturl='/'):
         params = {
             'client_id': self.client_id,
@@ -97,6 +118,7 @@ class WBOauthManager(BaseOauthManager):
         url = self.AUTH_URL + "?" + urllib.parse.urlencode(params)
         return url
 
+    # 通过授权码获取访问令牌的方法
     def get_access_token_by_code(self, code):
 
         params = {
@@ -116,6 +138,7 @@ class WBOauthManager(BaseOauthManager):
         else:
             raise OAuthAccessTokenException(rsp)
 
+    # 获取OAuth用户信息的方法
     def get_oauth_userinfo(self):
         if not self.is_authorized:
             return None
@@ -141,12 +164,15 @@ class WBOauthManager(BaseOauthManager):
             logger.error('weibo oauth error.rsp:' + rsp)
             return None
 
+    # 获取用户头像的方法
     def get_picture(self, metadata):
         datas = json.loads(metadata)
         return datas['avatar_large']
 
 
+# 代理管理器混入类
 class ProxyManagerMixin:
+    # 初始化方法，设置代理
     def __init__(self, *args, **kwargs):
         if os.environ.get("HTTP_PROXY"):
             self.proxies = {
@@ -156,23 +182,27 @@ class ProxyManagerMixin:
         else:
             self.proxies = None
 
+    # 使用代理的GET请求方法
     def do_get(self, url, params, headers=None):
         rsp = requests.get(url=url, params=params, headers=headers, proxies=self.proxies)
         logger.info(rsp.text)
         return rsp.text
 
+    # 使用代理的POST请求方法
     def do_post(self, url, params, headers=None):
         rsp = requests.post(url, params, headers=headers, proxies=self.proxies)
         logger.info(rsp.text)
         return rsp.text
 
 
+# 谷歌OAuth管理器类，继承代理混入类
 class GoogleOauthManager(ProxyManagerMixin, BaseOauthManager):
     AUTH_URL = 'https://accounts.google.com/o/oauth2/v2/auth'
     TOKEN_URL = 'https://www.googleapis.com/oauth2/v4/token'
     API_URL = 'https://www.googleapis.com/oauth2/v3/userinfo'
     ICON_NAME = 'google'
 
+    # 初始化方法
     def __init__(self, access_token=None, openid=None):
         config = self.get_config()
         self.client_id = config.appkey if config else ''
@@ -184,6 +214,7 @@ class GoogleOauthManager(ProxyManagerMixin, BaseOauthManager):
             access_token=access_token,
             openid=openid)
 
+    # 获取授权URL的方法
     def get_authorization_url(self, nexturl='/'):
         params = {
             'client_id': self.client_id,
@@ -194,6 +225,7 @@ class GoogleOauthManager(ProxyManagerMixin, BaseOauthManager):
         url = self.AUTH_URL + "?" + urllib.parse.urlencode(params)
         return url
 
+    # 通过授权码获取访问令牌的方法
     def get_access_token_by_code(self, code):
         params = {
             'client_id': self.client_id,
@@ -215,6 +247,7 @@ class GoogleOauthManager(ProxyManagerMixin, BaseOauthManager):
         else:
             raise OAuthAccessTokenException(rsp)
 
+    # 获取OAuth用户信息的方法
     def get_oauth_userinfo(self):
         if not self.is_authorized:
             return None
@@ -240,17 +273,20 @@ class GoogleOauthManager(ProxyManagerMixin, BaseOauthManager):
             logger.error('google oauth error.rsp:' + rsp)
             return None
 
+    # 获取用户头像的方法
     def get_picture(self, metadata):
         datas = json.loads(metadata)
         return datas['picture']
 
 
+# GitHub OAuth管理器类，继承代理混入类
 class GitHubOauthManager(ProxyManagerMixin, BaseOauthManager):
     AUTH_URL = 'https://github.com/login/oauth/authorize'
     TOKEN_URL = 'https://github.com/login/oauth/access_token'
     API_URL = 'https://api.github.com/user'
     ICON_NAME = 'github'
 
+    # 初始化方法
     def __init__(self, access_token=None, openid=None):
         config = self.get_config()
         self.client_id = config.appkey if config else ''
@@ -262,6 +298,7 @@ class GitHubOauthManager(ProxyManagerMixin, BaseOauthManager):
             access_token=access_token,
             openid=openid)
 
+    # 获取授权URL的方法
     def get_authorization_url(self, next_url='/'):
         params = {
             'client_id': self.client_id,
@@ -272,6 +309,7 @@ class GitHubOauthManager(ProxyManagerMixin, BaseOauthManager):
         url = self.AUTH_URL + "?" + urllib.parse.urlencode(params)
         return url
 
+    # 通过授权码获取访问令牌的方法
     def get_access_token_by_code(self, code):
         params = {
             'client_id': self.client_id,
@@ -291,6 +329,7 @@ class GitHubOauthManager(ProxyManagerMixin, BaseOauthManager):
         else:
             raise OAuthAccessTokenException(rsp)
 
+    # 获取OAuth用户信息的方法
     def get_oauth_userinfo(self):
 
         rsp = self.do_get(self.API_URL, params={}, headers={
@@ -313,17 +352,20 @@ class GitHubOauthManager(ProxyManagerMixin, BaseOauthManager):
             logger.error('github oauth error.rsp:' + rsp)
             return None
 
+    # 获取用户头像的方法
     def get_picture(self, metadata):
         datas = json.loads(metadata)
         return datas['avatar_url']
 
 
+# Facebook OAuth管理器类，继承代理混入类
 class FaceBookOauthManager(ProxyManagerMixin, BaseOauthManager):
     AUTH_URL = 'https://www.facebook.com/v16.0/dialog/oauth'
     TOKEN_URL = 'https://graph.facebook.com/v16.0/oauth/access_token'
     API_URL = 'https://graph.facebook.com/me'
     ICON_NAME = 'facebook'
 
+    # 初始化方法
     def __init__(self, access_token=None, openid=None):
         config = self.get_config()
         self.client_id = config.appkey if config else ''
@@ -335,6 +377,7 @@ class FaceBookOauthManager(ProxyManagerMixin, BaseOauthManager):
             access_token=access_token,
             openid=openid)
 
+    # 获取授权URL的方法
     def get_authorization_url(self, next_url='/'):
         params = {
             'client_id': self.client_id,
@@ -345,6 +388,7 @@ class FaceBookOauthManager(ProxyManagerMixin, BaseOauthManager):
         url = self.AUTH_URL + "?" + urllib.parse.urlencode(params)
         return url
 
+    # 通过授权码获取访问令牌的方法
     def get_access_token_by_code(self, code):
         params = {
             'client_id': self.client_id,
@@ -364,6 +408,7 @@ class FaceBookOauthManager(ProxyManagerMixin, BaseOauthManager):
         else:
             raise OAuthAccessTokenException(rsp)
 
+    # 获取OAuth用户信息的方法
     def get_oauth_userinfo(self):
         params = {
             'access_token': self.access_token,
@@ -387,11 +432,13 @@ class FaceBookOauthManager(ProxyManagerMixin, BaseOauthManager):
             logger.error(e)
             return None
 
+    # 获取用户头像的方法
     def get_picture(self, metadata):
         datas = json.loads(metadata)
         return str(datas['picture']['data']['url'])
 
 
+# QQ OAuth管理器类
 class QQOauthManager(BaseOauthManager):
     AUTH_URL = 'https://graph.qq.com/oauth2.0/authorize'
     TOKEN_URL = 'https://graph.qq.com/oauth2.0/token'
@@ -399,6 +446,7 @@ class QQOauthManager(BaseOauthManager):
     OPEN_ID_URL = 'https://graph.qq.com/oauth2.0/me'
     ICON_NAME = 'qq'
 
+    # 初始化方法
     def __init__(self, access_token=None, openid=None):
         config = self.get_config()
         self.client_id = config.appkey if config else ''
@@ -410,6 +458,7 @@ class QQOauthManager(BaseOauthManager):
             access_token=access_token,
             openid=openid)
 
+    # 获取授权URL的方法
     def get_authorization_url(self, next_url='/'):
         params = {
             'response_type': 'code',
@@ -419,6 +468,7 @@ class QQOauthManager(BaseOauthManager):
         url = self.AUTH_URL + "?" + urllib.parse.urlencode(params)
         return url
 
+    # 通过授权码获取访问令牌的方法
     def get_access_token_by_code(self, code):
         params = {
             'grant_type': 'authorization_code',
@@ -437,6 +487,7 @@ class QQOauthManager(BaseOauthManager):
         else:
             raise OAuthAccessTokenException(rsp)
 
+    # 获取OpenID的方法
     def get_open_id(self):
         if self.is_access_token_set:
             params = {
@@ -453,6 +504,7 @@ class QQOauthManager(BaseOauthManager):
                 self.openid = openid
                 return openid
 
+    # 获取OAuth用户信息的方法
     def get_oauth_userinfo(self):
         openid = self.get_open_id()
         if openid:
@@ -476,11 +528,13 @@ class QQOauthManager(BaseOauthManager):
                 user.picture = str(obj['figureurl'])
             return user
 
+    # 获取用户头像的方法
     def get_picture(self, metadata):
         datas = json.loads(metadata)
         return str(datas['figureurl'])
 
 
+# 获取所有启用的OAuth应用的缓存函数
 @cache_decorator(expiration=100 * 60)
 def get_oauth_apps():
     configs = OAuthConfig.objects.filter(is_enable=True).all()
@@ -492,6 +546,7 @@ def get_oauth_apps():
     return apps
 
 
+# 根据类型获取管理器实例的函数
 def get_manager_by_type(type):
     applications = get_oauth_apps()
     if applications:
@@ -501,4 +556,4 @@ def get_manager_by_type(type):
                 applications))
         if finds:
             return finds[0]
-    return None
+    return None

src/DjangoBlog/oauth/tests.py

@@ -11,23 +11,27 @@ from oauth.models import OAuthConfig
 from oauth.oauthmanager import BaseOauthManager
 
 
-# Create your tests here.
+# 创建测试类
 class OAuthConfigTest(TestCase):
     def setUp(self):
+        # 初始化测试客户端和请求工厂
         self.client = Client()
         self.factory = RequestFactory()
 
     def test_oauth_login_test(self):
+        # 创建OAuth配置实例
         c = OAuthConfig()
         c.type = 'weibo'
         c.appkey = 'appkey'
         c.appsecret = 'appsecret'
         c.save()
 
+        # 测试OAuth登录重定向
         response = self.client.get('/oauth/oauthlogin?type=weibo')
         self.assertEqual(response.status_code, 302)
         self.assertTrue("api.weibo.com" in response.url)
 
+        # 测试授权回调处理
         response = self.client.get('/oauth/authorize?type=weibo&code=code')
         self.assertEqual(response.status_code, 302)
         self.assertEqual(response.url, '/')
@@ -35,11 +39,13 @@ class OAuthConfigTest(TestCase):
 
 class OauthLoginTest(TestCase):
     def setUp(self) -> None:
+        # 初始化测试环境
         self.client = Client()
         self.factory = RequestFactory()
         self.apps = self.init_apps()
 
     def init_apps(self):
+        # 初始化所有OAuth应用配置
         applications = [p() for p in BaseOauthManager.__subclasses__()]
         for application in applications:
             c = OAuthConfig()
@@ -50,6 +56,7 @@ class OauthLoginTest(TestCase):
         return applications
 
     def get_app_by_type(self, type):
+        # 根据类型获取对应的OAuth应用
         for app in self.apps:
             if app.ICON_NAME.lower() == type:
                 return app
@@ -57,9 +64,11 @@ class OauthLoginTest(TestCase):
     @patch("oauth.oauthmanager.WBOauthManager.do_post")
     @patch("oauth.oauthmanager.WBOauthManager.do_get")
     def test_weibo_login(self, mock_do_get, mock_do_post):
+        # 测试微博OAuth登录流程
         weibo_app = self.get_app_by_type('weibo')
         assert weibo_app
         url = weibo_app.get_authorization_url()
+        # 模拟API响应
         mock_do_post.return_value = json.dumps({"access_token": "access_token",
                                                 "uid": "uid"
                                                 })
@@ -70,15 +79,18 @@ class OauthLoginTest(TestCase):
             "email": "email",
         })
         userinfo = weibo_app.get_access_token_by_code('code')
+        # 验证token和openid
         self.assertEqual(userinfo.token, 'access_token')
         self.assertEqual(userinfo.openid, 'id')
 
     @patch("oauth.oauthmanager.GoogleOauthManager.do_post")
     @patch("oauth.oauthmanager.GoogleOauthManager.do_get")
     def test_google_login(self, mock_do_get, mock_do_post):
+        # 测试Google OAuth登录流程
         google_app = self.get_app_by_type('google')
         assert google_app
         url = google_app.get_authorization_url()
+        # 模拟API响应
         mock_do_post.return_value = json.dumps({
             "access_token": "access_token",
             "id_token": "id_token",
@@ -91,17 +103,20 @@ class OauthLoginTest(TestCase):
         })
         token = google_app.get_access_token_by_code('code')
         userinfo = google_app.get_oauth_userinfo()
+        # 验证token和openid
         self.assertEqual(userinfo.token, 'access_token')
         self.assertEqual(userinfo.openid, 'sub')
 
     @patch("oauth.oauthmanager.GitHubOauthManager.do_post")
     @patch("oauth.oauthmanager.GitHubOauthManager.do_get")
     def test_github_login(self, mock_do_get, mock_do_post):
+        # 测试GitHub OAuth登录流程
         github_app = self.get_app_by_type('github')
         assert github_app
         url = github_app.get_authorization_url()
         self.assertTrue("github.com" in url)
         self.assertTrue("client_id" in url)
+        # 模拟API响应
         mock_do_post.return_value = "access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&scope=repo%2Cgist&token_type=bearer"
         mock_do_get.return_value = json.dumps({
             "avatar_url": "avatar_url",
@@ -111,16 +126,19 @@ class OauthLoginTest(TestCase):
         })
         token = github_app.get_access_token_by_code('code')
         userinfo = github_app.get_oauth_userinfo()
+        # 验证token和openid
         self.assertEqual(userinfo.token, 'gho_16C7e42F292c6912E7710c838347Ae178B4a')
         self.assertEqual(userinfo.openid, 'id')
 
     @patch("oauth.oauthmanager.FaceBookOauthManager.do_post")
     @patch("oauth.oauthmanager.FaceBookOauthManager.do_get")
     def test_facebook_login(self, mock_do_get, mock_do_post):
+        # 测试Facebook OAuth登录流程
         facebook_app = self.get_app_by_type('facebook')
         assert facebook_app
         url = facebook_app.get_authorization_url()
         self.assertTrue("facebook.com" in url)
+        # 模拟API响应
         mock_do_post.return_value = json.dumps({
             "access_token": "access_token",
         })
@@ -136,9 +154,11 @@ class OauthLoginTest(TestCase):
         })
         token = facebook_app.get_access_token_by_code('code')
         userinfo = facebook_app.get_oauth_userinfo()
+        # 验证token
         self.assertEqual(userinfo.token, 'access_token')
 
     @patch("oauth.oauthmanager.QQOauthManager.do_get", side_effect=[
+        # 模拟QQ登录的三步API调用响应
         'access_token=access_token&expires_in=3600',
         'callback({"client_id":"appid","openid":"openid"} );',
         json.dumps({
@@ -149,18 +169,22 @@ class OauthLoginTest(TestCase):
         })
     ])
     def test_qq_login(self, mock_do_get):
+        # 测试QQ OAuth登录流程
         qq_app = self.get_app_by_type('qq')
         assert qq_app
         url = qq_app.get_authorization_url()
         self.assertTrue("qq.com" in url)
         token = qq_app.get_access_token_by_code('code')
         userinfo = qq_app.get_oauth_userinfo()
+        # 验证token
         self.assertEqual(userinfo.token, 'access_token')
 
     @patch("oauth.oauthmanager.WBOauthManager.do_post")
     @patch("oauth.oauthmanager.WBOauthManager.do_get")
     def test_weibo_authoriz_login_with_email(self, mock_do_get, mock_do_post):
+        # 测试包含邮箱的微博授权登录完整流程
 
+        # 模拟API响应
         mock_do_post.return_value = json.dumps({"access_token": "access_token",
                                                 "uid": "uid"
                                                 })
@@ -172,14 +196,17 @@ class OauthLoginTest(TestCase):
         }
         mock_do_get.return_value = json.dumps(mock_user_info)
 
+        # 测试登录重定向
         response = self.client.get('/oauth/oauthlogin?type=weibo')
         self.assertEqual(response.status_code, 302)
         self.assertTrue("api.weibo.com" in response.url)
 
+        # 测试授权回调
         response = self.client.get('/oauth/authorize?type=weibo&code=code')
         self.assertEqual(response.status_code, 302)
         self.assertEqual(response.url, '/')
 
+        # 验证用户认证状态
         user = auth.get_user(self.client)
         assert user.is_authenticated
         self.assertTrue(user.is_authenticated)
@@ -187,6 +214,7 @@ class OauthLoginTest(TestCase):
         self.assertEqual(user.email, mock_user_info['email'])
         self.client.logout()
 
+        # 重复登录测试
         response = self.client.get('/oauth/authorize?type=weibo&code=code')
         self.assertEqual(response.status_code, 302)
         self.assertEqual(response.url, '/')
@@ -200,7 +228,9 @@ class OauthLoginTest(TestCase):
     @patch("oauth.oauthmanager.WBOauthManager.do_post")
     @patch("oauth.oauthmanager.WBOauthManager.do_get")
     def test_weibo_authoriz_login_without_email(self, mock_do_get, mock_do_post):
+        # 测试不包含邮箱的微博授权登录流程（需要补充邮箱）
 
+        # 模拟API响应
         mock_do_post.return_value = json.dumps({"access_token": "access_token",
                                                 "uid": "uid"
                                                 })
@@ -211,28 +241,34 @@ class OauthLoginTest(TestCase):
         }
         mock_do_get.return_value = json.dumps(mock_user_info)
 
+        # 测试登录重定向
         response = self.client.get('/oauth/oauthlogin?type=weibo')
         self.assertEqual(response.status_code, 302)
         self.assertTrue("api.weibo.com" in response.url)
 
+        # 测试授权回调（应该重定向到邮箱补充页面）
         response = self.client.get('/oauth/authorize?type=weibo&code=code')
-
         self.assertEqual(response.status_code, 302)
 
+        # 解析OAuth用户ID
         oauth_user_id = int(response.url.split('/')[-1].split('.')[0])
         self.assertEqual(response.url, f'/oauth/requireemail/{oauth_user_id}.html')
 
+        # 提交邮箱信息
         response = self.client.post(response.url, {'email': 'test@gmail.com', 'oauthid': oauth_user_id})
-
         self.assertEqual(response.status_code, 302)
+
+        # 生成邮箱确认签名
         sign = get_sha256(settings.SECRET_KEY +
                           str(oauth_user_id) + settings.SECRET_KEY)
 
+        # 验证绑定成功URL
         url = reverse('oauth:bindsuccess', kwargs={
             'oauthid': oauth_user_id,
         })
         self.assertEqual(response.url, f'{url}?type=email')
 
+        # 测试邮箱确认流程
         path = reverse('oauth:email_confirm', kwargs={
             'id': oauth_user_id,
             'sign': sign
@@ -240,10 +276,12 @@ class OauthLoginTest(TestCase):
         response = self.client.get(path)
         self.assertEqual(response.status_code, 302)
         self.assertEqual(response.url, f'/oauth/bindsuccess/{oauth_user_id}.html?type=success')
+
+        # 验证最终用户状态
         user = auth.get_user(self.client)
         from oauth.models import OAuthUser
         oauth_user = OAuthUser.objects.get(author=user)
         self.assertTrue(user.is_authenticated)
         self.assertEqual(user.username, mock_user_info['screen_name'])
         self.assertEqual(user.email, 'test@gmail.com')
-        self.assertEqual(oauth_user.pk, oauth_user_id)
+        self.assertEqual(oauth_user.pk, oauth_user_id)

src/DjangoBlog/oauth/urls.py

@@ -1,25 +1,40 @@
+# Django OAuth 认证模块的URL配置
 from django.urls import path
 
+# 导入视图模块
 from . import views
 
+# 定义应用命名空间，用于URL反向解析
 app_name = "oauth"
+
+# 定义URL模式列表
 urlpatterns = [
+    # OAuth授权回调处理路径
     path(
         r'oauth/authorize',
-        views.authorize),
+        views.authorize),  # 处理OAuth服务商返回的授权码
+
+    # 邮箱补充页面路径（当OAuth用户信息缺少邮箱时使用）
     path(
-        r'oauth/requireemail/<int:oauthid>.html',
-        views.RequireEmailView.as_view(),
-        name='require_email'),
+        r'oauth/requireemail/<int:oauthid>.html',  # 包含OAuth用户ID参数
+        views.RequireEmailView.as_view(),  # 使用类视图处理邮箱补充
+        name='require_email'),  # URL名称，用于反向解析
+
+    # 邮箱确认验证路径
     path(
-        r'oauth/emailconfirm/<int:id>/<sign>.html',
-        views.emailconfirm,
-        name='email_confirm'),
+        r'oauth/emailconfirm/<int:id>/<sign>.html',  # 包含用户ID和签名参数
+        views.emailconfirm,  # 处理邮箱确认请求
+        name='email_confirm'),  # URL名称，用于反向解析
+
+    # 绑定成功页面路径
     path(
-        r'oauth/bindsuccess/<int:oauthid>.html',
-        views.bindsuccess,
-        name='bindsuccess'),
+        r'oauth/bindsuccess/<int:oauthid>.html',  # 包含OAuth用户ID参数
+        views.bindsuccess,  # 显示绑定成功页面
+        name='bindsuccess'),  # URL名称，用于反向解析
+
+    # OAuth登录入口路径
     path(
         r'oauth/oauthlogin',
-        views.oauthlogin,
-        name='oauthlogin')]
+        views.oauthlogin,  # 处理OAuth登录请求
+        name='oauthlogin')  # URL名称，用于反向解析
+]

src/DjangoBlog/oauth/views.py

@@ -1,7 +1,11 @@
+# 导入日志模块
 import logging
-# Create your views here.
+# 创建视图文件
+
+# 导入URL解析模块
 from urllib.parse import urlparse
 
+# 导入Django相关模块
 from django.conf import settings
 from django.contrib.auth import get_user_model
 from django.contrib.auth import login
@@ -16,6 +20,7 @@ from django.utils import timezone
 from django.utils.translation import gettext_lazy as _
 from django.views.generic import FormView
 
+# 导入自定义模块
 from djangoblog.blog_signals import oauth_user_login_signal
 from djangoblog.utils import get_current_site
 from djangoblog.utils import send_email, get_sha256
@@ -23,17 +28,23 @@ from oauth.forms import RequireEmailForm
 from .models import OAuthUser
 from .oauthmanager import get_manager_by_type, OAuthAccessTokenException
 
+# 获取日志记录器
 logger = logging.getLogger(__name__)
 
 
 def get_redirecturl(request):
+    """获取重定向URL，进行安全性验证"""
+    # 从请求参数获取next_url
     nexturl = request.GET.get('next_url', None)
+    # 如果next_url是登录页面或为空，则重定向到首页
     if not nexturl or nexturl == '/login/' or nexturl == '/login':
         nexturl = '/'
         return nexturl
+    # 解析URL以验证域名安全性
     p = urlparse(nexturl)
     if p.netloc:
         site = get_current_site().domain
+        # 检查域名是否匹配当前站点（去除www前缀比较）
         if not p.netloc.replace('www.', '') == site.replace('www.', ''):
             logger.info('非法url:' + nexturl)
             return "/"
@@ -41,41 +52,53 @@ def get_redirecturl(request):
 
 
 def oauthlogin(request):
+    """处理OAuth登录请求，重定向到OAuth服务商授权页面"""
     type = request.GET.get('type', None)
     if not type:
         return HttpResponseRedirect('/')
+    # 根据类型获取对应的OAuth管理器
     manager = get_manager_by_type(type)
     if not manager:
         return HttpResponseRedirect('/')
+    # 获取重定向URL并生成授权URL
     nexturl = get_redirecturl(request)
     authorizeurl = manager.get_authorization_url(nexturl)
     return HttpResponseRedirect(authorizeurl)
 
 
 def authorize(request):
+    """处理OAuth授权回调，完成用户认证"""
     type = request.GET.get('type', None)
     if not type:
         return HttpResponseRedirect('/')
     manager = get_manager_by_type(type)
     if not manager:
         return HttpResponseRedirect('/')
+    # 获取授权码
     code = request.GET.get('code', None)
     try:
+        # 使用授权码获取访问令牌
         rsp = manager.get_access_token_by_code(code)
     except OAuthAccessTokenException as e:
+        # 处理访问令牌获取异常
         logger.warning("OAuthAccessTokenException:" + str(e))
         return HttpResponseRedirect('/')
     except Exception as e:
+        # 处理其他异常
         logger.error(e)
         rsp = None
     nexturl = get_redirecturl(request)
     if not rsp:
+        # 如果获取令牌失败，重新跳转到授权页面
         return HttpResponseRedirect(manager.get_authorization_url(nexturl))
+    # 获取OAuth用户信息
     user = manager.get_oauth_userinfo()
     if user:
+        # 处理昵称为空的情况
         if not user.nickname or not user.nickname.strip():
             user.nickname = "djangoblog" + timezone.now().strftime('%y%m%d%I%M%S')
         try:
+            # 检查是否已存在该OAuth用户
             temp = OAuthUser.objects.get(type=type, openid=user.openid)
             temp.picture = user.picture
             temp.metadata = user.metadata
@@ -83,9 +106,10 @@ def authorize(request):
             user = temp
         except ObjectDoesNotExist:
             pass
-        # facebook的token过长
+        # Facebook的token过长，清空处理
         if type == 'facebook':
             user.token = ''
+        # 如果用户有邮箱，直接完成登录
         if user.email:
             with transaction.atomic():
                 author = None
@@ -94,14 +118,17 @@ def authorize(request):
                 except ObjectDoesNotExist:
                     pass
                 if not author:
+                    # 创建或获取用户
                     result = get_user_model().objects.get_or_create(email=user.email)
                     author = result[0]
                     if result[1]:
                         try:
+                            # 检查用户名是否已存在
                             get_user_model().objects.get(username=user.nickname)
                         except ObjectDoesNotExist:
                             author.username = user.nickname
                         else:
+                            # 用户名冲突时生成唯一用户名
                             author.username = "djangoblog" + timezone.now().strftime('%y%m%d%I%M%S')
                         author.source = 'authorize'
                         author.save()
@@ -109,11 +136,14 @@ def authorize(request):
                 user.author = author
                 user.save()
 
+                # 发送用户登录信号
                 oauth_user_login_signal.send(
                     sender=authorize.__class__, id=user.id)
+                # 登录用户
                 login(request, author)
                 return HttpResponseRedirect(nexturl)
         else:
+            # 没有邮箱时保存用户并跳转到邮箱补充页面
             user.save()
             url = reverse('oauth:require_email', kwargs={
                 'oauthid': user.id
@@ -125,8 +155,10 @@ def authorize(request):
 
 
 def emailconfirm(request, id, sign):
+    """处理邮箱确认请求"""
     if not sign:
         return HttpResponseForbidden()
+    # 验证签名安全性
     if not get_sha256(settings.SECRET_KEY +
                       str(id) +
                       settings.SECRET_KEY).upper() == sign.upper():
@@ -136,21 +168,26 @@ def emailconfirm(request, id, sign):
         if oauthuser.author:
             author = get_user_model().objects.get(pk=oauthuser.author_id)
         else:
+            # 创建新用户
             result = get_user_model().objects.get_or_create(email=oauthuser.email)
             author = result[0]
             if result[1]:
                 author.source = 'emailconfirm'
+                # 处理昵称，如果为空则生成唯一用户名
                 author.username = oauthuser.nickname.strip() if oauthuser.nickname.strip(
                 ) else "djangoblog" + timezone.now().strftime('%y%m%d%I%M%S')
                 author.save()
         oauthuser.author = author
         oauthuser.save()
+    # 发送登录信号
     oauth_user_login_signal.send(
         sender=emailconfirm.__class__,
         id=oauthuser.id)
+    # 登录用户
     login(request, author)
 
     site = 'http://' + get_current_site().domain
+    # 准备绑定成功邮件内容
     content = _('''
      <p>Congratulations, you have successfully bound your email address. You can use
       %(oauthuser_type)s to directly log in to this website without a password.</p>
@@ -162,6 +199,7 @@ def emailconfirm(request, id, sign):
         %(site)s
     ''') % {'oauthuser_type': oauthuser.type, 'site': site}
 
+    # 发送绑定成功邮件
     send_email(emailto=[oauthuser.email, ], title=_('Congratulations on your successful binding!'), content=content)
     url = reverse('oauth:bindsuccess', kwargs={
         'oauthid': id
@@ -171,19 +209,22 @@ def emailconfirm(request, id, sign):
 
 
 class RequireEmailView(FormView):
+    """需要邮箱补充的视图类"""
     form_class = RequireEmailForm
     template_name = 'oauth/require_email.html'
 
     def get(self, request, *args, **kwargs):
+        """处理GET请求"""
         oauthid = self.kwargs['oauthid']
         oauthuser = get_object_or_404(OAuthUser, pk=oauthid)
         if oauthuser.email:
             pass
-            # return HttpResponseRedirect('/')
+            # 如果已有邮箱，可以重定向到首页
 
         return super(RequireEmailView, self).get(request, *args, **kwargs)
 
     def get_initial(self):
+        """初始化表单数据"""
         oauthid = self.kwargs['oauthid']
         return {
             'email': '',
@@ -191,6 +232,7 @@ class RequireEmailView(FormView):
         }
 
     def get_context_data(self, **kwargs):
+        """添加上下文数据"""
         oauthid = self.kwargs['oauthid']
         oauthuser = get_object_or_404(OAuthUser, pk=oauthid)
         if oauthuser.picture:
@@ -198,11 +240,13 @@ class RequireEmailView(FormView):
         return super(RequireEmailView, self).get_context_data(**kwargs)
 
     def form_valid(self, form):
+        """处理表单验证通过后的逻辑"""
         email = form.cleaned_data['email']
         oauthid = form.cleaned_data['oauthid']
         oauthuser = get_object_or_404(OAuthUser, pk=oauthid)
         oauthuser.email = email
         oauthuser.save()
+        # 生成安全签名
         sign = get_sha256(settings.SECRET_KEY +
                           str(oauthuser.id) + settings.SECRET_KEY)
         site = get_current_site().domain
@@ -214,6 +258,7 @@ class RequireEmailView(FormView):
         })
         url = "http://{site}{path}".format(site=site, path=path)
 
+        # 准备邮箱确认邮件内容
         content = _("""
                <p>Please click the link below to bind your email</p>
 
@@ -225,6 +270,7 @@ class RequireEmailView(FormView):
                   <br />
                  %(url)s
                 """) % {'url': url}
+        # 发送邮箱确认邮件
         send_email(emailto=[email, ], title=_('Bind your email'), content=content)
         url = reverse('oauth:bindsuccess', kwargs={
             'oauthid': oauthid
@@ -234,8 +280,10 @@ class RequireEmailView(FormView):
 
 
 def bindsuccess(request, oauthid):
+    """显示绑定成功页面"""
     type = request.GET.get('type', None)
     oauthuser = get_object_or_404(OAuthUser, pk=oauthid)
+    # 根据类型显示不同的成功信息
     if type == 'email':
         title = _('Bind your email')
         content = _(
@@ -250,4 +298,4 @@ def bindsuccess(request, oauthid):
     return render(request, 'oauth/bindsuccess.html', {
         'title': title,
         'content': content
-    })
+    })

src/DjangoBlog/owntracks/admin.py

@@ -1,7 +1,14 @@
+# 导入Django管理模块
 from django.contrib import admin
 
-# Register your models here.
+# 在这里注册模型到管理后台
 
 
+# 定义OwnTrackLogs模型的管理类
 class OwnTrackLogsAdmin(admin.ModelAdmin):
+    # 空pass语句，使用Django管理后台的默认配置
+    # 没有自定义任何管理选项，将使用Django的自动管理功能
     pass
+
+# 注意：这个类定义后还需要使用admin.site.register()来实际注册模型
+# 例如：admin.site.register(OwnTrackLogs, OwnTrackLogsAdmin)

src/DjangoBlog/owntracks/apps.py

@@ -1,5 +1,17 @@
+# 导入Django应用配置基类
 from django.apps import AppConfig
 
 
+# 定义Owntracks应用的配置类
 class OwntracksConfig(AppConfig):
+    # 指定应用的Python路径（Django 3.x及以下版本必需）
+    # 这应该与settings.INSTALLED_APPS中使用的路径匹配
     name = 'owntracks'
+
+    # 在Django 3.2及以上版本中，可以添加default_auto_field配置
+    # default_auto_field = 'django.db.models.BigAutoField'
+
+    # 可以在此添加应用启动时的初始化代码
+    # def ready(self):
+    #     # 导入信号处理器等
+    #     import owntracks.signals

src/DjangoBlog/owntracks/models.py

@@ -1,20 +1,31 @@
+# 导入Django模型和时区模块
 from django.db import models
 from django.utils.timezone import now
 
 
-# Create your models here.
+# 在这里创建模型
 
+# 定义OwnTrackLog模型类，用于存储位置跟踪数据
 class OwnTrackLog(models.Model):
+    # 用户标识字段，必填，最大长度100字符
     tid = models.CharField(max_length=100, null=False, verbose_name='用户')
+    # 纬度坐标，浮点数字段
     lat = models.FloatField(verbose_name='纬度')
+    # 经度坐标，浮点数字段
     lon = models.FloatField(verbose_name='经度')
+    # 创建时间字段，默认值为当前时间
     creation_time = models.DateTimeField('创建时间', default=now)
 
     def __str__(self):
+        # 定义对象的字符串表示，返回用户标识
         return self.tid
 
     class Meta:
+        # 按创建时间升序排列
         ordering = ['creation_time']
+        # 在管理后台显示的单数名称
         verbose_name = "OwnTrackLogs"
+        # 在管理后台显示的复数名称（与单数相同）
         verbose_name_plural = verbose_name
-        get_latest_by = 'creation_time'
+        # 指定获取最新记录的字段
+        get_latest_by = 'creation_time'

src/DjangoBlog/owntracks/tests.py

@@ -1,64 +1,92 @@
+# 导入JSON处理模块
 import json
 
+# 导入Django测试相关模块
 from django.test import Client, RequestFactory, TestCase
 
+# 导入用户模型和位置跟踪模型
 from accounts.models import BlogUser
 from .models import OwnTrackLog
 
 
-# Create your tests here.
+# 在这里创建测试
 
+# 定义OwnTrackLog模型测试类
 class OwnTrackLogTest(TestCase):
     def setUp(self):
+        # 初始化测试客户端和请求工厂
         self.client = Client()
         self.factory = RequestFactory()
 
     def test_own_track_log(self):
+        # 测试用例：验证位置跟踪日志功能
+
+        # 创建有效的位置数据（包含所有必需字段）
         o = {
-            'tid': 12,
-            'lat': 123.123,
-            'lon': 134.341
+            'tid': 12,  # 用户ID
+            'lat': 123.123,  # 纬度
+            'lon': 134.341  # 经度
         }
 
+        # 发送POST请求创建位置记录
         self.client.post(
-            '/owntracks/logtracks',
-            json.dumps(o),
-            content_type='application/json')
+            '/owntracks/logtracks',  # 位置记录接口
+            json.dumps(o),  # 将数据转换为JSON字符串
+            content_type='application/json')  # 设置内容类型为JSON
+
+        # 验证记录是否成功创建
         length = len(OwnTrackLog.objects.all())
-        self.assertEqual(length, 1)
+        self.assertEqual(length, 1)  # 应该有一条记录
 
+        # 创建无效的位置数据（缺少经度字段）
         o = {
             'tid': 12,
             'lat': 123.123
+            # 缺少lon字段
         }
 
+        # 发送POST请求（应该不会创建新记录）
         self.client.post(
             '/owntracks/logtracks',
             json.dumps(o),
             content_type='application/json')
+
+        # 验证记录数量没有增加
         length = len(OwnTrackLog.objects.all())
-        self.assertEqual(length, 1)
+        self.assertEqual(length, 1)  # 应该仍然只有一条记录
 
+        # 测试未登录用户访问地图页面（应该重定向到登录页）
         rsp = self.client.get('/owntracks/show_maps')
-        self.assertEqual(rsp.status_code, 302)
+        self.assertEqual(rsp.status_code, 302)  # 302表示重定向
 
+        # 创建超级用户用于后续测试
         user = BlogUser.objects.create_superuser(
-            email="liangliangyy1@gmail.com",
-            username="liangliangyy1",
-            password="liangliangyy1")
+            email="liangliangyy1@gmail.com",  # 邮箱
+            username="liangliangyy1",  # 用户名
+            password="liangliangyy1")  # 密码
 
+        # 使用新创建的用户登录
         self.client.login(username='liangliangyy1', password='liangliangyy1')
+
+        # 手动创建位置记录对象
         s = OwnTrackLog()
-        s.tid = 12
-        s.lon = 123.234
-        s.lat = 34.234
-        s.save()
+        s.tid = 12  # 设置用户ID
+        s.lon = 123.234  # 设置经度
+        s.lat = 34.234  # 设置纬度
+        s.save()  # 保存到数据库
 
+        # 测试日期显示页面（登录后应该可以正常访问）
         rsp = self.client.get('/owntracks/show_dates')
-        self.assertEqual(rsp.status_code, 200)
+        self.assertEqual(rsp.status_code, 200)  # 200表示成功
+
+        # 测试地图显示页面
         rsp = self.client.get('/owntracks/show_maps')
         self.assertEqual(rsp.status_code, 200)
+
+        # 测试获取数据接口（不带日期参数）
         rsp = self.client.get('/owntracks/get_datas')
         self.assertEqual(rsp.status_code, 200)
+
+        # 测试获取数据接口（带日期参数）
         rsp = self.client.get('/owntracks/get_datas?date=2018-02-26')
-        self.assertEqual(rsp.status_code, 200)
+        self.assertEqual(rsp.status_code, 200)

src/DjangoBlog/owntracks/urls.py

@@ -1,12 +1,23 @@
+# 导入Django URL配置模块
 from django.urls import path
 
+# 导入当前应用的视图模块
 from . import views
 
+# 定义应用命名空间，用于URL反向解析
 app_name = "owntracks"
 
+# 定义URL模式列表
 urlpatterns = [
+    # 位置数据记录接口 - 接收和处理OwnTracks客户端发送的位置数据
     path('owntracks/logtracks', views.manage_owntrack_log, name='logtracks'),
+
+    # 地图显示页面 - 展示位置数据在地图上的可视化
     path('owntracks/show_maps', views.show_maps, name='show_maps'),
+
+    # 数据获取接口 - 提供位置数据的JSON格式接口
     path('owntracks/get_datas', views.get_datas, name='get_datas'),
+
+    # 日期显示页面 - 展示有位置记录的日期列表
     path('owntracks/show_dates', views.show_log_dates, name='show_dates')
-]
+]

src/DjangoBlog/owntracks/views.py

@@ -1,4 +1,6 @@
-# Create your views here.
+# 在这里创建视图
+
+# 导入必要的模块
 import datetime
 import itertools
 import json
@@ -14,114 +16,138 @@ from django.http import JsonResponse
 from django.shortcuts import render
 from django.views.decorators.csrf import csrf_exempt
 
+# 导入位置跟踪模型
 from .models import OwnTrackLog
 
+# 获取日志记录器
 logger = logging.getLogger(__name__)
 
 
-@csrf_exempt
+@csrf_exempt  # 禁用CSRF保护，允许外部应用POST请求
 def manage_owntrack_log(request):
+    """处理OwnTracks客户端发送的位置数据"""
     try:
+        # 解析JSON请求体
         s = json.loads(request.read().decode('utf-8'))
-        tid = s['tid']
-        lat = s['lat']
-        lon = s['lon']
+        tid = s['tid']  # 获取用户ID
+        lat = s['lat']  # 获取纬度
+        lon = s['lon']  # 获取经度
 
+        # 记录位置信息日志
         logger.info(
             'tid:{tid}.lat:{lat}.lon:{lon}'.format(
                 tid=tid, lat=lat, lon=lon))
+        # 验证必需字段是否存在
         if tid and lat and lon:
-            m = OwnTrackLog()
+            m = OwnTrackLog()  # 创建位置记录对象
             m.tid = tid
             m.lat = lat
             m.lon = lon
-            m.save()
-            return HttpResponse('ok')
+            m.save()  # 保存到数据库
+            return HttpResponse('ok')  # 返回成功响应
         else:
-            return HttpResponse('data error')
+            return HttpResponse('data error')  # 返回数据错误响应
     except Exception as e:
+        # 记录异常日志
         logger.error(e)
-        return HttpResponse('error')
+        return HttpResponse('error')  # 返回错误响应
 
 
-@login_required
+@login_required  # 要求用户登录
 def show_maps(request):
+    """显示位置数据地图页面（仅超级用户可访问）"""
     if request.user.is_superuser:
+        # 获取默认日期（今天）
         defaultdate = str(datetime.datetime.now(timezone.utc).date())
+        # 从请求参数获取日期，默认为今天
         date = request.GET.get('date', defaultdate)
         context = {
-            'date': date
+            'date': date  # 将日期传递到模板
         }
         return render(request, 'owntracks/show_maps.html', context)
     else:
         from django.http import HttpResponseForbidden
-        return HttpResponseForbidden()
+        return HttpResponseForbidden()  # 非超级用户返回403禁止访问
 
 
-@login_required
+@login_required  # 要求用户登录
 def show_log_dates(request):
+    """显示有位置记录的日期列表"""
+    # 获取所有记录的创建时间
     dates = OwnTrackLog.objects.values_list('creation_time', flat=True)
+    # 提取唯一日期并排序
     results = list(sorted(set(map(lambda x: x.strftime('%Y-%m-%d'), dates))))
 
     context = {
-        'results': results
+        'results': results  # 将日期列表传递到模板
     }
     return render(request, 'owntracks/show_log_dates.html', context)
 
 
 def convert_to_amap(locations):
+    """将GPS坐标转换为高德地图坐标（批量转换，每批30个点）"""
     convert_result = []
-    it = iter(locations)
+    it = iter(locations)  # 创建迭代器
 
+    # 每次处理30个坐标点
     item = list(itertools.islice(it, 30))
     while item:
+        # 将坐标格式化为高德API要求的格式（经度,纬度;经度,纬度...）
         datas = ';'.join(
             set(map(lambda x: str(x.lon) + ',' + str(x.lat), item)))
 
-        key = '8440a376dfc9743d8924bf0ad141f28e'
-        api = 'http://restapi.amap.com/v3/assistant/coordinate/convert'
+        key = '8440a376dfc9743d8924bf0ad141f28e'  # 高德API密钥
+        api = 'http://restapi.amap.com/v3/assistant/coordinate/convert'  # 高德坐标转换API
         query = {
             'key': key,
             'locations': datas,
-            'coordsys': 'gps'
+            'coordsys': 'gps'  # 指定源坐标系为GPS
         }
-        rsp = requests.get(url=api, params=query)
-        result = json.loads(rsp.text)
+        rsp = requests.get(url=api, params=query)  # 发送API请求
+        result = json.loads(rsp.text)  # 解析响应
         if "locations" in result:
-            convert_result.append(result['locations'])
-        item = list(itertools.islice(it, 30))
+            convert_result.append(result['locations'])  # 添加转换后的坐标
+        item = list(itertools.islice(it, 30))  # 获取下一批坐标
 
-    return ";".join(convert_result)
+    return ";".join(convert_result)  # 返回所有转换后的坐标
 
 
-@login_required
+@login_required  # 要求用户登录
 def get_datas(request):
+    """获取指定日期的位置数据（JSON格式）"""
+    # 获取当前时间（UTC时区）
     now = django.utils.timezone.now().replace(tzinfo=timezone.utc)
+    # 设置查询日期（默认为今天）
     querydate = django.utils.timezone.datetime(
         now.year, now.month, now.day, 0, 0, 0)
+    # 如果请求中指定了日期，使用指定日期
     if request.GET.get('date', None):
         date = list(map(lambda x: int(x), request.GET.get('date').split('-')))
         querydate = django.utils.timezone.datetime(
             date[0], date[1], date[2], 0, 0, 0)
+    # 计算下一天（查询范围：querydate 到 nextdate）
     nextdate = querydate + datetime.timedelta(days=1)
+    # 查询指定日期范围内的位置记录
     models = OwnTrackLog.objects.filter(
         creation_time__range=(querydate, nextdate))
     result = list()
     if models and len(models):
+        # 按用户ID分组处理位置数据
         for tid, item in groupby(
                 sorted(models, key=lambda k: k.tid), key=lambda k: k.tid):
 
             d = dict()
-            d["name"] = tid
-            paths = list()
-            # 使用高德转换后的经纬度
+            d["name"] = tid  # 用户ID作为名称
+            paths = list()  # 存储路径点
+            # 注释掉的部分：使用高德地图坐标转换
             # locations = convert_to_amap(
             #     sorted(item, key=lambda x: x.creation_time))
             # for i in locations.split(';'):
             #     paths.append(i.split(','))
-            # 使用GPS原始经纬度
+
+            # 使用原始GPS坐标
             for location in sorted(item, key=lambda x: x.creation_time):
-                paths.append([str(location.lon), str(location.lat)])
-            d["path"] = paths
-            result.append(d)
-    return JsonResponse(result, safe=False)
+                paths.append([str(location.lon), str(location.lat)])  # 添加坐标点
+            d["path"] = paths  # 设置路径数据
+            result.append(d)  # 添加到结果列表
+    return JsonResponse(result, safe=False)  # 返回JSON响应

src/DjangoBlog/plugins/article_copyright/plugin.py

@@ -1,37 +1,51 @@
+# 导入插件基类和钩子管理模块
 from djangoblog.plugin_manage.base_plugin import BasePlugin
 from djangoblog.plugin_manage import hooks
 from djangoblog.plugin_manage.hook_constants import ARTICLE_CONTENT_HOOK_NAME
 
 
+# 定义文章版权插件类，继承自基础插件类
 class ArticleCopyrightPlugin(BasePlugin):
-    PLUGIN_NAME = '文章结尾版权声明'
-    PLUGIN_DESCRIPTION = '一个在文章正文末尾添加版权声明的插件。'
-    PLUGIN_VERSION = '0.2.0'
-    PLUGIN_AUTHOR = 'liangliangyy'
+    # 插件元数据配置
+    PLUGIN_NAME = '文章结尾版权声明'  # 插件显示名称
+    PLUGIN_DESCRIPTION = '一个在文章正文末尾添加版权声明的插件。'  # 插件功能描述
+    PLUGIN_VERSION = '0.2.0'  # 插件版本号
+    PLUGIN_AUTHOR = 'liangliangyy'  # 插件作者
 
     # 2. 实现 register_hooks 方法，专门用于注册钩子
     def register_hooks(self):
+        """注册插件钩子到系统钩子管理器"""
         # 在这里将插件的方法注册到指定的钩子上
+        # 将 add_copyright_to_content 方法注册到文章内容钩子
         hooks.register(ARTICLE_CONTENT_HOOK_NAME, self.add_copyright_to_content)
 
     def add_copyright_to_content(self, content, *args, **kwargs):
         """
         这个方法会被注册到 'the_content' 过滤器钩子上。
         它接收原始内容，并返回添加了版权信息的新内容。
+
+        参数:
+            content: 原始文章内容
+            *args: 可变位置参数
+            **kwargs: 可变关键字参数，包含文章对象等信息
         """
+        # 从关键字参数中获取文章对象
         article = kwargs.get('article')
         if not article:
+            # 如果没有文章对象，直接返回原始内容
             return content
-        
+
         # 如果是摘要模式（首页），不添加版权声明
         is_summary = kwargs.get('is_summary', False)
         if is_summary:
             return content
 
+        # 构建版权声明HTML
         copyright_info = f"\n<hr><p>本文由 {article.author.username} 原创，转载请注明出处。</p>"
+        # 在原文末尾添加版权声明
         return content + copyright_info
 
 
 # 3. 实例化插件。
 # 这会自动调用 BasePlugin.__init__，然后 BasePlugin.__init__ 会调用我们上面定义的 register_hooks 方法。
-plugin = ArticleCopyrightPlugin()
+plugin = ArticleCopyrightPlugin()  # 创建插件实例，触发插件注册流程

src/DjangoBlog/plugins/external_links/plugin.py

@@ -1,48 +1,69 @@
+# 导入正则表达式模块和URL解析模块
 import re
 from urllib.parse import urlparse
+
+# 导入插件管理相关模块
 from djangoblog.plugin_manage.base_plugin import BasePlugin
 from djangoblog.plugin_manage import hooks
 from djangoblog.plugin_manage.hook_constants import ARTICLE_CONTENT_HOOK_NAME
 
 
+# 定义外部链接处理插件类
 class ExternalLinksPlugin(BasePlugin):
-    PLUGIN_NAME = '外部链接处理器'
-    PLUGIN_DESCRIPTION = '自动为文章中的外部链接添加 target="_blank" 和 rel="noopener noreferrer" 属性。'
-    PLUGIN_VERSION = '0.1.0'
-    PLUGIN_AUTHOR = 'liangliangyy'
+    # 插件元数据配置
+    PLUGIN_NAME = '外部链接处理器'  # 插件名称
+    PLUGIN_DESCRIPTION = '自动为文章中的外部链接添加 target="_blank" 和 rel="noopener noreferrer" 属性。'  # 插件描述
+    PLUGIN_VERSION = '0.1.0'  # 插件版本
+    PLUGIN_AUTHOR = 'liangliangyy'  # 插件作者
 
     def register_hooks(self):
+        """注册插件钩子"""
+        # 将外部链接处理方法注册到文章内容钩子
         hooks.register(ARTICLE_CONTENT_HOOK_NAME, self.process_external_links)
 
     def process_external_links(self, content, *args, **kwargs):
+        """处理文章内容中的外部链接，添加安全属性"""
+        # 延迟导入以避免循环依赖
         from djangoblog.utils import get_current_site
+        # 获取当前站点域名
         site_domain = get_current_site().domain
 
         # 正则表达式查找所有 <a> 标签
+        # 匹配模式：<a 标签开始，href属性，链接URL，标签结束
         link_pattern = re.compile(r'(<a\s+(?:[^>]*?\s+)?href=")([^"]*)(".*?/a>)', re.IGNORECASE)
 
         def replacer(match):
+            """
+            链接替换函数，为外部链接添加安全属性
+
+            参数:
+                match: 正则匹配对象
+            """
             # match.group(1) 是 <a ... href="
             # match.group(2) 是链接 URL
             # match.group(3) 是 ">...</a>
             href = match.group(2)
 
-            # 如果链接已经有 target 属性，则不处理
+            # 如果链接已经有 target 属性，则不处理（避免重复添加）
             if 'target=' in match.group(0).lower():
                 return match.group(0)
 
-            # 解析链接
+            # 解析链接URL
             parsed_url = urlparse(href)
 
             # 如果链接是外部的 (有域名且域名不等于当前网站域名)
             if parsed_url.netloc and parsed_url.netloc != site_domain:
-                # 添加 target 和 rel 属性
+                # 添加 target="_blank" 和 rel="noopener noreferrer" 属性
+                # target="_blank": 在新窗口打开链接
+                # rel="noopener noreferrer": 安全属性，防止标签页钓鱼攻击
                 return f'{match.group(1)}{href}" target="_blank" rel="noopener noreferrer"{match.group(3)}'
 
-            # 否则返回原样
+            # 否则返回原样（内部链接不处理）
             return match.group(0)
 
+        # 使用正则表达式替换所有匹配的链接
         return link_pattern.sub(replacer, content)
 
 
-plugin = ExternalLinksPlugin()
+# 实例化插件，触发自动注册
+plugin = ExternalLinksPlugin()

src/DjangoBlog/plugins/image_lazy_loading/plugin.py

@@ -1,107 +1,138 @@
+# 导入必要的模块
 import re
 import hashlib
 from urllib.parse import urlparse
+# 导入插件管理相关模块
 from djangoblog.plugin_manage.base_plugin import BasePlugin
 from djangoblog.plugin_manage import hooks
 from djangoblog.plugin_manage.hook_constants import ARTICLE_CONTENT_HOOK_NAME
 
 
+# 定义图片性能优化插件类
 class ImageOptimizationPlugin(BasePlugin):
-    PLUGIN_NAME = '图片性能优化插件'
-    PLUGIN_DESCRIPTION = '自动为文章中的图片添加懒加载、异步解码等性能优化属性，显著提升页面加载速度。'
-    PLUGIN_VERSION = '1.0.0'
-    PLUGIN_AUTHOR = 'liangliangyy'
+    # 插件元数据配置
+    PLUGIN_NAME = '图片性能优化插件'  # 插件名称
+    PLUGIN_DESCRIPTION = '自动为文章中的图片添加懒加载、异步解码等性能优化属性，显著提升页面加载速度。'  # 插件详细描述
+    PLUGIN_VERSION = '1.0.0'  # 插件版本号
+    PLUGIN_AUTHOR = 'liangliangyy'  # 插件作者
 
     def __init__(self):
-        # 插件配置
+        # 插件配置字典，控制各项优化功能的开关
         self.config = {
-            'enable_lazy_loading': True,        # 启用懒加载
-            'enable_async_decoding': True,      # 启用异步解码
-            'add_loading_placeholder': True,    # 添加加载占位符
-            'optimize_external_images': True,   # 优化外部图片
-            'add_responsive_attributes': True,  # 添加响应式属性
-            'skip_first_image': True,          # 跳过第一张图片（LCP优化）
+            'enable_lazy_loading': True,  # 启用懒加载（延迟加载非首屏图片）
+            'enable_async_decoding': True,  # 启用异步解码（不阻塞页面渲染）
+            'add_loading_placeholder': True,  # 添加加载占位符（改善用户体验）
+            'optimize_external_images': True,  # 优化外部图片（添加安全属性）
+            'add_responsive_attributes': True,  # 添加响应式属性（适应不同屏幕）
+            'skip_first_image': True,  # 跳过第一张图片（LCP优化，确保首图快速加载）
         }
+        # 调用父类初始化方法
         super().__init__()
 
     def register_hooks(self):
+        """注册插件到文章内容钩子"""
         hooks.register(ARTICLE_CONTENT_HOOK_NAME, self.optimize_images)
 
     def optimize_images(self, content, *args, **kwargs):
         """
-        优化文章中的图片标签
+        优化文章中的图片标签的主方法
+
+        参数:
+            content: 原始文章内容
+            *args: 可变位置参数
+            **kwargs: 可变关键字参数
+
+        返回:
+            优化后的文章内容
         """
         if not content:
             return content
 
         # 正则表达式匹配 img 标签
+        # 匹配模式：<img 标签开始，捕获所有属性，标签结束
         img_pattern = re.compile(
             r'<img\s+([^>]*?)(?:\s*/)?>',
-            re.IGNORECASE | re.DOTALL
+            re.IGNORECASE | re.DOTALL  # 忽略大小写，匹配多行
         )
 
-        image_count = 0
-        
+        image_count = 0  # 图片计数器，用于识别首张图片
+
         def replace_img_tag(match):
-            nonlocal image_count
-            image_count += 1
-            
-            # 获取原始属性
+            """内部替换函数，处理单个图片标签"""
+            nonlocal image_count  # 引用外部计数器
+            image_count += 1  # 增加图片计数
+
+            # 获取原始属性字符串
             original_attrs = match.group(1)
-            
-            # 解析现有属性
+
+            # 解析现有属性为字典
             attrs = self._parse_img_attributes(original_attrs)
-            
-            # 应用优化
+
+            # 应用各种优化策略
             optimized_attrs = self._apply_optimizations(attrs, image_count)
-            
-            # 重构 img 标签
+
+            # 重构优化后的 img 标签
             return self._build_img_tag(optimized_attrs)
 
-        # 替换所有 img 标签
+        # 使用正则表达式替换所有匹配的图片标签
         optimized_content = img_pattern.sub(replace_img_tag, content)
-        
+
         return optimized_content
 
     def _parse_img_attributes(self, attr_string):
         """
-        解析 img 标签的属性
+        解析 img 标签的属性字符串为字典
+
+        参数:
+            attr_string: 属性字符串（如 'src="image.jpg" alt="图片"'）
+
+        返回:
+            属性字典
         """
         attrs = {}
-        
-        # 正则表达式匹配属性
+
+        # 正则表达式匹配属性（属性名=引号包围的属性值）
         attr_pattern = re.compile(r'(\w+)=(["\'])(.*?)\2')
-        
+
+        # 遍历所有匹配的属性
         for match in attr_pattern.finditer(attr_string):
-            attr_name = match.group(1).lower()
-            attr_value = match.group(3)
+            attr_name = match.group(1).lower()  # 属性名转为小写
+            attr_value = match.group(3)  # 属性值
             attrs[attr_name] = attr_value
-            
+
         return attrs
 
     def _apply_optimizations(self, attrs, image_index):
         """
-        应用各种图片优化
+        应用各种图片优化策略
+
+        参数:
+            attrs: 图片属性字典
+            image_index: 图片在文章中的序号
+
+        返回:
+            优化后的属性字典
         """
-        # 1. 懒加载优化（跳过第一张图片以优化LCP）
+        # 1. 懒加载优化（跳过第一张图片以优化LCP - Largest Contentful Paint）
         if self.config['enable_lazy_loading']:
+            # 如果配置了跳过首图且当前是首图，则不添加懒加载
             if not (self.config['skip_first_image'] and image_index == 1):
                 if 'loading' not in attrs:
-                    attrs['loading'] = 'lazy'
+                    attrs['loading'] = 'lazy'  # 添加懒加载属性
 
-        # 2. 异步解码
+        # 2. 异步解码（不阻塞页面渲染）
         if self.config['enable_async_decoding']:
             if 'decoding' not in attrs:
-                attrs['decoding'] = 'async'
+                attrs['decoding'] = 'async'  # 异步解码
 
-        # 3. 添加样式优化
+        # 3. 添加样式优化（确保图片响应式）
         current_style = attrs.get('style', '')
-        
+
         # 确保图片不会超出容器
         if 'max-width' not in current_style:
             if current_style and not current_style.endswith(';'):
                 current_style += ';'
-            current_style += 'max-width:100%;height:auto;'
+            current_style += 'max-width:100%;height:auto;'  # 响应式样式
             attrs['style'] = current_style
 
         # 4. 添加 alt 属性（SEO和可访问性）
@@ -110,41 +141,43 @@ class ImageOptimizationPlugin(BasePlugin):
             src = attrs.get('src', '')
             if src:
                 # 从文件名生成alt文本
-                filename = src.split('/')[-1].split('.')[0]
-                # 移除常见的无意义字符
+                filename = src.split('/')[-1].split('.')[0]  # 获取文件名（不含扩展名）
+                # 移除常见的无意义字符（如长hash值）
                 clean_name = re.sub(r'[0-9a-f]{8,}', '', filename)  # 移除长hash
-                clean_name = re.sub(r'[_-]+', ' ', clean_name).strip()
-                attrs['alt'] = clean_name if clean_name else '文章图片'
+                clean_name = re.sub(r'[_-]+', ' ', clean_name).strip()  # 替换分隔符为空格
+                attrs['alt'] = clean_name if clean_name else '文章图片'  # 设置alt文本
             else:
-                attrs['alt'] = '文章图片'
+                attrs['alt'] = '文章图片'  # 默认alt文本
 
-        # 5. 外部图片优化
+        # 5. 外部图片优化（安全性和性能）
         if self.config['optimize_external_images'] and 'src' in attrs:
             src = attrs['src']
-            parsed_url = urlparse(src)
-            
+            parsed_url = urlparse(src)  # 解析URL
+
             # 如果是外部图片，添加 referrerpolicy
             if parsed_url.netloc and parsed_url.netloc != self._get_current_domain():
-                attrs['referrerpolicy'] = 'no-referrer-when-downgrade'
+                attrs['referrerpolicy'] = 'no-referrer-when-downgrade'  # 引用策略
                 # 为外部图片添加crossorigin属性以支持性能监控
                 if 'crossorigin' not in attrs:
-                    attrs['crossorigin'] = 'anonymous'
+                    attrs['crossorigin'] = 'anonymous'  # 跨域属性
 
         # 6. 响应式图片属性（如果配置启用）
         if self.config['add_responsive_attributes']:
             # 添加 sizes 属性（如果没有的话）
             if 'sizes' not in attrs and 'srcset' not in attrs:
+                # 设置响应式断点
                 attrs['sizes'] = '(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw'
 
         # 7. 添加图片唯一标识符用于性能追踪
         if 'data-img-id' not in attrs and 'src' in attrs:
+            # 基于图片URL生成短hash作为唯一ID
             img_hash = hashlib.md5(attrs['src'].encode()).hexdigest()[:8]
-            attrs['data-img-id'] = f'img-{img_hash}'
+            attrs['data-img-id'] = f'img-{img_hash}'  # 添加追踪ID
 
         # 8. 为第一张图片添加高优先级提示（LCP优化）
         if image_index == 1 and self.config['skip_first_image']:
-            attrs['fetchpriority'] = 'high'
-            # 移除懒加载以确保快速加载
+            attrs['fetchpriority'] = 'high'  # 高加载优先级
+            # 移除懒加载以确保快速加载（首图需要立即加载）
             if 'loading' in attrs:
                 del attrs['loading']
 
@@ -152,31 +185,41 @@ class ImageOptimizationPlugin(BasePlugin):
 
     def _build_img_tag(self, attrs):
         """
-        重新构建 img 标签
+        重新构建优化后的 img 标签
+
+        参数:
+            attrs: 优化后的属性字典
+
+        返回:
+            完整的 img 标签字符串
         """
         attr_strings = []
-        
-        # 确保 src 属性在最前面
+
+        # 确保 src 属性在最前面（标准做法）
         if 'src' in attrs:
             attr_strings.append(f'src="{attrs["src"]}"')
-            
-        # 添加其他属性
-        for key, value in attrs.items():
+
+        # 添加其他属性（按字母顺序排序，便于阅读和调试）
+        for key, value in sorted(attrs.items()):
             if key != 'src':  # src 已经添加过了
                 attr_strings.append(f'{key}="{value}"')
-        
+
+        # 构建完整的 img 标签
         return f'<img {" ".join(attr_strings)}>'
 
     def _get_current_domain(self):
         """
-        获取当前网站域名
+        获取当前网站域名，用于判断图片是否为外部图片
+
+        返回:
+            当前站点域名字符串
         """
         try:
             from djangoblog.utils import get_current_site
             return get_current_site().domain
         except:
-            return ''
+            return ''  # 异常时返回空字符串
 
 
-# 实例化插件
-plugin = ImageOptimizationPlugin()
+# 实例化插件，触发自动注册
+plugin = ImageOptimizationPlugin()

src/DjangoBlog/plugins/reading_time/plugin.py

@@ -1,51 +1,77 @@
+# 导入数学计算和正则表达式模块
 import math
 import re
+# 导入插件管理相关模块
 from djangoblog.plugin_manage.base_plugin import BasePlugin
 from djangoblog.plugin_manage import hooks
 from djangoblog.plugin_manage.hook_constants import ARTICLE_CONTENT_HOOK_NAME
 
 
+# 定义阅读时间预测插件类
 class ReadingTimePlugin(BasePlugin):
-    PLUGIN_NAME = '阅读时间预测'
-    PLUGIN_DESCRIPTION = '估算文章阅读时间并显示在文章开头。'
-    PLUGIN_VERSION = '0.1.0'
-    PLUGIN_AUTHOR = 'liangliangyy'
+    # 插件元数据配置
+    PLUGIN_NAME = '阅读时间预测'  # 插件名称
+    PLUGIN_DESCRIPTION = '估算文章阅读时间并显示在文章开头。'  # 插件功能描述
+    PLUGIN_VERSION = '0.1.0'  # 插件版本号
+    PLUGIN_AUTHOR = 'liangliangyy'  # 插件作者
 
     def register_hooks(self):
+        """注册插件钩子"""
+        # 将阅读时间计算方法注册到文章内容钩子
         hooks.register(ARTICLE_CONTENT_HOOK_NAME, self.add_reading_time)
 
     def add_reading_time(self, content, *args, **kwargs):
         """
         计算阅读时间并添加到内容开头。
         只在文章详情页显示，首页（文章列表页）不显示。
+
+        参数:
+            content: 原始文章内容
+            *args: 可变位置参数
+            **kwargs: 可变关键字参数，包含is_summary等上下文信息
+
+        返回:
+            添加了阅读时间提示的内容
         """
         # 检查是否为摘要模式（首页/文章列表页）
-        # 通过kwargs中的is_summary参数判断
+        # 通过kwargs中的is_summary参数判断，默认为False
         is_summary = kwargs.get('is_summary', False)
         if is_summary:
             # 如果是摘要模式（首页），直接返回原内容，不添加阅读时间
             return content
-        
-        # 移除HTML标签和空白字符，以获得纯文本
+
+        # 移除HTML标签和空白字符，以获得纯文本用于字数统计
+        # 使用正则表达式移除所有HTML标签
         clean_content = re.sub(r'<[^>]*>', '', content)
+        # 移除首尾空白字符
         clean_content = clean_content.strip()
-        
+
         # 中文和英文单词混合计数的一个简单方法
         # 匹配中文字符或连续的非中文字符(视为单词)
+        # [\u4e00-\u9fa5] 匹配所有中文字符
+        # \w+ 匹配连续的字母数字字符（英文单词）
         words = re.findall(r'[\u4e00-\u9fa5]|\w+', clean_content)
+        # 获取总字数
         word_count = len(words)
-        
-        # 按平均每分钟200字的速度计算
+
+        # 按平均每分钟200字的速度计算阅读时间
+        # 这个速度是基于中文阅读的平均速度
         reading_speed = 200
+        # 使用math.ceil向上取整，确保至少1分钟
         reading_minutes = math.ceil(word_count / reading_speed)
 
         # 如果阅读时间少于1分钟，则显示为1分钟
+        # 避免显示0分钟的情况
         if reading_minutes < 1:
             reading_minutes = 1
-            
+
+        # 生成阅读时间提示的HTML代码
+        # 使用灰色文字和斜体样式，视觉上不突兀
         reading_time_html = f'<p style="color: #888;"><em>预计阅读时间：{reading_minutes} 分钟</em></p>'
-        
+
+        # 将阅读时间提示添加到文章内容开头
         return reading_time_html + content
 
 
-plugin = ReadingTimePlugin() 
+# 实例化插件，触发自动注册
+plugin = ReadingTimePlugin()

src/DjangoBlog/plugins/seo_optimizer/plugin.py

@@ -1,3 +1,4 @@
+# 导入必要的模块
 import json
 from django.utils.html import strip_tags
 from django.template.defaultfilters import truncatewords
@@ -8,140 +9,171 @@ from djangoblog.utils import get_blog_setting
 
 
 class SeoOptimizerPlugin(BasePlugin):
-    PLUGIN_NAME = 'SEO 优化器'
-    PLUGIN_DESCRIPTION = '为文章、页面等提供 SEO 优化，动态生成 meta 标签和 JSON-LD 结构化数据。'
-    PLUGIN_VERSION = '0.2.0'
-    PLUGIN_AUTHOR = 'liuangliangyy'
+    # 插件元数据配置
+    PLUGIN_NAME = 'SEO 优化器'  # 插件名称
+    PLUGIN_DESCRIPTION = '为文章、页面等提供 SEO 优化，动态生成 meta 标签和 JSON-LD 结构化数据。'  # 插件功能描述
+    PLUGIN_VERSION = '0.2.0'  # 插件版本号
+    PLUGIN_AUTHOR = 'liuangliangyy'  # 插件作者（注意：用户名可能有拼写错误）
 
     def register_hooks(self):
+        """注册插件到head_meta钩子"""
         hooks.register('head_meta', self.dispatch_seo_generation)
 
     def _get_article_seo_data(self, context, request, blog_setting):
+        """生成文章页面的SEO数据"""
+        # 从上下文中获取文章对象
         article = context.get('article')
+        # 检查是否为有效的文章对象
         if not isinstance(article, Article):
             return None
 
+        # 生成文章描述：移除HTML标签并截取前150个字符
         description = strip_tags(article.body)[:150]
+        # 生成关键词：使用文章标签或站点默认关键词
         keywords = ",".join([tag.name for tag in article.tags.all()]) or blog_setting.site_keywords
-        
+
+        # 生成Open Graph meta标签（用于社交媒体分享）
         meta_tags = f'''
-        <meta property="og:type" content="article"/>
-        <meta property="og:title" content="{article.title}"/>
-        <meta property="og:description" content="{description}"/>
-        <meta property="og:url" content="{request.build_absolute_uri()}"/>
-        <meta property="article:published_time" content="{article.pub_time.isoformat()}"/>
-        <meta property="article:modified_time" content="{article.last_modify_time.isoformat()}"/>
-        <meta property="article:author" content="{article.author.username}"/>
-        <meta property="article:section" content="{article.category.name}"/>
+        <meta property="og:type" content="article"/>  <!-- 内容类型为文章 -->
+        <meta property="og:title" content="{article.title}"/>  <!-- 文章标题 -->
+        <meta property="og:description" content="{description}"/>  <!-- 文章描述 -->
+        <meta property="og:url" content="{request.build_absolute_uri()}"/>  <!-- 文章URL -->
+        <meta property="article:published_time" content="{article.pub_time.isoformat()}"/>  <!-- 发布时间 -->
+        <meta property="article:modified_time" content="{article.last_modify_time.isoformat()}"/>  <!-- 修改时间 -->
+        <meta property="article:author" content="{article.author.username}"/>  <!-- 作者 -->
+        <meta property="article:section" content="{article.category.name}"/>  <!-- 分类 -->
         '''
+        # 为每个标签添加Open Graph标签
         for tag in article.tags.all():
             meta_tags += f'<meta property="article:tag" content="{tag.name}"/>'
+        # 添加站点名称
         meta_tags += f'<meta property="og:site_name" content="{blog_setting.site_name}"/>'
 
+        # 生成JSON-LD结构化数据（用于搜索引擎理解内容结构）
         structured_data = {
-            "@context": "https://schema.org",
-            "@type": "Article",
-            "mainEntityOfPage": {"@type": "WebPage", "@id": request.build_absolute_uri()},
-            "headline": article.title,
-            "description": description,
-            "image": request.build_absolute_uri(article.get_first_image_url()),
-            "datePublished": article.pub_time.isoformat(),
-            "dateModified": article.last_modify_time.isoformat(),
-            "author": {"@type": "Person", "name": article.author.username},
-            "publisher": {"@type": "Organization", "name": blog_setting.site_name}
+            "@context": "https://schema.org",  # Schema.org词汇表
+            "@type": "Article",  # 内容类型为文章
+            "mainEntityOfPage": {"@type": "WebPage", "@id": request.build_absolute_uri()},  # 页面主实体
+            "headline": article.title,  # 文章标题
+            "description": description,  # 文章描述
+            "image": request.build_absolute_uri(article.get_first_image_url()),  # 文章首图
+            "datePublished": article.pub_time.isoformat(),  # 发布时间
+            "dateModified": article.last_modify_time.isoformat(),  # 修改时间
+            "author": {"@type": "Person", "name": article.author.username},  # 作者信息
+            "publisher": {"@type": "Organization", "name": blog_setting.site_name}  # 发布者信息
         }
+        # 如果没有图片，移除image字段
         if not structured_data.get("image"):
             del structured_data["image"]
 
+        # 返回完整的文章SEO数据
         return {
-            "title": f"{article.title} | {blog_setting.site_name}",
-            "description": description,
-            "keywords": keywords,
-            "meta_tags": meta_tags,
-            "json_ld": structured_data
+            "title": f"{article.title} | {blog_setting.site_name}",  # 页面标题（文章标题 + 站点名称）
+            "description": description,  # 页面描述
+            "keywords": keywords,  # 页面关键词
+            "meta_tags": meta_tags,  # Meta标签HTML
+            "json_ld": structured_data  # JSON-LD结构化数据
         }
 
     def _get_category_seo_data(self, context, request, blog_setting):
+        """生成分类页面的SEO数据"""
+        # 从上下文中获取分类名称
         category_name = context.get('tag_name')
         if not category_name:
             return None
-        
+
+        # 查询分类对象
         category = Category.objects.filter(name=category_name).first()
         if not category:
             return None
 
+        # 生成分类页面标题、描述和关键词
         title = f"{category.name} | {blog_setting.site_name}"
         description = strip_tags(category.name) or blog_setting.site_description
         keywords = category.name
 
-        # BreadcrumbList structured data for category page
-        breadcrumb_items = [{"@type": "ListItem", "position": 1, "name": "首页", "item": request.build_absolute_uri('/')}]
-        breadcrumb_items.append({"@type": "ListItem", "position": 2, "name": category.name, "item": request.build_absolute_uri()})
-        
+        # 生成面包屑导航的结构化数据
+        breadcrumb_items = [
+            {"@type": "ListItem", "position": 1, "name": "首页", "item": request.build_absolute_uri('/')}]
+        breadcrumb_items.append(
+            {"@type": "ListItem", "position": 2, "name": category.name, "item": request.build_absolute_uri()})
+
+        # 生成面包屑导航的JSON-LD数据
         structured_data = {
             "@context": "https://schema.org",
-            "@type": "BreadcrumbList",
-            "itemListElement": breadcrumb_items
+            "@type": "BreadcrumbList",  # 面包屑列表类型
+            "itemListElement": breadcrumb_items  # 面包屑项目列表
         }
 
         return {
-            "title": title,
-            "description": description,
-            "keywords": keywords,
-            "meta_tags": "",
-            "json_ld": structured_data
+            "title": title,  # 页面标题
+            "description": description,  # 页面描述
+            "keywords": keywords,  # 页面关键词
+            "meta_tags": "",  # 分类页面不需要额外的meta标签
+            "json_ld": structured_data  # 面包屑结构化数据
         }
 
     def _get_default_seo_data(self, context, request, blog_setting):
-        # Homepage and other default pages
+        """生成首页和其他默认页面的SEO数据"""
+        # 生成网站整体的结构化数据
         structured_data = {
             "@context": "https://schema.org",
-            "@type": "WebSite",
-            "name": blog_setting.site_name,
-            "description": blog_setting.site_description,
-            "url": request.build_absolute_uri('/'),
+            "@type": "WebSite",  # 网站类型
+            "name": blog_setting.site_name,  # 网站名称
+            "description": blog_setting.site_description,  # 网站描述
+            "url": request.build_absolute_uri('/'),  # 网站URL
             "potentialAction": {
-                "@type": "SearchAction",
-                "target": f"{request.build_absolute_uri('/search/')}?q={{search_term_string}}",
-                "query-input": "required name=search_term_string"
+                "@type": "SearchAction",  # 搜索动作
+                "target": f"{request.build_absolute_uri('/search/')}?q={{search_term_string}}",  # 搜索目标URL
+                "query-input": "required name=search_term_string"  # 搜索查询输入
             }
         }
         return {
-            "title": f"{blog_setting.site_name} | {blog_setting.site_description}",
-            "description": blog_setting.site_description,
-            "keywords": blog_setting.site_keywords,
-            "meta_tags": "",
-            "json_ld": structured_data
+            "title": f"{blog_setting.site_name} | {blog_setting.site_description}",  # 默认页面标题
+            "description": blog_setting.site_description,  # 默认描述
+            "keywords": blog_setting.site_keywords,  # 默认关键词
+            "meta_tags": "",  # 默认页面不需要额外的meta标签
+            "json_ld": structured_data  # 网站结构化数据
         }
 
     def dispatch_seo_generation(self, metas, context):
+        """分发SEO生成的主方法，根据页面类型调用相应的SEO生成函数"""
+        # 从上下文中获取请求对象
         request = context.get('request')
         if not request:
             return metas
 
+        # 获取当前视图名称
         view_name = request.resolver_match.view_name
+        # 获取博客设置
         blog_setting = get_blog_setting()
-        
+
         seo_data = None
-        if view_name == 'blog:detailbyid':
+        # 根据视图名称选择相应的SEO生成方法
+        if view_name == 'blog:detailbyid':  # 文章详情页
             seo_data = self._get_article_seo_data(context, request, blog_setting)
-        elif view_name == 'blog:category_detail':
+        elif view_name == 'blog:category_detail':  # 分类详情页
             seo_data = self._get_category_seo_data(context, request, blog_setting)
-        
+
+        # 如果没有匹配的页面类型，使用默认SEO数据
         if not seo_data:
-             seo_data = self._get_default_seo_data(context, request, blog_setting)
+            seo_data = self._get_default_seo_data(context, request, blog_setting)
 
+        # 将JSON-LD数据转换为HTML脚本标签
         json_ld_script = f'<script type="application/ld+json">{json.dumps(seo_data.get("json_ld", {}), ensure_ascii=False, indent=4)}</script>'
 
+        # 组合所有SEO标签为HTML字符串
         seo_html = f"""
-        <title>{seo_data.get("title", "")}</title>
-        <meta name="description" content="{seo_data.get("description", "")}">
-        <meta name="keywords" content="{seo_data.get("keywords", "")}">
-        {seo_data.get("meta_tags", "")}
-        {json_ld_script}
+        <title>{seo_data.get("title", "")}</title>  <!-- 页面标题 -->
+        <meta name="description" content="{seo_data.get("description", "")}">  <!-- 页面描述 -->
+        <meta name="keywords" content="{seo_data.get("keywords", "")}">  <!-- 页面关键词 -->
+        {seo_data.get("meta_tags", "")}  <!-- Open Graph等meta标签 -->
+        {json_ld_script}  <!-- JSON-LD结构化数据 -->
         """
-        
+
         # 将SEO内容追加到现有的metas内容上
         return metas + seo_html
 
-plugin = SeoOptimizerPlugin()
+
+# 实例化插件，触发自动注册
+plugin = SeoOptimizerPlugin()

src/DjangoBlog/plugins/view_count/plugin.py

@@ -1,18 +1,35 @@
+# 导入插件管理相关模块
 from djangoblog.plugin_manage.base_plugin import BasePlugin
 from djangoblog.plugin_manage import hooks
 
 
+# 定义文章浏览次数统计插件类
 class ViewCountPlugin(BasePlugin):
-    PLUGIN_NAME = '文章浏览次数统计'
-    PLUGIN_DESCRIPTION = '统计文章的浏览次数'
-    PLUGIN_VERSION = '0.1.0'
-    PLUGIN_AUTHOR = 'liangliangyy'
+    # 插件元数据配置
+    PLUGIN_NAME = '文章浏览次数统计'  # 插件名称
+    PLUGIN_DESCRIPTION = '统计文章的浏览次数'  # 插件功能描述
+    PLUGIN_VERSION = '0.1.0'  # 插件版本号
+    PLUGIN_AUTHOR = 'liangliangyy'  # 插件作者
 
     def register_hooks(self):
+        """注册插件钩子"""
+        # 将浏览统计方法注册到文章内容获取后的钩子
+        # 当文章内容被获取后，自动触发浏览统计
         hooks.register('after_article_body_get', self.record_view)
 
     def record_view(self, article, *args, **kwargs):
+        """
+        记录文章浏览次数的核心方法
+
+        参数:
+            article: 文章对象实例
+            *args: 可变位置参数
+            **kwargs: 可变关键字参数
+        """
+        # 调用文章的viewed()方法来增加浏览次数
+        # 假设Article模型有一个viewed()方法来处理浏览计数逻辑
         article.viewed()
 
 
-plugin = ViewCountPlugin() 
+# 实例化插件，触发自动注册
+plugin = ViewCountPlugin()

src/DjangoBlog/servermanager/MemcacheStorage.py

@@ -1,32 +1,41 @@
+# 导入WeRoBot会话存储基类和工具函数
 from werobot.session import SessionStorage
 from werobot.utils import json_loads, json_dumps
 
+# 导入Django博客的缓存工具
 from djangoblog.utils import cache
 
 
+# 定义基于Memcache的会话存储类，继承自WeRoBot的SessionStorage
 class MemcacheStorage(SessionStorage):
     def __init__(self, prefix='ws_'):
-        self.prefix = prefix
-        self.cache = cache
+        # 初始化存储配置
+        self.prefix = prefix  # 缓存键前缀，用于区分不同的会话数据
+        self.cache = cache    # Django缓存实例
 
     @property
     def is_available(self):
-        value = "1"
-        self.set('checkavaliable', value=value)
-        return value == self.get('checkavaliable')
+        """检查缓存存储是否可用"""
+        value = "1"  # 测试值
+        self.set('checkavaliable', value=value)  # 设置测试值到缓存
+        return value == self.get('checkavaliable')  # 检查是否能正确读取设置的值
 
     def key_name(self, s):
-        return '{prefix}{s}'.format(prefix=self.prefix, s=s)
+        """生成完整的缓存键名"""
+        return '{prefix}{s}'.format(prefix=self.prefix, s=s)  # 组合前缀和会话ID
 
     def get(self, id):
-        id = self.key_name(id)
-        session_json = self.cache.get(id) or '{}'
-        return json_loads(session_json)
+        """根据会话ID获取会话数据"""
+        id = self.key_name(id)  # 生成完整键名
+        session_json = self.cache.get(id) or '{}'  # 从缓存获取数据，默认为空JSON对象
+        return json_loads(session_json)  # 将JSON字符串解析为Python字典
 
     def set(self, id, value):
-        id = self.key_name(id)
-        self.cache.set(id, json_dumps(value))
+        """设置会话数据"""
+        id = self.key_name(id)  # 生成完整键名
+        self.cache.set(id, json_dumps(value))  # 将值转换为JSON字符串后存入缓存
 
     def delete(self, id):
-        id = self.key_name(id)
-        self.cache.delete(id)
+        """删除会话数据"""
+        id = self.key_name(id)  # 生成完整键名
+        self.cache.delete(id)  # 从缓存中删除指定键的数据

src/DjangoBlog/servermanager/admin.py

@@ -1,19 +1,32 @@
+# 导入Django管理模块
 from django.contrib import admin
-# Register your models here.
 
 
+# 在这里注册模型到管理后台
+
+
+# 定义Commands模型的管理类
 class CommandsAdmin(admin.ModelAdmin):
-    list_display = ('title', 'command', 'describe')
+    # 设置在管理后台列表页面显示的字段
+    list_display = ('title', 'command', 'describe')  # 显示命令标题、命令内容和描述
 
 
+# 定义EmailSendLog模型的管理类
 class EmailSendLogAdmin(admin.ModelAdmin):
-    list_display = ('title', 'emailto', 'send_result', 'creation_time')
+    # 设置在管理后台列表页面显示的字段
+    list_display = ('title', 'emailto', 'send_result', 'creation_time')  # 显示邮件标题、收件人、发送结果和创建时间
+
+    # 设置只读字段（在编辑页面这些字段不可修改）
     readonly_fields = (
-        'title',
-        'emailto',
-        'send_result',
-        'creation_time',
-        'content')
+        'title',  # 邮件标题只读
+        'emailto',  # 收件人只读
+        'send_result',  # 发送结果只读
+        'creation_time',  # 创建时间只读
+        'content')  # 邮件内容只读
 
     def has_add_permission(self, request):
-        return False
+        """
+        重写添加权限方法，禁止在管理后台手动添加邮件发送日志
+        邮件发送日志应该只能通过系统自动创建
+        """
+        return False  # 返回False表示禁止添加新记录

src/DjangoBlog/servermanager/api/blogapi.py

@@ -1,27 +1,44 @@
+# 导入Haystack搜索查询集
 from haystack.query import SearchQuerySet
 
+# 导入博客模型
 from blog.models import Article, Category
 
 
+# 定义博客API类，提供博客数据的各种查询方法
 class BlogApi:
     def __init__(self):
+        # 初始化搜索查询集
         self.searchqueryset = SearchQuerySet()
+        # 执行空查询来初始化查询集
         self.searchqueryset.auto_query('')
+        # 设置最大返回结果数量限制
         self.__max_takecount__ = 8
 
     def search_articles(self, query):
+        """根据查询词搜索文章"""
+        # 使用Haystack的自动查询功能进行搜索
         sqs = self.searchqueryset.auto_query(query)
+        # 加载所有相关对象（避免N+1查询问题）
         sqs = sqs.load_all()
+        # 返回前N个搜索结果（N为最大限制数）
         return sqs[:self.__max_takecount__]
 
     def get_category_lists(self):
+        """获取所有分类列表"""
+        # 返回所有分类对象
         return Category.objects.all()
 
     def get_category_articles(self, categoryname):
+        """根据分类名称获取该分类下的文章"""
+        # 通过分类名称过滤文章
         articles = Article.objects.filter(category__name=categoryname)
+        # 如果找到文章，返回前N篇；否则返回None
         if articles:
             return articles[:self.__max_takecount__]
         return None
 
     def get_recent_articles(self):
-        return Article.objects.all()[:self.__max_takecount__]
+        """获取最近的文章（按时间倒序）"""
+        # 获取所有文章并按时间倒序排列，返回前N篇
+        return Article.objects.all()[:self.__max_takecount__]

src/DjangoBlog/servermanager/api/commonapi.py

@@ -1,64 +1,110 @@
+# 导入日志和操作系统模块
 import logging
 import os
 
+# 导入OpenAI库
 import openai
 
+# 导入自定义命令模型
 from servermanager.models import commands
 
+# 获取日志记录器
 logger = logging.getLogger(__name__)
 
+# 配置OpenAI API密钥（从环境变量获取）
 openai.api_key = os.environ.get('OPENAI_API_KEY')
+# 配置代理（如果环境变量中存在HTTP代理）
 if os.environ.get('HTTP_PROXY'):
     openai.proxy = os.environ.get('HTTP_PROXY')
 
 
+# 定义ChatGPT交互类
 class ChatGPT:
 
     @staticmethod
     def chat(prompt):
+        """
+        与ChatGPT进行对话的静态方法
+
+        参数:
+            prompt: 用户输入的提示词
+
+        返回:
+            ChatGPT的回复内容或错误信息
+        """
         try:
-            completion = openai.ChatCompletion.create(model="gpt-3.5-turbo",
-                                                      messages=[{"role": "user", "content": prompt}])
+            # 调用OpenAI API创建聊天完成
+            completion = openai.ChatCompletion.create(model="gpt-3.5-turbo",  # 指定使用gpt-3.5-turbo模型
+                                                      messages=[{"role": "user", "content": prompt}])  # 设置用户消息
+            # 返回模型生成的内容
             return completion.choices[0].message.content
         except Exception as e:
+            # 记录错误日志
             logger.error(e)
+            # 返回用户友好的错误信息
             return "服务器出错了"
 
 
+# 定义命令处理器类
 class CommandHandler:
     def __init__(self):
+        # 初始化时从数据库获取所有命令
         self.commands = commands.objects.all()
 
     def run(self, title):
         """
         运行命令
-        :param title: 命令
-        :return: 返回命令执行结果
+
+        参数:
+            title: 命令标题
+
+        返回:
+            命令执行结果或错误信息
         """
+        # 过滤匹配标题的命令（不区分大小写）
         cmd = list(
             filter(
-                lambda x: x.title.upper() == title.upper(),
+                lambda x: x.title.upper() == title.upper(),  # 转换为大写进行比较
                 self.commands))
         if cmd:
+            # 如果找到命令，执行对应的命令字符串
             return self.__run_command__(cmd[0].command)
         else:
+            # 未找到命令时返回帮助提示
             return "未找到相关命令，请输入hepme获得帮助。"
 
     def __run_command__(self, cmd):
+        """
+        内部方法：执行系统命令
+
+        参数:
+            cmd: 要执行的命令字符串
+
+        返回:
+            命令执行结果或错误信息
+        """
         try:
+            # 使用os.popen执行系统命令并读取结果
             res = os.popen(cmd).read()
             return res
         except BaseException:
+            # 捕获所有异常，返回错误信息
             return '命令执行出错!'
 
     def get_help(self):
+        """获取所有命令的帮助信息"""
         rsp = ''
+        # 遍历所有命令，格式化输出命令标题和描述
         for cmd in self.commands:
             rsp += '{c}:{d}\n'.format(c=cmd.title, d=cmd.describe)
         return rsp
 
 
+# 主程序入口（用于测试）
 if __name__ == '__main__':
+    # 创建ChatGPT实例
     chatbot = ChatGPT()
+    # 测试提示词
     prompt = "写一篇1000字关于AI的论文"
-    print(chatbot.chat(prompt))
+    # 打印ChatGPT的回复
+    print(chatbot.chat(prompt))

src/DjangoBlog/servermanager/apps.py

@@ -1,5 +1,17 @@
+# 导入Django应用配置基类
 from django.apps import AppConfig
 
 
+# 定义Servermanager应用的配置类
 class ServermanagerConfig(AppConfig):
+    # 指定应用的Python路径（Django 3.x及以下版本必需）
+    # 这应该与settings.INSTALLED_APPS中使用的路径匹配
     name = 'servermanager'
+
+    # 在Django 3.2及以上版本中，可以添加default_auto_field配置
+    # default_auto_field = 'django.db.models.BigAutoField'
+
+    # 可以在此添加应用启动时的初始化代码
+    # def ready(self):
+    #     # 导入信号处理器等
+    #     import servermanager.signals

src/DjangoBlog/servermanager/migrations/0001_initial.py

@@ -1,45 +1,61 @@
-# Generated by Django 4.1.7 on 2023-03-02 07:14
+# Django 数据库迁移文件
+# 由 Django 4.1.7 于 2023-03-02 07:14 生成
 
 from django.db import migrations, models
 
 
 class Migration(migrations.Migration):
 
-    initial = True
+    initial = True  # 标记为初始迁移
 
     dependencies = [
+        # 初始迁移没有依赖项
     ]
 
     operations = [
+        # 创建 commands 表（命令表）
         migrations.CreateModel(
             name='commands',
             fields=[
+                # 主键字段，使用BigAutoField（64位自增ID）
                 ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                # 命令标题字段，最大长度300字符
                 ('title', models.CharField(max_length=300, verbose_name='命令标题')),
+                # 命令字段，存储实际执行的命令，最大长度2000字符
                 ('command', models.CharField(max_length=2000, verbose_name='命令')),
+                # 命令描述字段，最大长度300字符
                 ('describe', models.CharField(max_length=300, verbose_name='命令描述')),
+                # 创建时间字段，自动设置为对象创建时间
                 ('created_time', models.DateTimeField(auto_now_add=True, verbose_name='创建时间')),
+                # 最后修改时间字段，自动设置为对象最后修改时间
                 ('last_mod_time', models.DateTimeField(auto_now=True, verbose_name='修改时间')),
             ],
             options={
-                'verbose_name': '命令',
-                'verbose_name_plural': '命令',
+                'verbose_name': '命令',  # 单数显示名称
+                'verbose_name_plural': '命令',  # 复数显示名称（中文中单复数相同）
             },
         ),
+        # 创建 EmailSendLog 表（邮件发送日志表）
         migrations.CreateModel(
             name='EmailSendLog',
             fields=[
+                # 主键字段
                 ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                # 收件人字段，存储收件人邮箱地址，最大长度300字符
                 ('emailto', models.CharField(max_length=300, verbose_name='收件人')),
+                # 邮件标题字段，最大长度2000字符
                 ('title', models.CharField(max_length=2000, verbose_name='邮件标题')),
+                # 邮件内容字段，使用TextField支持长文本
                 ('content', models.TextField(verbose_name='邮件内容')),
+                # 发送结果字段，布尔值，默认False（发送失败）
                 ('send_result', models.BooleanField(default=False, verbose_name='结果')),
+                # 创建时间字段，自动设置为日志记录创建时间
                 ('created_time', models.DateTimeField(auto_now_add=True, verbose_name='创建时间')),
             ],
             options={
-                'verbose_name': '邮件发送log',
-                'verbose_name_plural': '邮件发送log',
-                'ordering': ['-created_time'],
+                'verbose_name': '邮件发送log',  # 单数显示名称
+                'verbose_name_plural': '邮件发送log',  # 复数显示名称
+                'ordering': ['-created_time'],  # 按创建时间降序排列（最新的在前）
             },
         ),
-    ]
+    ]

src/DjangoBlog/servermanager/migrations/0002_alter_emailsendlog_options_and_more.py

@@ -1,32 +1,43 @@
-# Generated by Django 4.2.5 on 2023-09-06 13:19
+# Django 数据库迁移文件
+# 由 Django 4.2.5 于 2023-09-06 13:19 生成
 
 from django.db import migrations
 
 
 class Migration(migrations.Migration):
 
+    # 定义迁移依赖关系，依赖于初始迁移文件
     dependencies = [
-        ('servermanager', '0001_initial'),
+        ('servermanager', '0001_initial'),  # 依赖于 servermanager 应用的初始迁移
     ]
 
+    # 定义迁移操作序列
     operations = [
+        # 修改 EmailSendLog 模型的选项配置
         migrations.AlterModelOptions(
-            name='emailsendlog',
-            options={'ordering': ['-creation_time'], 'verbose_name': '邮件发送log', 'verbose_name_plural': '邮件发送log'},
+            name='emailsendlog',  # 指定要修改的模型名称
+            options={
+                'ordering': ['-creation_time'],  # 按创建时间降序排列（最新的在前）
+                'verbose_name': '邮件发送log',  # 单数显示名称
+                'verbose_name_plural': '邮件发送log',  # 复数显示名称
+            },
         ),
+        # 重命名 commands 模型的 created_time 字段为 creation_time
         migrations.RenameField(
-            model_name='commands',
-            old_name='created_time',
-            new_name='creation_time',
+            model_name='commands',  # 指定模型名称
+            old_name='created_time',  # 原字段名称
+            new_name='creation_time',  # 新字段名称
         ),
+        # 重命名 commands 模型的 last_mod_time 字段为 last_modify_time
         migrations.RenameField(
-            model_name='commands',
-            old_name='last_mod_time',
-            new_name='last_modify_time',
+            model_name='commands',  # 指定模型名称
+            old_name='last_mod_time',  # 原字段名称
+            new_name='last_modify_time',  # 新字段名称
         ),
+        # 重命名 EmailSendLog 模型的 created_time 字段为 creation_time
         migrations.RenameField(
-            model_name='emailsendlog',
-            old_name='created_time',
-            new_name='creation_time',
+            model_name='emailsendlog',  # 指定模型名称
+            old_name='created_time',  # 原字段名称
+            new_name='creation_time',  # 新字段名称
         ),
-    ]
+    ]

src/DjangoBlog/servermanager/models.py

@@ -1,33 +1,51 @@
+# 导入Django模型模块
 from django.db import models
 
 
-# Create your models here.
+# 在这里创建模型
+
+# 定义命令模型，用于存储系统命令信息
 class commands(models.Model):
+    # 命令标题字段，字符类型，最大长度300，用于显示命令名称
     title = models.CharField('命令标题', max_length=300)
+    # 命令字段，字符类型，最大长度2000，存储实际要执行的命令
     command = models.CharField('命令', max_length=2000)
+    # 命令描述字段，字符类型，最大长度300，说明命令的用途
     describe = models.CharField('命令描述', max_length=300)
+    # 创建时间字段，自动设置为对象创建时的时间
     creation_time = models.DateTimeField('创建时间', auto_now_add=True)
+    # 最后修改时间字段，自动更新为对象最后修改的时间
     last_modify_time = models.DateTimeField('修改时间', auto_now=True)
 
     def __str__(self):
+        # 定义对象的字符串表示，返回命令标题
         return self.title
 
     class Meta:
-        verbose_name = '命令'
-        verbose_name_plural = verbose_name
+        # 在Django管理后台显示的名称配置
+        verbose_name = '命令'  # 单数名称
+        verbose_name_plural = verbose_name  # 复数名称（与单数相同）
 
 
+# 定义邮件发送日志模型，用于记录邮件发送历史
 class EmailSendLog(models.Model):
+    # 收件人字段，字符类型，最大长度300，存储收件人邮箱地址
     emailto = models.CharField('收件人', max_length=300)
+    # 邮件标题字段，字符类型，最大长度2000
     title = models.CharField('邮件标题', max_length=2000)
+    # 邮件内容字段，文本类型，支持长文本内容
     content = models.TextField('邮件内容')
+    # 发送结果字段，布尔类型，默认False，表示发送成功或失败
     send_result = models.BooleanField('结果', default=False)
+    # 创建时间字段，自动设置为日志记录创建时的时间
     creation_time = models.DateTimeField('创建时间', auto_now_add=True)
 
     def __str__(self):
+        # 定义对象的字符串表示，返回邮件标题
         return self.title
 
     class Meta:
-        verbose_name = '邮件发送log'
-        verbose_name_plural = verbose_name
-        ordering = ['-creation_time']
+        # 在Django管理后台显示的名称配置和排序设置
+        verbose_name = '邮件发送log'  # 单数名称
+        verbose_name_plural = verbose_name  # 复数名称（与单数相同）
+        ordering = ['-creation_time']  # 按创建时间降序排列（最新的记录显示在最前面）

src/DjangoBlog/servermanager/robot.py

@@ -1,83 +1,100 @@
+# 导入必要的模块
 import logging
 import os
 import re
 
+# 导入JSON序列化工具
 import jsonpickle
+# 导入Django配置
 from django.conf import settings
+# 导入微信机器人框架
 from werobot import WeRoBot
 from werobot.replies import ArticlesReply, Article
 from werobot.session.filestorage import FileStorage
 
+# 导入自定义工具函数和API
 from djangoblog.utils import get_sha256
 from servermanager.api.blogapi import BlogApi
 from servermanager.api.commonapi import ChatGPT, CommandHandler
 from .MemcacheStorage import MemcacheStorage
 
+# 初始化微信机器人，设置token和启用会话
 robot = WeRoBot(token=os.environ.get('DJANGO_WEROBOT_TOKEN')
                       or 'lylinux', enable_session=True)
+# 创建Memcache存储实例
 memstorage = MemcacheStorage()
+# 检查Memcache是否可用，选择会话存储方式
 if memstorage.is_available:
-    robot.config['SESSION_STORAGE'] = memstorage
+    robot.config['SESSION_STORAGE'] = memstorage  # 使用Memcache存储会话
 else:
+    # 如果Memcache不可用，使用文件存储，并清理旧的会话文件
     if os.path.exists(os.path.join(settings.BASE_DIR, 'werobot_session')):
         os.remove(os.path.join(settings.BASE_DIR, 'werobot_session'))
     robot.config['SESSION_STORAGE'] = FileStorage(filename='werobot_session')
 
+# 初始化API处理器
 blogapi = BlogApi()
 cmd_handler = CommandHandler()
 logger = logging.getLogger(__name__)
 
 
 def convert_to_article_reply(articles, message):
-    reply = ArticlesReply(message=message)
-    from blog.templatetags.blog_tags import truncatechars_content
+    """将文章列表转换为微信图文回复格式"""
+    reply = ArticlesReply(message=message)  # 创建图文回复对象
+    from blog.templatetags.blog_tags import truncatechars_content  # 导入内容截取过滤器
     for post in articles:
+        # 从文章内容中提取第一张图片URL
         imgs = re.findall(r'(?:http\:|https\:)?\/\/.*\.(?:png|jpg)', post.body)
         imgurl = ''
         if imgs:
-            imgurl = imgs[0]
+            imgurl = imgs[0]  # 使用第一张图片作为封面
+        # 创建图文消息条目
         article = Article(
-            title=post.title,
-            description=truncatechars_content(post.body),
-            img=imgurl,
-            url=post.get_full_url()
+            title=post.title,  # 文章标题
+            description=truncatechars_content(post.body),  # 文章摘要
+            img=imgurl,  # 封面图片
+            url=post.get_full_url()  # 文章链接
         )
-        reply.add_article(article)
+        reply.add_article(article)  # 添加到回复中
     return reply
 
 
 @robot.filter(re.compile(r"^\?.*"))
 def search(message, session):
+    """处理搜索命令，格式：?关键词"""
     s = message.content
-    searchstr = str(s).replace('?', '')
-    result = blogapi.search_articles(searchstr)
+    searchstr = str(s).replace('?', '')  # 移除问号获取搜索关键词
+    result = blogapi.search_articles(searchstr)  # 搜索文章
     if result:
-        articles = list(map(lambda x: x.object, result))
-        reply = convert_to_article_reply(articles, message)
+        articles = list(map(lambda x: x.object, result))  # 提取文章对象
+        reply = convert_to_article_reply(articles, message)  # 转换为图文回复
         return reply
     else:
-        return '没有找到相关文章。'
+        return '没有找到相关文章。'  # 无结果提示
 
 
 @robot.filter(re.compile(r'^category\s*$', re.I))
 def category(message, session):
-    categorys = blogapi.get_category_lists()
-    content = ','.join(map(lambda x: x.name, categorys))
-    return '所有文章分类目录：' + content
+    """处理分类列表命令"""
+    categorys = blogapi.get_category_lists()  # 获取所有分类
+    content = ','.join(map(lambda x: x.name, categorys))  # 拼接分类名称
+    return '所有文章分类目录：' + content  # 返回分类列表
 
 
 @robot.filter(re.compile(r'^recent\s*$', re.I))
 def recents(message, session):
-    articles = blogapi.get_recent_articles()
+    """处理最近文章命令"""
+    articles = blogapi.get_recent_articles()  # 获取最新文章
     if articles:
-        reply = convert_to_article_reply(articles, message)
+        reply = convert_to_article_reply(articles, message)  # 转换为图文回复
         return reply
     else:
-        return "暂时还没有文章"
+        return "暂时还没有文章"  # 无文章提示
 
 
 @robot.filter(re.compile('^help$', re.I))
 def help(message, session):
+    """处理帮助命令，返回使用说明"""
     return '''欢迎关注!
             默认会与图灵机器人聊天~~
         你可以通过下面这些命令来获得信息
@@ -95,93 +112,119 @@ def help(message, session):
         music:音乐搜索
         如music:阴天快乐
         PS:以上标点符号都不支持中文标点~~
-        '''
+        '''  # 详细的帮助信息
 
 
 @robot.filter(re.compile(r'^weather\:.*$', re.I))
 def weather(message, session):
-    return "建设中..."
+    """处理天气查询命令（建设中）"""
+    return "建设中..."  # 功能未完成提示
 
 
 @robot.filter(re.compile(r'^idcard\:.*$', re.I))
 def idcard(message, session):
-    return "建设中..."
+    """处理身份证查询命令（建设中）"""
+    return "建设中..."  # 功能未完成提示
 
 
 @robot.handler
 def echo(message, session):
-    handler = MessageHandler(message, session)
-    return handler.handler()
+    """默认消息处理器"""
+    handler = MessageHandler(message, session)  # 创建消息处理器
+    return handler.handler()  # 处理消息
 
 
 class MessageHandler:
+    """消息处理核心类"""
+
     def __init__(self, message, session):
-        userid = message.source
+        userid = message.source  # 获取用户ID
         self.message = message
         self.session = session
         self.userid = userid
         try:
+            # 从会话中获取用户信息
             info = session[userid]
-            self.userinfo = jsonpickle.decode(info)
+            self.userinfo = jsonpickle.decode(info)  # 反序列化用户信息
         except Exception as e:
+            # 如果会话中没有用户信息，创建新的用户信息
             userinfo = WxUserInfo()
             self.userinfo = userinfo
 
     @property
     def is_admin(self):
+        """检查用户是否为管理员"""
         return self.userinfo.isAdmin
 
     @property
     def is_password_set(self):
+        """检查管理员密码是否已设置"""
         return self.userinfo.isPasswordSet
 
     def save_session(self):
-        info = jsonpickle.encode(self.userinfo)
+        """保存用户信息到会话"""
+        info = jsonpickle.encode(self.userinfo)  # 序列化用户信息
         self.session[self.userid] = info
 
     def handler(self):
-        info = self.message.content
+        """消息处理主逻辑"""
+        info = self.message.content  # 获取消息内容
 
+        # 管理员退出命令
         if self.userinfo.isAdmin and info.upper() == 'EXIT':
-            self.userinfo = WxUserInfo()
+            self.userinfo = WxUserInfo()  # 重置用户信息
             self.save_session()
             return "退出成功"
+
+        # 进入管理员模式命令
         if info.upper() == 'ADMIN':
             self.userinfo.isAdmin = True
             self.save_session()
             return "输入管理员密码"
+
+        # 管理员密码验证流程
         if self.userinfo.isAdmin and not self.userinfo.isPasswordSet:
-            passwd = settings.WXADMIN
-            if settings.TESTING:
+            passwd = settings.WXADMIN  # 从配置获取管理员密码
+            if settings.TESTING:  # 测试环境下使用简单密码
                 passwd = '123'
+            # 验证密码（双重SHA256加密）
             if passwd.upper() == get_sha256(get_sha256(info)).upper():
                 self.userinfo.isPasswordSet = True
                 self.save_session()
                 return "验证通过,请输入命令或者要执行的命令代码:输入helpme获得帮助"
             else:
-                if self.userinfo.Count >= 3:
-                    self.userinfo = WxUserInfo()
+                # 密码错误处理
+                if self.userinfo.Count >= 3:  # 超过最大尝试次数
+                    self.userinfo = WxUserInfo()  # 重置用户信息
                     self.save_session()
                     return "超过验证次数"
-                self.userinfo.Count += 1
+                self.userinfo.Count += 1  # 增加尝试次数
                 self.save_session()
                 return "验证失败，请重新输入管理员密码:"
+
+        # 管理员命令执行流程
         if self.userinfo.isAdmin and self.userinfo.isPasswordSet:
+            # 确认执行命令
             if self.userinfo.Command != '' and info.upper() == 'Y':
-                return cmd_handler.run(self.userinfo.Command)
+                return cmd_handler.run(self.userinfo.Command)  # 执行命令
             else:
+                # 获取命令帮助
                 if info.upper() == 'HELPME':
                     return cmd_handler.get_help()
+                # 保存命令等待确认
                 self.userinfo.Command = info
                 self.save_session()
                 return "确认执行: " + info + " 命令?"
 
+        # 默认使用ChatGPT回复
         return ChatGPT.chat(info)
 
 
 class WxUserInfo():
+    """微信用户信息类"""
+
     def __init__(self):
-        self.isAdmin = False
-        self.isPasswordSet = False
-        self.Count = 0
-        self.Command = ''
+        self.isAdmin = False  # 是否为管理员
+        self.isPasswordSet = False  # 密码是否已验证
+        self.Count = 0  # 密码尝试次数
+        self.Command = ''  # 待执行的命令

src/DjangoBlog/servermanager/tests.py

@@ -1,79 +1,101 @@
+# 导入Django测试相关模块
 from django.test import Client, RequestFactory, TestCase
 from django.utils import timezone
+# 导入WeRoBot文本消息类
 from werobot.messages.messages import TextMessage
 
+# 导入用户模型和博客模型
 from accounts.models import BlogUser
 from blog.models import Category, Article
+# 导入ChatGPT API和命令模型
 from servermanager.api.commonapi import ChatGPT
 from .models import commands
+# 导入机器人处理相关类
 from .robot import MessageHandler, CommandHandler
 from .robot import search, category, recents
 
 
-# Create your tests here.
+# 在这里创建测试
+
+# 定义服务器管理功能测试类
 class ServerManagerTest(TestCase):
     def setUp(self):
+        # 初始化测试客户端和请求工厂
         self.client = Client()
         self.factory = RequestFactory()
 
     def test_chat_gpt(self):
-        content = ChatGPT.chat("你好")
-        self.assertIsNotNone(content)
+        """测试ChatGPT功能是否正常工作"""
+        content = ChatGPT.chat("你好")  # 发送简单问候测试ChatGPT
+        self.assertIsNotNone(content)  # 验证返回内容不为空
 
     def test_validate_comment(self):
+        """综合测试评论验证及相关功能"""
+        # 创建超级用户用于测试
         user = BlogUser.objects.create_superuser(
-            email="liangliangyy1@gmail.com",
-            username="liangliangyy1",
-            password="liangliangyy1")
+            email="liangliangyy1@gmail.com",  # 测试邮箱
+            username="liangliangyy1",  # 测试用户名
+            password="liangliangyy1")  # 测试密码
 
+        # 登录测试用户
         self.client.login(username='liangliangyy1', password='liangliangyy1')
 
+        # 创建测试分类
         c = Category()
-        c.name = "categoryccc"
+        c.name = "categoryccc"  # 分类名称
         c.save()
 
+        # 创建测试文章
         article = Article()
-        article.title = "nicetitleccc"
-        article.body = "nicecontentccc"
-        article.author = user
-        article.category = c
-        article.type = 'a'
-        article.status = 'p'
+        article.title = "nicetitleccc"  # 文章标题
+        article.body = "nicecontentccc"  # 文章内容
+        article.author = user  # 设置作者
+        article.category = c  # 设置分类
+        article.type = 'a'  # 文章类型
+        article.status = 'p'  # 发布状态
         article.save()
-        s = TextMessage([])
-        s.content = "nice"
-        rsp = search(s, None)
-        rsp = category(None, None)
-        self.assertIsNotNone(rsp)
-        rsp = recents(None, None)
-        self.assertTrue(rsp != '暂时还没有文章')
 
+        # 创建文本消息对象用于测试机器人功能
+        s = TextMessage([])  # 创建空的文本消息
+        s.content = "nice"  # 设置消息内容
+        rsp = search(s, None)  # 测试搜索功能
+        rsp = category(None, None)  # 测试分类列表功能
+        self.assertIsNotNone(rsp)  # 验证分类列表返回不为空
+        rsp = recents(None, None)  # 测试最近文章功能
+        self.assertTrue(rsp != '暂时还没有文章')  # 验证有文章返回
+
+        # 创建测试命令
         cmd = commands()
-        cmd.title = "test"
-        cmd.command = "ls"
-        cmd.describe = "test"
+        cmd.title = "test"  # 命令标题
+        cmd.command = "ls"  # 执行的命令（列出文件）
+        cmd.describe = "test"  # 命令描述
         cmd.save()
 
+        # 测试命令处理器
         cmdhandler = CommandHandler()
-        rsp = cmdhandler.run('test')
-        self.assertIsNotNone(rsp)
-        s.source = 'u'
-        s.content = 'test'
-        msghandler = MessageHandler(s, {})
+        rsp = cmdhandler.run('test')  # 执行测试命令
+        self.assertIsNotNone(rsp)  # 验证命令执行结果不为空
+
+        # 测试消息处理器
+        s.source = 'u'  # 设置消息来源
+        s.content = 'test'  # 设置消息内容
+        msghandler = MessageHandler(s, {})  # 创建消息处理器
 
+        # 注释掉的管理员相关测试代码
         # msghandler.userinfo.isPasswordSet = True
         # msghandler.userinfo.isAdmin = True
-        msghandler.handler()
-        s.content = 'y'
-        msghandler.handler()
-        s.content = 'idcard:12321233'
-        msghandler.handler()
-        s.content = 'weather:上海'
-        msghandler.handler()
-        s.content = 'admin'
-        msghandler.handler()
-        s.content = '123'
-        msghandler.handler()
-
-        s.content = 'exit'
-        msghandler.handler()
+
+        msghandler.handler()  # 处理消息
+        s.content = 'y'  # 设置确认执行命令
+        msghandler.handler()  # 处理确认消息
+        s.content = 'idcard:12321233'  # 测试身份证查询功能
+        msghandler.handler()  # 处理身份证查询
+        s.content = 'weather:上海'  # 测试天气查询功能
+        msghandler.handler()  # 处理天气查询
+        s.content = 'admin'  # 测试进入管理员模式
+        msghandler.handler()  # 处理管理员命令
+        s.content = '123'  # 测试密码输入
+        msghandler.handler()  # 处理密码验证
+
+        s.content = 'exit'  # 测试退出管理员模式
+        msghandler.handler()  # 处理退出命令

src/DjangoBlog/servermanager/urls.py

@@ -1,10 +1,17 @@
+# 导入Django URL配置模块
 from django.urls import path
+# 导入WeRoBot的Django视图适配器
 from werobot.contrib.django import make_view
 
+# 导入自定义的微信机器人实例
 from .robot import robot
 
+# 定义应用命名空间，用于URL反向解析
 app_name = "servermanager"
-urlpatterns = [
-    path(r'robot', make_view(robot)),
 
-]
+# 定义URL模式列表
+urlpatterns = [
+    # 微信机器人消息处理接口
+    # 该路径用于接收微信服务器发送的消息和事件
+    path(r'robot', make_view(robot)),  # 将WeRoBot实例转换为Django视图
+]

src/DjangoBlog/setup_pet_blog.py

@@ -1,80 +1,89 @@
-# setup_pet_blog.py
+# 宠物博客主题设置脚本
 import os
 import django
 
+# 设置Django环境变量
 os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'djangoblog.settings')
+# 初始化Django配置
 django.setup()
 
+# 导入博客模型和用户模型
 from blog.models import Article, Category, Tag
 from accounts.models import BlogUser
 
 print("=== 设置宠物博客主题 ===")
 
-# 1. 清理旧数据
+# 1. 清理旧数据（清空现有文章、分类和标签）
 print("清理旧数据...")
-Article.objects.all().delete()
-Category.objects.all().delete()
-Tag.objects.all().delete()
+Article.objects.all().delete()  # 删除所有文章
+Category.objects.all().delete()  # 删除所有分类
+Tag.objects.all().delete()  # 删除所有标签
 
-# 2. 创建分类
+# 2. 创建宠物博客相关的分类
 print("创建分类...")
-categories = ['狗狗日常', '猫咪生活', '宠物健康', '训练技巧', '宠物用品']
+categories = ['狗狗日常', '猫咪生活', '宠物健康', '训练技巧', '宠物用品']  # 定义宠物博客分类
 for cat in categories:
-    Category.objects.get_or_create(name=cat)
-    print(f'创建分类: {cat}')
+    Category.objects.get_or_create(name=cat)  # 创建分类（如果不存在）
+    print(f'创建分类: {cat}')  # 输出创建信息
 
-# 3. 创建标签
+# 3. 创建宠物博客相关的标签
 print("创建标签...")
-tags = ['图文', '狗狗社交', '遛狗', '宠物医疗', '宠物食品', '训练方法', '宠物美容', '宠物玩具']
+tags = ['图文', '狗狗社交', '遛狗', '宠物医疗', '宠物食品', '训练方法', '宠物美容', '宠物玩具']  # 定义宠物博客标签
 for tag in tags:
-    Tag.objects.get_or_create(name=tag)
-    print(f'创建标签: {tag}')
+    Tag.objects.get_or_create(name=tag)  # 创建标签（如果不存在）
+    print(f'创建标签: {tag}')  # 输出创建信息
 
-# 4. 创建文章
+# 4. 创建示例文章
 print("创建文章...")
 try:
-    user = BlogUser.objects.first()
+    # 获取或创建博客用户
+    user = BlogUser.objects.first()  # 获取第一个用户
     if not user:
+        # 如果没有用户，创建默认宠物博主用户
         user = BlogUser.objects.create(username='pet_owner', email='pet@example.com')
-        user.set_password('123456')
+        user.set_password('123456')  # 设置密码
         user.save()
 
+    # 定义示例文章数据
     articles_data = [
         {
             'title': '我家狗狗的表演',
             'body': '欲擒故纵，你们见过吗。就是要出去的时候，故意离你远远的，让人你没法给它套上项圈，其实它很想出去。',
-            'category': '狗狗日常',
-            'tags': ['图文', '狗狗社交', '遛狗']
+            'category': '狗狗日常',  # 归属狗狗日常分类
+            'tags': ['图文', '狗狗社交', '遛狗']  # 关联标签
         },
         {
             'title': '猫咪的日常护理',
             'body': '定期为猫咪梳理毛发，保持清洁，注意观察猫咪的健康状况。',
-            'category': '猫咪生活',
-            'tags': ['宠物美容', '宠物健康']
+            'category': '猫咪生活',  # 归属猫咪生活分类
+            'tags': ['宠物美容', '宠物健康']  # 关联标签
         },
         {
             'title': '如何训练狗狗坐下',
             'body': '使用零食诱导，当狗狗完成动作时及时奖励，重复训练。',
-            'category': '训练技巧',
-            'tags': ['训练方法', '图文']
+            'category': '训练技巧',  # 归属训练技巧分类
+            'tags': ['训练方法', '图文']  # 关联标签
         }
     ]
 
+    # 遍历文章数据并创建文章
     for data in articles_data:
-        category = Category.objects.get(name=data['category'])
+        category = Category.objects.get(name=data['category'])  # 获取分类对象
         article = Article.objects.create(
-            title=data['title'],
-            body=data['body'],
-            author=user,
-            category=category,
-            status='p'
+            title=data['title'],  # 文章标题
+            body=data['body'],  # 文章内容
+            author=user,  # 文章作者
+            category=category,  # 文章分类
+            status='p'  # 发布状态（p表示已发布）
         )
+        # 为文章添加标签
         for tag_name in data['tags']:
-            tag, _ = Tag.objects.get_or_create(name=tag_name)
-            article.tags.add(tag)
-        print(f'创建文章: {data["title"]}')
+            tag, _ = Tag.objects.get_or_create(name=tag_name)  # 获取或创建标签
+            article.tags.add(tag)  # 关联标签到文章
+        print(f'创建文章: {data["title"]}')  # 输出创建信息
 
 except Exception as e:
+    # 处理创建文章过程中的异常
     print(f'创建文章时出错: {e}')
 
-print("=== 宠物博客主题设置完成 ===")
+print("=== 宠物博客主题设置完成 ===")  # 完成提示