本地开发
在本机运行 Nebutra-Sailor 单体仓库的完整分步指南 — 从安装 Node.js 到数据库填充数据。
前置条件
开始之前，请确保已安装以下工具：
- Node.js 22+ — nodejs.org 或使用 nvm
- pnpm 10.32+ —
npm install -g pnpm - Docker Desktop 24+ — docker.com/products/docker-desktop
- Git 2.40+ — git-scm.com
分步配置
# 使用 nvm（推荐）
nvm install 22
nvm use 22
# 验证
node --version # v22.x.xnpm install -g pnpm@latest
# 验证
pnpm --version # 10.32.x 或更高git clone https://github.com/nebutra/nebutra-sailor.git
cd nebutra-sailorpnpm install此命令安装所有应用和包的 workspace 依赖。首次运行可能需要 2–3 分钟。
pnpm infra:up此命令通过 docker-compose.infra.yml 启动三个容器：
- PostgreSQL 16，端口
5432 - Redis 7，端口
6379 - ClickHouse 24，端口
8123
如果只需要数据库（无需 Redis 或 ClickHouse），请改用 pnpm infra:lite。
为您计划运行的每个应用复制示例文件：
cp apps/web/.env.example apps/web/.env.local
cp backends/gateway/.env.example backends/gateway/.env.local
cp apps/landing/.env.example apps/landing/.env.local然后打开每个 .env.local 文件并填写您的密钥。完整的变量参考请参阅下方的环境变量章节。
pnpm db:generate此命令使用 packages/platform/db/prisma/schema.prisma 中的 Schema 运行 prisma generate。
pnpm db:migrate此命令将所有待执行的 Prisma 迁移应用到您的本地 PostgreSQL 实例。
pnpm db:seed向数据库填充测试组织、用户和示例数据，让您可以立即登录。
pnpm dev通过 Turborepo 并行启动所有应用。
pnpm dev:dashboard启动 apps/web（端口 3000）和 backends/gateway（端口 3001）。
pnpm dev:marketing启动 apps/landing（端口 3002）和 apps/studio（端口 3333）。
所有应用均支持热模块替换（HMR）。对源文件的修改无需完整页面刷新即可立即生效。
端口映射
| 服务 | URL | 备注 |
|---|---|---|
| SaaS 控制台 | http://localhost:3000 | 需要 Clerk 认证 |
| API 网关 | http://localhost:3001 | REST API，OpenAPI 文档位于 /doc |
| 营销网站 | http://localhost:3002 | 7 种语言，默认为 /en |
| 设计文档 | http://localhost:3004 | 仅内部使用 |
| Storybook | http://localhost:6006 | 组件库 |
| Sanity Studio | http://localhost:3333 | 内容管理 |
| PostgreSQL | localhost:5432 | 数据库 |
| Redis | localhost:6379 | 缓存和队列 |
| ClickHouse | localhost:8123 | 使用量计量 |
环境变量
backends/gateway
| 变量 | 是否必填 | 说明 |
|---|---|---|
DATABASE_URL | 是 | PostgreSQL 连接字符串，例如 postgresql://postgres:postgres@localhost:5432/nebutra |
REDIS_URL | 是 | Redis 连接字符串，例如 redis://localhost:6379 |
AUTH_PROVIDER | 否 | 认证提供商：better-auth、nextauth、clerk、supabase 或 dev |
NEXT_PUBLIC_AUTH_PROVIDER | 否 | 客户端可见的认证提供商；应与 AUTH_PROVIDER 保持一致 |
CLERK_SECRET_KEY | 使用 Clerk 时 | Clerk 后端 API 密钥 — 从 Clerk 控制台获取 |
CLERK_PUBLISHABLE_KEY | 使用 Clerk 时 | Clerk 可发布密钥 |
STRIPE_SECRET_KEY | 是 | Stripe 密钥 |
STRIPE_WEBHOOK_SECRET | 是 | Stripe Webhook 签名密钥 |
CLERK_WEBHOOK_SECRET | 使用 Clerk Webhook 时 | Clerk Webhook 签名密钥 |
CLICKHOUSE_URL | 是 | ClickHouse HTTP 接口 URL |
QUEUE_PROVIDER | 否 | qstash、bullmq 或 memory（自动检测） |
PERMISSIONS_PROVIDER | 否 | casl（默认）或 openfga |
apps/web
| 变量 | 是否必填 | 说明 |
|---|---|---|
AUTH_PROVIDER | 否 | 服务端路由选择的认证提供商 |
NEXT_PUBLIC_AUTH_PROVIDER | 否 | 客户端代码和 Landing One Tap 选择的认证提供商 |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | 使用 Clerk 时 | Clerk 可发布密钥 |
CLERK_SECRET_KEY | 使用 Clerk 时 | Clerk 后端 API 密钥 |
BETTER_AUTH_SECRET | 使用 Better Auth 时 | Better Auth 自托管签名密钥 |
AUTH_SECRET | 使用 NextAuth 时 | Auth.js / NextAuth 签名密钥 |
GOOGLE_CLIENT_ID | 使用 Google OAuth 时 | Google OAuth Web Client ID |
GOOGLE_CLIENT_SECRET | 使用 Google OAuth 时 | Google OAuth Web Client Secret |
NEXT_PUBLIC_API_URL | 是 | API 网关的基础 URL，例如 http://localhost:3001 |
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY | 是 | 客户端计费所用的 Stripe 可发布密钥 |
DATABASE_URL | 是 | PostgreSQL 连接字符串（用于 Server Actions） |
apps/landing
| 变量 | 是否必填 | 说明 |
|---|---|---|
NEXT_PUBLIC_SANITY_PROJECT_ID | 是 | Sanity 项目 ID |
NEXT_PUBLIC_SANITY_DATASET | 是 | Sanity 数据集名称，例如 production |
NEXT_PUBLIC_AUTH_PROVIDER | 否 | 用于选择 Landing One Tap 行为的认证提供商 |
NEXT_PUBLIC_GOOGLE_CLIENT_ID | 启用 Better Auth 或 NextAuth One Tap 时 | 公开 Google OAuth Web Client ID |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | 启用 Clerk One Tap 时 | Clerk 可发布密钥 |
SANITY_API_TOKEN | 否 | Sanity 读取 Token（草稿预览时需要） |
所有环境变量在启动时由 @nebutra/config 验证。如果缺少必填变量，进程会立即崩溃并显示详细的错误信息 — 不会有静默失败。
首次运行常见问题
"Cannot find module '@prisma/client'"
您需要先生成 Prisma 客户端：
pnpm db:generate"Error: connect ECONNREFUSED 127.0.0.1:5432"
PostgreSQL 未运行。启动基础设施容器：
pnpm infra:up"Error: connect ECONNREFUSED 127.0.0.1:6379"
Redis 未运行。使用 pnpm infra:up（不要使用 pnpm infra:lite，后者会跳过 Redis）。
端口已被占用
其他进程正在使用该端口。找到并终止它：
lsof -ti:3000 | xargs kill # 释放端口 3000
lsof -ti:3001 | xargs kill # 释放端口 3001pnpm 版本不匹配
本仓库要求 pnpm 10.32+。请升级：
npm install -g pnpm@latest运行单独的命令
pnpm typecheck # 跨所有包进行 TypeScript 检查
pnpm lint # Biome 代码检查
pnpm lint:fix # Biome 代码检查并自动修复
pnpm test # Vitest 单元测试
pnpm test:coverage # 带覆盖率报告的单元测试
pnpm test:arch # 架构边界测试
pnpm e2e # Playwright E2E（无界面模式）
pnpm e2e:ui # 带交互界面的 Playwright E2E
pnpm build # 生产构建（所有应用）相关内容
How is this guide?
最后更新于