Deploy Nexus

Choose a Node/Docker or Cloudflare adapter while keeping PostgreSQL authoritative and components independently reversible.

Outcome

选择一个 Runtime Adapter，明确 PostgreSQL、Admin API、Gateway、Worker 和 Console 的所有权，并在发布前验证迁移、健康检查、Secret 边界、监控和回滚路径。

Deployment topology

Console ───────→ Admin API/Auth
Client SDK ────→ Gateway ─────→ Provider
                    │
Admin API ──────────┼─────────→ PostgreSQL (authoritative)
Worker ─────────────┘           Access / Quota / Usage / Outbox

Cloudflare 与 Node/Docker 是相同 Application Core 的 Adapter。PostgreSQL 始终是 Access、Quota Reservation、Settlement 和 Usage 的事实源；不要用 KV、D1、Durable Objects、Analytics Engine 或进程内内存替代它。

Choose an adapter

Adapter	Current repository state	Use it for
Node and Docker	本地 Compose 可执行；生产需补齐外部 Secret、TLS、备份和基础设施	常规容器/VM 平台、本地黄金路径
Cloudflare	Worker Dry-run 可验证；占位资源和生产 Keyring 配置阻止生产部署	评审四入口拓扑与资源准备度

Configuration classes

Class	Examples	Rule
Database	`DATABASE_URL`	TLS、最小权限、备份/恢复演练；不能暴露给 Console
Auth	`BETTER_AUTH_URL`, `BETTER_AUTH_SECRET`	生产 Secret 至少 32 随机字节；Captcha 开启时服务端验证
Provider encryption	`NEXUS_PROVIDER_SECRET_DRIVER`, key version/material	加密材料只在 Server/Resolver；支持版本化轮换
Origins	`NEXUS_CONSOLE_ORIGIN`, `NEXUS_GATEWAY_ORIGIN`, `VITE_API_BASE_URL`	区分服务端 Origin 与公开 build-time Origin
Runtime	Ports、Worker poll、grace period	Health probe 与平台 termination grace 协调

Database migrations

发布采用 Expand/Contract：

expand schema
→ deploy API/Worker compatible readers
→ deploy Gateway
→ deploy Console/SDK
→ switch traffic
→ verify SLI and Quota invariants
→ later contract cleanup

迁移必须由受控发布步骤执行，不由每个应用实例抢跑。发布前保留近期备份和已演练恢复流程；常规应用回滚保留 Expand Schema，不要直接覆盖线上 Quota 真值。

Observability and health

至少监控 Admin、Gateway、Worker、Console Readiness，数据库连接，Queue/Outbox Lag，Reservation aging，Quota balance invariant，Provider/Nexus latency，5xx 和 Gateway 错误码。把 deploy/observability/nexus-beta-slo.json 导入选定的 OpenTelemetry/PostgreSQL Adapter，并验证告警能到达发布负责人。

Release and rollback

执行仓库 Release runbook 的质量门槛，记录 Artifact Digest 和前一已知良好版本。按依赖顺序逐步切流；发生 Quota 超支、重复结算、Secret 暴露、跨租户访问、Webhook 重复授额、无界 Queue Lag 或无法解释的显著延迟回归时停止发布。

回滚时先停新切流，恢复前一应用 Artifact，保持数据库 Expand Schema，最后验证 Reservation/Usage 对账。只有独立恢复环境和后续 Reconciliation 才能使用时间点数据库恢复。

Check your work

每个组件的 Readiness 和关闭 Grace Period 已由部署平台验证。
PostgreSQL 备份可恢复，Migration 顺序与旧 Writer 兼容。
生产 Secret 不在镜像、公开变量、Manifest、日志或仓库中。
Gateway、API、Worker、Console 可独立回滚，并能通过 Request ID 关联一次调用。