PeachPDF 安全实践:如何安全地渲染不可信 HTML(关闭本地文件访问)

原创2026-11-15 14:55:572,337 阅读

PeachPDF 安全实践:如何安全地渲染不可信 HTML(关闭本地文件访问)

如果你要用 PeachPDF 这个纯 .NET 的 HTML 转 PDF 渲染库来处理不可信来源的 HTML(用户提交、爬虫抓取、第三方模板),必须牢记一件事:PeachPDF 默认允许文档读取服务器上的本地文件。这一篇给你一套完整的 PeachPDF 安全配置指南:通过关闭本地文件访问,把渲染器变成一个"只读输入"的安全沙箱,防止不可信文档偷读磁盘上的图片、CSS 和字体。

⚠️ 为什么不可信 HTML 是风险?

PeachPDF 的默认行为对"渲染自己的模板"非常友好,但处理外部内容时恰恰是危险的:

  • 文档中的 file: 资源引用(图片、样式表、字体)会直接从磁盘读取;
  • 相对路径引用(如 <img src="logo.png">)会回退到进程当前工作目录解析;
  • 也就是说,一段恶意 HTML 只要写对路径,就可能把服务器上的文件"借道" PDF 渲染读取出来,甚至把敏感内容编码进输出。

核心关键词速记:PeachPDF 安全、渲染不可信 HTML、关闭本地文件访问、AllowLocalFileAccess。

🔧 一键配置:AllowLocalFileAccess = false

PeachPDF 把"文档能否触达本地文件系统"收敛到了一个开关上:PdfGenerateConfig 的 AllowLocalFileAccess 属性(默认 true,保留历史行为)。

渲染不可信输入时,只需在配置里加一行:

var config = new PdfGenerateConfig
{
    PageSize = PageSize.A4,
    AllowLocalFileAccess = false   // 🛡️ 拒绝一切本地文件访问
};

var pdf = await new PdfGenerator().GeneratePdf(untrustedHtml, config);

这一个开关覆盖了文档申请的所有资源类型,因为它们最终都走同一条解析路径(见 HtmlRenderContext.cs 的强制检查):

资源类型 关闭后的行为
<img src="file:///..."> 解析为"未找到",不嵌入
<link rel="stylesheet"> 的 file: 地址 样式表不加载
CSS url()(背景图、装饰) 不读取
SVG <image href> 不读取
@font-face src: url() 字体不嵌入,回退到默认字体
相对路径引用 不再回退到工作目录,保持"未解析"
data: URI(内联内容) ✅ 不受影响,正常渲染

💡 一个重要的安全设计:即使你显式配置了 FileUriNetworkLoader(专门读本地文件的加载器),拒绝依然生效。两个设置互相矛盾时,PeachPDF 选择"拒绝"这个安全读法——deny 永远赢。

📌 注意边界:根文档仍然会被读取

关闭本地文件访问限制的是"文档自己申请的资源",而不是你的输入本身:

  • 你直接传给 GeneratePdf 的 HTML 字符串,仍会正常渲染;
  • 你用 FileUriNetworkLoader 显式指定的那个根 HTML 文件,仍会被读取。

这是合理的边界:根文档是调用方主动提供的输入,不是文档"抓"来的。换句话说,你关的是文档伸向磁盘的"手",不是喂给它的"饭"。

⌨️ CLI 用户:一条 --no-local-files 就够了

如果你用 PeachPDF 附带的命令行工具,PeachPDF.Cli 提供了对应的开关(映射关系见 CliRunner.cs):

peachpdf input.html --no-local-files -o output.pdf

该选项对所有输入类型(HTML、MHTML、URL)一致生效:文档内的 file: 引用全部落空,相对引用不再回退工作目录;而你在命令行指定的输入文档本身仍会读取。完整说明见 docs/cli.md。

🧪 参考实现:浏览器 WASM 沙箱怎么配

仓库里有一个很好的"标准答案":Blazor WASM 示例 PdfRenderService.cs 把用户上传的文档完全"关进笼子":

  • AllowLocalFileAccess = false:文档无法触达本地文件系统(浏览器里根本没有文件系统);
  • 不配置 HTTP 加载器:文档也无法触达网络;
  • 默认只解析 data: URI(见 DataUriNetworkLoader.cs),所有内容只能来自用户上传的文件本身。

也就是说:不配置 NetworkLoader + 关闭本地文件 = 零外部访问的最小沙箱。

✅ 安全配置清单(Checklist)

处理不可信 HTML 时,建议逐项核对:

  1. ✅ AllowLocalFileAccess = false(或 CLI 加 --no-local-files)
  2. ✅ 确认是否真的需要 NetworkLoader——不需要就留空,默认加载器只认 data: URI,是最安全的组合
  3. ✅ 需要网络时,用 HttpClientNetworkLoader 之类的加载器并收紧 HttpClient(白名单域名、超时、代理)
  4. ✅ 资源加载失败是静默降级(图片缺位、字体回退),不会抛异常——检查输出 PDF 时别把它当渲染成功
  5. ✅ 为不可信输入单独创建 PdfGenerator 实例,避免字体注册等状态在文档间泄漏

这套行为的完整验证见集成测试 LocalFileAccessTests.cs——其中每个"拒绝"测试都有对应的"允许"孪生测试,确保开关真正被执行而不是空转。

❓ 常见问题

Q:关闭后相对路径图片还能用吗? A:不能从磁盘读了。把资源内联成 data: URI(base64),或用带 BaseUri 的自定义加载器从你信任的来源(内存字典、对象存储)提供。

Q:这会影响正常渲染自己的模板吗? A:默认值是 true,你的现有代码不受任何影响;只有显式设 false 时才收紧。

Q:发现 PeachPDF 的安全漏洞怎么报告? A:走 SECURITY.md 中的邮件渠道,不要公开提交 issue。

小结

PeachPDF 的安全模型很简单:一个开关(AllowLocalFileAccess)+ 一个默认安全的最小加载器(data: URI)。渲染自己的模板时保持默认;一旦输入来源不可信,加上 AllowLocalFileAccess = false 这一行,就把文件系统的攻击面整个关掉了——这正是把 HTML 转 PDF 库用在生产环境、处理外部内容时的第一道防线。

登录后查看全文
PeachPDF