用户指南
快速开始
在本地环境中设置和运行 TinyShip 项目
本指南将帮助你在本地环境中设置和运行 TinyShip 项目。
系统要求
在开始之前，请确保你的开发环境满足以下要求：
- Node.js: >= 22.20.0 （必须使用 22.20.0 或更高的 LTS 版本）
- PNPM: >= 9.0.0 （推荐的包管理器）
- PostgreSQL: >= 13.0 （数据库）
由于 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安装 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 作为主数据库，结合 Drizzle ORM 提供类型安全的数据库操作。
创建 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 文件中配置数据库连接：
DATABASE_URL="postgresql://username:password@localhost:5432/tinyship"pnpm run db:check初始化数据库架构
pnpm run db:push填充测试数据
pnpm run db:seed这将创建两个测试用户：
- 管理员:
admin@example.com/admin123456(角色: admin) - 普通用户:
user@example.com/user123456(角色: user)
最小化认证配置
在 .env 文件中配置认证环境变量：
BETTER_AUTH_SECRET="your-secret-key-here-32-characters-min"
BETTER_AUTH_URL="http://localhost:7001"
DATABASE_URL="postgresql://username:password@localhost:5432/tinyship"生成 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
# 访问 http://localhost:7001恭喜！ 你已经成功运行了 TinyShip 应用。