快速入门

在开始使用 shipsaas 之前，请确保你已经获取 shipsaas 并已获得 shipsaas 代码仓库访问权限。并且确保你已经完成了前置要求。

本地开发

第 1 步：拉取项目代码

拉取 shipsaas 源代码：

git clone git@github.com:shipsaasnet/shipsaas my-shipsaas-project

默认拉取的是 main 分支的代码，基于 Next.js 16，可部署在 Vercel，或通过 VPS + Dokploy 部署。

拉取完代码之后，进入项目根目录，后续的命令行操作都在项目根目录下执行。

cd my-shipsaas-project

第 2 步：安装依赖

执行以下命令，安装项目依赖。

pnpm install

第 3 步：复制环境变量到 .env

通过下面的命令，复制一份本地开发用的环境变量模板：

cp .env.example .env

ShipSaaS 当前的本地开发流程默认读取项目根目录下的 .env 文件，所以这里不要再复制到 .env.development。

第 4 步：修改 .env

根据你的项目实际情况，至少先修改下面这些字段：

# app
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_APP_NAME="My ShipSaaS App"

# database
DATABASE_URL="postgres://postgres:postgres@localhost:5432/my_shipsaas_project"

# better auth
BETTER_AUTH_SECRET="replace-with-strong-secret-32+chars"
BETTER_AUTH_BASE_URL="http://localhost:3000"

必填项：

• NEXT_PUBLIC_APP_URL：项目主页地址。本地开发时通常填 http://localhost:3000
• NEXT_PUBLIC_APP_NAME：应用名称。改成你的项目名称
• DATABASE_URL：数据库连接地址。如果你需要登录、支付、管理后台等功能，需要配置此项
• BETTER_AUTH_SECRET：Better Auth 鉴权密钥。开启用户登录时必填
• BETTER_AUTH_BASE_URL：Better Auth 使用的站点地址，本地开发时通常和 NEXT_PUBLIC_APP_URL 保持一致

可以通过以下命令生成随机密钥：

openssl rand -base64 32

第 5 步：启动开发服务器

执行以下命令，启动开发服务器。

pnpm dev

点击输出的 Local 地址，在浏览器打开网页：http://localhost:3000，即可预览项目。

启动的开发服务器默认监听 3000 端口，如果你希望使用其他端口，可以在启动开发服务器时指定端口。

pnpm dev --port 8080

新的项目预览地址就是：http://localhost:8080。

配置数据库

如果你的项目需要用户登录、管理后台等功能，必须按照以下步骤配置数据库。

第 1 步：先确认数据库连接地址

你可以在 Supabase、Neon 等云数据库平台创建数据库，得到云数据库的远程连接地址，类似这种：

postgresql://postgres.xxx:xxxxxx@aws-0-ap-southeast-1.pooler.supabase.com:6543/postgres

你也可以使用自建的 PostgreSQL 数据库，得到数据库的连接地址，类似这种：

postgresql://user:password@127.0.0.1:5432/my_shipsaas_project

建议本地开发使用自建的 PostgreSQL 数据库，线上版本使用 Supabase、Neon 等云数据库（兼容 PostgreSQL，无缝切换）。

常用数据库的创建和连接地址获取，可以参考：数据库 部分的文档。

把数据库连接地址填入 .env 文件中的 DATABASE_URL：

DATABASE_URL="postgresql://user:password@127.0.0.1:5432/my_shipsaas_project"

第 2 步：创建新的数据库

如果你使用的是本地 PostgreSQL，并且目标数据库还不存在，可以直接执行：

pnpm run db:init

这个命令会读取 .env 里的 DATABASE_URL，连接同一台 PostgreSQL 实例的 postgres 默认数据库，然后自动创建目标数据库。

使用前请确认两点：

• DATABASE_URL 里的数据库名称已经改成你真正想创建的名称，比如 my_shipsaas_project
• 当前 PostgreSQL 用户具备 CREATE DATABASE 权限

如果你使用的是 Supabase、Neon 这类云数据库平台，数据库通常已经由平台创建完成，这一步可以跳过。

