Stirling-PDF解密功能：移除PDF文件密码保护

Stirling-PDF解密功能：移除PDF文件密码保护

你是否曾遇到这样的尴尬：急需查看的PDF文件被密码锁定，却找不到密码提示？Stirling-PDF的密码移除功能让你无需专业技术，3步即可解锁受保护文档。本文将详解如何使用这一实用功能，以及它背后的实现原理。

功能定位与访问路径

Stirling-PDF的密码移除功能属于安全工具模块，在Web界面中通过以下路径访问：

• 主界面 → 安全工具 → 移除密码
• 直接访问URL：/remove-password

该功能的核心实现位于 src/main/java/stirling/software/SPDF/controller/api/security/PasswordController.java，前端页面由 src/main/java/stirling/software/SPDF/controller/web/SecurityWebController.java 控制路由。

操作步骤：3步解锁PDF文件

1. 准备工作

确保你已：

• 部署Stirling-PDF服务（参考 LocalRunGuide.md）
• 拥有PDF文件的合法访问密码
• 待解密文件大小不超过系统限制（默认无限制）

2. 上传与配置

在移除密码页面：

1. 点击"选择文件"按钮上传加密PDF
2. 在密码输入框填写正确的解密密码
3. 可选：勾选"保留原始元数据"（默认勾选）

3. 执行与下载

点击"移除密码"按钮后，系统将：

• 验证密码正确性
• 移除所有安全限制
• 自动下载处理后的文件

处理完成的文件名将自动添加_password_removed后缀，例如report.pdf将变为report_password_removed.pdf。

技术实现解析

核心代码逻辑

PasswordController的removePassword方法实现了解密功能：

@PostMapping(consumes = "multipart/form-data", value = "/remove-password")
public ResponseEntity<byte[]> removePassword(@ModelAttribute PDFPasswordRequest request) throws IOException {
    MultipartFile fileInput = request.getFileInput();
    String password = request.getPassword();

    PDDocument document = Loader.loadPDF(fileInput.getBytes(), password);
    document.setAllSecurityToBeRemoved(true);
    return WebResponseUtils.pdfDocToWebResponse(
        document,
        Filenames.toSimpleFileName(fileInput.getOriginalFilename())
            .replaceFirst("[.][^.]+$", "") + "_password_removed.pdf"
    );
}

实现原理

1. 密码验证：使用Apache PDFBox的Loader.loadPDF()方法尝试解密
2. 安全移除：通过setAllSecurityToBeRemoved(true)标记完整解密
3. 文件输出：调用WebResponseUtils工具类生成响应

使用限制与注意事项

支持的加密类型

• ✅ 标准PDF密码保护（用户密码）
• ✅ 128/256位AES加密
• ❌ 证书加密文档
• ❌ DRM保护文件

安全提示

• 解密操作在本地完成，文件不会上传至云端
• 建议解密后为敏感文档设置新密码（使用"添加密码"功能）
• 企业用户应启用审计日志（参考 DATABASE.md）

常见问题解决

密码正确但解密失败？

1. 确认使用的是用户密码而非所有者密码
2. 检查文件是否被多次加密
3. 尝试更新至最新版本（参考 README.md 升级指南）

处理大文件时超时？

修改应用配置文件增加超时限制：

# 在application.properties中添加
server.tomcat.connection-timeout=600000

相关功能扩展

完成PDF解密后，你可能还需要：

• 添加新密码保护：使用"安全工具→添加密码"
• 批量处理多个文件：通过 PipelineFeature.md 创建自动化流程
• 验证解密结果：使用"安全工具→PDF信息"功能检查权限状态

使用建议与最佳实践

1. 权限管理：为不同用户组配置功能访问权限（参考 Endpoint-groups.md）
2. 工作流整合：将解密功能加入文档处理流水线，例如：

   {
     "name": "解密-压缩-水印",
     "steps": [
       {"tool": "remove-password", "password": "${var:pdf_pass}"},
       {"tool": "compress", "quality": "medium"},
       {"tool": "add-watermark", "text": "内部文档"}
     ]
   }
   

3. 定期更新：关注安全工具模块更新（参考 Version-groups.md）

通过本文介绍的方法，你已经掌握了Stirling-PDF的密码移除功能。这一工具特别适合企业文秘、法务工作者和经常处理PDF文档的办公人员使用。如需了解更多安全功能，请查阅官方文档的"安全工具集"章节。

提示：使用过程中遇到问题？可通过 CONTRIBUTING.md 中提供的渠道提交反馈。