Skip to content
Nexus

Cloudflare deployment adapter

Validate the four-worker Cloudflare topology and identify the resources that still block production deployment.

Updated View as Markdown
Audience: operatorPlane: operationsAuth: noneStatus: preview

Outcome

对四个 Cloudflare Worker 做本地类型生成和 Dry-run Bundle，并得到一份明确的生产阻塞项清单。nexus-api 通过 Cloudflare Node HTTP bridge 在 Worker isolate 内运行完整 NestJS 服务，不依赖 Container 或单独的 Origin。

Four deployment units

Worker Responsibility Required resources
nexus-gateway Streaming Gateway、Access、凭证解析、遥测生产者 Admin Service Binding、Hyperdrive、Secret Keyring、KV Cache、Queue
nexus-api Worker isolate 内的完整 NestJS Admin/Auth/Webhook 运行时 Hyperdrive、API Secrets、Node HTTP compatibility
nexus-console 静态 Console 与内部控制面转发 Static Assets、API Service Binding
nexus-worker Outbox Publisher/Queue Consumer、Reservation recovery、Billing reconciliation Hyperdrive、Queue/DLQ、Cron、API Binding

KV 只允许 Cache，Queue 只承载可恢复的异步/遥测路径；二者都不是 Access、Quota 或 Usage 真值。

Local validation

Terminalsh
pnpm --filter @nexus/deploy-cloudflare wrangler:types
pnpm --filter @nexus/deploy-cloudflare wrangler:check
pnpm --filter @nexus/deploy-cloudflare audit:production:infrastructure
pnpm --filter @nexus/deploy-cloudflare audit:production
pnpm --filter @nexus/deploy-cloudflare smoke:production
pnpm --filter @nexus/deploy-cloudflare test
pnpm --filter @nexus/deploy-cloudflare typecheck

wrangler:check 为四个核心入口以及仓库中单独检入的 Connector Adapter 执行 Dry-run Bundle，并构建 Console；它不上传代码或修改 Cloudflare Account。Nexus 核心生产拓扑仍是本页列出的四个部署单元。

两个 audit:production* 命令同样是只读检查。Infrastructure 阶段验证 Hyperdrive、KV、 Queues、Turnstile hostname 和 Email Sending；Full 阶段额外验证五个部署单元及 required Secret 名称，不读取 Secret 值。权限不足、资源缺失或配置不一致都会失败关闭。

smoke:production 同样只读，验证 Console、API 健康状态、Docs 和 Gateway 非法路由的安全 响应，不创建用户、Key、Quota Reservation，也不会调用上游 Provider。

Provisioning checklist

通过经批准的 IaC/基础设施流程创建：

  1. nexus-api、Gateway 和 Worker 使用的受审计 Hyperdrive 配置。
  2. 只存非权威缓存的 nexus-cache KV Namespace。
  3. nexus-events Queue 和 nexus-events-dlq。
  4. 指向规范 PostgreSQL 的 Hyperdrive 配置，私网数据库使用 TLS 或 Workers VPC。
  5. 为 Gateway 和 nexus-api 注入同一套 Provider Secret Keyring。

随后替换 Manifest 的全零 ID，以只读 Account Inspection 确认资源确实存在，并通过 Worker Secrets 注入 API 生产配置。nexus-api 没有公网 Route；https://nexus.microvoid.io/api/* 由 Console Service Binding 转发。依赖顺序是 nexus-api，随后 Worker、Gateway、Console。

实际发布身份还必须拥有 Turnstile 和 Email Sending 的只读/写入权限；否则自动审计无法证明 Widget hostname 与发信域状态，发布脚本会拒绝继续。

现有完整迁移历史逐条 checksum-locked。生产迁移必须通过 pnpm db:migrate:production 的只读状态检查；空库和锁定历史的连续前缀可以安全前进， 非连续、非 Prisma 管理或陌生迁移历史会被拒绝。 Worker 每分钟把已提交 Outbox Event ID 发布到 Queue，并在 Consumer 中按 ID 幂等处理；Reservation Recovery 和 Billing Maintenance 保持五分钟一次。

Observability

Manifest 默认采样 10% Invocation Log 和 1% Trace。上线前根据真实流量、成本和事故响应需要调整；采样不能成为丢失 Quota/Usage 事实的理由，权威事实仍写 PostgreSQL。

Release guard

deploy:gateway、deploy:api、deploy:worker 和 deploy:console 会先运行 assert-deploy-ready.mjs 拒绝占位值。只有所有资源、Secret 所有权、迁移、备份、告警和回滚责任都已评审，才可以由授权发布流程调用这些会改变外部状态的脚本。

首次 API/Gateway 部署使用 Wrangler --secrets-file，文件必须位于仓库外。Console 生产构建必须 显式提供公开的 VITE_TURNSTILE_SITE_KEY，否则部署脚本会失败；Turnstile Secret 只进入 API Worker Secret。

Check your work

  • Types、Dry-run、测试和 Typecheck 全部通过。
  • Readiness Guard 在占位值或旧 NESTJS_ORIGIN 再次出现时按预期失败。
  • Provider API Key 不进入 Worker Variables；Gateway 解密 Keyring 只通过 Cloudflare Secret 注入。
  • Hyperdrive 最终指向与 Node Adapter 相同的权威 PostgreSQL 数据集。
Navigation

Type to search…

↑↓ navigate↵ selectEsc close