如何把OpenStory部署到Cloudflare Workers:一键部署与D1迁移陷阱清单

原创2026-11-02 22:29:491,628 阅读

如何把OpenStory部署到Cloudflare Workers:一键部署与D1迁移陷阱清单

OpenStory 是一个开源的 AI 驱动视频序列平台(基于 TanStack Start),可以把剧本自动拆分成场景、镜头并生成一致角色的视频。本文将带你用「一键部署」把它发布到 Cloudflare Workers,并给出一份 D1 数据库迁移陷阱清单,帮你避开生产环境最常见的 5 个坑。

OpenStory AI视频序列平台首页界面,展示剧本输入与风格选择

一、部署架构 30 秒速览

OpenStory 完全构建在 Cloudflare 生态上,没有外部数据库、没有 Docker(生产构建除外):

组件 用途
D1(SQLite) 数据库,绑定名 DB,生产库为 openstory-prd
R2 两个桶:R2_PUBLIC_ASSETS_BUCKET(公开素材)+ R2_STORAGE_BUCKET(生成的媒体)
Workflows 所有异步 AI 生成任务(图像、视频、语音等 30+ 个 workflow)
Durable Objects SSE 实时推送、配额限流、Assistant 流式日志

全部绑定声明在仓库根目录的 wrangler.jsonc 中,Worker 入口是 src/server.ts。理解了这一点,后面所有命令都在围绕这个文件转。

二、部署前准备清单

开始之前,确认以下条件已满足:

  • [ ] 一个 Cloudflare 账号(Workers / D1 / R2 权限)
  • [ ] 环境中已有 CLOUDFLARE_ACCOUNT_ID 和 CLOUDFLARE_API_TOKEN(手动部署时需要)
  • [ ] 本地装有 Bun(Wrangler CLI 作为 dev 依赖内置,用 bunx wrangler 即可)
  • [ ] 拿到两个 AI 服务密钥:FAL_KEY(fal.ai 图像/视频生成)、OPENROUTER_KEY(LLM 剧本分析)

三、一键部署的两种方式

方式 1:Deploy to Cloudflare 按钮

在 docs/deployment/cloudflare.md 顶部有官方 Deploy 按钮。点击后它会:

  1. 把仓库克隆到你自己的账号下(注意:是独立克隆,不是 fork,想同步上游需手动加 upstream remote);
  2. 自动创建 wrangler.jsonc 里声明的 D1、R2 等资源;
  3. 弹出 .dev.vars.example 中列出的必填密钥输入框;
  4. 配置好 CI,之后每次 push 自动部署。

⚠️ AI 密钥(FAL_KEY、OPENROUTER_KEY)故意不在部署弹窗里——弹窗里没有可选项,填占位符比不填更糟。部署完成后再补:在应用内 Settings → API Keys 按团队配置,或用 wrangler secret put 设置服务级密钥。

方式 2:bun setup --prod 交互式引导

