DocsAll
← Tutorials

GitHub Actions 异步重处理

GitHub Actions 异步重处理(Actions)

DocsAll 的 Tier 5 层利用 GitHub Actions 公开仓库的免费无限额度,在云端跑重型后端工具(LibreOffice / Calibre / veraPDF / Ghostscript)。当你需要高保真转换(如 PDF → Word 排版不丢失)或合规验证(PDF/A)时,前端 WASM 引擎力不从心,Actions 是免费的最佳选择。

适用场景

  • 高保真 PDF → Office:LibreOffice 引擎,排版 / 字体 / 表格精确保留
  • 电子书转换:Calibre 引擎,支持 EPUB / MOBI / AZW3 / PDF / TXT 互转
  • PDF/A 合规验证:veraPDF 引擎,验证 PDF/A-1a / 2b / 3a 等标准
  • Ghostscript 高级处理:PDF 优化压缩 / 转 PostScript / 转 PDF/A

异步流程

浏览器 ──上传文件──> Workers(R2 存储 24h)
                            │
                            ├─触发 repository_dispatch──> GitHub Actions
                            │                                 │
                            │                                 ├─下载输入
                            │                                 ├─LibreOffice/Calibre/veraPDF 处理
                            │                                 └─上传结果到 Release
                            │
                            └─前端轮询 /actions/status/<jobId>
                                       │
                                       └─Release 出现 → 返回下载 URL

整个流程通常 1-3 分钟,取决于 GitHub Actions 排队时间。

操作步骤

1. 切换到云端模式

Actions 工具需要 🔴 云端增强模式。按 Alt+P 循环切换,或在工具页右上角的隐私选择器选「云端增强」。

2. 选择工具

进工具总览,在「Actions」分类下选工具:

  • PDF 高保真转 Office:输出 DOCX / XLSX / PPTX
  • EPUB/MOBI 转换:电子书互转
  • PDF/A 验证:返回合规报告
  • Ghostscript 处理:优化 / 转换

3. 上传文件 + 配置参数

拖入文件,选择输出格式 / 验证版本 / 操作类型。点击「处理」提交任务。

4. 等待异步处理

页面会显示任务状态卡片:

  • ⏳ 排队中:GitHub Actions 还未开始执行
  • 🔄 处理中:Actions 正在跑(LibreOffice / Calibre 等)
  • ✅ 完成:结果已上传到 Release,可下载
  • ❌ 失败:通常是文件格式错误或 Actions 超时

前端每 5 秒轮询一次 Workers,Workers 内部也会主动查 Release。状态变化即时反映。

5. 下载结果

状态变为「完成」后,点击「下载结果」按钮。文件来自 GitHub Release,直链下载。

进阶技巧

任务保活

Workers 的 cron trigger 每 10 分钟跑一次:

  • ping 所有 HF Spaces 保活
  • 主动轮询 pending 状态的任务,刷新状态

所以即使你关闭浏览器,任务也会继续在 Actions 跑,下次打开页面用 jobId 查询即可。

多任务并发

可以同时提交多个任务(每个生成独立 jobId)。Actions 公开仓库可并行跑多个 workflow,但单 repo 默认并发上限 20。

文件保留期

  • 输入文件存 R2,24 小时后自动清理(cron 每小时扫一次)
  • 结果文件存 GitHub Release,永久保留(除非手动删除 release)
  • jobId 元数据存 D1,30 天后自动清理

失败排查

任务失败时,状态卡片会显示错误信息。常见原因:

  • 文件格式错误:输入不是有效 PDF / EPUB
  • Actions 超时:文件过大(>50MB)或 LibreOffice 卡死
  • Release 上传失败:GitHub 限流(罕见)

可重新提交,或换用前端 WASM 工具(Pandoc / pdf-lib)。

注意事项

  • 隐私:文件会上传到 R2 + GitHub Actions runner,24h 后 R2 自动清理,但 Release 永久保留结果。敏感文档请用 🟢 纯本地模式
  • 免费额度:GitHub Actions 公开仓库无限分钟,但单 job 最长 6 小时
  • 排队时间:高峰期可能排队 1-5 分钟才开始执行
  • 并发限制:单 repo 默认 20 并发,超出会排队
  • 文件大小:建议 < 50MB;超大文件用前端 WASM 分批处理
  • 网络:中国大陆访问 GitHub Release 可能慢,建议用代理或换用前端工具

与其他 Tier 的对比

| Tier | 引擎 | 保真度 | 速度 | 隐私 | 限制 | |---|---|---|---|---|---| | Tier 1(前端 WASM) | pdf-lib / Pandoc | 中 | 快 | 零上传 | 浏览器内存 | | Tier 4(HF Spaces) | PaddleOCR / Whisper | 高 | 中 | 云端 | HF 配额 | | Tier 5(Actions) | LibreOffice / Calibre | 最高 | 慢(异步) | 云端 | GitHub 限流 |

Actions 是保真度最高但最慢的层,适合不急的批量任务。