Tanplate Docs

Workers、D1、R2、Secrets、三环境规划、Production runbook 和三应用部署方式。

资源清单

Cloudflare 资源	名称	使用方	作用
Worker	`<project>`	Web	Landing 与当前 Profile 的同源 UI/API
Worker	`<project>-admin`	Admin（可选部署）	用户核心与已启用模块的管理/审计
Worker	`<project>-docs`	Docs（可选部署）	Fumadocs 页面、搜索和 LLM 输出
D1	`<project>`	启用的数据消费者	Auth/Projects/平台模块的关系事实
R2	`<project>-project-assets` / `<project>-user-assets`	对应模块消费者	Projects 与 User Assets 隔离私有对象

本地状态

Web 的 Wrangler 状态目录是本地 D1/R2 的单一来源。Admin 显式将 persistState 指向 Web 的状态目录；Docs 没有业务 binding，不参与共享状态。

初始化后执行 pnpm check:environment。命令先解析 Manifest，只读取当前 target 中 deploy=true 的应用，并只提取 Local .dev.vars 等号左侧名称。Authentication 开启时要求 Auth origin、RateLimit、Turnstile 和已选 Social Provider；只有 emailAndPassword 或 Newsletter 开启时才要求 AUTH_DELIVERY_ENVIRONMENT/Resend。D1/R2/Queue/AI 只在有消费者时校验。Preview preflight 只读取非继承的有效 environment，不回退 Production；Local 无需 Cloudflare account/token 或远程资源 ID。

Preview 规划

pnpm plan:preview -- --ref refs/heads/feature/demo --production-ref main

命令只读取本地 Manifest 和显式 Git/生命周期元数据，输出 preview/<id> identity、Manifest 启用的 Worker/D1/R2/KV/Queue inventory，以及 keep、report-only 或 cleanup-eligible 决策。PR 使用 pr-<number>；分支使用规范化名称加 ref 的 8 位 SHA-256。资源名超出 Provider 长度时保留完整名称 hash。

最后一次成功部署续期 7 天；PR 关闭后保留 24 小时。只有 recorded inventory 完全匹配、名称带 Preview 标记、TTL/grace 已过且没有部署进行中时才报告可清理。该 CLI 没有 GitHub/Cloudflare 客户端，不创建、部署或删除资源。

Deployment dry-run

pnpm plan:deployment -- --target local
PRODUCTION_REF=master
pnpm plan:deployment -- --target production --ref "refs/heads/$PRODUCTION_REF" --production-ref "$PRODUCTION_REF" --variable CLOUDFLARE_ACCOUNT_ID --secret deployment:CLOUDFLARE_API_TOKEN --secret web:BETTER_AUTH_SECRET --secret web:RESEND_API_KEY

该命令复用同一环境 preflight，输出 selected apps、资源/secret 名称、前置步骤与 blocked reasons。所有 step 都是 executable=false；Production 只接受声明 ref，并固定为 runbookOnly=true。参数只声明 secret 名称，不携带值。

Production runbook

仓库根 ai-docs/production-runbook.md 按 build、resource、remote migration、Admin bootstrap、secret、deploy 分段执行。资源创建和每个远程步骤都必须展示目标、获得在场批准、完成验证与恢复检查；自动 CI 只运行合成 dry-run。仓库不提交真实 D1 UUID、账号专属 workers.dev 域名或 Production secret，也不向环境预置 Project 业务数据。

部署

pnpm deploy:web
pnpm deploy:admin
pnpm deploy:docs

三个公开命令都会从脚本位置读取根 Manifest，在 deploy/skip 前拒绝生成快照漂移，并在真实部署前检查全部 initializer 受管配置。Web 固定部署；Admin/Docs 仅在 apps.<app>.deploy=true 时执行内部 Worker 部署，否则明确跳过。D1/R2 只在 Profile 需要时创建；若 Web/Admin 同时消费相同模块，它们共享 target-specific 资源。可用 node scripts/deploy-app.mjs --app <app> --dry-run 只查看计划。

三个应用无论 deploy flag 都执行 build；build 结束后删除 dist 内 .dev.vars / .env*，并扫描 build 与 Git tracked 文件是否含本地 secret 值。命中只报告文件与变量名，不打印值。

最小权限

Docs 不绑定 D1/R2。Admin 只获得已部署管理能力需要的 D1/R2，Web 也只获得当前 Profile 需要的资源；上传鉴权和对象 key 规则必须留在 Worker 服务端。

Cloudflare