在网站运营中，我们经常需要展示一些包含丰富格式的内容，比如文章详情页的图文混排、产品介绍页的HTML表格，或是自定义页面嵌入的一些互动代码。这些内容通常存储在数据库中，并在前端页面进行渲染。然而，许多内容管理系统（包括我们熟悉的AnQiCMS）在默认情况下，为了网站安全，会将从数据库中取出的HTML内容进行转义，导致前端显示为原始的HTML代码而非预期的效果。
今天，我们就来聊聊在AnQiCMS中，如何安全地将这些数据库中的HTML内容呈现在前端，同时避免被不必要的转义。
理解AnQiCMS的默认行为与安全考量
首先，我们需要理解为什么AnQiCMS（以及许多现代CMS）会默认对HTML内容进行转义。这主要是出于安全考虑，尤其是为了防范跨站脚本攻击（XSS）。如果一个恶意用户在内容中插入了 <script>alert('XSS')</script> 这样的代码，并且系统不对其进行转义就直接显示在前端，那么其他访问页面的用户就可能受到攻击。AnQiCMS作为一款注重安全性的Go语言CMS，其设计理念之一便是“让天下都是安全的网站”，因此默认的自动转义机制是其安全防护的重要一环。
当AnQiCMS的模板引擎从数据库中取出内容并将其输出到前端时，它会将 < 转换为 <，> 转换为 >，" 转换为 " 等HTML实体，这样浏览器就不会将其解析为HTML标签或执行其中的脚本，而是将其显示为纯文本。
何时需要显示未转义的HTML内容？
当然，并非所有HTML内容都是恶意的。在许多合法的场景下，我们确实需要展示数据库中存储的富文本内容，例如：
- 富文本编辑器（WYSIWYG）输出的内容： 后台编辑文章时，使用富文本编辑器创建的标题、段落、图片、链接等，本身就是合法的HTML结构。
- 产品详情页的复杂布局： 可能包含表格、列表、特殊样式等。
- 自定义页面的嵌入代码： 例如嵌入第三方视频播放器、地图组件等。
在这种情况下，我们需要明确告知AnQiCMS的模板引擎，这部分内容是“安全”的，不需要进行转义，可以直接按HTML解析。
AnQiCMS的解决方案：|safe 过滤器
在AnQiCMS的模板系统中，要显示未转义的HTML内容，最常用且直接的方法就是使用 |safe 过滤器。
当你在模板中输出一个变量时，只需要在变量名后加上 |safe，AnQiCMS就会跳过这部分内容的HTML转义过程，直接将其作为HTML代码输出到浏览器，从而实现你想要的效果。
例如，如果我们的文章详情页模板中，有一个 articleContent 变量存储着文章的HTML内容，我们通常会这样使用它：
<div>
{%- archiveDetail articleContent with name="Content" %}
{{ articleContent|safe }}
</div>
在这里，archiveDetail 标签用于获取文档详情，并将文档内容赋值给 articleContent。随后，{{ articleContent|safe }} 确保了这部分HTML内容能够被浏览器正确解析和渲染。无论是文章的 Content 字段，还是分类的 Content 字段，甚至是单页面的 Content 字段，都可以通过这种方式安全地显示。
针对Markdown内容的额外处理：|render 与 |safe 的组合
随着Markdown编辑器的普及，很多运营者习惯用Markdown格式编写内容。AnQiCMS也支持在后台启用Markdown编辑器。Markdown本身是一种轻量级标记语言，它需要先被“渲染”成HTML，才能在浏览器中显示为富文本。
如果你的数据库中存储的是Markdown格式的内容，并且你希望在前端将其渲染为HTML，那么你需要先使用 |render 过滤器将其转换为HTML，然后，同样需要使用 |safe 过滤器来确保这些转换后的HTML不会被转义。
例如，如果你有一个自定义字段 introduction 存储的是Markdown文本：
{% archiveDetail introduction with name="introduction" %}
{{ introduction|render|safe }}
这里的 |render 会将Markdown文本解析并生成HTML，而紧随其后的 |safe 则确保了这些生成的HTML能够直接被浏览器解析，而不是作为纯文本显示。
更广泛的控制：autoescape 标签
除了对单个变量使用 |safe 过滤器外，AnQiCMS的模板引擎还提供了 autoescape 标签，用于控制模板中某个区块的自动转义行为。
你可以用 {% autoescape off %} 和 {% autoescape on %} 来包裹一段代码，明确地关闭或开启自动转义。
{% autoescape off %}
{# 在这里的所有变量输出都将默认不被转义 #}
{{ someHtmlContent }}
<div>
{{ anotherHtmlSnippet }}
</div>
{% autoescape on %}
{# 再次开启自动转义，恢复默认安全行为 #}
{{ plainText }}
{% endautoescape %}
然而，请务必谨慎使用 {% autoescape off %}。 它会关闭整个区块的自动转义功能，如果区块内包含了来自用户输入或其他不可信源的内容，将大大增加XSS攻击的风险。通常情况下，我们更推荐使用 |safe 过滤器，因为它将“不转义”的权限精确到每一个变量，使得代码更容易审查，也更不容易出错。只在万不得已、且对内容来源有绝对把握的情况下，才考虑使用 autoescape off。
总结与**实践
在AnQiCMS中，安全地显示数据库中的HTML内容而不被转义，主要依赖于 |safe 过滤器。对于Markdown内容，则需要 |render|safe 组合使用。
- 明确意图： 只有当你确定一段内容是合法的、且需要按HTML解析时，才使用
|safe。 - 输入净化： 尽管
|safe允许HTML内容显示，但前端渲染只是最后一步。最关键的防护应该在内容进入数据库之前就完成。确保所有用户输入（尤其是富文本编辑器中的内容）都经过了严格的服务器端净化和验证，过滤掉潜在的恶意脚本。AnQiCMS内置的内容安全管理和敏感词过滤等功能，是很好的第一道防线，但我们作为运营者和开发者，也需要对内容的来源和安全性保持警惕。 - 局部控制： 尽量使用
|safe过滤器对特定变量进行处理，而非全局关闭autoescape，以将安全风险降到最低。
通过这些方法，我们既能利用AnQiCMS的强大功能展示丰富多样的内容，又能有效维护网站的安全性。
常见问题 (FAQ)
Q1: 如果我忘记对HTML内容使用 |safe 过滤器会发生什么？
A1: 如果忘记使用 |safe 过滤器，AnQiCMS的模板引擎会将从数据库中取出的HTML标签和特殊字符进行默认转义。这意味着你的用户在前端页面看到的将是原始的HTML代码，例如 <p>这是一个段落</p> 会显示为 <p>这是一个段落</p>，而不是实际渲染出的段落效果。页面布局可能会因此混乱，或者失去应有的样式和交互。
Q2: 使用 |safe 过滤器后，我的网站就完全安全了吗？
A2: 不完全是。|safe 过滤器只是告诉AnQiCMS的模板引擎，这段内容你认为它是安全的，不需要再进行转义。但内容的实际安全性取决于其来源。如果从数据库中取出的HTML内容本身就包含了恶意脚本（例如通过未经净化的用户输入存储进去的），那么 |safe 过滤器会允许这些恶意脚本在前端执行，从而导致XSS攻击。因此，确保内容源的可靠性并对用户输入进行服务器端净化（过滤恶意HTML标签和属性）是至关重要的第一步。