写了就发云端实况架构解析:Supabase Edge Function + GitHub Actions macOS 兜底全链路
写了就发云端实况架构解析: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,它本身不做渲染,只做五件事:
- create(建任务):在 createJob() 中校验素材(视频 ≤150MB、卡片画面/遮罩各 ≤15MB、合计 ≤180MB),做限流(游客 6 次/小时、登录 12 次/小时),生成任务 ID 与一次性 access_token(只存 SHA-256 哈希),并为 3 个文件签发私有签名上传地址;
- start(开工):确认素材已传齐后,把任务置为
queued,并调用 GitHubrepository_dispatch接口推送cloud-live-photo事件,"喊醒"云端的 Mac; - status / cancel(查询与取消):前端轮询进度;完成后签发结果包下载链接;
- 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。
成品下载走和单张、批量导出一致的打包结构,实况包与普通图片同级并列、按页码统一编号:
整组卡片同样支持一次性打包,普通图片与实况页按原始顺序排列:
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 触发凭证。


