---
title: "Cloudflare deployment adapter"
description: "Validate the four-worker Cloudflare topology and identify the resources that still block production deployment."
---

> Documentation Index
> Fetch the complete documentation index at: https://nexus.microvoid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare deployment adapter

## Outcome

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

> **External resources still required**
>
> Not production-deployable yet：在完成下列外部资源、Secret 和发布检查前，不要执行生产部署。 Gateway KV ID
> 仍为全零，Queues、Turnstile、生产 Keyring 和 API Secrets 尚未配置。 不要绕过仓库 readiness guard。

## 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

```sh title="Terminal"
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 数据集。

Source: https://nexus.microvoid.io/docs/deploy-nexus/cloudflare/index.mdx