常见问题处理

一、排查路线

如果在导出文件过程中遇到了问题，可以先参考如下流程确认问题出现在哪个阶段，然后再去对应章节寻找解决方法：

排查前可以采集"事发任务"的如下关键字段：taskId、fileId、目标 type、源文件大小 / URL、status、message、最近一次 progress、首次创建时间等，以方便后续问题定位。

二、创建任务阶段

2.1 创建任务返回 `status != 0`

现象调用 /v2/import 或 /export/{fileId}，HTTP 200，但响应 status 不是 0，data 是 null。

原因任务根本没有被创建。常见来源：参数错（type 不在支持列表里）、签名 / token 失效、fileId 已存在且关联了别的协同文件、源文件无法访问。

排查

先看 message：石墨在这里通常会给出可读的原因。

核对 type 是否在指南的"导入 / 导出支持格式表"内。

核对 X-Shimo-Signature 与 X-Shimo-Token 是否仍在有效期内，时钟是否同步。

导入场景：在你的应用服务器侧用 curl -I "${fileUrl}" 验证石墨能否拉到源文件。

修复按 message 处理对应一项，并在业务库里把这条记录直接打 failed，不要进入轮询。重试前换一个新的 fileId，不要复用。

2.2 `fileId` 冲突

现象创建导入任务时 status != 0，message 提示文件已存在或类型不匹配。

原因同一个 fileId 已经关联到某个石墨协同文件（可能是上次半成功的导入，也可能被另外的业务流程用过）。石墨不支持对已存在的 fileId 做覆盖式导入。

排查在你的应用业务库里搜这个 fileId，看它是不是上一次失败任务残留的 importing 记录。

修复

如果是残留的 importing：标记为 abandoned，重新生成 fileId 再发起导入。

如果是真重复：业务侧逻辑出错，应该在调石墨前就拦截。

预防业务侧生成 fileId 用 UUID / Snowflake 这类全局唯一方案；不要把"原始文件名"或"用户 ID + 时间戳秒级"作为 fileId。

2.3 `fileUrl` 拉取失败

现象创建任务 status != 0，message 指向下载错误；或任务接受了但轮询很快变成失败。

原因石墨服务端访问不到你给的 fileUrl：内网地址、未签名的对象存储私链、CDN 防盗链拦截、源文件已被删除等。

排查

用 curl -I "${fileUrl}" 模拟石墨服务端拉取，看 HTTP 状态码。

如果用了对象存储，确认链接是不是"预签名 URL"且签名未过期。

看看是不是 CDN 加了 Referer / IP 白名单导致石墨被拦。

修复生成"长有效期 + 公网可达"的下载链接（通常对象存储预签名 URL 给 ≥30 分钟就够石墨拉一次）。建议把源文件先转存到一个石墨可达的中转存储再调接口。

2.4 上传了 0kb 文件

现象创建任务直接返回 status != 0。石墨文档明确写了"不支持导入 0kb 文件"。

原因用户上传时网络中断、前端代码先建空文件再写入但写入失败、源文件被截断等。

修复在你的应用前端 / 后端生成 fileUrl 之前先校验文件大小 > 0；前端展示"文件为空"提示，不要把空文件传到石墨。

2.5 不支持的导出格式

现象 status != 0，message 提示文件类型不支持。

原因例如把 .rtf 走 document 通道、把 .numbers 走 spreadsheet 通道。

修复严格对照支持格式表，业务侧在用户上传时就用扩展名 + MIME 双重校验。需要支持的扩展名应通过白名单而非黑名单方式维护。

三、轮询与超时

3.1 创建任务返回 `status: 0` 就当成功

现象用户在导入完成提示出现后立刻打开文件，看到空白；或导出后用户点击下载，链接根本不存在。

原因 /v2/import 与 /export/{fileId} 是任务创建接口，status: 0 只代表"任务被石墨接收"，文件还在转换中。

