Run Nexus locally

Start the PostgreSQL, Admin API, Gateway, and Console development composition on loopback.

Goal

在本机启动 Nexus PostgreSQL、Admin API、Node Gateway 和 Console，并准备好执行与部署环境相同的 Workspace 接入流程。

Outcome

Console 位于 http://localhost:5173，Admin API 位于 http://localhost:3000，内部 Node Gateway 位于 http://localhost:4000。开发时 Console 的 /providers/* 会代理到 Gateway，因此 Console 复制的用户 Base URL 可直接使用 5173 Origin。

Who this is for

需要本地开发、评审部署 Adapter 或在不修改产品契约的情况下复现黄金路径的自部署工程师。

Prerequisites

Node.js 22.12+ 和仓库声明的 pnpm 版本。
Docker（推荐用于 PostgreSQL），或支持 PostgreSQL wire protocol 的 PGlite 本地模式。
未占用的 3000、4000、5173 和 PostgreSQL 端口。

1. Install and configure

在仓库根目录运行：

Terminalsh

pnpm install --frozen-lockfile
cp .env.example .env

2. Start PostgreSQL

使用 Docker 只启动本地 PostgreSQL：

Terminalsh

docker compose --env-file .env -f deploy/docker-compose/compose.yaml up -d postgres
pnpm db:migrate

没有 Docker 时，在一个终端启动持久化 PGlite wire server，再从另一个终端迁移：

Terminal 1sh

pnpm db:local

Terminal 2sh

DATABASE_URL=postgresql://postgres@127.0.0.1:5432/postgres pnpm db:migrate:local

3. Start Nexus

Terminalsh

pnpm dev

该命令启动仓库现有的开发 Composition。不要把 Vite Console Proxy 误认为生产拓扑；生产环境仍独立部署 Console 和 Gateway。

4. Check readiness

Terminalsh

curl --fail http://localhost:3000/health/ready
curl --fail http://localhost:4000/health/ready
curl --fail --head http://localhost:5173/

Admin Swagger 位于 http://localhost:3000/admin/docs。它只用于查看本地契约；公开 API Reference 仍由仓库接受的 OpenAPI 文件生成。

5. Complete the golden path

打开 Console，按 Add Nexus to my product 创建 Workspace、ProviderConnection、Plan 和用户。只输入你授权用于本地测试的 Provider 凭证，并使用该 Provider 接受的原始模型名。

Check your work

Admin 和 Gateway readiness 返回成功，Console 根页面可访问。
PostgreSQL 中已应用仓库迁移，而不是由应用进程临时创建表。
Gateway Base URL 使用不可变 providerConnectionId UUID。
一次测试请求能在 Console 的 Usage 和 Activity 中按应用用户归因。

What Nexus stored

本地 PostgreSQL 保存 Access、Quota Reservation、Usage 与管理事实；Provider Secret 使用 .env 指定的本地加密 Driver 保存。停止进程不会把这些事实改成内存真值。

What the user received

通过本地 Console Provision 的用户仍只接收 Inference Key 和 Gateway Base URL，不接收 Provider 或 Management 凭证。

Troubleshooting

PostgreSQL 未就绪：检查 Compose health、端口占用和 .env 的 DATABASE_URL。
Admin 可用但 Gateway 不可用：检查 NEXUS_GATEWAY_PORT 和 Gateway 日志，不能绕过 PostgreSQL/Quota。
5173 请求失败：确认 Vite 与 Gateway 都在运行；开发 Proxy 只转发 /providers/*。
迁移错误：不要手工修改数据库结构；回到仓库迁移和错误输出定位。

Next steps

完成本地黄金路径后，使用 Use my Nexus access 验证独立应用用户视角。按 Ctrl-C 停止开发进程；Docker PostgreSQL 可用以下命令停止：

Terminalsh

docker compose --env-file .env -f deploy/docker-compose/compose.yaml down