create-sailor | Nebutra Sailor Docs

交互式脚手架向导——几秒钟内引导你完成 Nebutra-Sailor 生产级项目的初始化。

create-sailor 是一次性脚手架工具，它会克隆 Nebutra-Sailor 模板，通过配置问题引导你完成设置，并写入 .env.local——让你在不到一分钟内就能开始编码。

已发布 npm 包：[email protected]（可用 npx create-sailor@latest 拉取当前版）。

脚手架默认偏向快速上手（--auth clerk、--deploy vercel）。第一方 nebutra.com 生产使用 Better Auth 登录中心 auth.nebutra.com（ECS）， app/API 亦在 ECS——若要对齐该拓扑，请选 --auth betterauth 与 --deploy selfhost（或自行对接 ECS）。

执行流程

提示输入目标目录（默认：./my-saas-app）。

仅 4 个交互问题：项目目录、Region、Auth、AI 拓扑。其余设置全部通过标志或基于 Region 的默认值解析。

自动生成随机 AUTH_SECRET / JWT_SECRET，并写入带服务商占位 Key 的 .env.local，稍后填入真实密钥即可。

克隆 Nebutra-Sailor 仓库，在 package.json 中设置项目名称，写入 nebutra.config.json，裁剪未使用的模板功能，并注入环境变量。

显示接下来要运行的命令：cd my-saas-app && pnpm install && pnpm dev。

交互式问答

向导只问 4 个问题，其余设置全部由标志或 Region 默认值解析：

项目目录 —— 默认 ./my-saas-app

Region —— global | cn | hybrid

认证服务商 —— clerk | betterauth | nextauth | none

AI 拓扑 —— gateway（推荐）| direct | custom | none。选择 direct 会追问 Provider 适配器多选；选择 custom 会追问端点名、Base URL 和 API Key 环境变量名。

其余（ORM、数据库、支付、邮件、存储……）均为标志驱动。

核心标志

标志	取值	默认
`--region`	`global`、`cn`、`hybrid`	`global`
`--orm`	`prisma`、`drizzle`	`prisma`（选 `drizzle` 进入双 ORM 模式：在 Prisma 旁追加 `db-drizzle`）
`--db`	`postgres`、`mysql`、`sqlite`、`none`	`postgresql`
`--db-host`	`local`、`supabase`、`neon`、`vercel-postgres`、`planetscale`、`railway`、`aliyun-rds`、`tencent-cdb`、`none`	基于 Region（global 选 `supabase`，cn 选 `local`）
`--auth`	`clerk`、`betterauth`、`nextauth`、`none`	`clerk`
`--payment`	`stripe`、`lemon`、`wechat`、`alipay`、`none`	`stripe`（global）/ `wechat`（cn）
`--ai`	拓扑速写（`gateway`、`direct`、`custom`、`none`）或逗号分隔的 Provider ID	`gateway`
`--deploy`	`vercel`、`railway`、`cloudflare`、`selfhost`、`none`	`vercel`
`--docs`	`fumadocs`、`none`（v1.x 中其他值会回退到 fumadocs）	`fumadocs`
`-y`, `--yes`	（开关）接受所有默认值，非交互模式	关
`--dry-run`	（开关）打印计划但不写入文件	关
`--json`	（开关）机器可读的事件流输出	关

--db-host=planetscale 指 PlanetScale Postgres。Vitess/MySQL 产品需要单独的 Prisma schema 和迁移策略，才能作为生产级 Sailor runtime 支持。

完整的按功能标志（--email、--storage、--monitoring、--analytics、--sms、--queue、--search、--cache、--notifications、--webhooks、--cms、--feature-flags、--captcha、--mcp、--metering、--billing-mode、--idp 等）请执行 npx create-sailor --help。

进阶标志

脚手架扩展

标志	效果
`--with-workflows`	添加 `workflows/{inngest,n8n,pusher}/` 起始目录，便于稍后通过 `nebutra workflow init` 选择服务商。
`--with-python-backend`	添加 `backends/python/` FastAPI 存根。仅当 TS-by-Default ADR 例外成立时启用——批处理 / 队列任务、机器学习 / 科学计算、或无对应 TS 端口的专用库。生成的 README 会要求你声明引用的具体理由。
`--no-install`	跳过脚手架完成后的 `pnpm install`。
`--no-git`	跳过 `git init` 和初始提交。
`--no-color`	关闭 stdout 的 ANSI 颜色（适配 CI）。

合规 / Wave-3 开关

均接受 true / false，默认 true；--china-compliance 在 --region=cn 时自动翻转为 true。

--cron-jobs、--audit-log、--api-keys、--command-palette、--cookie-consent、--legal-pages、--china-compliance。

Wave-2 治理

标志	取值	默认
`--billing-mode`	`usage`、`seat`、`credits`	`usage`
`--idp`	`clerk`、`oauth-server`	`clerk`
`--social-login`	中国社交登录（`wechat,qq,dingtalk,workweixin,feishu,weibo`，逗号分隔）	无

包版本策略

生成的项目中 @nebutra/* 包以 npm caret 区间（如 "@nebutra/ui": "^0.1.0"）声明，而不是 workspace:*。正因如此，create-sailor 生成的仓库可以脱离 Nebutra-Sailor monorepo 独立 install / run。版本来源是脚手架运行时读取的已发布版本注册表。

示例会话

  create-sailor

✔ 项目创建在哪里？ … ./my-saas
✔ Target region? › global — 海外优先
✔ Auth provider? › Clerk
✔ AI topology? › Multi-provider AI Gateway / router

  ▸ Region            global
  ▸ Auth              clerk
  ▸ ORM               prisma
  ▸ Database          postgresql
  ▸ Payment           stripe
  ▸ AI topology       gateway
  ▸ Email             resend
  ▸ Storage           r2
  ▸ Deploy Target     vercel
  ▸ Docs Framework    fumadocs

⠋ 正在克隆 Nebutra-Sailor 模板到 ./my-saas...
✔ 项目 my-saas 初始化成功！

  后续步骤：
  cd ./my-saas
  pnpm install
  pnpm dev

脚手架后的操作

cd my-saas
pnpm install          # 安装所有依赖
pnpm infra:lite       # 启动 PostgreSQL（Docker）
pnpm db:generate      # 生成 Prisma 客户端
pnpm db:migrate       # 运行初始迁移
pnpm dev:dashboard    # 启动 Web 应用 + API 网关

create-sailor 是一次性工具。项目创建后，日常任务（添加组件、管理基础设施、运行迁移）请使用 nebutra CLI。