tinyship-setup

TinyShip 设置

TinyShip SaaS 入门项目的交互式设置向导。

这是一个对话式的逐步向导。在每个决策点，你都必须询问用户，并等待他们回答后再继续。绝不要替用户做选择。

步骤 0：检测模板

阅读 ../../references/template-detection.md， 并检测当前项目使用的是哪个模板（shipeasy 或 tinyship-cf）。 在下面的每个步骤中遵循相应的分支。对于 tinyship-cf，所有标记为 “仅限 shipeasy”的步骤都应完全跳过。

前置条件

开始前，请确认：

1. Node.js >= 22.20.0 — 运行 node -v 检查（Nuxt 4 的 oxc-parser 原生绑定需要此版本）
2. pnpm >= 9.0.0 — 运行 pnpm -v 检查。若未安装，请运行 npm install -g pnpm 安装

如果不满足前置条件，请告知用户需要安装什么，然后停止。

步骤 1：环境配置

shipeasy：

1. 复制模板：cp env.example .env
2. 生成身份验证密钥：openssl rand -hex 32
3. 将生成的密钥设为 .env 中的 BETTER_AUTH_SECRET

tinyship-cf：

1. 复制模板：cp apps/tanstack-app/.dev.vars.example apps/tanstack-app/.dev.vars
2. 生成身份验证密钥：openssl rand -hex 32
3. 将生成的密钥设为 .dev.vars 中的 BETTER_AUTH_SECRET

暂时不要配置数据库方言——这取决于用户在步骤 2 中的选择。

步骤 2：选择数据库

⛔ 停止 — 继续之前必须先询问用户。

tinyship-cf： 默认且推荐使用的数据库是 Cloudflare D1——它已在 wrangler.jsonc 中绑定，无需连接字符串。只需运行：

cd apps/tanstack-app
npx wrangler d1 migrations apply tinyship-db --local

然后跳至步骤 3。如果用户明确想使用 PostgreSQL（Hyperdrive），请转交给 tinyship-cloudflare 技能的 Hyperdrive 流程。

shipeasy： 展示以下选项，并等待用户回答：

选项	数据库	适用场景
A	SQLite	最快上手、无需配置、本地开发
B	PostgreSQL	生产环境、团队协作

如果用户选择 SQLite：

在 .env 中设置：

DB_DIALECT="sqlite"

然后运行：

mkdir -p data
pnpm install
pnpm db:push:sqlite
pnpm db:seed:sqlite

重要： 必须执行 mkdir -p data——创建数据库文件之前，SQLite 要求 data/ 目录已存在。

如果用户选择 PostgreSQL：

在询问用户连接详情之前，自动检测本地 PostgreSQL 环境：

1. 运行 pg_isready，检查本地 PostgreSQL 是否正在运行。
2. 如果 PostgreSQL 正在运行：
   • 告知用户：“PostgreSQL 已在您的计算机上运行。”
   • 尝试自动创建 tinyship 数据库：

     # 尝试使用常见的超级用户帐户创建数据库
     createdb tinyship 2>/dev/null || \
       createdb -U postgres tinyship 2>/dev/null || \
       createdb -U $(whoami) tinyship 2>/dev/null
     

   • 如果数据库创建成功，检测连接字符串：

     # 根据 pg_isready 的输出或默认值确定 PostgreSQL 用户和端口
     # 常见情况：
     #   macOS Homebrew/Postgres.app：用户 = 当前操作系统用户，端口 = 5432
     #   Linux 系统安装：用户 = postgres，端口 = 5432
     

   • 自动构建 DATABASE_URL。常见的本地配置：
     • postgresql://localhost:5432/tinyship（macOS Postgres.app / Homebrew，peer 身份验证）
     • postgresql://postgres:postgres@localhost:5432/tinyship（带密码的 Linux）
     • postgresql://<os-username>@localhost:5432/tinyship（使用用户名的 macOS）
   • 向用户显示检测到的连接字符串，并在使用前征求确认。
   • 如果数据库创建失败，告知用户，并改为请求用户手动输入。
3. 如果 PostgreSQL 未运行：
   • 告知用户此计算机上未检测到 PostgreSQL。
   • 提供以下选项：
     • Docker：启动容器化的 PostgreSQL（需要 Docker 正在运行）
     • 手动：用户提供自己的连接字符串

自动检测成功 — 在 .env 中设置：

DB_DIALECT="pg"
DATABASE_URL="<the auto-detected or confirmed connection string>"

Docker 备用方案 — 运行：

docker run --name tinyship-db \
  -e POSTGRES_USER=tinyship \
  -e POSTGRES_PASSWORD=tinyship123 \
  -e POSTGRES_DB=tinyship \
  -p 5432:5432 \
  -d postgres:15

在 .env 中设置：

DB_DIALECT="pg"
DATABASE_URL="postgresql://tinyship:tinyship123@localhost:5432/tinyship"

数据库配置完成后（无论使用哪种方式），运行：

pnpm install
pnpm db:push
pnpm db:seed

