整体概述

一、文件预览说明

石墨文档中台的文件预览，本质上是把第三方业务系统里的 Office/PDF/图片等实体文件，通过一个受控的在线预览页面展示给用户。你的应用继续负责文件存储、用户身份、权限判断和下载地址管理；石墨文档中台负责在用户打开预览页时，通过回调接口实时获取必要信息，下载文件，解析生成预览内容，并把渲染页面返回给前端。

因此，文件预览接入不是把文件提前同步到石墨，也不是把你的应用文件系统改造成石墨文件系统，而是通过“前端嵌入 + 后端回调 + 预览解析服务”的方式完成解耦。

二、三个核心要素

要素	由谁提供	作用
应用与凭证	你的应用在石墨文档中台侧配置	标识接入应用，生成访问预览页所需的 `signature`、`token` 等凭证
回调接口	你的应用后端	向石墨实时返回当前用户信息、文件元信息、权限、下载地址等数据
预览页面	你的应用前端 + 石墨预览服务	前端用 iframe 或 SDK 嵌入预览地址，石墨负责文件解析和页面渲染

这三个要素里，最关键的是回调服务。石墨文档中台采用无状态集成思路，不长期保存你的应用的用户、文件和权限数据；当预览链路需要这些信息时，石墨服务端会回调你的应用后端实时获取。

三、角色分工

角色	职责
用户	打开业务系统页面，加载石墨预览 iframe
你的应用前端	拼接或获取预览 URL，把预览页嵌入业务系统
你的应用后端	生成 fileId、维护文件元信息、校验用户身份、暴露回调接口和文件下载地址
石墨文档中台	校验访问凭证，回调你的应用获取用户和文件信息，下载源文件，创建或读取预览缓存，返回预览页面

四、架构示意图

下面的架构图对应文件预览场景。你的应用前端负责嵌入预览页面，你的应用后端负责实现回调接口，石墨文档中台服务负责解析并渲染预览内容。

五、预览链路

5.1 文件预览地址

预览文档不需要像协同文档那样先调用“创建协同文件”接口。你的应用准备好 fileId、signature 和 token 后，按照如下的格式拼接后，前端直接打开预览页即可。

https://__石墨文档中台域名__/sdk/v2/api/cloud-files/{fileId}/page?signature={signature}&token={token}

也可以在业务页面中用 iframe 嵌入：

5.2 石墨文档中台何时请求回调接口

石墨文档中台不直接存储你的应用的业务文件列表数据、权限数据。它只依赖约定好的回调接口：

用户打开预览页时，石墨回调“当前用户信息接口”，你的应用根据 X-WebOffice-Token 等凭证识别用户。

石墨回调“文件元信息接口”，你的应用返回该 fileId 对应的文件标题、文件类型、可读权限、下载地址和扩展名。

石墨通过 downloadUrl 拉取源文件并解析。

典型的文件元信息返回如下：

{
  "id": "my-preview-file-a1b2c3",
  "name": "示例文档.docx",
  "type": "file",
  "permissions": {
    "readable": true
  },
  "downloadUrl": "https://example.com/download/my-preview-file-a1b2c3.docx",
  "ext": "docx"
}

这里的 type 固定表示第三方文件类型，permissions.readable 决定当前用户是否可读，downloadUrl 是石墨服务端拉取源文件的地址，ext 用于在下载响应头不足以识别文件类型时明确告诉石墨文件扩展名。

需要注意的是，预览缓存和 fileId 强相关。同一个 fileId 已经生成预览缓存后，即使你的应用修改 downloadUrl 指向的新文件内容，也不应期待原预览结果自动变化。需要展示新内容时，应生成新的 fileId，让石墨重新创建预览缓存。

六、与协同文件的区别

	文件预览	协同文件
文件来源	你的应用已有的第三方文件，例如 `.docx`、`.xlsx`、`.pptx`、`.pdf`	石墨在线文件类型
是否可编辑	不可编辑，仅预览	支持在线编辑和多人协同
是否需要创建文档	不需要创建协同文档，直接用 `fileId` 访问预览页	通常需要创建或维护石墨协同文档
元信息返回	`type: "file"`，必须返回 `downloadUrl` 和 `ext`	返回协同文档对应的类型与访问数据
内容更新方式	新内容建议使用新 `fileId` 生成新缓存	编辑内容由协同链路保存和同步

七、权限与安全要点

预览访问要以你的应用自己的用户身份和权限体系为准，石墨只通过回调接口获取判断结果。

用户操作触发的回调通常携带 X-WebOffice-Token，你的应用应校验 token 格式、签名、过期时间和用户权限。

系统主动触发的请求可能使用签名类凭证，你的应用应按 X-Shimo-Credential-Type 区分验证方式。

downloadUrl 需要能被石墨服务端访问。如果使用内网、专线或对象存储临时 URL，需要保证有效期覆盖预览解析过程。

不建议把长期有效、无鉴权的真实文件地址直接暴露为下载地址。可以使用短期签名 URL、一次性下载 URL 或带服务端鉴权的中转下载接口。

八、接入检查清单

已在石墨文档中台侧完成应用配置，并能生成访问预览页需要的凭证。

你的应用后端能生成全局唯一且稳定的 fileId。

已实现当前用户信息接口。

已实现文件元信息接口，并返回 id、name、type、permissions、downloadUrl、ext。

downloadUrl 可被石墨服务端访问，且响应头或 ext 能明确标识文件类型。

业务权限变化能实时反映到回调接口返回值。

首次打开体验有要求时，已考虑提前创建预览缓存。

文件内容更新时，已明确是否生成新的 fileId。

已记录预览任务错误码、回调日志、下载日志，便于定位问题。

九、小结

石墨文件预览的关键设计，是把“文件在哪里、谁能看、如何下载”留在你的应用系统，把“如何解析、如何渲染、如何在线展示”交给石墨文档中台。接入时只要把前端预览入口、后端回调接口、文件下载链路和权限校验打通，就可以在不迁移原始文件存储的前提下，为业务系统补上在线预览能力。

一、文件预览说明#

二、三个核心要素#

三、角色分工#

四、架构示意图#

五、预览链路#

5.1 文件预览地址#

5.2 石墨文档中台何时请求回调接口#

六、与协同文件的区别#

七、权限与安全要点#

八、接入检查清单#

九、小结#