如何防盗链

在预览接入的过程中，downloadUrl 是接入方（即你的应用）提供给石墨服务端用来下载源文件的入口。它和"用户浏览器下载链接"不是同一回事，如果能明确这个前提，那么绝大多数 401/403、内网不可达、防盗链拦截问题都能在设计阶段避开。

一、下载文件的是石墨文档中台服务端，不是用户的浏览器

石墨在生成预览时，会用接入方在元信息回调里返回的 downloadUrl，从石墨服务端主动发起一次 HTTP 下载，再把下载到的文件流交给后端解析引擎转换成预览资源，最后才把渲染好的页面推给用户浏览器。

第 3 步是关键。这一步发起方是石墨文档中台服务端，所以默认情况下：

没有用户浏览器的 Cookie、Session、SSO 登录态

没有用户的 IP、Referer、UA

走的是公网，不是用户内网（除非接入方专门拉了专线 / 网关白名单）

所有防盗链规则都要在"一台陌生服务器来拉文件"这个前提下设计。

二、downloadUrl 必须满足的四个条件

条件	含义	反例
公网可达	石墨服务端能直接访问，不依赖内网或专线（除非已打通）	`http://10.0.0.5/...`、`http://internal-bucket.local/...`
自包含鉴权	URL 本身带短期凭证，不依赖 Cookie / Session / SSO	`https://corp.com/file/123`（需登录）
过期时间够长	至少覆盖一次完整下载 + 解析的时间	30 秒签名 + 100 MB 大文件
内容随文件变化	文件内容变更后生成新的 `fileId` 和新的 `downloadUrl`	对象存储覆盖写、URL 不变

三、常见防盗链规则与对应改法

防盗链规则	表现	改法
校验 Cookie / Session	服务端下载得到 HTML 登录页或 401	改为短期签名 URL，凭证放进 query string
校验 Referer	服务端下载返回 403	关闭 Referer 校验，或在 CDN / 网关层为石墨出口 IP 段放行
校验 User-Agent	服务端下载返回 403	关闭 UA 校验，或为石墨 UA / 出口 IP 放行
校验客户端 IP	仅允许用户当时的 IP，服务端来时被拒	改为不绑 IP 的签名，或绑石墨出口 IP 段
仅内网可达	服务端下载超时 / 拒绝连接	走公网网关、对象存储外网域名，或接专线

落到实操上，最稳的方案就是对象存储或 CDN 的短期签名 URL（S3 presigned URL、阿里云 OSS / 腾讯云 COS 临时签名等）—— 鉴权信息全在 URL 里，天然满足上一节的四个条件。

四、签名 URL 怎么签

四条经验值：

过期时间 ≥ 10 分钟。常规文档够用；大文件（数十 MB 以上）或解析较慢的格式（pptx、复杂 xlsx）建议 30 分钟。

凭证放进 query string，不依赖请求 header。

不要在 URL 里放长期 token / AK，只放本次下载用的临时签名。

每次元信息回调动态生成，不要缓存复用；文件内容变化后必须重签。

正例：

https://oss.example.com/files/abc.docx
  ?Expires=1716800000
  &OSSAccessKeyId=STS.xxx
  &Signature=...
  &security-token=...

反例：

https://corp.example.com/api/files/abc.docx        # 需要 Cookie 登录
https://internal.example.com/files/abc.docx        # 内网地址
https://example.com/files/abc.docx?token=LONG_AK   # 长期 AK 暴露

五、上线前怎么验证

在一台与用户浏览器无关的服务器上跑 curl，模拟石墨服务端视角：

通过标准：

HTTP 状态码是 200，不是 302（重定向到登录页是最常见的隐性失败）

Content-Length 与真实文件大小一致

Content-Type 是文件真实类型，不是 text/html

多次请求都能成功，不是只能用一次

任意一条不满足，就是 downloadUrl 没设计对。建议把这条 curl 命令固化进自动化测试，每次发布预览接入相关改动时都跑一遍。

六、回调接口的其他字段

除了 downloadUrl 之外，元信息回调里有两个字段经常和防盗链一起翻车：

ext：当 downloadUrl 的响应头无法准确返回 Content-Type / Content-Disposition 时（比如对象存储统一返回 application/octet-stream），用 ext 兜底告诉石墨这是什么类型。不带点，例如 docx，不是 .docx。

permissions.readable：2021-12-01 之后强制必填，缺失会让预览在权限校验阶段直接失败。

字段定义详见获取文件元信息-预览文档。预览失败后的全链路排查见文件预览失败排查指南。

七、小结

把石墨服务端当成"一台不在你内网、没有用户登录态的陌生服务器"，给它一条公网可达、短期签名、自包含鉴权的下载链接，防盗链问题基本就到此为止。

排查时如果服务端拿到的是 HTML 登录页、401、403 或超时，回到第三节按规则类型对号入座，再用第五节的 curl -I 在生产环境复现一次，问题归属通常一眼就能看出来。

一、下载文件的是石墨文档中台服务端，不是用户的浏览器#

二、downloadUrl 必须满足的四个条件#

三、常见防盗链规则与对应改法#

四、签名 URL 怎么签#

五、上线前怎么验证#

六、回调接口的其他字段#