---
title: "Deploy Nexus"
description: "Choose a Node/Docker or Cloudflare adapter while keeping PostgreSQL authoritative and components independently reversible."
---

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

# Deploy Nexus

## Outcome

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

## Deployment topology

```text
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](/docs/deploy-nexus/node-docker) | 本地 Compose 可执行；生产需补齐外部 Secret、TLS、备份和基础设施 | 常规容器/VM 平台、本地黄金路径 |
| [Cloudflare](/docs/deploy-nexus/cloudflare)       | Worker Dry-run 可验证；占位资源和生产 Keyring 配置阻止生产部署  | 评审四入口拓扑与资源准备度     |

> **Adapter readiness is not production readiness**
>
> 仓库中的 Compose 使用 development Profile；Cloudflare Manifest
> 含明确占位值。完成页面中的门槛之前，不要把任一配置直接当作生产模板。

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

```text
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](https://github.com/example/nexus/blob/main/docs/RELEASE_RUNBOOK.md) 的质量门槛，记录 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 关联一次调用。

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