用户指南
快速开始
在本地环境中设置和运行 TinyShip 项目
本指南将帮助你在本地环境中设置和运行 TinyShip 项目。
系统要求
在开始之前，请确保你的开发环境满足以下要求：
- Node.js: >= 22.20.0 （必须使用 22.20.0 或更高的 LTS 版本）
- PNPM: >= 9.0.0 （推荐的包管理器）
- SQLite / PostgreSQL: 二选一（默认推荐 PostgreSQL；仅在你明确要使用 Cloudflare D1 时再选择 SQLite / D1）
由于 Nuxt 4 使用的 oxc-parser 原生绑定问题，Node.js 版本必须 >= 22.20.0。低于此版本可能导致安装失败。
快速安装
克隆项目
git clone https://github.com/TinyshipCN/tinyship.git
cd tinyship
# 或者使用 SSH
git clone git@github.com:TinyshipCN/tinyship.git
cd tinyship安装 AI Agent Skills（可选，推荐）
如果你使用 AI 编辑器（Cursor、Claude Code、Codex、OpenCode 等），现在就可以安装 TinyShip Agent Skills 获得 AI 引导式配置体验：
npx skills add TinyshipCN/tinyship-skills安装后，你可以直接对 AI 说「帮我设置 TinyShip」、「all-in Cloudflare」、「配置 Stripe 支付」、「用 recipe 做导航站」等，AI 会交互式引导你完成配置。支持 67+ AI 编辑器。Recipes 说明见用户指南对应章节。
安装 PNPM（如果尚未安装）
# 使用 npm 安装 pnpm
npm install -g pnpm
# 或使用 corepack (Node.js 16.10+)
corepack enable
corepack prepare pnpm@latest --activate
# 验证安装
pnpm --version复制环境变量模板
cp env.example .env安装项目依赖
pnpm install数据库配置
TinyShip 默认并推荐使用 PostgreSQL（pg），这是当前项目最稳定、最完整验证的数据库方案。\n同时也支持 sqlite（本地文件）和 d1（Cloudflare D1）作为补充场景。
1. PostgreSQL（默认、推荐、最稳）
方法 1: 使用 Docker（推荐）
docker run --name tinyship-db \
-e POSTGRES_USER=tinyship \
-e POSTGRES_PASSWORD=your_password \
-e POSTGRES_DB=tinyship \
-p 5432:5432 \
-d postgres:15
# 验证容器运行
docker ps | grep tinyship-db方法 2: 本地安装
sudo -u postgres createuser --interactive tinyship
sudo -u postgres createdb tinyship --owner=tinyship
sudo -u postgres psql -c "ALTER USER tinyship PASSWORD 'your_password';"方法 3: 云数据库服务
支持以下云服务提供商：
- Vercel Postgres: 与 Vercel 部署无缝集成
- Supabase: 提供免费套餐，易于设置
- AWS RDS: 企业级选择
- 阿里云 RDS: 国内用户推荐
在项目根目录 .env 文件中配置数据库连接：
# 默认就是 pg，可不写 DB_DIALECT
DB_DIALECT="pg"
DATABASE_URL="postgresql://username:password@localhost:5432/tinyship"
# 可选：SQLite（与 D1 兼容）
# DB_DIALECT="sqlite"
# SQLITE_DB_PATH="./data/local.sqlite"# 检查数据库连接
pnpm db:check
# 推送表结构（开发环境）
pnpm db:push
# 填充测试数据
pnpm db:seed2. SQLite（可选，与 D1 兼容）
DB_DIALECT="sqlite"
# SQLITE_DB_PATH="./data/local.sqlite"# 检查 SQLite 连接
pnpm db:check:sqlite
# 推送 SQLite 表结构
pnpm db:push:sqlite
# 填充 SQLite 测试数据
pnpm db:seed:sqlite
# 打开可视化数据库管理界面
pnpm db:studio:sqlite3. D1 与 SQLite 的关系
sqlite: 本地文件数据库d1: Cloudflare Workers 托管 SQLite- 两者复用同一套 schema
- Cloudflare Workers 线上部署可使用
DB_DIALECT="d1"
这将创建两个测试用户：
- 管理员:
admin@example.com/admin123(角色: admin) - 普通用户:
user@example.com/user123456(角色: user)
最小化认证配置
在 .env 文件中配置认证环境变量：
BETTER_AUTH_SECRET="your-secret-key-here-32-characters-min"
BETTER_AUTH_URL="http://localhost:7001"
DB_DIALECT="pg"
DATABASE_URL="postgresql://username:password@localhost:5432/tinyship"
# 可选：SQLite（与 D1 兼容）
# DB_DIALECT="sqlite"
# SQLITE_DB_PATH="./data/local.sqlite"生成 32 位随机字符串：
# 使用 openssl
openssl rand -hex 32
# 使用 Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"启动应用
# 启动 Next.js 应用
pnpm run dev:next
# 或者启动 Nuxt.js 应用
pnpm run dev:nuxt
# 或者启动 TanStack Start 应用
pnpm run dev:tanstack
# 访问 http://localhost:7001恭喜！ 你已经成功运行了 TinyShip 应用。