OnlyOffice转换文档后获取URL遇403错误，求解决方案

阿华AIGC实验室

2026-5-27

解决OnlyOffice转换后PDF URL返回403的问题

我之前在对接OnlyOffice转换API时也碰到过一模一样的403问题，给你几个实际可行的排查方向和解决思路：

1. 检查JWT签名参数是否完整携带

如果你的OnlyOffice实例开启了JWT验证（这是默认推荐的安全配置），转换后返回的文件URL通常会包含签名参数（比如token或者signature）。绝对不能只截取URL的基础部分，必须完整保留所有查询参数。

举个例子，返回的URL可能是这样的：
https://your-onlyoffice-domain.com/cache/files/conv_xxxxxx/output.pdf?token=abc123
如果只取https://your-onlyoffice-domain.com/cache/files/conv_xxxxxx/output.pdf去访问，必然会403。

另外，还要确保你在发起转换请求时配置的JWT密钥和服务器端完全一致，签名算法（比如HS256）也匹配。

2. 排查临时文件的IP白名单与有效期

转换后的PDF是临时存储文件，OnlyOffice默认会限制访问来源IP，同时文件有有效期（一般几小时）：

试试在发起转换请求的服务器上直接用curl访问URL，如果能正常下载，说明是本地浏览器的IP不在白名单里。需要登录OnlyOffice管理后台，在「安全设置」里添加允许访问的IP范围。
如果服务器访问也403，可能是文件已经过期，重新发起一次转换请求再尝试下载。

3. 模拟转换请求的HTTP头信息

有些OnlyOffice部署会验证请求的Referer或User-Agent头，避免外部非法访问。你可以尝试在下载请求中带上和转换请求相同的头信息：

用curl测试：

curl -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)" -H "Referer: https://your-app-domain.com/" "https://the-converted-pdf-url"

用PHP的file_get_contents实现：

$pdfUrl = "https://the-converted-pdf-url";
$context = stream_context_create([
    'http' => [
        'header' => "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)\r\n" .
                    "Referer: https://your-app-domain.com/\r\n"
    ]
]);
$pdfContent = file_get_contents($pdfUrl, false, $context);

4. 检查转换API响应的隐藏字段

有时候官方文档的返回示例不全，实际响应里可能包含更准确的下载标识，比如key字段。你可以试试用这个key调用OnlyOffice的下载接口：

curl -H "Authorization: Bearer your-jwt-token" "https://your-onlyoffice-domain.com/download/{key}"

这里的your-jwt-token需要用你配置的JWT密钥生成，payload里要包含key参数。

5. 排查自建OnlyOffice实例的存储配置

如果是自己部署的OnlyOffice，检查以下两点：

查看/etc/onlyoffice/documentserver/local.json中的storage配置，确保private字段设为false（如果需要公开访问临时文件），或者配置了正确的allowOrigins。
检查临时存储目录的权限：/var/www/onlyoffice/Data/cache/files/目录需要允许web服务器用户（比如www-data）读取，执行chown -R www-data:www-data /var/www/onlyoffice/Data/cache/修复权限。

如果以上方法都不行，建议查看OnlyOffice的日志文件（/var/log/onlyoffice/documentserver/converter/out.log），里面会记录具体的403原因，比如签名验证失败、IP不在白名单等，能帮你快速定位问题。

内容的提问来源于stack exchange，提问作者Bdloul