快速入门

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

本地开发

初始化项目

拉取 shipsaas-life 源代码：

git clone [email protected]:shipsaasnet/shipsaas-life my-shipsaas-project

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

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

cd my-shipsaas-project

安装依赖

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

pnpm install

启动开发服务器

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

pnpm dev

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

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

pnpm dev --port 8080

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

预览项目

打开项目预览地址，首次看到的页面是这样的：

如果你想通过 AI 快速完成项目初始化，可以参考 使用 Agent Skills 初始化项目。

配置环境变量

创建配置文件

通过下面的命令，复制一份配置文件，用于配置本地开发用到的环境变量。

cp .env.example .env.development

修改环境变量值

根据你的项目信息，自行修改配置文件中的内容。

# app
NEXT_PUBLIC_APP_URL = "http://localhost:3000"
NEXT_PUBLIC_APP_NAME = "shipsaas.net"

# database
DATABASE_URL = ""

# auth secret
# openssl rand -base64 32
AUTH_SECRET = ""

必填项：

• NEXT_PUBLIC_APP_URL：项目主页地址。复制项目预览地址填入
• NEXT_PUBLIC_APP_NAME：应用名称。改成你的项目名称

选填项：

• DATABASE_URL：数据库连接地址。如果你需要用户登录、管理后台等功能，需要配置此项。
• AUTH_SECRET：鉴权密钥。如果要开启用户登录功能，需要配置此项。

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

openssl rand -base64 32

配置数据库

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

创建数据库

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

postgresql://postgres.xxx:[email protected]:6543/postgres

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

postgresql://user:[email protected]:5432/my_shipsaas_project

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

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

设置环境变量

把上一步骤得到的数据库连接地址填入环境变量 DATABASE_URL。

DATABASE_URL = "postgresql://user:[email protected]:5432/my_shipsaas_project"

迁移数据表

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

pnpm db:generate
pnpm db:migrate

迁移数据表命令，在连接数据库时，读取的是 .env.development 文件中的 DATABASE_URL 变量。

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

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

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

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

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

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

# local database
DATABASE_URL = "postgresql://user:[email protected]:5432/my_shipsaas_project"
# remote database
# DATABASE_URL = "postgresql://postgres.xxx:[email protected]:6543/postgres"

配置登录鉴权

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

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

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

生成鉴权密钥

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

openssl rand -base64 32

设置环境变量

把上一步骤生成的鉴权密钥填入 .env.development 文件中的 AUTH_SECRET 变量。

AUTH_SECRET = "your-secret-key"

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

自定义配置

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

修改项目信息

修改文件：.env.development 和 .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 部署