operations

Cloudflare Workers 部署

Dashloom Cloud 会部署成一个 vinext Worker，同时包含静态资源、名为 `DB` 的 D1 Binding、两个 Cron Trigger 和 Workers 可观测性。`wrangler.jsonc` 是唯一的 Worker 配置来源。

Dashloom Cloud 会部署成一个 vinext Worker，同时包含静态资源、名为 DB 的 D1 Binding、两个 Cron Trigger 和 Workers 可观测性。wrangler.jsonc 是唯一的 Worker 配置来源。

1. 前置条件

Node.js 22.13 或更高版本，并已执行 npm ci。
本地使用 npx wrangler login 选择 Cloudflare 账号；CI 使用 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID。
确定公开 Origin，例如 https://app.example.com 或部署后分配的 workers.dev 地址。
准备生产 D1 数据库。只有在确认尚不存在时才创建：

npx wrangler whoami
npx wrangler d1 create dashloom-cloud-d1

把返回的 UUID 填入 wrangler.jsonc 的 d1_databases[0].database_id。生产环境不能保留 00000000-0000-4000-8000-000000000000。如果数据库已经存在，使用 npx wrangler d1 list，确认账号与数据库名称后再复制 ID。

如果使用自定义域名，先确定唯一规范 Origin，再加入：

"routes": [{ "pattern": "app.example.com", "custom_domain": true }]

2. 必填运行配置

可以在 Workers > Settings > Variables and Secrets 中填写，也可以执行 npx wrangler secret put NAME。wrangler.jsonc 已设置 keep_vars: true，以后部署不会删除 Dashboard 中维护的普通变量；Secret 始终由 Cloudflare 加密保存。

名称	填写要求
`BETTER_AUTH_SECRET`	至少 32 字符的随机值，不能与其他密钥复用。
`BETTER_AUTH_URL`	完整公开 HTTPS Origin，不带路径和末尾 `/`，例如 `https://app.example.com`。
`CREDENTIALS_ENCRYPTION_KEY`	另一份至少 32 字符的独立随机值。必须安全备份；更换或丢失后，已经保存的 Connector 凭证将无法解密。

在本地生成两份独立随机值：

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"

命令执行两次，分别保存为 BETTER_AUTH_SECRET 和 CREDENTIALS_ENCRYPTION_KEY。

3. 托管运营建议配置

名称	用途
`REPORT_CRON_SECRET`	独立随机值，用于保护手动 Cron 接口。原生 Cron Trigger 不会传这个值，但运营接口需要。
`DASHLOOM_OPERATOR_EMAILS`	可以进入运营/支持功能的登录邮箱，多个邮箱用英文逗号分隔。

当前计划为 */15 * * * * 和 17 3 * * *。Cloudflare Cron 使用 UTC，因此每日任务对应中国标准时间 11:17。

4. 按功能选填

Google Analytics 与 Search Console

填写 GOOGLE_OAUTH_CLIENT_ID、GOOGLE_OAUTH_CLIENT_SECRET，并在 Google Cloud 注册准确回调地址：

https://YOUR_ORIGIN/api/connectors/google/callback

Origin 必须与 BETTER_AUTH_URL 完全一致。详见 docs/google-cloud-setup.zh-CN.md。

Bing Webmaster Tools

Bing 不需要 Worker 环境变量。每个 Workspace 的 Owner 在 Dashboard > Sources 中输入 Bing Webmaster API Key；Dashloom 会使用 CREDENTIALS_ENCRYPTION_KEY 加密保存。

事务邮件

填写 RESEND_API_KEY，并在 RESEND_FROM_EMAIL 填写已通过 Resend 域名验证的发件人，例如 Dashloom <auth@example.com>。在真实收到验证邮件并测试链接之前，保持 AUTH_REQUIRE_EMAIL_VERIFICATION=false，验证成功后再改为 true。

Waffo 与 Anyway 计费

Waffo 需要填写 WAFFO_MODE、WAFFO_MERCHANT_ID、WAFFO_PRIVATE_KEY_BASE64 和三个 WAFFO_PRODUCT_*；Webhook 地址为：

https://YOUR_ORIGIN/api/billing/webhook/waffo

Anyway 需要填写三个 ANYWAY_PAYMENT_LINK_* 和对应的 ANYWAY_PRODUCT_*；Webhook 地址为 https://YOUR_ORIGIN/api/billing/webhook/anyway。两个渠道都必须先完成测试结账、签名 Webhook、续费、取消与权益变更验证，再启用正式付款。详见 docs/payment-billing.zh-CN.md。

托管 AI

Dashloom Cloud 的套餐内托管模型统一使用 kie.ai。填写 KIE_AI_API_KEY 后启用，默认接入 kie.ai 的 OpenAI 兼容 Gemini 3 Flash 接口：

KIE_AI_BASE_URL=https://api.kie.ai/gemini-3-flash/v1
KIE_AI_MODEL=gemini-3-5-flash-thinking
KIE_AI_API_KEY=...

服务端会把 Base URL 限制在官方 api.kie.ai 主机。切换其他 kie.ai 对话模型时，必须同时修改 Base URL 路径和 Model。未填写 KIE_AI_API_KEY 时，用户仍可连接 BYOK Provider，但不能使用托管 AI。

5. 生产数据库门禁

数据库迁移是独立且明确的发布步骤。Worker 上传成功不代表生产 D1 已经是最新状态。

npm run config:check
npx wrangler d1 info dashloom-cloud-d1 --json
npm run db:status:remote
npm run db:migrate:remote
npm run db:status:remote
npx wrangler d1 execute dashloom-cloud-d1 --remote --command "SELECT name FROM sqlite_schema WHERE type='table' AND name IN ('user','session','workspaces','connector_accounts','metric_points') ORDER BY name"

必须确认输出的 D1 UUID 与 wrangler.jsonc 一致、没有待执行迁移，并且查询中的五张表全部存在。已有生产数据时，执行 Schema 变更前先备份。

6. 校验与部署

npm ci
npm run typecheck
npm run lint
npm test
npm run config:check
npm run deploy:dry-run
npm run deploy

deploy:dry-run 会构建 vinext 并校验生成的 dist/server/wrangler.json，不会上传。deploy 会构建并上传 Worker，但不会执行 D1 迁移。

部署后检查：首页、注册、登录、Workspace 创建、至少一个 Connector 保存与同步、Cron Trigger 历史、Worker 日志；启用 Google 后检查 OAuth 回调，启用邮件后检查 Resend 投递，启用计费后分别检查对应渠道的测试 Checkout 与 Webhook。