本教程旨在解决在django模板中安全地展示用户输入html内容的挑战，即只允许特定的html标签（如`br`, `italic`, `strong`, `ul`, `li`）出现，同时有效防范跨站脚本（xss）攻击。我们将详细介绍如何利用python的`bleach`库实现精细的html标签白名单过滤，确保内容显示既符合业务需求又兼顾安全性。
在Web应用开发中，允许用户输入HTML内容并将其直接渲染到页面上是一个常见的需求，例如富文本编辑器或评论系统。然而，直接使用Django模板的|safe过滤器虽然能将HTML标记为安全并避免转义，但这种做法存在严重的安全隐患。|safe过滤器会允许所有HTML标签，包括恶意脚本（如
为了在满足业务需求的同时保障安全性，我们需要一种机制来严格控制允许显示的HTML标签，即实现一个HTML标签的白名单过滤。
引入 bleach 库进行内容净化
bleach 是一个强大的Python库，由Mozilla开发，专门用于从不受信任的字符串中清除HTML标签和属性，使其可以安全地在浏览器中显示。它通过明确的白名单机制工作，这意味着只有明确允许的标签和属性才会被保留，其他所有内容都将被移除或转义。
安装 bleach
首先，您需要通过pip安装bleach库：
立即学习“前端免费学习笔记（深入）”；
pip install bleach
定义允许的HTML标签
bleach 的核心功能之一是允许您精确定义哪些HTML标签是安全的。这通过一个简单的列表来实现。例如，如果您的需求是只允许
, (或italic), , 和
ALLOWED_TAGS = ['br', 'i', 'strong', 'ul', 'li'] # 注意：HTML标签通常是小写，bleach会自动处理大小写。 # 'italic'在HTML中是，这里我们直接使用'i'
使用 bleach.clean() 进行内容净化
定义了允许的标签列表后，就可以使用 bleach.clean() 方法来处理用户输入的内容。这个方法会遍历输入字符串，移除所有不在 tags 参数中指定的标签。
import bleach # 定义允许的标签列表 ALLOWED_TAGS = ['br', 'i', 'strong', 'ul', 'li'] # 示例用户输入，包含允许和不允许的标签 user_input = '这是一个 示例，其中包含一些文本和。
- 列表项1
- 列表项2
' # 使用bleach.clean()进行净化 cleaned_user_input = bleach.clean(user_input, tags=ALLOWED_TAGS) print("原始输入：") print(user_input) print("\n净化后的输出：") print(cleaned_user_input)
运行上述代码，您将得到如下输出：
原始输入：这是一个 示例，其中包含一些文本和。
- 列表项1
- 列表项2
净化后的输出： 这是一个 示例，其中包含一些文本和。
- 列表项1
- 列表项2
从输出中可以看出，
标签和
在Django中集成 bleach
在Django应用中，您可以将 bleach 集成到视图逻辑中，或者创建一个自定义的模板过滤器。
方法一：在视图中处理数据
这是最推荐的做法，因为它确保了在数据保存到数据库或传递到模板之前，内容就已经被净化。
# views.py
from django.shortcuts import render
import bleach
ALLOWED_TAGS = ['br', 'i', 'strong', 'ul', 'li']
def display_user_content(request):
raw_content = request.POST.get('user_html_input', '') # 假设从表单获取
# 净化用户输入
cleaned_content = bleach.clean(raw_content, tags=ALLOWED_TAGS)
# 将净化后的内容传递给模板
context = {'display_content': cleaned_content}
return render(request, 'my_template.html', context)
# my_template.html
用户内容展示
用户生成内容
{{ display_content|safe }} {# 注意：这里仍然需要|safe，因为内容已经被bleach净化，现在是安全的 #}
方法二：创建自定义模板过滤器
如果您希望在模板层面进行净化（例如，在展示数据库中未净化的旧数据时），可以创建自定义模板过滤器。
# myapp/templatetags/bleach_filters.py
from django import template
import bleach
register = template.Library()
ALLOWED_TAGS = ['br', 'i', 'strong', 'ul', 'li']
# 您还可以定义允许的属性，例如：
# ALLOWED_ATTRIBUTES = {
# '*': ['class', 'id'], # 允许所有标签有class和id属性
# 'a': ['href', 'title'], # 允许a标签有href和title属性
# }
@register.filter(name='bleach_clean')
def bleach_clean_filter(value):
"""
使用bleach库净化HTML内容，只保留白名单中的标签。
"""
if not isinstance(value, str):
return value
return bleach.clean(value, tags=ALLOWED_TAGS) #, attributes=ALLOWED_ATTRIBUTES)
然后在您的模板中加载并使用这个过滤器：
{% load bleach_filters %}
用户内容展示
用户生成内容
{{ user_raw_content|bleach_clean|safe }}
请注意，即使使用了 bleach_clean 过滤器，最终在模板中显示时，仍然需要加上 |safe 过滤器，因为 bleach 返回的是一个普通的字符串，Django模板引擎默认会对其进行HTML转义。|safe 告诉Django这个字符串已经被净化，可以安全地渲染为HTML。
注意事项与最佳实践
- 始终优先在后端净化： 最佳实践是在数据保存到数据库之前或从数据库读取后、渲染到模板之前，在视图或模型层进行内容净化。这确保了数据库中存储的是干净的数据。
- 明确的白名单策略： 仔细考虑您的应用需要哪些HTML标签和属性，并只将它们添加到白名单中。任何未明确允许的都应该被移除。bleach 默认会移除所有属性，如果您需要允许特定属性（例如 标签的 href），需要通过 attributes 参数显式指定。
- 不仅仅是标签： bleach 不仅可以过滤标签，还可以过滤HTML属性 (attributes 参数) 和 CSS 样式 (styles 参数)。对于更复杂的富文本场景，这些功能非常有用。
- 结合其他安全措施： bleach 是XSS防护的重要一环，但并非唯一手段。它应该与其他安全措施结合使用，例如输入验证、输出编码、内容安全策略（CSP）等，以构建一个多层次的安全防御体系。
- 性能考虑： 对于处理大量或非常大的HTML字符串，bleach 的净化操作可能会有轻微的性能开销。在大多数Web应用场景中，这种开销通常可以忽略不计。
通过遵循这些指导原则并利用 bleach 库，您可以在Django应用中安全、灵活地处理用户输入的HTML内容，有效防止XSS攻击，同时保持页面内容的丰富性。