修复任何"任务已接收"的响应都必须接上轮询；只有进度接口返回 progress == 100 才算业务上的成功。前端展示一定要分"导入中 / 导入成功"两态，不要合并。

3.2 不轮询直接放用户进编辑器

现象用户点开新 fileId，看到空文档或编辑器报"文件不存在 / 权限错误"。

原因导入任务还没完成时，新 fileId 在石墨侧还没有内容；如果你的应用前端立刻打开它，编辑器要么拿到空内容、要么连协同会话都建不起来。

修复业务侧严格按"importing → 轮询完成 → ready"切换状态，前端只在 ready 才允许进入编辑器；中间态展示"导入中"占位页。

3.3 轮询间隔太短

现象进度接口短时间内被打了几百次，任务服务返回 429 / 5xx，或被治理系统限流。

原因误把"轮询"理解成"高频探测"。文件转换是 CPU / IO 密集任务，轮询间隔再小也不会更快完成。

修复间隔 ≥ 3 秒，并采用指数退避（如 3s → 5s → 8s → 13s …，上限 30s）；任务长跑场景由后端定时器统一轮询，前端通过 WebSocket / SSE / 定时拉业务库接收推送，而不是前端自己 1 秒打一次。

3.4 任务超过 10 分钟仍未完成

现象进度 progress 在 70-90 区间晃悠，过了 10 分钟还没到 100。

原因石墨任务最长执行时间是 10 分钟，超过会被服务端终止，但终止的标志可能延后反馈。

修复业务侧自己设总超时（建议导入 ≤15 分钟 / 导出 ≤30 分钟），超过即视为失败，停止轮询并落 failed。重试时新建任务而不是继续轮询旧 taskId。

3.5 进度长时间停滞

现象 progress 卡在某个值（例如 35），持续 30 分钟以上不变。

原因石墨官方明确：导出进度 ≥30 分钟未更新即可认为失败。导入虽然没有同等说明，但行为类似——通常是文件特别大、特别复杂或源拉取卡住。

修复在轮询逻辑里加"上次进度变化时间"判断，超过阈值视为失败。提示用户"文件可能过大或损坏，请精简后重试"。

3.6 网络抖动 / 5xx

现象轮询过程中偶发 502 / 503 / 504 或连接重置。

原因网关 / 中间代理抖动，并非任务真的失败。

修复进度查询接口可重试 1–3 次（指数退避）。不要因为一次 5xx 就把任务标 failed；也不要因为重试就新建任务（创建任务接口幂等性弱，会产生新 taskId）。

四、导出下载阶段

4.1 `downloadUrl` 已过期

现象进度接口拿到 downloadUrl，业务侧晚了几分钟才去下载，结果 403 / 404。

原因石墨返回的 downloadUrl 是临时签名链接，有效期仅 5 分钟。

修复拿到 downloadUrl 后立刻消费——后端在同一次轮询完成的处理函数里下载并转存到自己的对象存储。如果一定要延后下载，需要在 5 分钟内重新调进度接口（同一个 taskId 仍有效）拿新的 URL，而不是把旧 URL 再用一次。

4.2 把 `downloadUrl` 直接返回前端

现象用户在导出完成几分钟后点下载链接，浏览器报 403。

原因同上：5 分钟有效期 + 无防盗链。前端持有时间往往超过 5 分钟（用户去开会、切换窗口、转发给别人等场景太常见）。

修复

后端拿到 downloadUrl 后立刻下载文件流，转存到自己的对象存储（OSS / S3 / COS …）。

前端只看到你的对象存储的链接（自己可控的有效期、防盗链、审计）。

如果需要"按需下载"，前端访问你的应用一个稳定接口，由后端按需重取 downloadUrl 并代理流给前端。

4.3 没有重复下载机制

现象用户重新刷新页面想再次下载，找不到链接。

原因业务侧只把 downloadUrl 留在内存或前端 state，没落到自己的对象存储。

修复把"转存对象存储"做成导出完成的强制收尾步骤，业务库存储路径而不是石墨的临时 URL；前端"下载"按钮始终指向你的对象存储路径。

