开发环境概览

Nebutra-Sailor 单体仓库简介 — 每个应用的功能介绍、工作区组织结构，以及如何开始贡献代码。

什么是 Nebutra-Sailor？

Nebutra-Sailor 是一个 Turborepo 单体仓库，以可运行代码的形式提供完整的 AI 原生 SaaS 产品。它包含 7 个可独立部署的应用和 20+ 个共享包，从头到尾均有完整类型定义，共享同一套设计系统、API 契约和运行时 Token 系统。

该仓库是 nebutra.com、app.nebutra.com、auth.nebutra.com、api.nebutra.com 与 nebutra.com/docs 的源码真相来源。

应用一览

应用	端口	用途	框架
`apps/web`	3000 / 3001	已认证 SaaS 控制台	Next.js 16（生产）+ 可选 Vite
`apps/auth`	3101	登录中心 `auth.nebutra.com`	Next.js 16 + Better Auth
`backends/gateway`	3002	REST API — 认证、RBAC、计费、AI 代理	Hono（`@nebutra/gateway`）
`apps/landing`	—	公开营销网站	Next.js 16 + next-intl
`apps/sailor-docs`	—	公开产品文档（本站）	Next.js 16 + Fumadocs
`apps/design-docs`	—	内部设计系统文档	Next.js 16 + Fumadocs
`apps/storybook`	6006	组件库演示平台	Storybook
`apps/studio`	3333	内容管理	Sanity Studio

前置条件

在运行单体仓库之前，您需要在本机安装以下工具。

工具	最低版本	用途
Node.js	22.x	所有应用和工具链的运行时
pnpm	10.32+	Workspace 包管理器
Docker	24+	本地 PostgreSQL、Redis 和 ClickHouse
Git	2.40+	源代码管理

本仓库使用 pnpm workspaces。运行 npm install 或 yarn install 会产生错误结果，不受支持。

快速开始

git clone https://github.com/nebutra/nebutra-sailor.git
cd nebutra-sailor

pnpm install

pnpm infra:up

此命令通过 Docker Compose 启动 PostgreSQL 16、Redis 7 和 ClickHouse 24。

复制示例环境变量文件并填写您的密钥：

cp apps/web/.env.example apps/web/.env.local
cp apps/auth/.env.example apps/auth/.env.local   # 若存在
cp backends/gateway/.env.example backends/gateway/.env.local
cp apps/landing/.env.example apps/landing/.env.local
# 本地建议 AUTH_PROVIDER=better-auth，与生产一致

pnpm db:generate   # 生成 Prisma 客户端
pnpm db:migrate    # 执行所有待执行的迁移
pnpm db:seed       # 填充开发测试数据

pnpm dev           # 并行启动所有应用

或者仅启动您需要的部分：

pnpm dev:dashboard   # web + gateway（见根 package.json scripts）
pnpm dev:marketing   # landing + studio

如需了解完整的环境变量说明、常见问题和端口分配，请参阅本地开发指南。

关键约定

包管理器： pnpm 10.32+，使用 workspaces。请始终在仓库根目录运行 pnpm。

Linter + 格式化： Biome（替代 ESLint + Prettier）。运行 pnpm lint:fix 自动修复。

类型检查： pnpm typecheck 通过 Turbo 在所有包中运行 tsc --noEmit。

测试： 单元测试使用 Vitest，E2E 测试使用 Playwright。运行 pnpm test 和 pnpm e2e。

构建系统： Turborepo，支持 Vercel Remote Cache。任务定义在 turbo.json 中。

什么是 Nebutra-Sailor？

应用一览

前置条件

快速开始

关键约定

相关内容

项目结构

本地开发

编辑器配置

更新升级

目录