从自己的克隆(如 git clone https://gitcode.com/gh_mirrors/op/openstory)出发,这条命令会一步步引导你完成全部生产配置:生产环境变量(.env.production)、R2 域名 + CORS、可选服务、把密钥推送到 Cloudflare 和 GitHub,最后执行首次部署。

bun setup --prod      # 交互式生产配置 + 首次部署
bun setup --deploy    # 只重跑「推密钥 + 部署」阶段

如果你是手动部署老手,也可以直接跑(对应 package.json 中的 cf:deploy:prd 脚本):

bun cf:deploy:prd
# 等价于:wrangler types → CLOUDFLARE_ENV=production 构建
#         → D1 远程迁移 → wrangler deploy --env=production

四、部署成功后你会看到什么

OpenStory AI生成视频序列中的动画风格分镜画面

部署完成后打开你的域名,系统会在第一个请求时自动播种系统模板(src/platform/server/db/seed-system-templates.ts),把模板哈希存入 app_metadata,之后每个 isolate 只需一次 SELECT 校验,无需手动 seed。

随后你就可以像这样创建序列:粘贴剧本 → 选择风格 → 一键 Generate,平台会持续生成角色、场景、镜头视频,并保持一致的角色形象:

OpenStory生成的AI角色设定三视图,用于验证部署后生成能力

五、D1 迁移陷阱清单(重点)

这是全文最有价值的部分。OpenStory 用 drizzle-kit 生成迁移、用 wrangler d1 migrations apply 应用到远程 D1,两者之间存在几个隐蔽的坑。

陷阱 1:嵌套迁移目录会被静默读成 0 个文件

drizzle-kit 生成的迁移是嵌套结构:drizzle/migrations/<时间戳>_<名字>/migration.sql。但 wrangler d1 migrations apply 只认扁平的 *.sql 文件——对嵌套目录它不会报错,而是静默地"没有迁移可应用",部署照样变绿,数据库却没迁移。

解法是 scripts/flatten-migrations.ts:每次部署前把嵌套迁移渲染成扁平的 drizzle/migrations-wrangler/*.sql(gitignore,每次重建)。deploy / deploy:production / db:migrate:prd 这几个脚本都会自动先跑它。如果你自己拼命令迁移,切记先 flatten。

陷阱 2:表重建(table rebuild)+ CASCADE = 删库级事故

这是 OpenStory 在 2026-04-29 真实发生过的生产事故(#612)。原理:

  1. D1 把多语句迁移包进隐式事务,而 SQLite 在事务内静默忽略 PRAGMA foreign_keys = OFF;
  2. SQLite 标准的"表重建"模式(建新表 → 拷贝 → DROP 旧表 → RENAME)在 DROP 父表瞬间,所有指向它的 ON DELETE CASCADE 外键全部触发;
  3. 结果:team_members、session、account、passkey 被连根清空。PRAGMA defer_foreign_keys = ON 也救不了——它只推迟约束检查,CASCADE 照样触发。

项目定下的规则(详见 AGENTS.md 的 "D1 table-rebuild trap" 一节):

  • 优先用 ALTER TABLE … RENAME/ADD/DROP COLUMN,避免整表重建;
  • 对 user、teams、sequences 这类长生命周期父表,不要用 ON DELETE CASCADE,改用 restrict / no action,在应用代码里清理子表;
  • 确实必须重建时,按官方样例迁移 20261006232156_drop_character_legacy_columns 的做法:先放宽外键 → 文件头部加守卫(检测到 CASCADE 外键直接失败)→ 用"drop 后重建同名表再回填"代替 rename → 在生产的副本库 + 一次性远程 D1 上验证通过再合并。

本地还有一道护栏:scripts/check-migrations.ts 在提交前检查 DROP TABLE 等破坏性语句并标注入站 CASCADE 外键数量。

陷阱 3:CLOUDFLARE_ENV=production 缺失会"大声失败"

wrangler.jsonc 的默认块里 D1 的 database_id 是占位符 dev-local-d1,只指向本地 Miniflare,这是刻意设计的安全网。生产构建必须设置 CLOUDFLARE_ENV=production,它会在构建期把 [env.production] 块固化进 dist/server/wrangler.json;忘了设,部署会直接失败,而不是用错的库覆盖生产。另外生产块显式写了 "name": "openstory" 锁定 worker 名——否则 legacy_env 会部署出一个叫 openstory-production 的新 worker,部署"成功"但线上站点永远不更新。

陷阱 4:迁移只能走部署流水线,永远不要手工执行

D1 的迁移历史记在 wrangler 的 d1_migrations 表里,drizzle 的 __drizzle_migrations 它不认。历史上一份把库从 velro-prd 迁到 openstory-prd 的手册(docs/deployment/cloudflare.md "Prod database cutover" 一节)明确标注:只执行过一次,不要当作模式复用。日常场景下,任何迁移都只应通过合并 + 部署自动应用——不点 dashboard、不手跑 wrangler d1 execute、不手插 d1_migrations 记录。

陷阱 5:compatibility_date 不能随手调大

当前锁在 2026-10-08(见 wrangler.jsonc 与 src/platform/server/compatibility-date.test.ts),这是本地 workerd 二进制能启动的最新日期——调得更大,本地开发和 e2e 会直接拒绝启动。同时 enable_request_signal 没有默认日期、必须保留在 compatibility_flags 里,否则 SSE 断连后 Durable Object 的订阅和心跳不会释放。

六、避坑速查表

场景 正确做法
手动迁移远程 D1 先跑 bun scripts/flatten-migrations.ts,再 wrangler d1 migrations apply DB --remote
生产部署 带 CLOUDFLARE_ENV=production 构建,迁移步骤加 --env=production
改表结构 优先原生 ALTER TABLE,禁用对父表的 CASCADE 外键
补 AI 密钥 部署后 wrangler secret put FAL_KEY / 应用内 Settings → API Keys
升级 compatibility date 先确认新版 Wrangler 的 workerd 能启动该日期,再同步测试

相关文件速查

按这份清单走完,你的 OpenStory 实例就能稳定跑在 Cloudflare Workers 上,而 D1 迁移再也不会给你"惊喜"。🚀

登录后查看全文
openstory