ZFile项目文件上传拦截%25字符问题分析与解决方案

问题背景

在ZFile项目从4.1.5版本升级到4.2.0版本后，用户反馈了一个关于文件上传功能的异常行为：当上传的文件名中包含"%"字符时，系统会拦截请求并返回"非法请求"的错误信息。这个问题在4.1.5版本中并不存在，表明这是新版本引入的安全机制导致的兼容性问题。

问题现象

具体表现为：当用户尝试上传一个文件名包含"%"字符（特别是编码后的"%25"）的文件时，例如"序列号.%txt"，系统会拒绝该请求并返回错误响应。通过分析请求和响应，我们可以看到：

请求示例：

PUT /file/upload/1/%E5%BA%8F%E5%88%97%E5%8F%B7.%25txt
Content-Type: multipart/form-data

响应示例：

HTTP/1.1 200
非法请求：/file/upload/1/%E5%BA%8F%E5%88%97%E5%8F%B7.%25txt

技术分析

经过深入调查，这个问题源于4.2.0版本中引入的安全策略。具体来说，拦截逻辑位于cn.dev33.satoken.strategy.SaStrategy类中，该类定义了一个名为INVALID_CHARACTER的校验规则。

安全考量

"%25"是百分号"%"的URL编码形式。系统拦截这种编码形式主要是出于以下安全考虑：

1. 双重编码攻击防护：攻击者可能利用多重编码绕过安全检查
2. 路径遍历防护：防止通过编码形式进行目录遍历攻击
3. 注入攻击防护：防范潜在的SQL注入或命令注入风险

版本差异

4.1.5版本没有此限制，而4.2.0版本增加了这一安全策略，这反映了项目在安全方面的持续改进。然而，这种改进也带来了对合法用例的兼容性问题。

解决方案

针对这一问题，可以考虑以下几种解决方案：

1. 文件名预处理

在上传前对文件名进行处理，避免直接使用"%"字符：

String safeFilename = originalFilename.replace("%", "％"); // 使用全角百分号

2. 安全策略配置调整

如果确定业务场景需要允许"%"字符，可以修改安全策略配置：

SaManager.getConfig().setCheckUrlEncoding(false);

3. 自定义校验规则

扩展SaToken的安全策略，添加对特定场景的例外处理：

SaStrategy.me.addHandler(SaStrategy.INVALID_CHARACTER, (str)->{
    // 自定义校验逻辑
    return !str.contains("%25");
});

最佳实践建议

1. 文件命名规范：建议用户尽量避免在文件名中使用特殊字符
2. 版本升级测试：升级前应充分测试文件上传功能
3. 安全与便利平衡：根据实际业务需求调整安全级别
4. 错误处理改进：可以提供更友好的错误提示，指导用户如何修正

总结

ZFile 4.2.0版本引入的文件名安全校验机制虽然增强了系统安全性，但也带来了对特定字符的限制。开发团队需要在安全防护和用户体验之间找到平衡点，通过合理的配置或代码调整来解决这一问题。对于普通用户而言，最简单的解决方案是避免在文件名中使用"%"字符，或者等待开发团队在后续版本中提供更灵活的配置选项。