前几天在内部文档平台上了个上传模块，刚交付没两天，安全团队就甩过来一条通告：有人上传了一份PDF，里面被人塞了一段JavaScript，只要有人打开这份PDF，脚本就会在浏览器上下文里执行。排查到后半夜，我被SpringBoot里一个随手就能用的能力彻底圈粉——利用全局过滤器在入口处扫描上传PDF，把XSS、危险动作这类威胁挡在业务处理之前。代码量不大，效果却非常直接。这篇文章就完整还原我当时的方案、踩坑过程，以及怎么把它扩展成一套可配置的文件安全扫描体系，适合正在做文件上传、内容管理、文档系统的后端同学参考。
1. 项目背景：一份PDF引发的安全思考
安全通告里写得很简洁，但复现链路一点都不简单。攻击者通过平台的上传接口，提交了一份带着恶意脚本的PDF文件，系统没有对文件内容做任何检查，这份PDF被转存到对象存储后，其他用户只要在线预览，脚本就会被PDF阅读器或浏览器插件解析执行。由于系统里用户身份信息靠Cookie维持，脚本一旦跑起来，就等于把当前用户的会话直接交了出去。
这次事件给我最直接的教训是：文件上传安全不能只靠“扩展名黑名单”和“文件大小限制”两层粗糙校验。攻击者完全可以把可执行的payload塞进PDF这类结构化文件内部，绕过所有表层过滤。要挡住这类威胁，必须向前走一步，在文件进入业务逻辑之前，对文件内容本身做解析和识别。
1.1 一次上传漏洞的完整画像
我们的平台是一个内部文档管理系统，核心流程是上传PDF、转存、在线预览、分享链接。攻击路径其实很常规：注册一个普通账号，通过页面上传功能提交文件，但文件不是普通PDF，而是经过构造的恶意PDF。
第一版代码里，上传接口只做了三件事：校验扩展名是否为pdf、限制文件大小20MB、然后交给存储服务。这三个检查完全没碰到文件内容，等于把所有风险都留给了下游。攻击者利用的正是这个空档。PDF本身是一个容器格式，里面可以包含文本、字体、图片、注释，也可以包含JavaScript脚本、内嵌文件、自动触发动作。阅读器在打开文档时，可能会执行其中的脚本或动作，XSS就这样产生了。
这次漏洞暴露出的根本问题，不是某个框架或组件有漏洞，而是我们缺少一个全局性的文件安全防线。单点修复固然能解决当前接口的问题，但同一个平台可能还有别的上传入口，比如头像上传、附件上传、批量导入，任何一个口子没堵住都会被绕过。所以当时的结论非常明确：要在所有上传入口共用一层安全过滤机制。
1.2 为什么PDF会成为XSS的载体
很多人听到XSS，第一反应都是网页里的脚本注入，不会想到PDF。实际上PDF的规范很早就支持嵌入JavaScript，并且可以在文档打开、关闭、打印等时机触发，这为攻击者提供了很舒服的避风港。
我对几个高危特征做了归类：
| 特征对象 | 作用说明 | 风险等级 |
|---|---|---|
| /JavaScript | 声明文档内嵌的JavaScript脚本 | 高 |
| /OpenAction | 文档打开时自动执行的动作，可关联脚本 | 高 |
| /AA | Additional Action，在页面或文档级挂接额外动作 | 高 |
| /Launch | 调用外部程序或打开外部文件 | 高 |
| /URI | 指向外部链接，可用于钓鱼或诱导跳转 | 中 |
| /EmbeddedFile | 内嵌附件，可藏匿HTML、EXE等文件 | 中 |
这里面的逻辑很简单：PDF的底层结构是对象树，每个对象用CObject来表示，包括字典、数组、流、名称等。对象字典里如果出现上面这些键，就说明文档里存在可执行或可交互的能力。安全扫描的本质，就是递归遍历这棵对象树，把携带危险键的PDF找出来。
1.3 这个“神仙功能”到底指什么
修复过程里有个细节让我非常感慨：SpringBoot把Filter的注册和使用简化到了几乎没有成本。你只需要写一个继承了OncePerRequestFilter的类，注册成Bean，再用FilterRegistrationBean设置好拦截路径和顺序，一个全站级别的安全过滤器就生效了。不需要配置web.xml，不需要处理复杂的Servlet初始化逻辑，SpringBoot自动装配把这些底层东西全都接好了。
真正惊艳的，是SpringBoot对这种“中间件组件”的包容度。它没有要求你必须用拦截器、必须用AOP，而是保留了Servlet体系里最原汁原味的Filter机制，并且把它变成Spring容器里一个普普通通的Bean。这意味着你可以用依赖注入、配置绑定、条件装配这些Spring能力来增强它，获得的是拦截器做不到的最外层控制力。
2. 技术选型：为什么是全局过滤器
做技术方案的时候，团队里不只一次讨论过到底用Filter、Interceptor还是AOP。三者看起来都能在请求处理过程中插一脚，但边界完全不同。选错方案会导致后面加功能时非常别扭。
2.1 Filter、Interceptor、AOP的边界对比
一句话总结三者的关系：Filter在DispatcherServlet之前执行，Interceptor在SpringMVC的HandlerAdapter调用目标方法前后执行，AOP则在Spring Bean调用链上切入。
| 维度 | Filter | Interceptor | AOP |
|---|---|---|---|
| 执行层级 | Servlet容器级 | SpringMVC内部 | Spring Bean代理层 |
| 是否经过Spring容器 | 注册后由容器管理 | 是 | 是 |
| 可操作对象 | ServletRequest、ServletResponse | HandlerMethod、ModelAndView | 方法参数、返回值 |
| 能拦截静态资源 | 能 | 不能 | 不直接 |
| 能看到业务方法返回值 | 不能 | 能 | 能 |
做文件安全扫描，最核心的需求是：能在任何业务代码执行之前，拿到原始上传请求，先检查，不合格就拒绝。Filter的位置决定了它天然适合这件事，因为它在请求进入SpringMVC之前就能决定请求的去留。Interceptor虽然也在Controller之前执行，但它拦不了静态资源，而且此时SpringMVC已经完成了一部分解析工作，能做的拦截比Filter晚一步。AOP更不适合这类场景，因为它是针对Service层或Controller层方法调用的，覆盖不到所有请求入口。
2.2 SpringBoot注册Filter的三种方式
SpringBoot里给Filter开的路非常宽，我在项目里都试过，简单说明一下各自的使用方式和坑。
第一种是传统的Servlet注解方式，在Filter类上标@WebFilter(urlPatterns="/api/*")，然后在启动类上加@ServletComponentScan。这种方式最接近原生Servlet写法，但坏处是@WebFilter的参数是写死的，没法从配置文件动态调整，而且和Spring容器管理结合得不紧密，注入其他Bean时会碰到顺序问题。
第二种是直接用@Component让Spring容器管理Filter，SpringBoot启动时会自动把它注册到Servlet容器。好处是代码最少，缺点是@Component注册的Filter默认拦截所有URL，顺序由@Order控制，但它的Order作用和FilterRegistrationBean里的顺序语义容易让新人混淆。
第三种是我最推荐的方式：写一个配置类，通过FilterRegistrationBean显式注册。这种方式可以精确设置URL模式、过滤器顺序、初始化参数，也能通过ConditionalOnProperty控制是否启用。你可以在配置类里注入PdfXssSecurityFilter，然后利用SpringBoot自动配置机制完成注册。代码只多几行，但对后续的维护、排查、灰度都要友好得多。
2.3 全局过滤器的设计边界与收益
在动手写代码前，我把这个Filter的边界想得比较清楚。它不应该代替业务层的所有校验，而是只负责一个职责：识别并阻断携带危险内容的PDF文件。这样Filter内部始终只做两类事，一类是判断当前请求是否需要扫描，另一类是执行扫描并给出结果。
收益非常明显。因为所有上传请求都汇聚到这一层，新增一个上传入口时不需要再单独处理安全问题，会在同一个过滤器里被覆盖。这种“从入口处统一管控”的思路，比在业务层逐个方法加拦截代码要好维护得多。后续如果安全团队提出新的威胁特征，我们只需要升级过滤器里的识别规则，全站所有入口同时生效，不需要改任何业务代码。
3. 实战实现：全局过滤器扫描上传PDF
下面进入正题，完整展示我在项目中落地的方案。整体架构是：一个PdfXssSecurityFilter负责拦截上传请求，一个PdfContentScanner负责解析PDF对象结构并识别风险特征，一个配置类负责注册过滤器。分模块写出来，逻辑会清晰很多。
3.1 过滤器骨架与请求类型判断
为了防止同一个请求被过滤器处理两次，继承OncePerRequestFilter是SpringBoot下的标准做法。这个类会保证即便Filter被Servlet容器和SpringBoot重复注册，一次请求也只执行一次过滤逻辑。
@Configuration public class PdfXssFilterConfig { @Bean public FilterRegistrationBean<PdfXssSecurityFilter> pdfXssFilterRegistration( PdfXssSecurityFilter filter) { FilterRegistrationBean<PdfXssSecurityFilter> registration = new FilterRegistrationBean<>(); registration.setFilter(filter); registration.addUrlPatterns("/api/*"); registration.setName("pdfXssSecurityFilter"); registration.setOrder(Ordered.HIGHEST_PRECEDENCE); return registration; } }Filter本体这样写：
@Configuration public class PdfXssSecurityFilter extends OncePerRequestFilter { private final PdfSecurityProperties properties; private final PdfContentScanner scanner; public PdfXssSecurityFilter(PdfSecurityProperties properties, PdfContentScanner scanner) { this.properties = properties; this.scanner = scanner; } @Override protected boolean shouldNotFilter(HttpServletRequest request) { if (!properties.isEnabled()) { return true; } String contentType = request.getContentType(); if (contentType == null || !contentType.toLowerCase().contains("multipart/form-data")) { return true; } return !isPdfInRequest(request); } private boolean isPdfInRequest(HttpServletRequest request) { try { Collection<Part> parts = request.getParts(); for (Part part : parts) { String name = part.getSubmittedFileName(); if (name != null && name.toLowerCase().endsWith(".pdf")) { return true; } } } catch (Exception ignored) { // 解析失败时不要在这里放行，返回true是让后续交由主逻辑处理 } return false; } @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { List<Part> pdfParts = new ArrayList<>(); Collection<Part> parts = request.getParts(); for (Part part : parts) { String name = part.getSubmittedFileName(); if (name != null && name.toLowerCase().endsWith(".pdf")) { pdfParts.add(part); } } for (Part part : pdfParts) { if (part.getSize() > properties.getMaxPdfSize()) { writeJsonError(response, "PDF文件大小超过安全扫描限制"); return; } File tempFile = savePartToTemp(part); try { ScanResult result = scanner.scan(tempFile); if (result.isBlocked()) { writeJsonError(response, result.getMessage()); return; } } finally { tempFile.delete(); } } filterChain.doFilter(request, response); } }shouldNotFilter的作用是在请求进来时先做一次低成本过滤，如果当前请求不是multipart上传，或者没有PDF文件，就直接放行，避免后续无意义的解析。这里有个细节：判断文件类型时，不能只依赖Content-Type请求头，有些客户端上传时会把Content-Type乱填，所以我把part.getSubmittedFileName()作为补充判断条件，双保险。
先落盘再扫描的设计也是经验之谈。PDFBox解析PDF时，对文件的随机访问需求比较高，直接从内存流解析对JVM堆压力很大，尤其当上传文件达到几十MB时，很容易触发FullGC。我把Part先复制到系统临时目录，再让扫描器读临时文件，既能控制内存占用，也让PDFBox底层对文件的操作更舒服。
3.2 PDF内容解析：识别JavaScript与危险对象
扫描器的核心是遍历PDF对象树，识别/JavaScript、/OpenAction、/AA、/Launch这些危险特性。这里我用的工具是Apache PDFBox，Pom依赖如下：
<dependency> <groupId>org.apache.pdfbox</groupId> <artifactId>pdfbox</artifactId> <version>2.0.28</version> </dependency>PDFBox 3.x开始推荐用Loader.loadPDF(File)替代PDDocument.load(File)，如果你用的是3.x以上版本，注意调整API。下面给出一个兼容2.x和3.x的思路：
@Component public class PdfContentScanner { private static final List<String> DANGEROUS_KEYS = List.of( "JavaScript", "OpenAction", "AA", "Launch", "EmbeddedFile" ); private static final List<String> HIGH_RISK_KEYS = List.of( "JavaScript", "OpenAction", "AA", "Launch" ); public ScanResult scan(File pdfFile) { ScanResult result = new ScanResult(); result.setBlocked(false); try (PDDocument document = loadDocument(pdfFile)) { if (document == null) { result.setBlocked(true); result.setMessage("PDF文件损坏或无法解析"); return result; } COSDictionary catalogDict = document.getDocumentCatalog().getCOSObject(); Set<String> hits = new HashSet<>(); walkCOSObject(catalogDict, 0, hits); if (!hits.isEmpty()) { result.setBlocked(true); result.setMessage("检测到PDF包含危险对象: " + String.join(", ", hits)); result.setHitKeywords(new ArrayList<>(hits)); } else { // 文本层再扫一轮，防止payload藏在文本流中 List<String> textHits = scanTextContent(document); if (!textHits.isEmpty()) { result.setBlocked(true); result.setMessage("检测到PDF文本包含疑似XSS攻击内容: " + String.join(", ", textHits)); result.setHitKeywords(textHits); } } } catch (Exception e) { result.setScanError(e.getMessage()); } return result; } private void walkCOSObject(COSBase base, int depth, Set<String> hits) { if (base == null || depth > 10) { return; } if (base instanceof COSDictionary) { COSDictionary dict = (COSDictionary) base; for (COSName key : dict.keySet()) { String keyName = key.getName(); if (DANGEROUS_KEYS.contains(keyName)) { hits.add(keyName); } if (keyName.equalsIgnoreCase("URI")) { COSBase uriValue = dict.getItem(key); if (uriValue instanceof COSString) { String uri = ((COSString) uriValue).getString(); if (containsSuspiciousUri(uri)) { hits.add("URI:" + uri); } } } walkCOSObject(dict.getDictionaryObject(key), depth + 1, hits); } } else if (base instanceof COSArray) { COSArray array = (COSArray) base; for (COSBase item : array) { walkCOSObject(item, depth + 1, hits); } } else if (base instanceof COSStream) { COSStream stream = (COSStream) base; String filtered = streamToText(stream); if (filtered.contains("/JavaScript") || filtered.contains("app.")) { hits.add("Stream-JavaScript"); } } } }遍历对象树时，要特别注意控制递归深度。正常PDF的结构深度通常很浅，但恶意PDF可以构造极深的嵌套数组和字典，把扫描器活活拖垮。我把最大深度限制在10层，超过就不再深入，既保证覆盖常见结构，又避免恶意递归导致栈溢出。
文本层扫描用的是PDFBox的文本抽取能力，逐页提取文字，检查是否存在<script>、document.cookie、onload=这类明显的注入特征。结构扫描加文本扫描两层组合，基本可以覆盖大部分已知的PDF恶意构造方式。这两层各有分工：结构扫描能发现“藏得很深”的脚本对象，文本扫描能抓住“明文写在页面上”的攻击载荷。
3.3 把“危险等级”做成可配置策略
刚开始实现时，我的逻辑非常简单：只要命中/JavaScript、/OpenAction这些高危键，就直接拒绝上传。但上线没多久就发现误杀问题很严重，尤其是/URI这个键，正常PDF里大量存在。几乎每份带链接的PDF都会命中/URI，如果凡是URI就拦截，平台基本没法正常使用。
后来把策略改成了分级处理。核心思想是：不同危险特征的重要程度不一样，需要配置化地决定“直接拦截”还是“告警放行”。配置项可以放在application.yml中：
app: security: pdf: enabled: true max-pdf-size: 20MB max-parse-pages: 100 block-on-error: false action: JavaScript: block OpenAction: block Launch: block AA: block URI: report EmbeddedFile: report这个配置对应到扫描器里的一个策略对象：
public class ScanPolicy { private Map<String, String> action = new HashMap<>(); public boolean shouldBlock(String feature) { return "block".equalsIgnoreCase(action.get(feature)); } }使用这样的配置化策略后，/JavaScript、/OpenAction这种直接可执行动作的特征命中时直接拦截，/URI、/EmbeddedFile这种需要结合上下文判断的，先记录下来，通过告警日志发给安全团队，由安全运营人员决定是否收紧策略。整个流程下来，真正的恶意文件被挡住了，正常业务几乎没有受损。
3.4 注册过滤器与全局配置
过滤器之所以能在SpringBoot里“开箱即用”，靠的是SpringBoot的自动配置能力。但你如果直接用@Component注册过滤器，默认拦截所有URL，顺序不可控，实际项目里还是推荐使用FilterRegistrationBean。
把这个注册逻辑放在独立配置类后，需要注意的一点是：如果项目里同时使用了Spring Security，FilterRegistrationBean的排序要放在Spring Security的过滤器链之前或之后，取决于你的真实诉求。我的选择是放在Spring Security之后，这样可以让认证通过后的请求再进入PDF扫描，避免未登录用户消耗扫描资源。如果你希望所有请求包括未登录的都先过文件扫描，那就把它放在最高优先级。
配置类里我还会配合@ConfigurationProperties写一个属性绑定类，把所有PDF安全参数集中管理，避免魔法值散落在代码里。这样在安全团队需要临时调整拦截策略时，只需要改配置文件并重新启动即可，不用改代码。如果用的是Spring Cloud Config这类配置中心，甚至可以做到运行时刷新，进一步降低运维成本。
4. 上线后踩过的坑与排障实录
任何方案落到生产环境都会遇到意想不到的问题，这套过滤器也不例外。下面几个坑是我实际花时间解决过的，写出来帮你少走弯路。
4.1 过滤器不生效，排查了整整一个下午
第一次上线时，我基于@Component写了过滤器，日志里能看到SpringBoot启动时输出了Filter的注册信息，但测试环境里无论怎么传恶意PDF，过滤器都没有触发。排查了大半天，最后定位到问题：配置类写在了一个子包路径下，而这个子包没有被启动类的@ComponentScan扫描到。
SpringBoot对Bean的扫描默认只从启动类所在包开始，如果你的过滤器类放在了其他模块或非扫描路径下，就不会被注册成Bean，自然也就不会生效。后来改用了@Bean加FilterRegistrationBean的显式注册方式，这个问题从根上解决了。排查这类问题时，可以留意启动日志里是否输出了类似Mapping filter: 'pdfXssSecurityFilter' to urls: [/api/*]的内容，如果没有，就说明过滤器根本没有注册成功。
4.2 上传流被读取后Controller拿不到文件
第一版实现里，我在Filter中直接调用了request.getInputStream()去读取整个请求体，然后用IOUtils把它转成字节数组交给PDFBox解析。测试同学很快就反馈了一个严重问题：所有上传功能都失效了，Controller里拿到的MultipartFile是空的。
这个问题的根因我在前面提到了一点：multipart请求的内容一旦被request.getInputStream()提前消费，Servlet容器在后续解析request.getParts()时就什么都取不到了。后来改成直接使用request.getParts()获取Part对象，再通过Part.getInputStream()读取文件内容，问题迎刃而解。Part.getInputStream()每次调用都会返回一个新的输入流，对后续Controller获取MultipartFile没有影响。
如果你的场景里需要对整个request body做缓存后再读取，可以用ContentCachingRequestWrapper包装原始Request。但因为它会把整个请求体缓存在内存中，对大文件上传并不友好，我的经验是：能用Part流就直接用Part流，不要画蛇添足。
4.3 解析大文件导致CPU飙升与超时
PDFBox解析PDF文档不是一次简单的读文件操作，它需要解析对象引用、还原流、解析字体和页面结构。20MB的PDF在解析高峰时，CPU占用率可能打满单个核心，持续几秒钟，导致请求超时。
我的处理方式是给扫描加上几个硬性限制：文件大小限制、最大解析页数限制、解析超时限制。在扫描前先通过PDDocument.getNumberOfPages()判断页数，超过max-parse-pages的PDF不进入文本抽取阶段，只做结构扫描。解析超时用Future配合ExecutorService实现，超时后直接按“告警放行”处理，而不是阻塞业务请求。
还有一个很容易忽略的配置项：PDFBox解析大文件时会使用内存和临时文件，可以提前把临时文件的存储目录配置到磁盘剩余空间充足的路径，避免写满系统盘。如果你遇到服务启动后临时文件堆积的情况，也可以检查一下是否有PDF扫描任务异常终止，导致临时文件没有被正确清理。
4.4 正则误杀与特征加权
最早做文本层扫描时，我写了一堆正则，比如document\.cookie、\.innerHTML、<script，测试时发现大量正常PDF被拦截。仔细一看，很多电子书、技术文档的正文里本身就包含<script>这个单词，或者引用了“document.cookie”这些字样，被正则误判为了攻击。
后来我采用了“特征加权”的思路，而不是“单特征命中即拦截”。每个特征给一个分值，比如JavaScript对象命中加50分，OpenAction命中加50分，文本中出现<script>加10分，出现document.cookie加10分。总分超过80分才拦截，50到80分之间记告警日志，低于50分放行。这套机制上线后误杀率降到了接近零，同时真正的恶意文件依然能被识别出来。
5. 扩展思路：从一个Filter到一套安全方案
这次处理PDF上传的经验，完全可以扩展到其他文件类型。SVG文件就是一个典型的后续目标，SVG是XML格式，可以直接内嵌<script>，还可以用事件属性比如onload="alert(1)"来触发XSS，我们的PDF扫描Filter只需要增加分支就能覆盖。Office系列里的docm、xlsm文件是宏病毒的载体，扫描思路也更类似，可以解析其内部的宏代码。压缩包则需要额外注意Zip炸弹和路径穿越漏洞，解压前先检查压缩文件大小和条目数，解压时对路径做归一化校验。
如果想让这套能力复用性更高，我建议把它封装成独立的Spring Boot Starter。核心模块提供一个@EnablePdfSecurity注解，启动时自动装配扫描器、配置属性、过滤器注册，业务项目只需要引入依赖、加上注解、写上配置，就拥有了全站文件安全扫描能力。这样无论是内部多个项目部署，还是后续开放给其他团队使用，都只需要维护一套代码。
还要考虑和现有安全体系的联动。每次拦截恶意文件时，除了返回错误信息给客户端，还可以把文件指纹(MD5/SHA256)、来源IP、命中特征、上传路径写入审计日志，方便后续追踪。如果企业有统一的安全运营平台，可以把这些事件通过消息队列上报，自动触发告警和封禁策略。对于希望“不能误伤正常用户”的开放平台，还可以设计白名单机制，被误杀的用户可以通过反馈流程快速放行，而不是每次都要提工单改配置。
写在最后
最后再分享一个让我印象深刻的细节。这批过滤器上线后，安全团队再做渗透测试时，特意来找我说“你们这个上传接口现在不好打了”，听到这话比收到任何表扬都舒服。SpringBoot在这个场景里真正“神仙”的地方，不是某个新注解或新特性，而是它把Filter注册、自动配置、属性绑定这些底层细节全部收口了，让开发者可以把精力集中在真正重要的事情上：设计合理的扫描逻辑、配置合适的拦截策略、持续补充风险特征。如果你也正在做文件上传类的功能，建议直接按这个思路把全局文件安全过滤器搭起来。一开始不需要做得太复杂，先拦最明显的危险对象，再根据线上反馈逐步调整策略。这个过程中踩过的坑，大概率都能在上面这几个类别里找到答案，能帮你省下不少排障时间。