种子数据会创建两个测试用户

• 管理员：[email protected] / admin123（角色：admin）
• 用户：[email protected] / user123456（角色：user）

步骤 3：选择框架（仅限 shipeasy）

⛔ 停止 — 继续之前必须询问用户。

展示以下选项并等待用户回复：

选项	框架	适用场景	开发命令
A	Next.js	React 开发者、部署到 Vercel、生态最丰富	pnpm dev:next
B	Nuxt.js	Vue 开发者、约定优于配置	pnpm dev:nuxt
C	TanStack Start	轻量级 React、部署到 Cloudflare Workers 边缘网络	pnpm dev:tanstack

注意： 若要部署到 Cloudflare Workers，建议改用 tinyship-cf 模板， 该模板已预先配置好 Workers，无需变通方案。

tinyship-cf： 跳过选择 — TanStack Start 是唯一的框架。开发命令 为 pnpm dev。

用户选择后（或使用 tinyship-cf 时），启动应用并进行验证：

1. 运行开发命令（例如 pnpm dev:next / pnpm dev）
2. 打开 http://localhost:7001 — 首页应能加载
3. 检查 http://localhost:7001/api/health — 应返回响应
4. 尝试使用 [email protected] / admin123 登录

告知用户每个验证步骤的结果。

步骤 4：选择定价模式（可选）

⛔ 停止 — 继续之前必须询问用户。

TinyShip 支持两种定价模式。展示以下选项：

选项	模式	适用场景
A	静态（默认）	设置简单、方案定义在代码中、需重新部署才能更新
B	动态	通过管理界面管理、无需重新部署即可更新方案

如果用户选择静态（或跳过）：

无需其他配置。方案定义在 config/payment.ts 中，并直接显示在定价页面上。这是默认行为。

如果用户选择 Dynamic：

在 .env（shipeasy）或 apps/tanstack-app/.dev.vars（tinyship-cf）中设置：

PRICING_MODE="dynamic"

动态定价会将套餐存储在数据库中，并在 /admin/pricing 提供管理界面， 用于创建、编辑和管理套餐，无需更改代码。功能包括：

• 多语言套餐名称／描述（可扩展的 i18n 标签页）
• 支持 Markdown 的功能列表
• 划线价格（显示原价）
• 基于区域设置筛选套餐
• 每个支付提供商对应的支付 ID（Stripe Price ID、PayPal Plan ID 等）
• 一键将现有静态套餐导入数据库

注意：pricing_plan 表的数据库迁移已包含在内。 设置完成后，可通过 /admin/pricing 管理所有套餐。 对于 tinyship-cf，还需要在 wrangler.jsonc 的 vars 中设置 PRICING_MODE， 以应用于已部署的 Worker。

告知用户：“以后随时可以通过更改环境文件中的 PRICING_MODE 来切换模式。config/payment.ts 中的静态套餐仍可作为回退选项使用。”

步骤 5：清理框架（可选，仅限 shipeasy）

⛔ 停止 — 继续之前必须先询问用户。未经明确确认，不得删除任何内容。

确认应用正常运行后，询问用户：

你的项目目前包含全部三个框架（Next.js、Nuxt.js、TanStack Start）。 你是否想移除未使用的两个框架，以简化项目？

• 是 — 移除未使用的框架，并清理所有相关配置
• 否 — 保留全部三个框架（以后随时可以移除）

只有用户明确表示同意时，才能继续清理。

如果同意，请阅读并遵循 references/framework-cleanup.md 中的详细清理步骤。

清理将会：

• 删除未使用的 apps/ 目录
• 清理工作区配置、构建脚本、Docker 和 CI
• 如果只保留 Nuxt，则移除 libs/react-shared（它仅适用于 React）
• 验证剩余应用仍可正确构建

步骤 6：后续步骤

设置完成后，告知用户接下来可以做什么：

1. 自定义品牌 — 更改应用名称、徽标和主题（使用 tinyship-brand 技能）
2. 添加身份验证 — 配置 OAuth 提供商（使用 tinyship-auth 技能）
3. 设置支付 — 集成支付提供商（使用 tinyship-payment 技能）
4. 配置 AI — 设置 AI 聊天／图像／视频功能（使用 tinyship-ai 技能）
5. 部署 — 部署到 Vercel、Docker 或 Cloudflare（使用 tinyship-deploy 技能； 对于 Cloudflare Workers，使用 tinyship-cloudflare 完成全部设置）

TinyShip 仓库中的参考文件

执行此技能时，请阅读用户 TinyShip 项目中的以下文件，以了解相关背景：

• env.example（shipeasy）／apps/tanstack-app/.dev.vars.example（tinyship-cf）— 环境变量
• docs/user-guide/get-started.md — 详细的入门指南
• docs/user-guide/database.md — 数据库配置详情
• docs/user-guide/payment/dynamic-pricing.md — 动态定价功能指南
• pnpm-workspace.yaml — 工作区结构
• package.json — 可用脚本