第 3 步：迁移数据表

执行以下命令，迁移数据表：

pnpm db:generate
pnpm db:migrate

迁移数据表命令会读取 .env 文件中的 DATABASE_URL 变量。

第 4 步：排查数据库连接问题

如果在执行迁移命令 pnpm db:migrate 时遇到 Timeout 超时问题，或者长时间无响应，可以先通过以下命令检查数据库能否被正常连接：

psql "postgresql://user:password@address:port/database" # YOUR-DATABASE-URL

如果通过命令直接连接数据库也无法连上，你需要检查你的数据库地址是否有误，或者是否存在网络问题（比如防火墙、代理等）。

正常执行 pnpm db:migrate 迁移数据表成功后，你可以再次执行上述命令，验证数据表是否成功创建。

第 5 步：切换本地和线上数据库

你可以在本地开发时，把 DATABASE_URL 设置成本地数据库地址。部署上线前，把 DATABASE_URL 设置成线上数据库地址，执行完迁移数据表命令，再改回本地数据库地址。

在 .env 文件中，可以通过注释来切换数据库地址。

# local database
DATABASE_URL="postgresql://user:password@127.0.0.1:5432/my_shipsaas_project"
# remote database
# DATABASE_URL="postgresql://postgres.xxx:xxxxxx@aws-0-ap-southeast-1.pooler.supabase.com:6543/postgres"

配置登录鉴权

shipsaas 使用了 Better Auth 实现用户登录鉴权功能。

如果你的网站只使用 Landing Page 实现静态网站功能，可以不配置登录鉴权。

如果你的网站需要用户登录、支付、管理后台等功能，必须配置登录鉴权。

生成鉴权密钥

通过以下命令生成随机的鉴权密钥。

openssl rand -base64 32

设置环境变量

把上一步骤生成的鉴权密钥填入 .env 文件中的 BETTER_AUTH_SECRET 变量，并同步设置 BETTER_AUTH_BASE_URL：

BETTER_AUTH_SECRET="your-secret-key"
BETTER_AUTH_BASE_URL="http://localhost:3000"

配置了 BETTER_AUTH_SECRET 后，默认开启邮箱登录，用户访问你的网站时，会请求 /api/auth/get-session 接口检查登录状态。未配置时，不会检查登录状态。

自定义配置

请参考以下步骤，自定义你的项目。

修改项目信息

修改文件：本地开发改 .env，生产环境使用 .env.production 或部署平台环境变量。 修改内容：项目名称、部署 URL、鉴权基础地址。 参考：设置应用基本信息。

修改项目图标

修改文件：public/logo.png 和 public/favicon.ico。 修改内容：为你的项目设计 Logo 和 Favicon，替换默认的图标文件。 参考：设置应用图标。

修改站点地图

修改文件：public/sitemap.xml。 修改内容：更新为你网站的页面列表。 参考：设置站点地图。

修改网站协议

修改文件：content/pages/privacy-policy.mdx 和 content/pages/terms-of-service.mdx。 修改内容：更新为你网站的隐私政策和服务条款。 参考：设置网站协议。

修改网站通用展示内容

修改文件：src/config/locale/messages/{locale}/common.json。 修改内容：更新为你网站的通用展示内容。 参考：设置通用展示内容。

修改着陆页展示内容

修改文件：src/config/locale/messages/{locale}/landing.json。 修改内容：更新为你网站的着陆页展示内容。 参考：设置着陆页内容。

修改网站主题样式

修改文件：src/config/style/theme.css。 修改内容：更新为你网站的主题样式。 参考：设置主题样式。

修改多语言配置

修改文件：src/config/locale/index.ts。 修改内容：设置项目支持显示的语言。 参考：设置多语言切换。

项目最小化改动参考

发布上线

在完成本地开发和自定义配置之后，你可以选择一种部署方案，将你的项目发布上线。

• 部署到 Vercel
• 部署到 Cloudflare Workers
• 使用 Dokploy 部署