快速开始

已根据 starter 提交 e632762 验证。

先从 Core 开始：客户端应用、持久化 worker、PostgreSQL、Redis 和私有本地对象存储。第一个目标是走通完整本地流程：登录、查看演示积分发放、运行一个模拟图片任务，再检查私有结果和账本记录。这个本地体验不需要 Stripe、邮件或 AI 供应商账号。

选择起点

可以随时添加其他应用。这些配置只选择本地工具和构建目标，不会改变产品套餐、权限或可用 API 路由。

1. 准备环境

• Git
• Node.js >=24.22.1 <25（仓库的 .nvmrc 固定了已测试版本）
• pnpm 10.22.0
• 本地已启动的 Docker 和 Compose

2. 运行 Core

在终端中执行下列命令。新分支从已审核的源码提交创建，确保代码与指南一致。

git clone https://github.com/PansaLegrand/sushi-saas-template.git
cd sushi-saas-template
git switch -c my-saas e63276252e4b64566229cb87225afc72da6991de
export SAAS_STARTER_PROFILE=core
pnpm starter core install
pnpm starter core setup
pnpm starter core doctor
pnpm starter core demo

demo 先执行只读 doctor 检查，通过后才创建演示账号，再启动 Core：开启模拟图片、将模拟供应商失败次数设为零，并禁用本地验证码。这些进程中的邮件、Slack 和 Stripe 会禁用，环境文件保持不变，也不会调用商业 AI 供应商。命令使用 bash/zsh 或 WSL。普通的 pnpm starter core dev 仍用于正常开发，不会自动启用此演示模式。

保持终端运行，打开 localhost:3000/zh/login。

Setup 会创建缺失且已被 Git 忽略的环境文件，启动 PostgreSQL、Redis 和 Garage，创建本地应用、测试及恢复演练数据库，应用 Drizzle 迁移，并配置私有 sushi-dev bucket。Core 跳过 Content Studio 的安装、环境文件、数据库创建和迁移。可以重复执行 setup，它不会覆盖已有环境文件。

Setup 会先检查 Docker 是否运行、Docker Compose 是否可用，以及 5432/6379 端口上的服务是否属于当前项目，再写入环境文件。工具缺失、Docker 停止或端口被其他服务占用时会报错退出；请解决提示的前置条件后重试。

doctor 只读检查工具、环境边界、基础设施、迁移、存储和端口，不输出秘密值。Demo 在 seed 前运行 doctor，然后启动 web 和 worker，不再重复执行同一检查。按 Ctrl-C 会停止两个进程。

筛选安装后，在每个用于 pnpm lint 或提交的终端中导出 SAAS_STARTER_PROFILE=core，让检查采用相同配置。这里的 export 适用于 POSIX shell；PowerShell 使用 $env:SAAS_STARTER_PROFILE="core"。

3. 看到第一个可用页面

1. 新账号使用 demo@example.test 和 DemoPass123!，或创建账号时使用的 DEV_SEED_PASSWORD。已有账号继续使用原密码，demo 输出会明确提示密码未变更。
2. 打开 账户 → 积分。找到一次性发放的 1,000 演示积分。Worker 还可能处理独立的 10 积分注册奖励，因此新环境总余额可能变为 1,010。演示发放金额不代表总余额始终为 1,000。
3. 打开 账户 → 个人资料与安全探索设置。此时工作区和会话已在真实的本地应用中运行。

这些凭据仅用于本地开发。Seed 创建使用保留域名的已验证账号，并修复缺失的演示数据，不会重复发放同一笔积分，也不需要发送邮件。已有演示活动可能改变显示的余额。

4. 完成第一个图片任务

1. 启动时的积分发放处理完毕后，刷新 账户 → 积分并记下余额。整个流程保持在同一工作区。
2. 打开本地图片任务，保留应用自动添加的 org 参数。在提示词中输入 我的第一个 Sushi SaaS 图片任务，点击一次生成图像。
3. 状态可能短暂显示正在等待工作进程…和正在生成并存储图像…。等待图像已就绪。预期结果是一张蓝紫色 SVG，带有 Image generation mock 字样和你的提示词。这是模拟响应，不是 AI 绘制的插画。
4. 刷新同一个任务 URL，应恢复相同任务 ID 和图片，不产生第二笔扣费。再生成一张图片会主动创建新任务，再扣五积分。
5. 回到同一工作区的 账户 → 积分，找到一条图像生成的 −5 扣除记录。没有其他账本活动时，余额等于原余额减五：1,000 → 995，或注册奖励到账后的 1,010 → 1,005。在 账户 → 文件中，结果文件名为 generated-<任务 ID>.svg。

结果存放在本地私有 Garage bucket。页面使用有效期为 15 分钟的签名 URL 显示图片；重新打开保存的任务 URL 会获取新链接。持有签名 URL 的人可以临时访问文件，它不是永久公开资源地址。

**你已验证：**登录 → 工作区授权 → 一次五积分扣除 → 持久化 worker → 私有结果 → 可恢复的任务界面。Free 套餐已包含此图片示例，无需订阅，也无需 --paid-examples seed。

首次运行遇到问题

验证本地服务

在另一个终端中检查服务：

curl http://localhost:3000/api/health
curl http://localhost:3000/api/ready
pnpm test:fast

构建前先按 Ctrl-C 停止开发启动器，因为开发和生产构建共用 .next：

pnpm starter core build

构建保留根目录测试套件，并打包 worker 运行时。完整浏览器流程见测试与 CI，它在可丢弃环境中覆盖真实本地存储和模拟供应商任务。

5. 开始定制

运行 pnpm customize 设置产品身份、外观和语言，然后阅读定制产品和架构与错误契约。等用到对应功能时再配置外部服务，参考环境配置。

按需添加应用

切换配置前先停止正在运行的开发启动器。要添加位于 http://localhost:3001 的管理后台：

export SAAS_STARTER_PROFILE=operations
pnpm starter operations install
pnpm starter operations setup
pnpm starter operations dev

按照管理后台设置配置运营权限与 MFA；演示客户账号不会自动成为管理员。

要进一步添加位于 http://localhost:3002/admin 的 Content Studio：

export SAAS_STARTER_PROFILE=publishing
pnpm starter publishing install
pnpm starter publishing setup
pnpm starter publishing dev

Publishing 创建独立的 Payload 数据库并应用迁移。它的身份验证和数据库必须与 SaaS 分离，详见 Content Studio 与营销。

所有配置都支持 doctor、lint、build 和 --dry-run。未选择配置时，pnpm run setup、pnpm dev:all 和 pnpm build 保留完整应用默认行为。需要交互式完整安装与定制时，在没有 SAAS_STARTER_PROFILE 的 shell 中执行 ./scripts/setup.sh development。

确认后再重置本地演示数据

pnpm dev:reset -- --dry-run
pnpm dev:reset

先预览目标。Reset 拒绝外部服务，要求明确确认，只重建当前 Compose 项目的本地数据，重新迁移并默认重新填充演示数据。环境配置文件会保留。普通重启无需重置。