五、业务一致性与幂等

5.1 把 `taskId` 当业务幂等键

现象用户重复点了 3 次导出按钮，业务库里出现 3 个不同的 taskId、3 份导出文件。

原因 taskId 由石墨生成，每次调用创建接口都会得到新值。用它做去重，永远去不掉。

修复业务侧自己维护一个去重键（如 fileId + type + 触发时间窗），在调石墨之前先查表：

如果窗口内已经有 exporting / ready 的同键任务，直接返回那个 taskId 给用户。

没有再调石墨创建新任务。

5.2 用户重复点击导入 / 导出

现象短时间内同一个用户对同一个文件触发了多次导入或导出请求。

原因前端没做按钮 disabled、网络慢用户多点了几下、前端组件状态丢失。

修复

前端：点击后立即 disabled，并在收到后端响应后再恢复。

后端：基于 D.1 的去重键拦截，幂等返回当前任务的 taskId 与状态。

5.3 失败时业务库未回滚 / 未落终态

现象业务库里堆积了一批永远停在 importing 或 exporting 的记录，用户列表里看到"导入中"几十分钟没动静。

原因任务失败后只在日志里记了一行，没把业务库改成 failed；或者代码里只处理了"成功"分支，"失败"路径漏写。

修复

轮询循环必须保证退出时总有一次终态写库（ready 或 failed）。

加补偿任务：定时扫描"创建 > N 分钟仍在 importing / exporting"的记录，按 B.4 / B.5 的逻辑判定失败。

5.4 失败时没保留 `taskId`

现象用户报"刚才导入失败了，能查下原因吗"，业务侧只有一句"任务失败"，没法回查石墨日志。

原因失败分支只写了人类可读的 message，没把 taskId / fileId / type / fileUrl / 时间 这些定位字段一起持久化。

修复失败日志至少包含：

taskId / fileId / 目标 type / 源文件大小 / 源文件 URL（脱敏）/ 最近一次 status & message / 重试次数 / 时间戳

。这套字段也方便你在排查时拿去找石墨支持。

六、上线检查清单

检查项	验证方式
轮询有总超时	模拟一个永不完成的任务，确认 N 分钟后业务侧自动落 `failed`
轮询间隔 ≥ 3s 且指数退避	抓包看一次完整轮询的间隔序列
`downloadUrl` 在 5 分钟内被消费	看导出日志，从拿到 URL 到下载完成的时间戳差 < 5min
导出文件落到自家对象存储	业务库存的是对象存储路径，不是石墨临时 URL
业务侧幂等键去重	连续点 3 次同样的导出按钮，最终只产生 1 个有效任务
0kb / 不支持格式 / 过大文件被前端拦截	用极端样本走一遍流程
失败日志含完整上下文	日志样本里有 taskId / fileId / type / message
任务长跑监控	有看板或告警跟踪"`importing` / `exporting` 超过 N 分钟"的记录数
重试时使用新 `fileId` / 新 `taskId`	失败重试不是简单复用旧任务

一、排查路线#

二、创建任务阶段#

2.1 创建任务返回 status != 0#

2.2 fileId 冲突#

2.3 fileUrl 拉取失败#

2.4 上传了 0kb 文件#

2.5 不支持的导出格式#

三、轮询与超时#

3.1 创建任务返回 status: 0 就当成功#

3.2 不轮询直接放用户进编辑器#

3.3 轮询间隔太短#

3.4 任务超过 10 分钟仍未完成#

3.5 进度长时间停滞#

3.6 网络抖动 / 5xx#

四、导出下载阶段#

4.1 downloadUrl 已过期#

4.2 把 downloadUrl 直接返回前端#

4.3 没有重复下载机制#

五、业务一致性与幂等#

5.1 把 taskId 当业务幂等键#

5.2 用户重复点击导入 / 导出#

5.3 失败时业务库未回滚 / 未落终态#

5.4 失败时没保留 taskId#

六、上线检查清单#