写了就发云端实况架构解析:Supabase Edge Function + GitHub Actions macOS 兜底全链路

原创2026-11-16 14:04:271,737 阅读

写了就发云端实况架构解析:Supabase Edge Function + GitHub Actions macOS 兜底全链路

写了就发(write-then-publish)是一款本地优先的中文内容排版工具,可以把 Markdown 一键转成小红书图文卡片、公众号长文和可下载图片,并支持 Obsidian 工作流。它的招牌功能之一是生成 iPhone 实况照片(Live Photo)卡片:浏览器支持 WebCodecs 时全程本地合成,视频不出设备;不支持时,则走"云端实况"兜底链路——由 Supabase Edge Function 做任务调度,GitHub Actions 的 macOS Runner 做渲染兜底。本文完整拆解这条链路的设计与实现。

1️⃣ 为什么需要"云端实况"兜底

实况照片要求把一段视频无损裁进卡片画面、生成封面帧、写入 Apple 私有配对标记(JPG 与 MOV 内同一 UUID),再用 makelive 打包成 .pvt 文件。这套流程强依赖 macOS + FFmpeg,而浏览器里的 src/live-photo-browser.js 方案只能在支持 WebCodecs 的浏览器本地完成。

于是项目设计了双链路:

场景 生成方式 说明
支持 WebCodecs 的浏览器 浏览器本地合成 视频不出设备,实测约 0.6 秒合成一张 5 秒实况
不支持 WebCodecs / 无本机服务 云端实况兜底 上传素材 → 云端 Mac 渲染 → 下载成品 ZIP

在编辑器里选定时长(3 / 5 / 8 秒)、倍速(原速 ~ 3×)、比例与片段后,系统会判断走哪条链路:

写了就发云端实况的实况照片编辑器,左侧带裁剪框的视频画面,右侧时长、倍速与时间轴设置

2️⃣ 第一站:Supabase Edge Function 做"调度中心"

云端链路的"大脑"是 supabase/functions/live-photo-jobs/index.ts,它本身不做渲染,只做五件事:

  1. create(建任务):在 createJob() 中校验素材(视频 ≤150MB、卡片画面/遮罩各 ≤15MB、合计 ≤180MB),做限流(游客 6 次/小时、登录 12 次/小时),生成任务 ID 与一次性 access_token(只存 SHA-256 哈希),并为 3 个文件签发私有签名上传地址;
  2. start(开工):确认素材已传齐后,把任务置为 queued,并调用 GitHub repository_dispatch 接口推送 cloud-live-photo 事件,"喊醒"云端的 Mac;
  3. status / cancel(查询与取消):前端轮询进度;完成后签发结果包下载链接;
  4. worker_job / worker_update(对 Worker 说话):凭 x-worker-secret 共享密钥,把输入文件的签名 URL、manifest 参数和结果包上传地址交给 Worker,并接收进度回报。

配套的地基在 supabase/migrations/20260731_cloud_live_photo.sql:live_photo_jobs 任务表(含状态机 uploading → queued → processing → complete / failed、进度、1 小时过期时间)+ 私有 Storage 桶 live-photo-jobs(限 180MB、白名单 MIME 类型)。

安全细节值得借鉴:

  • 任务表开启 RLS 并 revoke all,前端永远无法直接查任务,一切经由 Edge Function 的 service role 代查;
  • originAllowed() 白名单校验网页来源,防止其他站点盗用接口;
  • config.toml 中 verify_jwt = false——这里改用自签的一次性 access_token,而非透传用户 JWT。

3️⃣ 第二站:GitHub Actions macOS Runner 做"渲染机"

被唤醒的是 .github/workflows/cloud-live-photo.yml,它跑在 macos-15-intel Runner 上(15 分钟超时,按 job_id 串行)。为把冷启动压到最短,workflow 做了三层"提速":

优化 做法 收益
sparse checkout 只检出 server.py 和 scripts/ 跳过仓库里 25MB+ 的截图素材
FFmpeg 缓存 actions/cache 缓存 Homebrew 装好的 ffmpeg 8.1.2 全家桶 免重复 brew install
makelive venv 缓存 缓存装好 makelive==0.7.0 的独立虚拟环境 免重复下载约 86MB 依赖

workflow 还支持手动 workflow_dispatch + warm_cache 参数预热缓存,确保首个真实任务不用等环境安装。

4️⃣ 第三站:复用同一套渲染管线

Runner 上真正干活的是 scripts/cloud_live_photo_worker.py,流程是:

worker_job 取任务 → 签名 URL 下载素材 → 调用 server.render_live_photo()
→ 上传 result.zip → worker_update 回报进度

关键设计:云端与本机渲染是同一个函数 render_live_photo()。FFmpeg 按 iPhone 原生规格输出 30fps、H.264 CRF 18(音轨兼容时原样搬运),再用 makelive 完成 Apple 配对打包与校验。云端兜底目前按 3 / 5 秒原速处理(见 README 能力矩阵)。

Worker 每一步都通过 report() 回报中文进度,比如"正在下载视频和卡片"→"正在无损裁剪并合成卡片"→"实况下载包已完成",失败也会上报完整错误,前端因此能显示一条诚实的进度条。

5️⃣ 隐私边界:传了就删,用完就散

这条链路对"素材出设备"保持克制:

  • 私有签名上传:前端只能往指定 jobs/{id}/input/ 路径写文件,无列表、无读取权限;
  • 任务 1 小时过期:cleanupExpiredJobs() 每次建任务时顺手清理过期任务的输入与结果文件,并删除任务记录;
  • 完成即删输入:任务结束(无论成功失败)立即删除原始视频与素材,下载链接随任务过期失效;
  • 敏感凭证不出服务端:GITHUB_DISPATCH_TOKEN、CLOUD_JOB_SECRET、service role key 全部只存在于 Supabase 环境变量与 GitHub Secrets。

成品下载走和单张、批量导出一致的打包结构,实况包与普通图片同级并列、按页码统一编号:

写了就发云端实况单张下载面板,可长按预览的 Live Photo 卡片、文件大小与下载按钮

整组卡片同样支持一次性打包,普通图片与实况页按原始顺序排列:

写了就发云端实况批量下载面板,左侧整组卡片缩略图,右侧实况照片与高清图片清单

6️⃣ 一句话总结

环节 角色 核心文件
调度 Supabase Edge Function supabase/functions/live-photo-jobs/index.ts
数据 任务表 + 私有桶 supabase/migrations/20260731_cloud_live_photo.sql
渲染 GitHub Actions macOS Runner .github/workflows/cloud-live-photo.yml
执行 Python Worker 复用本机管线 scripts/cloud_live_photo_worker.py、server.py

Edge Function 管"派活",macOS Runner 管"干活",签名 URL 管"安全",1 小时 TTL 管"遗忘"——这套组合让一个纯前端应用,在不维护自己的 Mac 服务器的前提下,也能给不支持 WebCodecs 的用户兜底生成实况照片。

当前在线版处于维护期,云端实况兜底入口已暂停(详见 README 中的说明);架构本身仍完整保留在仓库中,可自行部署:应用迁移 SQL、部署 live-photo-jobs 函数,并配置仓库专用 GitHub 触发凭证。

登录后查看全文
write-then-publish